@namzu/sdk 0.1.8 → 0.3.0

package/src/runtime/query/__tests__/context.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest'
+import { DefaultPathBuilder, type PathBuilder } from '../../../session/workspace/path-builder.js'
+import type { RunId, SessionId, TenantId } from '../../../types/ids/index.js'
+import type { LLMProvider } from '../../../types/provider/index.js'
+import type { AgentRunConfig } from '../../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { RunContextFactory } from '../context.js'
+
+function mockProvider(): LLMProvider {
+	return {
+		id: 'mock',
+		supports: () => true,
+		chat: async () => ({ message: { role: 'assistant', content: '' } }),
+	} as unknown as LLMProvider
+}
+
+function buildConfig(overrides: Partial<Parameters<typeof RunContextFactory.build>[0]> = {}) {
+	const sessionId = 'ses_test' as SessionId
+	const threadId = 'thd_test' as ThreadId
+	const projectId = 'prj_test' as ProjectId
+	const tenantId = 'tnt_test' as TenantId
+	const runConfig: AgentRunConfig = {
+		model: 'test',
+		tokenBudget: 1_000,
+		timeoutMs: 5_000,
+	}
+
+	return {
+		agentId: 'agent-1',
+		agentName: 'agent-1',
+		runConfig,
+		provider: mockProvider(),
+		messages: [],
+		sessionId,
+		threadId,
+		projectId,
+		tenantId,
+		workingDirectory: '/tmp/run-context-test',
+		...overrides,
+	}
+}
+
+describe('RunContextFactory.build', () => {
+	it('requires sessionId, threadId, projectId, tenantId and returns them on the context', () => {
+		const cfg = buildConfig()
+		const ctx = RunContextFactory.build(cfg)
+
+		expect(ctx.sessionId).toBe(cfg.sessionId)
+		expect(ctx.threadId).toBe(cfg.threadId)
+		expect(ctx.projectId).toBe(cfg.projectId)
+		expect(ctx.tenantId).toBe(cfg.tenantId)
+	})
+
+	it('uses the injected PathBuilder to resolve the output dir (no hardcoded .namzu/threads)', () => {
+		const pathBuilderMock: PathBuilder = {
+			rootDir: vi.fn(() => '/mock/root'),
+			projectDir: vi.fn((pid) => `/mock/root/projects/${pid}`),
+			sessionDir: vi.fn((pid, sid) => `/mock/root/projects/${pid}/sessions/${sid}`),
+			subSessionDir: vi.fn(),
+			runDir: vi.fn(),
+		}
+
+		const cfg = buildConfig({ pathBuilder: pathBuilderMock })
+		const ctx = RunContextFactory.build(cfg)
+
+		expect(pathBuilderMock.sessionDir).toHaveBeenCalledWith(cfg.projectId, cfg.sessionId)
+		expect(ctx.outputDir).toBe(`/mock/root/projects/${cfg.projectId}/sessions/${cfg.sessionId}`)
+		// Legacy hardcoded path must not leak.
+		expect(ctx.outputDir).not.toContain('.namzu/threads')
+	})
+
+	it('falls back to DefaultPathBuilder rooted at {cwd}/.namzu when no pathBuilder is provided', () => {
+		const cfg = buildConfig()
+		const ctx = RunContextFactory.build(cfg)
+
+		// Layout lives under projects/{pid}/sessions/{sid} — no `.namzu/threads/`.
+		expect(ctx.outputDir).toContain('/.namzu/projects/prj_test/sessions/ses_test')
+		expect(ctx.outputDir).not.toContain('threads')
+	})
+
+	it('seeds RunPersistence with propagated sessionId/threadId/tenantId/projectId', () => {
+		const cfg = buildConfig()
+		const ctx = RunContextFactory.build(cfg)
+
+		expect(ctx.runMgr.sessionId).toBe(cfg.sessionId)
+		expect(ctx.runMgr.threadId).toBe(cfg.threadId)
+		expect(ctx.runMgr.tenantId).toBe(cfg.tenantId)
+		expect(ctx.runMgr.projectId).toBe(cfg.projectId)
+	})
+
+	it('reuses the runId supplied by the caller', () => {
+		const runId = 'run_fixed' as RunId
+		const ctx = RunContextFactory.build(buildConfig({ runId }))
+		expect(ctx.runId).toBe(runId)
+	})
+
+	it('DefaultPathBuilder lays out runs under sessions/{sessionId}/runs', () => {
+		const builder = new DefaultPathBuilder('/base/.namzu')
+		const runDir = builder.runDir('prj_x' as ProjectId, 'ses_y' as SessionId, 'run_z' as RunId)
+		expect(runDir).toBe('/base/.namzu/projects/prj_x/sessions/ses_y/runs/run_z')
+	})
+})

