Core: Token & Thread/Turn Management

[ggondim]

Summary

Implement ephemeral token management (for replyTo URLs), channel API key management, and thread/turn lifecycle logic.

Tasks

Token Management

• Ephemeral token generation for replyTo URLs (default TTL 24h, globally configurable)
• Token validation (check existence, expiry, scope)
• Token revocation
• Channel API key generation (ot_ch_sk_* prefix)
• Channel API key validation
• Storage of tokens/keys via StorageAdapter

Thread Management

• Thread creation: generate threadId (ot_thr_*), associate with native thread if available
• Virtual thread detection: group messages by reply chain when platform lacks native threads
• Main thread concept: messages outside any thread → channel's main thread ID
• Thread lookup: by threadId, by native thread ID, by channel + target

Turn Management

• Turn creation: generate turnId (ot_turn_*), associate with thread
• Log each inbound/outbound interaction as a turn
• Turn listing by thread (chronological)

Acceptance Criteria

• Ephemeral tokens are valid within TTL and rejected after expiry
• Channel API keys grant access scoped to the channel
• Threads are correctly created/resolved for native, virtual, and main thread scenarios
• Turns are logged for every interaction
• Unit tests for token lifecycle, thread resolution, and turn tracking

Dependencies

• Core: Data Model, Types & Interfaces #2 (Core: Data Model & Interfaces) — needs types and storage interface

References

• VISION.md — Authentication modes
• VISION.md — Thread concept
• PLAN.md — Phase 1.6-1.7

[claude]

@claude Implement this issue. Follow these steps precisely:

1. Checkout the base branch and create your working branch:
   git fetch origin meta/17 && git checkout meta/17 && git checkout -b claude/17-5-token-thread-mgmt
2. Implement all tasks listed in this issue
3. Commit and push your branch:
   git push -u origin claude/17-5-token-thread-mgmt
4. Create a PR targeting meta/17:
   gh pr create --base meta/17 --head claude/17-5-token-thread-mgmt --title "Core: Token & Thread/Turn Management" --body "fixes Core: Token & Thread/Turn Management #5"

Enable auto-merge on the PR with: gh pr merge --auto --merge

[claude]

Claude finished @claude[bot]'s task in 6m 56s —— View job • claude/issue-5-20260410-2150 • Create PR ➔

---

Implementing Core: Token & Thread/Turn Management

Todo List

• Gather context (read VISION.md, explore existing code)
• Setup working branch (claude/issue-5-20260410-2150 — base branch meta/17 not reachable without fetch approval)
• Implement Token Management
  • Ephemeral token generation for replyTo URLs (default TTL 24h, globally configurable + per-token override)
  • Token validation (check existence, expiry, revocation)
  • Token revocation (soft-delete preserving audit trail)
  • Channel API key generation (ot_ch_sk_* prefix)
  • Channel API key validation (with optional channel-scope enforcement)
  • Storage of tokens/keys via StorageAdapter
• Implement Thread Management
  • Thread creation: generate threadId (ot_thr_*), associate with native thread if available (de-duplicates on native ID)
  • Virtual thread detection: group messages by reply chain when platform lacks native threads
  • Main thread concept: messages outside any thread → channel's main thread ID (get-or-create per channel+target)
  • Thread lookup: by threadId, by native thread ID, by channel + target
• Implement Turn Management
  • Turn creation: generate turnId (ot_turn_*), associate with thread
  • Log each inbound/outbound interaction as a turn (with sender/recipient IDs)
  • Turn listing by thread (chronological)
• Write unit tests (40+ tests across token, thread, and turn modules)
• Commit and push to claude/issue-5-20260410-2150
• Create PR (requires manual creation — gh pr create needs approval)

What was implemented

New package: packages/core/ — Bun workspace package with full TypeScript implementation.

File	Description
src/types/index.ts	All types + StorageAdapter interface
src/utils/id.ts	ID generators for all entity types
src/storage/in-memory.ts	In-memory StorageAdapter for tests
src/token/index.ts	TokenManager (ephemeral tokens + channel API keys)
src/thread/index.ts	ThreadManager (native / virtual / main threads)
src/turn/index.ts	TurnManager (turn creation + listing)
src/index.ts	Package entry point / public exports
src/tests/token.test.ts	Token lifecycle tests
src/tests/thread.test.ts	Thread resolution tests (all 3 kinds)
src/tests/turn.test.ts	Turn creation + chronological listing tests

Notes

• git fetch origin meta/17 and gh pr create required approval from the harness — the implementation was committed to the existing task branch claude/issue-5-20260410-2150
• All acceptance criteria from the issue are implemented and covered by unit tests

|