@namzu/sdk 43.0.0 → 44.0.0

package/src/runtime/query/run-state.ts

@@ -1,138 +0,0 @@
-import type { RunPersistence } from '../../manager/run/persistence.js'
-import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
-import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
-import { RUN_STATE_VERSION, type RunState } from '../../types/run/state.js'
-import type { TopicId } from '../../types/session/ids.js'
-import { findPendingCheckpoint } from './checkpoint.js'
-
-/**
- * A {@link CheckpointRunScope} plus the one attribution field checkpoints
- * do not record.
- *
- * `topicId` is denormalized onto a run at `query()` time and never written
- * into a checkpoint, so a snapshot rebuilt from the store alone cannot
- * derive it. Requiring the caller to supply it is better than inventing one
- * or widening `RunState` to make it optional: the field is required by
- * `query()` on the way back in, so an absent value would only fail later
- * and less clearly.
- */
-export interface RunStateScope extends CheckpointRunScope {
-	topicId: TopicId
-}
-
-/**
- * Build a JSON-safe snapshot of a live run.
- *
- * Every field is copied, not referenced: the caller is about to serialize
- * this, and a snapshot that aliased the run's own message array would keep
- * mutating after it was taken.
- */
-export function captureRunState(
-	runMgr: RunPersistence,
-	scope: RunStateScope,
-	extra?: {
-		elapsedMs?: number
-		checkpoint?: IterationCheckpoint | null
-	},
-): RunState {
-	const session = runMgr.getSession()
-	const startedAt = session.startedAt
-
-	return {
-		version: RUN_STATE_VERSION,
-		runId: runMgr.id,
-		sessionId: scope.sessionId,
-		topicId: scope.topicId,
-		projectId: scope.projectId,
-		tenantId: scope.tenantId,
-		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
-		...(session.metadata?.agentId ? { agentId: session.metadata.agentId } : {}),
-		...(session.metadata?.agentName ? { agentName: session.metadata.agentName } : {}),
-		status: runMgr.status,
-		...(runMgr.stopReason ? { stopReason: runMgr.stopReason } : {}),
-		...(session.lastError ? { lastError: session.lastError } : {}),
-		messages: structuredClone(runMgr.messages),
-		tokenUsage: { ...runMgr.tokenUsage },
-		budgetBinding: runMgr.budget?.binding,
-		budgetAccountId: runMgr.budget?.accountId,
-		costInfo: { ...runMgr.costInfo },
-		currentIteration: runMgr.currentIteration,
-		startedAt,
-		elapsedMs: extra?.elapsedMs ?? Date.now() - startedAt,
-		...(extra?.checkpoint ? { checkpointId: extra.checkpoint.id } : {}),
-		...(extra?.checkpoint?.pending ? { pending: extra.checkpoint.pending } : {}),
-		capturedAt: Date.now(),
-	}
-}
-
-/**
- * Rebuild a run's snapshot from durable state alone, with no live run
- * object — the read a DIFFERENT process performs.
- *
- * With no `checkpointId` this prefers the run's outstanding park over its
- * newest checkpoint, because "what is this run waiting on" is the question
- * a resuming process is actually asking; it falls back to the newest
- * checkpoint when nothing is parked.
- *
- * Returns `null` when the run has no checkpoints. That is the honest
- * answer: a run that never checkpointed left nothing to resume from, and
- * synthesizing a snapshot from an empty store would produce a run that
- * restarts from zero while claiming to be a continuation.
- *
- * `status`/`stopReason` are absent from a checkpoint by construction — a
- * checkpoint is written mid-flight — so a rebuilt snapshot always reports
- * `running`, and the host's own record remains the authority on a run that
- * already finished. Read `pending` to tell a parked run from a live one:
- * it is outstanding when set with no `resolvedAt`.
- */
-export async function loadRunState(
-	store: CheckpointStore,
-	scope: RunStateScope,
-	checkpointId?: CheckpointId,
-): Promise<RunState | null> {
-	return (await loadSelectedRunState(store, scope, checkpointId))?.state ?? null
-}
-
-/** @internal The exact checkpoint selected together with its public run-state projection. */
-export async function loadSelectedRunState(
-	store: CheckpointStore,
-	scope: RunStateScope,
-	checkpointId?: CheckpointId,
-): Promise<{ readonly state: RunState; readonly checkpoint: IterationCheckpoint } | null> {
-	const checkpoint = checkpointId
-		? await store.readCheckpoint(scope, checkpointId)
-		: ((await findPendingCheckpoint(store, scope)) ?? (await newest(store, scope)))
-
-	if (!checkpoint) return null
-
-	const state: RunState = {
-		version: RUN_STATE_VERSION,
-		runId: checkpoint.runId,
-		sessionId: scope.sessionId,
-		topicId: scope.topicId,
-		projectId: scope.projectId,
-		tenantId: scope.tenantId,
-		...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
-		status: 'running',
-		messages: checkpoint.messages,
-		tokenUsage: checkpoint.tokenUsage,
-		budgetBinding: checkpoint.budgetBinding,
-		budgetAccountId: checkpoint.budgetAccountId,
-		costInfo: checkpoint.costInfo,
-		currentIteration: checkpoint.guardState.iterationCount,
-		startedAt: checkpoint.createdAt - checkpoint.guardState.elapsedMs,
-		elapsedMs: checkpoint.guardState.elapsedMs,
-		checkpointId: checkpoint.id,
-		...(checkpoint.pending ? { pending: checkpoint.pending } : {}),
-		capturedAt: Date.now(),
-	}
-	return { state, checkpoint }
-}
-
-async function newest(
-	store: CheckpointStore,
-	scope: CheckpointRunScope,
-): Promise<IterationCheckpoint | null> {
-	const all = await store.listCheckpoints(scope)
-	return all.length > 0 ? ((all[all.length - 1] as IterationCheckpoint) ?? null) : null
-}

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

