@namzu/sdk 0.1.8 → 0.2.0

package/src/session/workspace/index.ts

@@ -0,0 +1,25 @@
+// Sub-barrel for the workspace module (Convention #4).
+// Concrete types + driver implementation live in sibling files; re-export
+// them here so other modules import via `../session/workspace/index.js`.
+
+export type {
+	WorkspaceRef,
+	WorkspaceBackendMeta,
+	WorkspaceBackendKind,
+	GitWorktreeBackendMeta,
+} from './ref.js'
+
+export type {
+	WorkspaceBackendDriver,
+	CreateWorkspaceParams,
+	BranchWorkspaceParams,
+	WorkspaceInspection,
+} from './driver.js'
+
+export { DefaultPathBuilder } from './path-builder.js'
+export type { PathBuilder } from './path-builder.js'
+
+export { WorkspaceBackendRegistry } from './registry.js'
+
+export { GitWorktreeDriver, parseWorktreeList } from './git-worktree.js'
+export type { ExecFile, ExecFileResult, GitWorktreeDriverConfig } from './git-worktree.js'

package/src/session/workspace/path-builder.ts

@@ -0,0 +1,71 @@
+/**
+ * PathBuilder — canonical filesystem layout generator for the session
+ * hierarchy.
+ *
+ * Replaces the hardcoded `.namzu/threads/{threadId}/runs` path at
+ * `runtime/query/context.ts:60-64`. Phase 3 ships the abstraction; wiring
+ * into the factory happens in Phase 6 (sub-session spawn refactor) so the
+ * cutover is atomic with the new `projectId` / `sessionId` requirements
+ * (Convention #0: no dual paths).
+ *
+ * Layout matches session-hierarchy.md §13.4 (on-disk layout after migration):
+ *
+ *   {rootDir}/projects/{projectId}/
+ *     project.json
+ *     sessions/{sessionId}/
+ *       session.json
+ *       messages.jsonl
+ *       subsessions/{subSessionId}/
+ *         subsession.json
+ *       runs/{runId}/
+ *         ...  (Run-pattern owned; unchanged internally)
+ */
+
+import { join } from 'node:path'
+import type { ProjectId, RunId, SessionId } from '../../types/ids/index.js'
+import type { SubSessionId } from '../../types/session/ids.js'
+
+/**
+ * Canonical filesystem layout contract. All paths returned are absolute
+ * when `root` is absolute (recommended); consumers treat them as opaque.
+ */
+export interface PathBuilder {
+	rootDir(): string
+	projectDir(projectId: ProjectId): string
+	sessionDir(projectId: ProjectId, sessionId: SessionId): string
+	subSessionDir(projectId: ProjectId, sessionId: SessionId, subSessionId: SubSessionId): string
+	runDir(projectId: ProjectId, sessionId: SessionId, runId: RunId): string
+}
+
+/**
+ * Default implementation over `node:path.join`. The `root` constructor
+ * argument is injected by the consumer (e.g. `join(cwd, '.namzu')`); no
+ * process-global fallback — the kernel refuses to guess paths.
+ */
+export class DefaultPathBuilder implements PathBuilder {
+	private readonly root: string
+
+	constructor(root: string) {
+		this.root = root
+	}
+
+	rootDir(): string {
+		return this.root
+	}
+
+	projectDir(projectId: ProjectId): string {
+		return join(this.root, 'projects', projectId)
+	}
+
+	sessionDir(projectId: ProjectId, sessionId: SessionId): string {
+		return join(this.projectDir(projectId), 'sessions', sessionId)
+	}
+
+	subSessionDir(projectId: ProjectId, sessionId: SessionId, subSessionId: SubSessionId): string {
+		return join(this.sessionDir(projectId, sessionId), 'subsessions', subSessionId)
+	}
+
+	runDir(projectId: ProjectId, sessionId: SessionId, runId: RunId): string {
+		return join(this.sessionDir(projectId, sessionId), 'runs', runId)
+	}
+}

package/src/session/workspace/ref.ts

