@namzu/sdk 42.0.2 → 44.0.0

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

@@ -0,0 +1,354 @@
+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 {
+	SharedSessionWorkspaceAgentRecord,
+	SharedSessionWorkspaceManifest,
+	SharedSessionWorkspacePlan,
+	SharedSessionWorkspaceRefs,
+	SharedSessionWorkspaceSource,
+} from '../../types/workspace/shared-session.js'
+
+export interface SharedSessionWorkspaceConfig {
+	/**
+	 * 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 RegisterSharedSessionPlanInput {
+	id?: string
+	briefText: string
+	status?: SharedSessionWorkspacePlan['status']
+}
+
+/**
+ * A `_work` directory a turn'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 SharedSessionWorkspaceConfig} 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 turn, 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 turn 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 SharedSessionWorkspace {
+	readonly hostRoot: string
+	readonly runtimeRoot: string
+	private manifestWriteQueue: Promise<void> = Promise.resolve()
+
+	private constructor(private readonly config: Required<SharedSessionWorkspaceConfig>) {
+		this.hostRoot = config.hostRoot
+		this.runtimeRoot = trimTrailingSlash(config.runtimeRoot)
+	}
+
+	static async create(config: SharedSessionWorkspaceConfig): Promise<SharedSessionWorkspace> {
+		const workspace = new SharedSessionWorkspace({
+			hostRoot: config.hostRoot,
+			runtimeRoot: config.runtimeRoot ?? config.hostRoot,
+			label: config.label ?? '',
+			now: config.now ?? new Date(),
+		})
+		await workspace.ensure()
+		return workspace
+	}
+
+	refs(): SharedSessionWorkspaceRefs {
+		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<SharedSessionWorkspaceManifest> {
+		const content = await readFile(this.hostPath('manifest.json'), 'utf8').catch(() => '')
+		if (!content.trim()) return this.initialManifest()
+		return JSON.parse(content) as SharedSessionWorkspaceManifest
+	}
+
+	async writeManifest(
+		update: (manifest: SharedSessionWorkspaceManifest) => SharedSessionWorkspaceManifest,
+	): Promise<SharedSessionWorkspaceManifest> {
+		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 SharedSessionWorkspaceSource[]): Promise<string> {
+		const lines = [
+			'# Source Inventory',
+			'',
+			sources.length
+				? 'These are the canonical input references for this turn. Prefer this inventory and targeted source reads over rediscovering uploads in every worker.'
+				: 'No user-uploaded source files were registered for this turn.',
+			'',
+			...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: RegisterSharedSessionPlanInput): 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?: SharedSessionWorkspaceAgentRecord['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(): SharedSessionWorkspaceManifest {
+		const now = this.config.now.toISOString()
+		return {
+			schemaVersion: 1,
+			kind: 'shared-session-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(`SharedSessionWorkspace 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]
+}

package/src/session-query/index.ts

@@ -0,0 +1,152 @@
+import { SESSION_STATUS_READ_MODEL_ID, createSessionStatusReadModel } from '../read-model/index.js'
+import type { SessionStatusState } from '../read-model/index.js'
+import { ReadModelRegistry } from '../read-model/registry.js'
+import {
+	type SessionLog,
+	SpillIntegrityError,
+	SpillUnavailableError,
+	foldSessionMessages,
+} from '../store/session-log/index.js'
+import type { Message } from '../types/message/index.js'
+import type { SessionRecord, TurnStatus } from '../types/session/index.js'
+
+/**
+ * Asking a session what happened, from its log.
+ *
+ * The log is the one source: `records()` is every record, the fold is the
+ * conversation that survived compaction, and `compaction_shed` carries
+ * exactly the messages each pass removed, in their original order — so
+ * "everything that was ever in this conversation" has one answer.
+ */
+
+export interface SessionQueryOptions {
+	/** The session log to ask. */
+	readonly log: SessionLog
+	/** Injectable for the same reason the read model injects it. */
+	readonly now?: () => number
+}
+
+export type SessionTranscriptUnavailableReason =
+	/** A record of the log does not chain to the one before it. */
+	| 'log-integrity'
+	/** A message body was spilled and the spill cannot be read or verified. */
+	| 'spill-unavailable'
+
+/**
+ * Refusal to call a partial or unverifiable reconstruction "complete".
+ */
+export class SessionTranscriptUnavailableError extends Error {
+	readonly reason: SessionTranscriptUnavailableReason
+	/** The last record the log could vouch for. */
+	readonly throughSeq: number | undefined
+
+	constructor(input: {
+		reason: SessionTranscriptUnavailableReason
+		throughSeq?: number
+		cause?: unknown
+	}) {
+		const detail =
+			input.reason === 'log-integrity'
+				? `the session log breaks after record ${input.throughSeq ?? 'unknown'}`
+				: 'a spilled message body cannot be read back'
+		super(
+			`Complete session transcript unavailable: ${detail}.`,
+			input.cause ? { cause: input.cause } : undefined,
+		)
+		this.name = 'SessionTranscriptUnavailableError'
+		this.reason = input.reason
+		this.throughSeq = input.throughSeq
+	}
+}
+
+/** What one compaction pass removed. */
+export interface ShedPass {
+	readonly iteration: number
+	readonly reason: Extract<SessionRecord, { type: 'compaction_shed' }>['reason']
+	readonly messages: readonly Message[]
+	/** Where in the log the pass sits. */
+	readonly seq: number
+}
+
+export class SessionQuery {
+	constructor(private readonly options: SessionQueryOptions) {}
+
+	/** The session's records, oldest first. Refused when the log does not chain. */
+	async records(): Promise<readonly SessionRecord[]> {
+		const read = await this.options.log.readAll({ mode: 'tolerant' })
+		if (!read.intact) {
+			throw new SessionTranscriptUnavailableError({
+				reason: 'log-integrity',
+				throughSeq: read.throughSeq,
+				cause: read.break,
+			})
+		}
+		return read.entries.map((entry) => entry.record)
+	}
+
+	/** Every message compaction removed, one entry per pass, oldest first. */
+	async shedHistory(): Promise<readonly ShedPass[]> {
+		return shedPassesFrom(await this.records())
+	}
+
+	/**
+	 * Everything that was ever in this conversation: shed passes oldest
+	 * first, then the conversation that survived (the fold of the log, or
+	 * `messages` when given). Complete, not interleaved: the log records what
+	 * each pass removed, not where its summary sits relative to what came
+	 * after.
+	 */
+	async fullTranscript(messages?: readonly Message[]): Promise<readonly Message[]> {
+		const records = await this.records()
+		const shed = shedPassesFrom(records)
+		let surviving: readonly Message[]
+		if (messages !== undefined) {
+			surviving = messages
+		} else {
+			try {
+				surviving = await foldSessionMessages(records, {
+					readSpill: (ref) => this.options.log.readSpill(ref),
+				})
+			} catch (error) {
+				if (
+					error instanceof SpillUnavailableError ||
+					error instanceof SpillIntegrityError ||
+					error instanceof SyntaxError
+				)
+					throw new SessionTranscriptUnavailableError({ reason: 'spill-unavailable', cause: error })
+				throw error
+			}
+		}
+		if (shed.length === 0) return surviving
+		return [...shed.flatMap((pass) => pass.messages), ...surviving]
+	}
+
+	/** The session's status, folded from its own log through the read model. */
+	async status(): Promise<TurnStatus> {
+		return (await this.statusState()).status
+	}
+
+	/** The whole projected state, for a caller that wants the park too. */
+	async statusState(): Promise<SessionStatusState> {
+		const registry = new ReadModelRegistry()
+		registry.register(
+			createSessionStatusReadModel(this.options.now ? { now: this.options.now } : {}),
+		)
+		registry.replay(await this.records())
+		return registry.get<SessionStatusState>(SESSION_STATUS_READ_MODEL_ID)
+	}
+}
+
+function shedPassesFrom(records: readonly SessionRecord[]): ShedPass[] {
+	const passes: ShedPass[] = []
+	for (const record of records) {
+		if (record.type !== 'compaction_shed') continue
+		passes.push({
+			iteration: record.iteration,
+			reason: record.reason,
+			messages: record.messages,
+			seq: record.seq,
+		})
+	}
+	return passes
+}

package/src/skills/registry.ts

@@ -128,7 +128,7 @@ export class SkillRegistry {
 	 *
 	 * The cache was permanent: once a body had been read, `existing.body`
 	 * short-circuited every later call, so an edited SKILL.md could not reach
-	 * the model without restarting the process. That is fine for a run and
+	 * the model without restarting the process. That is fine for a turn and
 	 * wrong for a long-lived one — a skill is a file an author is editing
 	 * WHILE the agent is running, which is the whole reason it is a file and
 	 * not a constant.

package/src/store/activity/memory.ts

@@ -6,7 +6,7 @@ import type {
 	ActivityType,
 } from '../../types/activity/index.js'
 import { isTerminalActivityStatus } from '../../types/activity/index.js'
-import type { ActivityId, RunId } from '../../types/ids/index.js'
+import type { ActivityId, TurnId } from '../../types/ids/index.js'
 import { generateActivityId } from '../../utils/id.js'
 
 export interface ActivityEvent {
@@ -24,12 +24,12 @@ export type ActivityEventListener = (event: ActivityEvent) => void
 
 export class ActivityStore {
 	private activities = new Map<ActivityId, Activity>()
-	private runId: RunId
+	private turnId: TurnId
 	private config: ActivityTrackingConfig
 	private listeners: ActivityEventListener[] = []
 
-	constructor(runId: RunId, config: ActivityTrackingConfig) {
-		this.runId = runId
+	constructor(turnId: TurnId, config: ActivityTrackingConfig) {
+		this.turnId = turnId
 		this.config = config
 	}
 
@@ -67,7 +67,7 @@ export class ActivityStore {
 
 		const activity: Activity = {
 			id: generateActivityId(),
-			runId: this.runId,
+			turnId: this.turnId,
 			type: params.type,
 			status: 'pending',
 			description: params.description,

package/src/store/attachment/index.ts

@@ -5,11 +5,11 @@ import type { Message, MessageAttachment } from '../../types/message/index.js'
  *
  * Every attachment was inline base64 on the message. That is fine for one
  * screenshot and wrong for everything else it implies: the bytes are copied
- * into the run's durable transcript, into every checkpoint, into every
+ * into the turn's durable transcript, into every checkpoint, into every
  * compaction pass that walks the history, and — because a conversation
  * resends its history — into every subsequent request. A 4 MB PDF attached
  * once is 4 MB in the transcript and 4 MB on the wire per turn for the rest
- * of the run.
+ * of the turn.
  *
  * So a message may carry a REFERENCE instead. The kernel treats `ref` as
  * opaque: this seam says nothing about whether it is a hash, a path, or a
@@ -72,7 +72,7 @@ export interface AttachmentResolutionOptions extends AttachmentOperationOptions
 	readonly timeoutMs?: number
 }
 
-/** One minute is long enough for remote stores without letting a run wedge forever. */
+/** One minute is long enough for remote stores without letting a turn wedge forever. */
 export const DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS = 60_000
 
 const MAX_TIMER_DELAY_MS = 2_147_483_647
@@ -100,13 +100,13 @@ export class AttachmentNotFoundError extends Error {
 	}
 }
 
-/** A message that carries a ref, in a run with nowhere to resolve it. */
+/** A message that carries a ref, in a turn with nowhere to resolve it. */
 export class NoAttachmentStoreError extends Error {
 	readonly details: { ref: string }
 
 	constructor(details: { ref: string }) {
 		super(
-			`A message carries a stored attachment ("${details.ref}") but this run has no attachment store.`,
+			`A message carries a stored attachment ("${details.ref}") but this turn has no attachment store.`,
 		)
 		this.name = 'NoAttachmentStoreError'
 		this.details = details