@namzu/sdk 0.1.8 → 0.3.0

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/types/agent/base.ts

@@ -1,9 +1,10 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
-import type { RunId, 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, ThreadId } from '../session/ids.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -22,8 +23,33 @@ export interface BaseAgentConfig {
 	permissionMode?: PermissionMode
 	env?: Record<string, string>
 
+	/**
+	 * 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.
+	 */
+	projectId?: ProjectId
+
+	/**
+	 * 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.
+	 */
 	threadId?: ThreadId
 
+	/** Session under which the run executes. See `projectId` for the tightening plan. */
+	sessionId?: SessionId
+
+	/** Isolation boundary (Convention #17). See `projectId` for the tightening plan. */
+	tenantId?: TenantId
+
 	parentRunId?: RunId
 
 	depth?: number

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

@@ -1,7 +1,10 @@
+import type { ActorRef } from '../../session/hierarchy/actor.js'
+import type { WorkspaceBackendKind } from '../../session/workspace/ref.js'
 import type { TokenUsage } from '../common/index.js'
-import type { RunId, TaskId, ThreadId } from '../ids/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, 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'
@@ -19,6 +22,12 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 	return state === 'completed' || state === 'failed' || state === 'canceled' || state === 'rejected'
 }
 
+/**
+ * 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
 
@@ -32,7 +41,37 @@ export interface AgentTaskContext {
 
 	factoryOptions?: AgentFactoryOptions
 
-	threadId?: ThreadId
+	/** 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. 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
+
+	/**
+	 * The actor invoking this task. Children built off this context stamp
+	 * their own `parentActor: ActorRef` linking back via the actor chain
+	 * (session-hierarchy.md §4.3 / §10.4).
+	 */
+	parentActor: ActorRef
 }
 
 export interface AgentTaskBudget {
@@ -66,6 +105,12 @@ export interface AgentTaskProgress {
 	recentActivities: string[]
 }
 
+/**
+ * Options accepted by {@link AgentManager.sendMessage}. Phase 6 adds the
+ * required sub-session spawn scope (`parentSessionId`, `tenantId`, `projectId`,
+ * `parentActor`) so the manager can create a SubSession + child Session +
+ * WorkspaceRef triple atomically on every spawn.
+ */
 export interface SendMessageOptions {
 	agentId: string
 
@@ -77,6 +122,25 @@ export interface SendMessageOptions {
 		tokenBudget?: number
 		timeoutMs?: number
 	}
+
+	/**
+	 * Parent session under which the new sub-session is created. Capacity
+	 * validation (depth + width) is applied against this session.
+	 */
+	parentSessionId: SessionId
+
+	tenantId: TenantId
+
+	projectId: ProjectId
+
+	/** The actor requesting the spawn — seeds the child's `parentActor`. */
+	parentActor: ActorRef
+
+	/**
+	 * Workspace backend to provision for the child session. Defaults to
+	 * `git-worktree` — the MVP reference backend from Phase 3.
+	 */
+	workspaceBackend?: WorkspaceBackendKind
 }
 
 export interface AgentManagerConfig {

package/src/types/ids/index.ts

@@ -1,7 +1,6 @@
-export type ThreadId = `thd_${string}`
 export type RunId = `run_${string}`
 export type MessageId = `msg_${string}`
-export type SessionId = `sess_${string}`
+export type SessionId = `ses_${string}`
 export type ToolCallId = `call_${string}`
 export type ActivityId = `act_${string}`
 export type TaskId = `task_${string}`
@@ -11,7 +10,7 @@ export type DocumentId = `doc_${string}`
 export type ChunkId = `chk_${string}`
 export type ConnectorId = `conn_${string}`
 export type ConnectorInstanceId = `ci_${string}`
-export type TenantId = `ten_${string}`
+export type TenantId = `tnt_${string}`
 export type CredentialId = `cred_${string}`
 export type ExecutionContextId = `ectx_${string}`
 export type MCPServerId = `mcp_${string}`
@@ -26,3 +25,35 @@ export type EmergencySaveId = `esave_${string}`
 export type MemoryId = `mem_${string}`
 export type PluginId = `plg_${string}`
 export type SandboxId = `sbx_${string}`
+
+// Actor identifiers (Session Hierarchy §4.3). Branded so actor refs cannot be
+// constructed from bare strings.
+export type UserId = `usr_${string}`
+export type AgentId = `agt_${string}`
+
+// Shared-store placeholder refs (Session Hierarchy §4.2 / §3.2). Full shapes
+// land in later phases; kept here as opaque branded IDs so ProjectConfig can
+// reference them today.
+export type MemoryStoreRef = `mms_${string}`
+export type VaultRef = `vlt_${string}`
+export type KnowledgeBaseRef = `kbs_${string}`
+
+// Session hierarchy IDs. Convention #2 branded IDs; prefixes mandated by the
+// five-layer hierarchy (Project → Thread → Session → SubSession → Run). The
+// `types/session/ids.ts` barrel re-exports these for co-location ergonomics.
+export type ProjectId = `prj_${string}`
+export type ThreadId = `thd_${string}`
+export type SubSessionId = `sub_${string}`
+export type HandoffId = `hof_${string}`
+export type WorkspaceId = `wsp_${string}`
+export type SummaryId = `sum_${string}`
+export type DeliverableId = `del_${string}`
+
+/**
+ * Sentinel {@link TenantId} for legacy pre-0.2.0 runs rehomed by the
+ * boot-time filesystem migration. Consumers with strict tenant enforcement
+ * should either tag these records on first access or reject them until a
+ * real tenant is assigned — the kernel surfaces the sentinel but does not
+ * prescribe policy (Convention #17).
+ */
+export const UNKNOWN_TENANT_ID = 'tnt_unknown_legacy' as TenantId