@@ -0,0 +1,50 @@
+/**
+ * WorkspaceRef + backend metadata.
+ *
+ * See session-hierarchy.md §4.9 (WorkspaceRef) and §7 (Workspace and
+ * Worktree). The `meta` field is a discriminated union on `backend` — Phase 3
+ * ships the `git-worktree` variant; `tmpfs`, `container`, and `shared` land
+ * in a later phase of the overall roadmap (post-MVP) without breaking
+ * existing consumers (Convention #6).
+ */
+
+import type { WorkspaceId } from '../../types/session/ids.js'
+
+/**
+ * Supported backend kinds. Additional variants are append-only; existing
+ * consumers switch with an `_exhaustive` never-guard and will fail to compile
+ * when the union grows — paired with the update at the discriminated
+ * {@link WorkspaceBackendMeta} site (Convention #6).
+ */
+export type WorkspaceBackendKind = 'git-worktree' | 'tmpfs' | 'container' | 'shared'
+
+/**
+ * Git-worktree backend metadata. Matches session-hierarchy.md §4.9 /§7.2.
+ */
+export interface GitWorktreeBackendMeta {
+	backend: 'git-worktree'
+	/** Absolute path to the canonical repo (`.git` directory). */
+	repoRoot: string
+	/** Branch / ref the worktree tracks. */
+	branch: string
+	/** Absolute path to the worktree directory. */
+	worktreePath: string
+}
+
+/**
+ * Discriminated union of backend-specific metadata. Only `git-worktree` is
+ * populated in Phase 3. Future variants (tmpfs, container, shared) must be
+ * added here and to every exhaustive consumer.
+ */
+export type WorkspaceBackendMeta = GitWorktreeBackendMeta
+
+/**
+ * Persisted ref to a provisioned workspace. Every {@link Session} with a
+ * running Run persists a {@link WorkspaceRef} so recovery after process
+ * restart is possible (session-hierarchy.md §7.1).
+ */
+export interface WorkspaceRef {
+	id: WorkspaceId
+	meta: WorkspaceBackendMeta
+	createdAt: Date
+}

package/src/session/workspace/registry.ts

@@ -0,0 +1,42 @@
+/**
+ * WorkspaceBackendRegistry — deny-by-default driver lookup.
+ *
+ * Convention #9 (Registry + Manager + Store): this is the Registry for
+ * {@link WorkspaceBackendDriver} implementations. Unknown kinds throw
+ * — no silent fallback (Convention #5).
+ */
+
+import type { WorkspaceBackendDriver, WorkspaceBackendKind } from './driver.js'
+
+export class WorkspaceBackendRegistry {
+	private readonly drivers = new Map<WorkspaceBackendKind, WorkspaceBackendDriver>()
+
+	/**
+	 * Registers a driver. A second registration for the same kind replaces the
+	 * previous entry (test ergonomics); production code should register each
+	 * backend exactly once at boot.
+	 */
+	register(driver: WorkspaceBackendDriver): void {
+		this.drivers.set(driver.kind, driver)
+	}
+
+	/**
+	 * Returns the driver for `kind`. Throws when no driver is registered —
+	 * deny-by-default per Convention #5; the caller must register every
+	 * backend their workload can reach before invoking this.
+	 */
+	get(kind: WorkspaceBackendKind): WorkspaceBackendDriver {
+		const driver = this.drivers.get(kind)
+		if (!driver) {
+			throw new Error(
+				`No WorkspaceBackendDriver registered for kind "${kind}". Register one before use.`,
+			)
+		}
+		return driver
+	}
+
+	/** True iff a driver for `kind` has been registered. */
+	has(kind: WorkspaceBackendKind): boolean {
+		return this.drivers.has(kind)
+	}
+}

package/src/store/conversation/memory.ts

@@ -1,3 +1,22 @@
+/**
+ * @deprecated Use `InMemorySessionStore` from
+ * `@namzu/sdk/store/session`. This class implements the deprecated
+ * `ConversationStore` contract (thread-scoped, no tenantId) and is kept
+ * for one migration window per session-hierarchy.md §13.1; it will be
+ * removed in 0.3.0.
+ *
+ * INTERPRETATION (Phase 3): the old class exposes helpers
+ * (`addUserMessage`, `createThread`, `hasThread`, `deleteThread`,
+ * `messageCount`, `clear`) that are not part of `ConversationStore` and
+ * whose signatures rely on `ThreadId` + `Message` without `TenantId`.
+ * Those signatures are structurally incompatible with the new
+ * `SessionStore` surface, so a strict alias re-export would lose API
+ * (roadmap §2 Phase 3 option (a)). We pick option (b) — retain the
+ * original class body verbatim with a deprecation banner — to preserve
+ * existing consumers during the migration window without polluting the
+ * new `InMemorySessionStore` with thread-scoped helpers.
+ */
+
 import { findSafeTrimIndex } from '../../compaction/dangling.js'
 import type { ConversationStore } from '../../types/conversation/index.js'
 import type { MessageId, RunId, ThreadId } from '../../types/ids/index.js'