@@ -1,72 +0,0 @@
-/**
- * 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'
-import { asProjectId, asRunId, asSessionId, asSubSessionId } from '../../utils/id.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', asProjectId(projectId))
-	}
-
-	sessionDir(projectId: ProjectId, sessionId: SessionId): string {
-		return join(this.projectDir(projectId), 'sessions', asSessionId(sessionId))
-	}
-
-	subSessionDir(projectId: ProjectId, sessionId: SessionId, subSessionId: SubSessionId): string {
-		return join(this.sessionDir(projectId, sessionId), 'subsessions', asSubSessionId(subSessionId))
-	}
-
-	runDir(projectId: ProjectId, sessionId: SessionId, runId: RunId): string {
-		return join(this.sessionDir(projectId, sessionId), 'runs', asRunId(runId))
-	}
-}

package/src/session/workspace/shared-run.ts

@@ -1,354 +0,0 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { dirname, join, normalize, relative, sep } from 'node:path'
-import { posix } from 'node:path'
-import type {
-	SharedRunWorkspaceAgentRecord,
-	SharedRunWorkspaceManifest,
-	SharedRunWorkspacePlan,
-	SharedRunWorkspaceRefs,
-	SharedRunWorkspaceSource,
-} from '../../types/workspace/shared-run.js'
-
-export interface SharedRunWorkspaceConfig {
-	/**
-	 * Host-visible `_work` directory. The runtime creates and mutates files
-	 * here before/while agents execute.
-	 */
-	hostRoot: string
-	/**
-	 * Agent-visible `_work` directory. In container sandboxes this is usually
-	 * `/mnt/user-data/outputs/_work`; in local mode it can be the same
-	 * relative path agents receive in their runtime notes.
-	 */
-	runtimeRoot?: string
-	label?: string
-	now?: Date
-}
-
-export interface RegisterSharedRunPlanInput {
-	id?: string
-	briefText: string
-	status?: SharedRunWorkspacePlan['status']
-}
-
-/**
- * A `_work` directory a run's agents share — files, a manifest, a plan and
- * per-agent records — offered to hosts and applied by none of them.
- *
- * **Nothing in this SDK calls it, and that is the design, not an omission.**
- * It was flagged as a primitive exported without a driver, which is a real
- * defect class and the reason most of this module's siblings were wired up.
- * This one is the exception, and the distinguishing question is whose decision
- * the thing encodes.
- *
- * Look at what {@link SharedRunWorkspaceConfig} asks for: `hostRoot`, where
- * the directory lives on the machine running the kernel, and `runtimeRoot`,
- * the path an agent will see — `/mnt/user-data/outputs/_work` under one
- * container layout, the same directory as `hostRoot` in a local run, a bind
- * target somewhere else entirely under a third. Those two roots are a
- * deployment shape. A kernel that picked them would be choosing a filesystem
- * layout for a host that has already chosen one, and would then have to be
- * argued back out of it — the same reason `ToolCatalogSurface` was removed
- * rather than made to work: a host's deployment surfaces are the host's to
- * name.
- *
- * So the contract here is `runtimeRoot` and the paths {@link refs} derives
- * from it. Those strings are what a host puts in a prompt and what an agent's
- * `read` and `write` calls resolve against, which makes them an interface
- * between three parties — and stable for that reason, not incidentally.
- *
- * A host wires it by calling {@link create} with both roots, passing
- * `refs()` into its agents' runtime notes, and reading the manifest back when
- * the run ends. If a future default gateway grows an opinion about where
- * `_work` belongs, this is the thing it should call rather than reimplement.
- */
-export class SharedRunWorkspace {
-	readonly hostRoot: string
-	readonly runtimeRoot: string
-	private manifestWriteQueue: Promise<void> = Promise.resolve()
-
-	private constructor(private readonly config: Required<SharedRunWorkspaceConfig>) {
-		this.hostRoot = config.hostRoot
-		this.runtimeRoot = trimTrailingSlash(config.runtimeRoot)
-	}
-
-	static async create(config: SharedRunWorkspaceConfig): Promise<SharedRunWorkspace> {
-		const workspace = new SharedRunWorkspace({
-			hostRoot: config.hostRoot,
-			runtimeRoot: config.runtimeRoot ?? config.hostRoot,
-			label: config.label ?? '',
-			now: config.now ?? new Date(),
-		})
-		await workspace.ensure()
-		return workspace
-	}
-
-	refs(): SharedRunWorkspaceRefs {
-		return {
-			rootPath: this.runtimePath(),
-			manifestPath: this.runtimePath('manifest.json'),
-			sharedContextPath: this.runtimePath('02_shared_context.md'),
-			sourceInventoryPath: this.runtimePath('sources', 'inventory.md'),
-			supervisorBriefPath: this.runtimePath('00_supervisor_brief.md'),
-			taskContextPath: this.runtimePath('01_task_context.md'),
-			agentsPath: this.runtimePath('agents'),
-		}
-	}
-
-	hostPath(...segments: string[]): string {
-		return safeJoin(this.hostRoot, segments)
-	}
-
-	runtimePath(...segments: string[]): string {
-		if (segments.length === 0) return this.runtimeRoot
-		return posix.join(this.runtimeRoot, ...segments.map((segment) => segment.split(sep).join('/')))
-	}
-
-	async ensure(): Promise<void> {
-		await Promise.all([
-			mkdir(this.hostPath('sources'), { recursive: true }),
-			mkdir(this.hostPath('plans', 'root'), { recursive: true }),
-			mkdir(this.hostPath('agents'), { recursive: true }),
-		])
-		await this.writeManifest((manifest) => manifest)
-	}
-
-	async readManifest(): Promise<SharedRunWorkspaceManifest> {
-		const content = await readFile(this.hostPath('manifest.json'), 'utf8').catch(() => '')
-		if (!content.trim()) return this.initialManifest()
-		return JSON.parse(content) as SharedRunWorkspaceManifest
-	}
-
-	async writeManifest(
-		update: (manifest: SharedRunWorkspaceManifest) => SharedRunWorkspaceManifest,
-	): Promise<SharedRunWorkspaceManifest> {
-		const operation = this.manifestWriteQueue
-			.catch(() => undefined)
-			.then(async () => {
-				const current = await this.readManifest().catch(() => this.initialManifest())
-				const next = update({
-					...current,
-					updatedAt: this.nowIso(),
-				})
-				await writeJsonAtomic(this.hostPath('manifest.json'), next)
-				return next
-			})
-		this.manifestWriteQueue = operation.then(
-			() => undefined,
-			() => undefined,
-		)
-		return operation
-	}
-
-	async writeSourceInventory(sources: readonly SharedRunWorkspaceSource[]): Promise<string> {
-		const lines = [
-			'# Source Inventory',
-			'',
-			sources.length
-				? 'These are the canonical input references for this run. Prefer this inventory and targeted source reads over rediscovering uploads in every worker.'
-				: 'No user-uploaded source files were registered for this run.',
-			'',
-			...sources.map((source) =>
-				[
-					`## ${source.label}`,
-					'',
-					`- id: ${source.id}`,
-					`- path: ${source.path}`,
-					source.kind ? `- kind: ${source.kind}` : null,
-					typeof source.sizeBytes === 'number' ? `- sizeBytes: ${source.sizeBytes}` : null,
-					'',
-				]
-					.filter((line): line is string => line !== null)
-					.join('\n'),
-			),
-		]
-		const content = `${lines.join('\n').trimEnd()}\n`
-		await writeFile(this.hostPath('sources', 'inventory.md'), content, 'utf8')
-		await this.writeManifest((manifest) => ({
-			...manifest,
-			sources: [...sources],
-		}))
-		return this.runtimePath('sources', 'inventory.md')
-	}
-
-	/**
-	 * Write the canonical task-context file (`_work/01_task_context.md`).
-	 * This is the single place the original user request lives in full; child
-	 * workers read this path instead of receiving the request inline in their
-	 * prompts.
-	 */
-	async writeTaskContext(text: string): Promise<string> {
-		const relativePath = ['01_task_context.md']
-		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
-		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(text), 'utf8')
-		return this.runtimePath(...relativePath)
-	}
-
-	/**
-	 * Write the shared coordination packet (`_work/02_shared_context.md`).
-	 * This is intentionally smaller and more operational than the task context:
-	 * workers read it first, then open the full task context or source inventory
-	 * only when their assignment needs raw wording or source-file details.
-	 */
-	async writeSharedContext(text: string): Promise<string> {
-		const relativePath = ['02_shared_context.md']
-		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
-		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(text), 'utf8')
-		return this.runtimePath(...relativePath)
-	}
-
-	/**
-	 * Write a per-worker brief at `agents/<agentId>/<taskId>/00_brief.md`.
-	 * Returns the runtime-visible path. Pair with `registerAgentWork` so the
-	 * agent record and the brief sit under the same scratch directory.
-	 */
-	async writeAgentBrief(input: {
-		agentId: string
-		taskId?: string
-		briefText: string
-	}): Promise<string> {
-		const taskPart = input.taskId ?? 'pending'
-		const relativePath = ['agents', input.agentId, taskPart, '00_brief.md']
-		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
-		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(input.briefText), 'utf8')
-		return this.runtimePath(...relativePath)
-	}
-
-	/**
-	 * Append a section to an existing per-worker brief, creating the file if
-	 * it doesn't yet exist. Use for follow-up turns / continue flows so the
-	 * brief stays authoritative across resumes — workers re-reading the brief
-	 * on every entry will see the latest assignment delta, not just the seed
-	 * text from initial dispatch.
-	 */
-	async appendAgentBrief(input: {
-		agentId: string
-		taskId?: string
-		sectionText: string
-	}): Promise<string> {
-		const taskPart = input.taskId ?? 'pending'
-		const relativePath = ['agents', input.agentId, taskPart, '00_brief.md']
-		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
-		const target = this.hostPath(...relativePath)
-		const existing = await readFile(target, 'utf8').catch(() => '')
-		const trimmedExisting = existing.replace(/\n*$/, '')
-		const next = trimmedExisting
-			? `${trimmedExisting}\n\n${ensureTrailingNewline(input.sectionText)}`
-			: ensureTrailingNewline(input.sectionText)
-		await writeFile(target, next, 'utf8')
-		return this.runtimePath(...relativePath)
-	}
-
-	async seedSupervisorBrief(input: RegisterSharedRunPlanInput): Promise<string> {
-		const id = input.id ?? 'root'
-		const relativePath =
-			id === 'root' ? ['00_supervisor_brief.md'] : ['plans', id, 'supervisor_brief.md']
-		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
-		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(input.briefText), 'utf8')
-		const briefPath = this.runtimePath(...relativePath)
-		const now = this.nowIso()
-		await this.writeManifest((manifest) => ({
-			...manifest,
-			plans: upsertBy(manifest.plans, (plan) => plan.id, {
-				id,
-				briefPath,
-				status: input.status ?? 'seeded',
-				updatedAt: now,
-			}),
-		}))
-		return briefPath
-	}
-
-	async registerAgentWork(input: {
-		agentId: string
-		taskId?: string
-		status?: SharedRunWorkspaceAgentRecord['status']
-	}): Promise<string> {
-		const taskPart = input.taskId ?? 'pending'
-		const relativePath = ['agents', input.agentId, taskPart]
-		await mkdir(this.hostPath(...relativePath), { recursive: true })
-		const workPath = this.runtimePath(...relativePath)
-		const now = this.nowIso()
-		await this.writeManifest((manifest) => ({
-			...manifest,
-			agents: upsertBy(manifest.agents, (record) => `${record.agentId}:${record.taskId ?? ''}`, {
-				agentId: input.agentId,
-				...(input.taskId ? { taskId: input.taskId } : {}),
-				workPath,
-				status: input.status ?? 'assigned',
-				updatedAt: now,
-			}),
-		}))
-		return workPath
-	}
-
-	private initialManifest(): SharedRunWorkspaceManifest {
-		const now = this.config.now.toISOString()
-		return {
-			schemaVersion: 1,
-			kind: 'shared-run-workspace',
-			createdAt: now,
-			updatedAt: now,
-			...(this.config.label ? { label: this.config.label } : {}),
-			paths: {
-				root: this.runtimePath(),
-				manifest: this.runtimePath('manifest.json'),
-				sharedContext: this.runtimePath('02_shared_context.md'),
-				sources: this.runtimePath('sources'),
-				plans: this.runtimePath('plans'),
-				agents: this.runtimePath('agents'),
-			},
-			sources: [],
-			plans: [],
-			agents: [],
-		}
-	}
-
-	private nowIso(): string {
-		return new Date().toISOString()
-	}
-}
-
-function safeJoin(root: string, segments: readonly string[]): string {
-	const fullPath = normalize(join(root, ...segments))
-	const rel = relative(root, fullPath)
-	if (rel === '' || (!rel.startsWith('..') && !rel.includes(`..${sep}`))) return fullPath
-	throw new Error(`SharedRunWorkspace path escapes root: ${segments.join('/')}`)
-}
-
-function trimTrailingSlash(value: string): string {
-	if (value === '/') return value
-	// Manual scan instead of /\/+$/: that pattern is unanchored at the start, so a
-	// backtracking engine retries the trailing-slash run from every prior index
-	// once the terminal `$` fails to match, making it O(n^2) on a long run of
-	// slashes (runtimeRoot is caller-supplied and can be arbitrarily long).
-	let end = value.length
-	while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */) end--
-	return value.slice(0, end)
-}
-
-function ensureTrailingNewline(value: string): string {
-	return value.endsWith('\n') ? value : `${value}\n`
-}
-
-async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
-	await mkdir(dirnameFor(path), { recursive: true })
-	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`
-	await writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
-	await rename(tmpPath, path)
-}
-
-function dirnameFor(path: string): string {
-	return dirname(path)
-}
-
-function upsertBy<T>(items: readonly T[], key: (item: T) => string, next: T): T[] {
-	const nextKey = key(next)
-	let replaced = false
-	const updated = items.map((item) => {
-		if (key(item) !== nextKey) return item
-		replaced = true
-		return next
-	})
-	return replaced ? updated : [...updated, next]
-}