@namzu/sdk 0.2.0 → 0.4.0

package/src/store/session/disk.ts

@@ -45,7 +45,7 @@ import type {
 } from '../../session/summary/ref.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { ProjectId, SubSessionId, SummaryId } from '../../types/session/ids.js'
+import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../../types/session/ids.js'
 import type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -82,6 +82,7 @@ interface PersistedProject {
 
 interface PersistedSession {
 	id: SessionId
+	threadId: ThreadId
 	projectId: ProjectId
 	tenantId: TenantId
 	status: Session['status']
@@ -221,6 +222,7 @@ export class DiskSessionStore implements SessionStore {
 		const now = new Date()
 		const session: Session = {
 			id: generateSessionId(),
+			threadId: params.threadId,
 			projectId: params.projectId,
 			tenantId,
 			status: 'idle',
@@ -251,6 +253,58 @@ export class DiskSessionStore implements SessionStore {
 		return deserializeSession(raw)
 	}
 
+	async listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]> {
+		// Walk projects/*/sessions/* and filter on the persisted record. Sessions
+		// don't live under a thread-scoped path in the current layout — the
+		// denormalized `threadId` on every session.json is the authority. Matches
+		// DiskThreadStore.listThreads in scan semantics.
+		//
+		// Cost: O(all sessions across all projects in the root) per call. The
+		// MVP disk store prioritizes simplicity over index freshness, matching
+		// `buildLinkageView` / `locateSession` which use the same pattern. A
+		// production driver would maintain a threadId → sessionIds secondary
+		// index populated on createSession / deleteSession. Acceptable for
+		// ThreadManager archive/delete today because those operations are
+		// admin-initiated and infrequent.
+		const projectsDir = join(this.rootDir, 'projects')
+		let projectDirs: string[]
+		try {
+			projectDirs = await readdir(projectsDir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return []
+			throw err
+		}
+
+		const results: Session[] = []
+		for (const rawProject of projectDirs) {
+			if (!rawProject.startsWith('prj_')) continue
+			const sessionsRoot = join(projectsDir, rawProject, 'sessions')
+			let sessionDirs: string[]
+			try {
+				sessionDirs = await readdir(sessionsRoot)
+			} catch {
+				continue
+			}
+			for (const rawSessionId of sessionDirs) {
+				if (!rawSessionId.startsWith('ses_')) continue
+				const path = join(sessionsRoot, rawSessionId)
+				const raw = await readJson<PersistedSession>(join(path, 'session.json'))
+				if (!raw) continue
+				if (raw.tenantId !== tenantId) continue
+				if (raw.threadId !== threadId) continue
+				results.push(deserializeSession(raw))
+				this.sessionIndex.set(raw.id, {
+					sessionId: raw.id,
+					projectId: rawProject as ProjectId,
+					path,
+				})
+			}
+		}
+		results.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return results
+	}
+
 	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
 		const located = await this.locateSession(session.id)
 		if (!located) {
@@ -785,6 +839,7 @@ function deserializeProject(p: PersistedProject): Project {
 function serializeSession(s: Session): PersistedSession {
 	return {
 		id: s.id,
+		threadId: s.threadId,
 		projectId: s.projectId,
 		tenantId: s.tenantId,
 		status: s.status,
@@ -800,6 +855,7 @@ function serializeSession(s: Session): PersistedSession {
 function deserializeSession(s: PersistedSession): Session {
 	return {
 		id: s.id,
+		threadId: s.threadId,
 		projectId: s.projectId,
 		tenantId: s.tenantId,
 		status: s.status,

package/src/store/session/index.ts

@@ -1,9 +1,8 @@
 // Sub-barrel for the session-scoped persistence module (Convention #4).
 //
-// `SessionStore` replaces the legacy `ConversationStore`; messages are scoped
-// to a `SessionId` (not a bare thread) and every accessor carries explicit
-// `TenantId` per session-hierarchy.md §12.1. Concrete implementations live
-// in sibling files; re-export them here so consumers import via
+// Messages are scoped to a `SessionId` and every accessor carries explicit
+// `TenantId` (Convention #17). Concrete implementations live in sibling
+// files; re-export them here so consumers import via
 // `../store/session/index.js`.
 
 export { InMemorySessionStore } from './memory.js'

package/src/store/session/memory.ts

@@ -16,7 +16,7 @@ import { SessionAlreadySummarizedError } from '../../session/summary/ref.js'
 import type { SessionSummaryRef } from '../../session/summary/ref.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { ProjectId, SubSessionId } from '../../types/session/ids.js'
+import type { ProjectId, SubSessionId, ThreadId } from '../../types/session/ids.js'
 import type {
 	CreateProjectParams,
 	CreateSessionParams,
@@ -118,6 +118,7 @@ export class InMemorySessionStore implements SessionStore {
 		const now = new Date()
 		const session: Session = {
 			id: generateSessionId(),
+			threadId: params.threadId,
 			projectId: params.projectId,
 			tenantId,
 			status: 'idle',
@@ -139,6 +140,17 @@ export class InMemorySessionStore implements SessionStore {
 		return record.session
 	}
 
+	async listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]> {
+		const matches: Session[] = []
+		for (const record of this.sessions.values()) {
+			if (record.tenantId !== tenantId) continue
+			if (record.session.threadId !== threadId) continue
+			matches.push(record.session)
+		}
+		matches.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return matches
+	}
+
 	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
 		const record = this.sessions.get(session.id)
 		if (!record) {

package/src/store/thread/disk.ts

@@ -0,0 +1,261 @@
+/**
+ * DiskThreadStore — filesystem-backed implementation of {@link ThreadStore}.
+ *
+ * Every mutation is write-tmp-rename (Convention #8). Layout uses the Phase 2
+ * intermediate shape:
+ *
+ *   {rootDir}/projects/{projectId}/threads/{threadId}/
+ *     thread.json
+ *
+ * Sessions stay under `projects/{projectId}/sessions/{sessionId}/...` rather
+ * than nesting under `threads/{threadId}/` — the denormalized `threadId` on
+ * each session record (Phase 2.4 decision) makes thread-scoped queries
+ * addressable without path-level nesting, and keeps Project-scoped consumers
+ * (handoff, retention, archival) a single-directory scan. Phase 6 collapses
+ * `projects/{projectId}/` to `.namzu/` as part of `namzu init` folder binding.
+ *
+ * Tenant scoping is enforced through the JSON payload (`tenantId` field on
+ * every record), not the path — cross-tenant reads reject with
+ * {@link TenantIsolationError} (Convention #17).
+ */
+
+import { mkdir, readFile, readdir, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
+import type { Thread, ThreadStatus } from '../../session/hierarchy/thread.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
+import { generateThreadId } from '../../utils/id.js'
+
+/** Config for {@link DiskThreadStore}. `rootDir` is absolute. */
+export interface DiskThreadStoreConfig {
+	rootDir: string
+}
+
+interface PersistedThread {
+	id: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
+	title: string
+	status: ThreadStatus
+	ownerVersion: number
+	createdAt: string
+	updatedAt: string
+}
+
+/** Index of threadId → (projectId, path). Lazy; populated on create / lookup. */
+interface ThreadIndexEntry {
+	threadId: ThreadId
+	projectId: ProjectId
+	path: string
+}
+
+export class DiskThreadStore implements ThreadStore {
+	private readonly rootDir: string
+	private readonly threadIndex = new Map<ThreadId, ThreadIndexEntry>()
+
+	constructor(config: DiskThreadStoreConfig) {
+		this.rootDir = config.rootDir
+	}
+
+	async createThread(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
+		const now = new Date()
+		const thread: Thread = {
+			id: generateThreadId(),
+			projectId: params.projectId,
+			tenantId,
+			title: params.title,
+			status: 'open',
+			ownerVersion: 0,
+			createdAt: now,
+			updatedAt: now,
+		}
+		const dir = join(this.rootDir, 'projects', params.projectId, 'threads', thread.id)
+		await mkdir(dir, { recursive: true })
+		await atomicWriteJson(join(dir, 'thread.json'), serializeThread(thread))
+		this.threadIndex.set(thread.id, {
+			threadId: thread.id,
+			projectId: params.projectId,
+			path: dir,
+		})
+		return thread
+	}
+
+	async getThread(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
+		const located = await this.locateThread(threadId)
+		if (!located) return null
+		const raw = await readJson<PersistedThread>(join(located.path, 'thread.json'))
+		if (!raw) return null
+		this.assertTenant(raw.tenantId, tenantId, `thread(${threadId})`)
+		return deserializeThread(raw)
+	}
+
+	async updateThread(thread: Thread, tenantId: TenantId): Promise<void> {
+		if (thread.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `thread(${thread.id}) payload`,
+			})
+		}
+		const located = await this.locateThread(thread.id)
+		if (!located) {
+			throw new Error(`Thread ${thread.id} not found`)
+		}
+		const existing = await readJson<PersistedThread>(join(located.path, 'thread.json'))
+		if (!existing) {
+			throw new Error(`Thread ${thread.id} not found`)
+		}
+		this.assertTenant(existing.tenantId, tenantId, `thread(${thread.id})`)
+
+		// CAS on ownerVersion. On mismatch, caller must re-read + re-apply +
+		// retry. No silent overwrite (Convention #0).
+		if (thread.ownerVersion !== existing.ownerVersion) {
+			throw new StaleThreadError({
+				threadId: thread.id,
+				expectedVersion: thread.ownerVersion,
+				actualVersion: existing.ownerVersion,
+			})
+		}
+
+		const updated: Thread = {
+			...thread,
+			ownerVersion: existing.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		await atomicWriteJson(join(located.path, 'thread.json'), serializeThread(updated))
+	}
+
+	async deleteThread(threadId: ThreadId, tenantId: TenantId): Promise<void> {
+		const located = await this.locateThread(threadId)
+		if (!located) return // Idempotent: missing = no-op.
+		const existing = await readJson<PersistedThread>(join(located.path, 'thread.json'))
+		if (!existing) return
+		this.assertTenant(existing.tenantId, tenantId, `thread(${threadId})`)
+
+		// The store does NOT enforce "no attached sessions" here — that is a
+		// cross-store precondition owned by ThreadManager. This keeps the
+		// boundary clean; ThreadStore has no awareness of SessionStore layout.
+		await rm(located.path, { recursive: true, force: true })
+		this.threadIndex.delete(threadId)
+	}
+
+	async listThreads(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
+		const threadsDir = join(this.rootDir, 'projects', projectId, 'threads')
+		let entries: string[]
+		try {
+			entries = await readdir(threadsDir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return []
+			throw err
+		}
+
+		const results: Thread[] = []
+		for (const entry of entries) {
+			if (!entry.startsWith('thd_')) continue
+			const path = join(threadsDir, entry)
+			const raw = await readJson<PersistedThread>(join(path, 'thread.json'))
+			if (!raw) continue
+			// Cross-tenant records in the same directory are skipped silently —
+			// the listing is scoped to the caller's tenant. Mismatch is not an
+			// isolation violation because the caller never requested the record.
+			if (raw.tenantId !== tenantId) continue
+			results.push(deserializeThread(raw))
+			this.threadIndex.set(raw.id, { threadId: raw.id, projectId, path })
+		}
+		results.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return results
+	}
+
+	private async locateThread(threadId: ThreadId): Promise<ThreadIndexEntry | null> {
+		const cached = this.threadIndex.get(threadId)
+		if (cached) return cached
+
+		// Walk projects/* looking for the thread dir. Cost is bounded by number
+		// of projects (usually 1) × number of threads per project.
+		const projectsDir = join(this.rootDir, 'projects')
+		let projectDirs: string[]
+		try {
+			projectDirs = await readdir(projectsDir)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return null
+			throw err
+		}
+
+		for (const rawProject of projectDirs) {
+			if (!rawProject.startsWith('prj_')) continue
+			const threadPath = join(projectsDir, rawProject, 'threads', threadId)
+			const raw = await readJson<PersistedThread>(join(threadPath, 'thread.json'))
+			if (raw?.id === threadId) {
+				const entry: ThreadIndexEntry = {
+					threadId,
+					projectId: rawProject as ProjectId,
+					path: threadPath,
+				}
+				this.threadIndex.set(threadId, entry)
+				return entry
+			}
+		}
+		return null
+	}
+
+	private assertTenant(owning: TenantId, requested: TenantId, resource: string): void {
+		if (owning !== requested) {
+			throw new TenantIsolationError({ requested, resource })
+		}
+	}
+}
+
+// Serialization -----------------------------------------------------------
+
+function serializeThread(thread: Thread): PersistedThread {
+	return {
+		id: thread.id,
+		projectId: thread.projectId,
+		tenantId: thread.tenantId,
+		title: thread.title,
+		status: thread.status,
+		ownerVersion: thread.ownerVersion,
+		createdAt: thread.createdAt.toISOString(),
+		updatedAt: thread.updatedAt.toISOString(),
+	}
+}
+
+function deserializeThread(raw: PersistedThread): Thread {
+	return {
+		id: raw.id,
+		projectId: raw.projectId,
+		tenantId: raw.tenantId,
+		title: raw.title,
+		status: raw.status,
+		ownerVersion: raw.ownerVersion,
+		createdAt: new Date(raw.createdAt),
+		updatedAt: new Date(raw.updatedAt),
+	}
+}
+
+// FS helpers -----------------------------------------------------------------
+
+async function readJson<T>(path: string): Promise<T | null> {
+	try {
+		const raw = await readFile(path, 'utf-8')
+		return JSON.parse(raw) as T
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code
+		if (code === 'ENOENT') return null
+		throw err
+	}
+}
+
+async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
+	const tempPath = `${filePath}.tmp`
+	try {
+		await writeFile(tempPath, JSON.stringify(value, null, 2), 'utf-8')
+		await rename(tempPath, filePath)
+	} catch (err) {
+		await unlink(tempPath).catch(() => undefined)
+		throw err
+	}
+}

package/src/store/thread/index.ts

@@ -0,0 +1,7 @@
+// Sub-barrel for the Thread persistence module (Convention #4).
+// Concrete implementations live in sibling files; re-export them here so
+// consumers import via `../store/thread/index.js`.
+
+export { InMemoryThreadStore } from './memory.js'
+export { DiskThreadStore } from './disk.js'
+export type { DiskThreadStoreConfig } from './disk.js'

package/src/store/thread/memory.ts

@@ -0,0 +1,104 @@
+/**
+ * InMemoryThreadStore — reference in-memory implementation of
+ * {@link ThreadStore}.
+ *
+ * Mirrors the write-time CAS contract of the disk store: every
+ * `updateThread` compares the supplied `ownerVersion` against the persisted
+ * copy and rejects with `StaleThreadError` on mismatch. Convention #17:
+ * cross-tenant access throws `TenantIsolationError` with no fallback.
+ */
+
+import { StaleThreadError, TenantIsolationError } from '../../session/errors.js'
+import type { Thread } from '../../session/hierarchy/thread.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
+import { generateThreadId } from '../../utils/id.js'
+
+interface ThreadRecord {
+	tenantId: TenantId
+	thread: Thread
+}
+
+export class InMemoryThreadStore implements ThreadStore {
+	private readonly threads = new Map<ThreadId, ThreadRecord>()
+
+	async createThread(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
+		const now = new Date()
+		const thread: Thread = {
+			id: generateThreadId(),
+			projectId: params.projectId,
+			tenantId,
+			title: params.title,
+			status: 'open',
+			ownerVersion: 0,
+			createdAt: now,
+			updatedAt: now,
+		}
+		this.threads.set(thread.id, { tenantId, thread })
+		return thread
+	}
+
+	async getThread(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
+		const record = this.threads.get(threadId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `thread(${threadId})`)
+		return record.thread
+	}
+
+	async updateThread(thread: Thread, tenantId: TenantId): Promise<void> {
+		if (thread.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `thread(${thread.id}) payload`,
+			})
+		}
+		const existing = this.threads.get(thread.id)
+		if (!existing) {
+			throw new Error(`Thread ${thread.id} not found`)
+		}
+		this.assertTenant(existing.tenantId, tenantId, `thread(${thread.id})`)
+
+		// CAS on ownerVersion — supplied version must match persisted exactly.
+		// Any drift means another writer already advanced the record; the caller
+		// must re-read + re-apply + retry.
+		if (thread.ownerVersion !== existing.thread.ownerVersion) {
+			throw new StaleThreadError({
+				threadId: thread.id,
+				expectedVersion: thread.ownerVersion,
+				actualVersion: existing.thread.ownerVersion,
+			})
+		}
+
+		const updated: Thread = {
+			...thread,
+			ownerVersion: existing.thread.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		this.threads.set(thread.id, { tenantId, thread: updated })
+	}
+
+	async deleteThread(threadId: ThreadId, tenantId: TenantId): Promise<void> {
+		const record = this.threads.get(threadId)
+		if (!record) return // Idempotent: missing = no-op.
+		this.assertTenant(record.tenantId, tenantId, `thread(${threadId})`)
+		this.threads.delete(threadId)
+	}
+
+	async listThreads(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
+		const matches: Thread[] = []
+		for (const { tenantId: ownerTenant, thread } of this.threads.values()) {
+			if (ownerTenant !== tenantId) continue
+			if (thread.projectId !== projectId) continue
+			matches.push(thread)
+		}
+		matches.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+		return matches
+	}
+
+	private assertTenant(owning: TenantId, requested: TenantId, resource: string): void {
+		if (owning !== requested) {
+			throw new TenantIsolationError({ requested, resource })
+		}
+	}
+}

package/src/telemetry/runtime-accessors.ts

@@ -0,0 +1,19 @@
+// SDK-internal tracer/meter readers. Not re-exported by the root barrel.
+//
+// These wrap `@opentelemetry/api` globals so SDK internal call sites
+// (runtime/query, runtime/query/iteration, registry/tool/execute) have a
+// single place to resolve the active tracer/meter. When `@namzu/telemetry`
+// is registered, its `registerTelemetry()` mutates the api globals and
+// these readers pick up the real providers; without registration, they
+// return the no-op defaults and every span/meter write is silently
+// discarded — standard OTEL library behavior.
+
+import { type Meter, type Tracer, metrics, trace } from '@opentelemetry/api'
+
+export function getTracer(): Tracer {
+	return trace.getTracer('namzu')
+}
+
+export function getMeter(): Meter {
+	return metrics.getMeter('namzu')
+}

package/src/types/agent/base.ts

@@ -1,10 +1,10 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
-import type { RunId, SessionId, TenantId, ThreadId } from '../ids/index.js'
+import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { StopReason } from '../run/stop-reason.js'
-import type { ProjectId } from '../session/ids.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -24,29 +24,25 @@ export interface BaseAgentConfig {
 	env?: Record<string, string>
 
 	/**
-	 * @deprecated Use `projectId`. Kept as a migration-window mirror; when both
-	 * are present `projectId` wins. See session-hierarchy.md §13.1.
+	 * Long-lived goal scope for the run. Required at runtime — agents reject
+	 * configs missing this (`'X requires sessionId, projectId, and tenantId
+	 * in config'`).
+	 *
+	 * Kept optional at the TYPE level because {@link AgentManager} stamps
+	 * this field AFTER `configBuilder` returns (manager/agent/lifecycle.ts).
+	 * Tightening to required is a separate task alongside
+	 * `AgentFactoryOptions` carrying the triple.
 	 */
-	threadId?: ThreadId
+	projectId?: ProjectId
 
 	/**
-	 * Long-lived goal scope for the run. Required at runtime in 0.2.0 per
-	 * session-hierarchy.md §12.1 — `{@link ReactiveAgent}`, `{@link
-	 * SupervisorAgent}`, etc. reject configs missing this (`'X requires
-	 * sessionId, projectId, and tenantId in config (§12.1)'`).
-	 *
-	 * Kept optional at the TYPE level during the 0.2.x migration window
-	 * because {@link AgentManager} stamps this field AFTER `configBuilder`
-	 * returns (manager/agent/lifecycle.ts:228–230). That stamping path is
-	 * how every `@namzu/agents` configBuilder currently gets its tenant /
-	 * session / project triple; flipping the type to required without first
-	 * updating every {@link AgentFactoryOptions} consumer (which does not
-	 * carry these fields) would be a gratuitous downstream break.
-	 *
-	 * Tightening to required is Phase 9 Known Delta #6. The type-level flip
-	 * lands in 0.3.0 alongside `AgentFactoryOptions` gaining the triple.
+	 * Topic the run belongs to. Optional at the TYPE level for the same
+	 * reason as `projectId` — {@link AgentManager} stamps this field after
+	 * `configBuilder` returns so `configBuilder` implementations do not
+	 * need to be updated before this tightens. Tightening to required
+	 * lands with the `AgentFactoryOptions` triple refactor.
 	 */
-	projectId?: ProjectId
+	threadId?: ThreadId
 
 	/** Session under which the run executes. See `projectId` for the tightening plan. */
 	sessionId?: SessionId

package/src/types/agent/factory.ts

@@ -14,7 +14,14 @@ export interface AgentDefinition {
 }
 
 export interface AgentFactoryOptions {
-	apiKey: string
+	/**
+	 * API key for providers that authenticate via key (OpenAI, Anthropic,
+	 * OpenRouter). Optional because BYO-provider flows (Bedrock IAM, custom
+	 * `ProviderRegistry.create(...)`) resolve credentials outside this object.
+	 * `configBuilder` implementations should treat an absent `apiKey` as the
+	 * BYO signal and use the provider passed via the agent config instead.
+	 */
+	apiKey?: string
 	model?: string
 	workingDirectory?: string
 	tokenBudget?: number
@@ -39,8 +46,6 @@ export interface AgentFactoryOptions {
 
 	taskRouter?: TaskRouterConfig
 
-	threadId?: string
-
 	runId?: string
 
 	parentRunId?: string

package/src/types/agent/task.ts

@@ -4,7 +4,7 @@ import type { TokenUsage } from '../common/index.js'
 import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { RunEventListener } from '../run/events.js'
-import type { ProjectId } from '../session/ids.js'
+import type { ProjectId, ThreadId } from '../session/ids.js'
 import type { AgentInput, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { Agent } from './core.js'
 import type { AgentFactoryOptions } from './factory.js'
@@ -23,15 +23,10 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 }
 
 /**
- * Context carried into {@link AgentManager.sendMessage}. Phase 6 promotes
- * `tenantId`, `sessionId`, `projectId`, and `parentActor` to required fields —
- * the spawn path is the ingress point for the session hierarchy; callers must
- * provide the full scoping set (session-hierarchy.md §12.1 required-callsite
- * matrix).
- *
- * `threadId` was removed — `projectId` owns the root scope. The deprecated
- * alias `type ThreadId = ProjectId` still compiles for consumers transitioning
- * off the name, but the shape no longer exposes a separate slot.
+ * Context carried into {@link AgentManager.sendMessage}. `tenantId`,
+ * `threadId`, `sessionId`, `projectId`, and `parentActor` are required —
+ * the spawn path is the ingress point for the session hierarchy; callers
+ * must provide the full scoping set.
  */
 export interface AgentTaskContext {
 	parentRunId: RunId
@@ -49,13 +44,26 @@ export interface AgentTaskContext {
 	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
 	tenantId: TenantId
 
+	/**
+	 * Topic the current task belongs to. Required in 0.3.0 — spawn copies
+	 * this onto the child session without a second ThreadStore round-trip,
+	 * and gates creation on {@link ThreadManager.requireOpen}. Children
+	 * inherit the parent's `threadId` verbatim; cross-thread spawn is
+	 * forbidden by design (a delegated sub-agent stays on the same topic).
+	 */
+	threadId: ThreadId
+
 	/**
 	 * Parent session under which any sub-agent spawn is recorded. Required
 	 * in 0.2.0; a spawn cannot be attributed without it.
 	 */
 	sessionId: SessionId
 
-	/** Long-lived goal scope (replaces `threadId`). Required. */
+	/**
+	 * Long-lived goal scope. Required. Denormalized from the owning Thread
+	 * (see {@link Thread}) — structurally immutable per Phase 2.4 decision
+	 * (sessions never cross threads, threads never cross projects).
+	 */
 	projectId: ProjectId
 
 	/**