@@ -27,6 +46,10 @@ export interface InMemoryConversationStoreConfig {
 	readonly maxMessages?: number
 }
 
+/**
+ * @deprecated See module banner. Use `InMemorySessionStore` from
+ * `@namzu/sdk/store/session`.
+ */
 export class InMemoryConversationStore implements ConversationStore {
 	private readonly threads = new Map<ThreadId, ConversationMessage[]>()
 	private readonly maxMessages: number

package/src/store/session/__tests__/disk.test.ts

@@ -0,0 +1,346 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { TenantIsolationError } from '../../../session/errors.js'
+import type { ActorRef } from '../../../session/hierarchy/actor.js'
+import type { AgentId, TenantId, UserId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import { DiskSessionStore } from '../disk.js'
+
+const tenantA = 'tnt_alpha' as TenantId
+const tenantB = 'tnt_beta' as TenantId
+
+function userActor(tenantId: TenantId): ActorRef {
+	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
+}
+
+function agentActor(tenantId: TenantId): ActorRef {
+	return { kind: 'agent', agentId: 'agt_a' as AgentId, tenantId }
+}
+
+async function seed(store: DiskSessionStore, tenantId: TenantId) {
+	const project = await store.createProject({ tenantId, name: 'p1' }, tenantId)
+	const session = await store.createSession(
+		{ projectId: project.id, currentActor: userActor(tenantId) },
+		tenantId,
+	)
+	return { project, session }
+}
+
+describe('DiskSessionStore', () => {
+	let rootDir: string
+	let store: DiskSessionStore
+
+	beforeEach(() => {
+		rootDir = mkdtempSync(join(tmpdir(), 'namzu-session-disk-'))
+		store = new DiskSessionStore({ rootDir })
+	})
+
+	afterEach(() => {
+		rmSync(rootDir, { recursive: true, force: true })
+	})
+
+	it('writes the canonical directory layout (projects/.../sessions/.../subsessions)', async () => {
+		const { project, session } = await seed(store, tenantA)
+		const child = await store.createSession(
+			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			tenantA,
+		)
+		const sub = await store.createSubSession(
+			{
+				parentSessionId: session.id,
+				childSessionId: child.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor(tenantA),
+			},
+			tenantA,
+		)
+
+		const projectJson = join(rootDir, 'projects', project.id, 'project.json')
+		const sessionJson = join(
+			rootDir,
+			'projects',
+			project.id,
+			'sessions',
+			session.id,
+			'session.json',
+		)
+		const subJson = join(
+			rootDir,
+			'projects',
+			project.id,
+			'sessions',
+			session.id,
+			'subsessions',
+			sub.id,
+			'subsession.json',
+		)
+		expect(JSON.parse(await readFile(projectJson, 'utf-8')).id).toBe(project.id)
+		expect(JSON.parse(await readFile(sessionJson, 'utf-8')).id).toBe(session.id)
+		expect(JSON.parse(await readFile(subJson, 'utf-8')).id).toBe(sub.id)
+	})
+
+	it('round-trips a session across store instances (cold read)', async () => {
+		const { project, session } = await seed(store, tenantA)
+
+		// Construct a fresh store against the same rootDir — must find the session.
+		const fresh = new DiskSessionStore({ rootDir })
+		const reloaded = await fresh.getSession(session.id, tenantA)
+		expect(reloaded).not.toBeNull()
+		expect(reloaded?.id).toBe(session.id)
+		expect(reloaded?.projectId).toBe(project.id)
+		expect(reloaded?.currentActor?.kind).toBe('user')
+	})
+
+	it('writes are atomic: no *.tmp file remains after mutation', async () => {
+		const { project, session } = await seed(store, tenantA)
+		await store.updateSession({ ...session, status: 'active' }, tenantA)
+
+		// Recursively list everything under rootDir and ensure no lingering .tmp
+		async function walk(dir: string, out: string[]): Promise<void> {
+			for (const entry of await readdir(dir, { withFileTypes: true })) {
+				const path = join(dir, entry.name)
+				out.push(path)
+				if (entry.isDirectory()) await walk(path, out)
+			}
+		}
+		const files: string[] = []
+		await walk(rootDir, files)
+		expect(files.some((p) => p.endsWith('.tmp'))).toBe(false)
+		expect(files).toContain(
+			join(rootDir, 'projects', project.id, 'sessions', session.id, 'session.json'),
+		)
+	})
+
+	it('rejects cross-tenant reads of persisted sessions', async () => {
+		const { session } = await seed(store, tenantA)
+		await expect(store.getSession(session.id, tenantB)).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('appendMessage + loadMessages round-trips via messages.jsonl', async () => {
+		const { project, session } = await seed(store, tenantA)
+		await store.appendMessage(session.id, createUserMessage('hello'), tenantA)
+		await store.appendMessage(session.id, createUserMessage('world'), tenantA)
+
+		const loaded = await store.loadMessages(session.id, tenantA)
+		expect(loaded.map((m) => m.content)).toEqual(['hello', 'world'])
+
+		const jsonl = await readFile(
+			join(rootDir, 'projects', project.id, 'sessions', session.id, 'messages.jsonl'),
+			'utf-8',
+		)
+		const lines = jsonl.split('\n').filter((l) => l.length > 0)
+		expect(lines).toHaveLength(2)
+	})
+
+	it('loadMessages returns [] when no messages yet persisted', async () => {
+		const { session } = await seed(store, tenantA)
+		expect(await store.loadMessages(session.id, tenantA)).toEqual([])
+	})
+
+	it('drill returns children and ancestry after a cold reload', async () => {
+		const { project, session: root } = await seed(store, tenantA)
+		const child = await store.createSession(
+			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			tenantA,
+		)
+		await store.createSubSession(
+			{
+				parentSessionId: root.id,
+				childSessionId: child.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor(tenantA),
+			},
+			tenantA,
+		)
+
+		const fresh = new DiskSessionStore({ rootDir })
+		const rootView = await fresh.drill(root.id, tenantA)
+		expect(rootView?.children.map((c) => c.childSessionId)).toEqual([child.id])
+
+		const childView = await fresh.drill(child.id, tenantA)
+		expect(childView?.ancestry).toEqual([root.id, child.id])
+	})
+
+	it('missing session returns null rather than throwing', async () => {
+		const fresh = new DiskSessionStore({ rootDir })
+		expect(await fresh.getSession('ses_missing' as SessionId, tenantA)).toBeNull()
+	})
+
+	// Summary (§4.7 / §8.1) ---------------------------------------------------
+
+	it('recordSummary persists summary.json and flips session status atomically', async () => {
+		const { project, session } = await seed(store, tenantA)
+		await store.updateSession({ ...session, status: 'active' }, tenantA)
+
+		const summary: SessionSummaryRef & { materializedBy: 'kernel' } = {
+			id: 'sum_disk1' as SummaryId,
+			sessionRef: session.id,
+			tenantId: tenantA,
+			outcome: { status: 'succeeded' },
+			deliverables: [],
+			agentSummary: 'done',
+			keyDecisions: [],
+			at: new Date('2026-04-17T00:00:00Z'),
+			materializedBy: 'kernel',
+		}
+		await store.recordSummary(summary, tenantA)
+
+		const summaryJson = join(
+			rootDir,
+			'projects',
+			project.id,
+			'sessions',
+			session.id,
+			'summary.json',
+		)
+		const rawSummary = JSON.parse(await readFile(summaryJson, 'utf-8'))
+		expect(rawSummary.id).toBe('sum_disk1')
+		expect(rawSummary.materializedBy).toBe('kernel')
+
+		const reloadedSession = await store.getSession(session.id, tenantA)
+		expect(reloadedSession?.status).toBe('idle')
+	})
+
+	it('recordSummary is idempotent when replaying the same summary (recovery)', async () => {
+		const { session } = await seed(store, tenantA)
+		await store.updateSession({ ...session, status: 'active' }, tenantA)
+
+		const summary: SessionSummaryRef & { materializedBy: 'kernel' } = {
+			id: 'sum_disk2' as SummaryId,
+			sessionRef: session.id,
+			tenantId: tenantA,
+			outcome: { status: 'succeeded' },
+			deliverables: [],
+			agentSummary: '',
+			keyDecisions: [],
+			at: new Date('2026-04-17T00:00:00Z'),
+			materializedBy: 'kernel',
+		}
+		await store.recordSummary(summary, tenantA)
+
+		// Force session back to active (simulating a crash mid-flip).
+		const mid = await store.getSession(session.id, tenantA)
+		if (!mid) throw new Error('mid session missing')
+		await store.updateSession({ ...mid, status: 'active' }, tenantA)
+
+		// Replay with the same summary — no throw, status flips again.
+		await store.recordSummary(summary, tenantA)
+		const after = await store.getSession(session.id, tenantA)
+		expect(after?.status).toBe('idle')
+	})
+
+	it('recordSummary rejects a different summary for an already-summarized session', async () => {
+		const { session } = await seed(store, tenantA)
+		const first: SessionSummaryRef & { materializedBy: 'kernel' } = {
+			id: 'sum_disk3a' as SummaryId,
+			sessionRef: session.id,
+			tenantId: tenantA,
+			outcome: { status: 'succeeded' },
+			deliverables: [],
+			agentSummary: '',
+			keyDecisions: [],
+			at: new Date(),
+			materializedBy: 'kernel',
+		}
+		await store.recordSummary(first, tenantA)
+
+		const second = { ...first, id: 'sum_disk3b' as SummaryId }
+		await expect(store.recordSummary(second, tenantA)).rejects.toMatchObject({
+			name: 'SessionAlreadySummarizedError',
+		})
+	})
+
+	it('deleteSession removes the session directory recursively', async () => {
+		const { project, session } = await seed(store, tenantA)
+		await store.appendMessage(session.id, createUserMessage('hi'), tenantA)
+
+		await store.deleteSession(session.id, tenantA)
+
+		const sessionDir = join(rootDir, 'projects', project.id, 'sessions', session.id)
+		// Directory should be gone.
+		const sessionsDirListing = await readdir(join(rootDir, 'projects', project.id, 'sessions'))
+		expect(sessionsDirListing).not.toContain(session.id)
+		// Session read returns null.
+		expect(await store.getSession(session.id, tenantA)).toBeNull()
+		// Path sanity: no ghost file at the session path.
+		void sessionDir
+	})
+
+	it('deleteSession tolerates missing session directory (idempotent)', async () => {
+		await expect(
+			store.deleteSession('ses_nonexistent' as SessionId, tenantA),
+		).resolves.toBeUndefined()
+	})
+
+	it('deleteSession rejects if sub-sessions are still attached', async () => {
+		const { project, session: root } = await seed(store, tenantA)
+		const child = await store.createSession(
+			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			tenantA,
+		)
+		await store.createSubSession(
+			{
+				parentSessionId: root.id,
+				childSessionId: child.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor(tenantA),
+			},
+			tenantA,
+		)
+
+		await expect(store.deleteSession(root.id, tenantA)).rejects.toThrow(/attached sub-sessions/)
+	})
+
+	it('deleteSubSession removes the sub-session directory and is idempotent', async () => {
+		const { project, session: root } = await seed(store, tenantA)
+		const child = await store.createSession(
+			{ projectId: project.id, currentActor: agentActor(tenantA) },
+			tenantA,
+		)
+		const sub = await store.createSubSession(
+			{
+				parentSessionId: root.id,
+				childSessionId: child.id,
+				kind: 'agent_spawn',
+				spawnedBy: userActor(tenantA),
+			},
+			tenantA,
+		)
+
+		await store.deleteSubSession(sub.id, tenantA)
+		expect(await store.getSubSession(sub.id, tenantA)).toBeNull()
+
+		const subsDir = join(rootDir, 'projects', project.id, 'sessions', root.id, 'subsessions')
+		const listing = await readdir(subsDir).catch(() => [] as string[])
+		expect(listing).not.toContain(sub.id)
+
+		// Idempotent.
+		await expect(store.deleteSubSession(sub.id, tenantA)).resolves.toBeUndefined()
+	})
+
+	it('getSummary rejects cross-tenant reads', async () => {
+		const { session } = await seed(store, tenantA)
+		const summary: SessionSummaryRef & { materializedBy: 'kernel' } = {
+			id: 'sum_disk4' as SummaryId,
+			sessionRef: session.id,
+			tenantId: tenantA,
+			outcome: { status: 'succeeded' },
+			deliverables: [],
+			agentSummary: '',
+			keyDecisions: [],
+			at: new Date(),
+			materializedBy: 'kernel',
+		}
+		await store.recordSummary(summary, tenantA)
+
+		await expect(store.getSummary(session.id, tenantB)).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+})
+
+import type { SessionSummaryRef } from '../../../session/summary/ref.js'
+// Import after use so tests are self-contained w.r.t. types we already use.
+import type { SessionId } from '../../../types/ids/index.js'
+import type { SummaryId } from '../../../types/session/ids.js'