package/src/runtime/query/context-cache.ts

@@ -1,14 +1,14 @@
 import { createHash } from 'node:crypto'
 import type { AgentContextLevel } from '../../types/agent/factory.js'
-import type { ThreadId } from '../../types/ids/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
+import type { ProjectId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
 import { PromptBuilder, type PromptSegments } from './prompt.js'
 
 export interface ContextCacheConfig {
 	agentId: string
-	threadId: ThreadId
+	projectId: ProjectId
 }
 
 export interface PromptCacheInput {
@@ -21,7 +21,7 @@ export interface PromptCacheInput {
 }
 
 export class ContextCache {
-	readonly threadId: ThreadId
+	readonly projectId: ProjectId
 	readonly agentId: string
 
 	private cachedPrompt: string | undefined
@@ -30,7 +30,7 @@ export class ContextCache {
 	private cachedStaticHash: string | undefined
 
 	constructor(config: ContextCacheConfig) {
-		this.threadId = config.threadId
+		this.projectId = config.projectId
 		this.agentId = config.agentId
 	}
 

package/src/runtime/query/context.ts

@@ -1,17 +1,42 @@
 import { join } from 'node:path'
 import { PlanManager } from '../../manager/plan/lifecycle.js'
 import { RunPersistence } from '../../manager/run/persistence.js'
+import {
+	DefaultFilesystemMigrator,
+	type FilesystemMigrationResult,
+	type FilesystemMigrationSink,
+	type FilesystemMigrator,
+	NOOP_FILESYSTEM_MIGRATION_SINK,
+} from '../../session/migration/index.js'
+import { DefaultPathBuilder, type PathBuilder } from '../../session/workspace/path-builder.js'
 import { ActivityStore } from '../../store/activity/memory.js'
 import { type ActivityTrackingConfig, resolveActivityTracking } from '../../types/activity/index.js'
-import type { RunId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { LLMProvider } from '../../types/provider/index.js'
 import type { AgentRunConfig } from '../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { generateRunId } from '../../utils/id.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
 
+/**
+ * Config accepted by {@link RunContextFactory.build}. `sessionId`,
+ * `threadId`, `projectId`, and `tenantId` are required — runs carry the full
+ * five-layer scope (Tenant → Project → Thread → Session → Run) per
+ * Convention #17.
+ *
+ * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
+ * constructed against `{workingDirectory}/.namzu`.
+ *
+ * `filesystemMigrator` + `migrationSink` are optional; when absent a
+ * {@link DefaultFilesystemMigrator} wired to the
+ * {@link NOOP_FILESYSTEM_MIGRATION_SINK} is used. Migration runs once per
+ * process via {@link RunContextFactory.ensureMigrated}; the static `build`
+ * method stays synchronous so existing call sites are not broken — async
+ * callers (e.g. `query()`) invoke `ensureMigrated` themselves before build.
+ */
 export interface RunContextConfig {
 	agentId: string
 	agentName: string
@@ -23,7 +48,22 @@ export interface RunContextConfig {
 	messages: Message[]
 	signal?: AbortSignal
 
+	sessionId: SessionId
 	threadId: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
+
+	pathBuilder?: PathBuilder
+
+	/**
+	 * Optional injected migrator — tests pass a stub; production code relies
+	 * on the {@link DefaultFilesystemMigrator}. See session-hierarchy.md
+	 * §13.4.1.
+	 */
+	filesystemMigrator?: FilesystemMigrator
+
+	/** Optional sink for `filesystem.migrated` events. Defaults to no-op. */
+	migrationSink?: FilesystemMigrationSink
 
 	runId?: RunId
 
@@ -32,9 +72,13 @@ export interface RunContextConfig {
 	depth?: number
 }
 
+/** Result of {@link RunContextFactory.build}. */
 export interface RunContext {
 	runId: RunId
+	sessionId: SessionId
 	threadId: ThreadId
+	projectId: ProjectId
+	tenantId: TenantId
 	runMgr: RunPersistence
 	activityStore: ActivityStore
 	planManager: PlanManager
@@ -46,7 +90,44 @@ export interface RunContext {
 	trackingConfig: ActivityTrackingConfig
 }
 
+/**
+ * Module-level first-call guard for the boot-time filesystem migration
+ * (session-hierarchy.md §13.4.1). Keyed on the root directory so a single
+ * process that spans multiple `.namzu` roots (unusual but legal) migrates
+ * each one once. Subsequent calls short-circuit via the cached promise —
+ * never re-reading the on-disk marker per call.
+ */
+const migrationPromises = new Map<string, Promise<FilesystemMigrationResult>>()
+
+/** Testing hook — clears the first-call guard cache. */
+export function __resetMigrationGuardForTests(): void {
+	migrationPromises.clear()
+}
+
 export class RunContextFactory {
+	/**
+	 * Run the boot-time filesystem migration for `rootDir` at most once per
+	 * process. Safe to `await` from any async entry point; concurrent callers
+	 * for the same root share a single migration promise (no duplicate work,
+	 * no race with the on-disk `.tmp` lock).
+	 */
+	static ensureMigrated(
+		rootDir: string,
+		migrator: FilesystemMigrator = new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK),
+	): Promise<FilesystemMigrationResult> {
+		const cached = migrationPromises.get(rootDir)
+		if (cached) return cached
+		const promise = migrator.migrate(rootDir)
+		migrationPromises.set(rootDir, promise)
+		// Crash-safety: if the migration rejects, drop the cached promise so
+		// the next caller gets a fresh attempt. Successful results stay cached
+		// (idempotency — further calls short-circuit without re-running).
+		promise.catch(() => {
+			migrationPromises.delete(rootDir)
+		})
+		return promise
+	}
+
 	static build(config: RunContextConfig): RunContext {
 		const abortController = new AbortController()
 		if (config.signal) {
@@ -57,17 +138,18 @@ export class RunContextFactory {
 		const permissionMode = config.runConfig.permissionMode ?? 'auto'
 		const runId = config.runId ?? generateRunId()
 
-		if (!config.threadId) {
-			throw new Error('threadId is required for run persistence — all runs must belong to a thread')
-		}
-		const threadId: ThreadId = config.threadId
-		const outputDir = join(cwd, '.namzu', 'threads', threadId, 'runs')
+		const pathBuilder = config.pathBuilder ?? new DefaultPathBuilder(join(cwd, '.namzu'))
+		const outputDir = pathBuilder.sessionDir(config.projectId, config.sessionId)
+		const runsDir = join(outputDir, 'runs')
 
 		const log = getRootLogger().child({
 			component: 'query',
 			agent: config.agentName,
 			runId,
-			threadId,
+			sessionId: config.sessionId,
+			threadId: config.threadId,
+			projectId: config.projectId,
+			tenantId: config.tenantId,
 		})
 
 		const runMgr = new RunPersistence({
@@ -76,9 +158,13 @@ export class RunContextFactory {
 			agentName: config.agentName,
 			runConfig: config.runConfig,
 			providerId: config.provider.id,
-			outputDir,
+			outputDir: runsDir,
 			pricing: config.pricing,
 			log,
+			sessionId: config.sessionId,
+			threadId: config.threadId,
+			tenantId: config.tenantId,
+			projectId: config.projectId,
 			parentRunId: config.parentRunId,
 			depth: config.depth,
 		})
@@ -89,7 +175,10 @@ export class RunContextFactory {
 
 		return {
 			runId,
-			threadId,
+			sessionId: config.sessionId,
+			threadId: config.threadId,
+			projectId: config.projectId,
+			tenantId: config.tenantId,
 			runMgr,
 			activityStore,
 			planManager,

package/src/runtime/query/events.ts

@@ -80,6 +80,10 @@ export class EventTranslator {
 					})
 					break
 				default: {
+					// `TaskEvent.type` is scoped to task-store events; sub-session
+					// lifecycle events (subsession_spawned / _messaged / _idled) and
+					// run-scoped `RunEvent` variants never reach this wrapper. The
+					// exhaustiveness guard below enforces that at compile time.
 					const _exhaustive: never = event.type
 					throw new Error(`Unhandled task event type: ${_exhaustive}`)
 				}
@@ -134,6 +138,10 @@ export class EventTranslator {
 				case 'plan.failed':
 					break
 				default: {
+					// `PlanEvent.type` is scoped to plan-manager events; sub-session
+					// lifecycle events and other `RunEvent` variants never reach this
+					// wrapper. The exhaustiveness guard below enforces that at compile
+					// time.
 					const _exhaustive: never = event.type
 					throw new Error(`Unhandled plan event type: ${_exhaustive}`)
 				}

package/src/runtime/query/index.ts

@@ -8,6 +8,7 @@ import { extractFromUserMessage } from '../../compaction/extractor.js'
 import { WorkingStateManager } from '../../compaction/manager.js'
 import type { CompactionConfig } from '../../config/runtime.js'
 import { getTracer } from '../../provider/telemetry/setup.js'
+import type { PathBuilder } from '../../session/workspace/path-builder.js'
 import { GENAI, NAMZU, agentRunSpanName } from '../../telemetry/attributes.js'
 import { buildAdvisoryTools } from '../../tools/advisory/index.js'
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
@@ -20,7 +21,7 @@ import {
 	type ResumeHandler,
 	autoApproveHandler,
 } from '../../types/hitl/index.js'
-import type { RunId, ThreadId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import { type Message, createSystemMessage } from '../../types/message/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
@@ -28,6 +29,7 @@ import type { LLMProvider } from '../../types/provider/index.js'
 import type { TaskRouterConfig } from '../../types/router/index.js'
 import type { AgentRun, AgentRunConfig, RunEvent, RunEventListener } from '../../types/run/index.js'
 import type { Sandbox, SandboxProvider } from '../../types/sandbox/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import type { Skill } from '../../types/skills/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolRegistryContract } from '../../types/tool/index.js'
@@ -65,8 +67,31 @@ export interface QueryParams {
 	resumeHandler: ResumeHandler
 	resumeFromCheckpoint?: CheckpointId
 
+	/** Session scope for the run. Required — every run is attributed to a Session. */
+	sessionId: SessionId
+
+	/**
+	 * Topic the Session lives under. Required in 0.3.0 — every run carries
+	 * the full five-layer scope (Tenant → Project → Thread → Session →
+	 * Run). Denormalized from `session.threadId`; callers build this
+	 * alongside `sessionId` so the query pipeline never needs a second
+	 * SessionStore round-trip to recover it.
+	 */
 	threadId: ThreadId
 
+	/** Long-lived goal scope for the run. Required. */
+	projectId: ProjectId
+
+	/** Isolation boundary (Convention #17). Required. */
+	tenantId: TenantId
+
+	/**
+	 * Optional path layout override. Defaults to a {@link DefaultPathBuilder}
+	 * rooted at `{workingDirectory}/.namzu`. First-call filesystem migration
+	 * runs on this same entry point.
+	 */
+	pathBuilder?: PathBuilder
+
 	runId?: RunId
 
 	parentRunId?: RunId
@@ -112,6 +137,14 @@ export interface QueryParams {
 }
 
 export async function* query(params: QueryParams): AsyncGenerator<RunEvent, AgentRun> {
+	// Boot-time filesystem migration (session-hierarchy.md §13.4.1). First
+	// call per process per root actually runs; subsequent calls short-circuit
+	// via the in-memory guard in `context.ts`. Kept here rather than inside
+	// the synchronous `RunContextFactory.build` so the factory signature stays
+	// sync for tests / non-async call sites.
+	const cwdForMigration = params.workingDirectory ?? process.cwd()
+	await RunContextFactory.ensureMigrated(`${cwdForMigration}/.namzu`)
+
 	const ctx = RunContextFactory.build({
 		agentId: params.agentId,
 		agentName: params.agentName,
@@ -122,7 +155,11 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Agen
 		enableActivityTracking: params.enableActivityTracking,
 		messages: params.messages,
 		signal: params.signal,
+		sessionId: params.sessionId,
 		threadId: params.threadId,
+		projectId: params.projectId,
+		tenantId: params.tenantId,
+		pathBuilder: params.pathBuilder,
 		runId: params.runId,
 		parentRunId: params.parentRunId,
 		depth: params.depth,