@namzu/sdk 49.0.0 → 50.1.0

package/src/runtime/harness-session/journal.ts

@@ -0,0 +1,209 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { assertSessionLogAttribution } from '../../manager/session/attribution.js'
+import type { SessionLease, SessionLog, SessionRecordDraft } from '../../store/session-log/index.js'
+import {
+	HarnessBindingSchema,
+	HarnessJournalTransitionSchema,
+	harnessSnapshot,
+} from '../../types/harness/schema.js'
+import type {
+	HarnessBinding,
+	HarnessJournalTransition,
+	HarnessScope,
+} from '../../types/harness/session.js'
+import { type SessionEvent, isEphemeralEvent } from '../../types/session/events.js'
+
+export class HarnessSessionError extends Error {
+	override readonly name = 'HarnessSessionError'
+	constructor(
+		readonly code: string,
+		message: string,
+	) {
+		super(message)
+	}
+}
+
+/** Stable hash for captured JSON; object insertion order never changes authority. */
+export function harnessDigest(value: unknown): string {
+	const canonical = (v: unknown): unknown => {
+		if (Array.isArray(v)) return v.map(canonical)
+		if (!v || typeof v !== 'object') return v
+		return Object.fromEntries(
+			Object.entries(v)
+				.sort(([a], [b]) => a.localeCompare(b))
+				.map(([k, entry]) => [k, canonical(entry)]),
+		)
+	}
+	return createHash('sha256')
+		.update(JSON.stringify(canonical(value)))
+		.digest('hex')
+}
+
+export class HarnessJournal {
+	private leaseToken?: SessionLease
+	private heartbeat?: ReturnType<typeof setInterval>
+	private renewals: Promise<void> = Promise.resolve()
+	private failure?: unknown
+	private readonly holder = `harness:${process.pid}:${randomUUID()}`
+	private readonly ttlMs = 60000
+	constructor(
+		readonly log: SessionLog,
+		readonly scope: HarnessScope,
+		readonly engineId: string,
+		readonly profileRef: string,
+	) {}
+
+	async inspect(): Promise<{ binding?: HarnessBinding; transitions: HarnessJournalTransition[] }> {
+		const opened = await assertSessionLogAttribution(this.log, this.scope)
+		if (!opened) return { transitions: [] }
+		const { entries } = await this.log.readAll()
+		const start = entries[0]?.record
+		if (
+			start?.type !== 'session_started' ||
+			!start.harness ||
+			start.parent ||
+			start.forkedFrom ||
+			start.cwd !== this.scope.cwd
+		) {
+			throw new HarnessSessionError(
+				'binding-mismatch',
+				'Only an ordinary session with an exact immutable harness binding may be reopened.',
+			)
+		}
+		const binding = harnessSnapshot(HarnessBindingSchema.parse(start.harness))
+		this.validateBinding(binding)
+		const transitions = entries.flatMap(({ record }) =>
+			record.type === 'session_updated' && record.harness
+				? [HarnessJournalTransitionSchema.parse(record.harness)]
+				: [],
+		)
+		return { binding, transitions }
+	}
+
+	validateBinding(binding: HarnessBinding): void {
+		if (
+			binding.engineId !== this.engineId ||
+			binding.profileRef !== this.profileRef ||
+			binding.cwd !== this.scope.cwd
+		) {
+			throw new HarnessSessionError(
+				'binding-mismatch',
+				'The engine, profile or canonical execution directory differs from this session binding.',
+			)
+		}
+	}
+
+	async claim(): Promise<void> {
+		await this.inspect() // never repair a foreign journal before validating ownership
+		if (this.leaseToken) {
+			await this.current()
+			return
+		}
+		const lease = await this.log.claim({
+			holder: this.holder,
+			ttlMs: this.ttlMs,
+			repairTornTail: false,
+		})
+		if (!lease) throw new HarnessSessionError('writer-busy', 'Another writer owns this session.')
+		this.leaseToken = lease
+		try {
+			await this.inspect()
+		} catch (error) {
+			await this.release()
+			throw error
+		}
+		this.heartbeat = setInterval(() => {
+			this.renewals = this.renewals
+				.then(() => this.renew())
+				.catch((error: unknown) => {
+					this.failure ??= error
+				})
+		}, this.ttlMs / 2)
+		this.heartbeat.unref()
+	}
+
+	private async renew(): Promise<void> {
+		if (!this.leaseToken || this.failure) return
+		const previous = this.leaseToken
+		const next = await this.log.claim({
+			holder: this.holder,
+			ttlMs: this.ttlMs,
+			repairTornTail: false,
+		})
+		if (!next || next.fence !== previous.fence)
+			throw new HarnessSessionError('writer-lost', 'The harness session writer lease was lost.')
+		this.leaseToken = next
+	}
+
+	async current(): Promise<SessionLease> {
+		await this.renewals
+		if (this.failure) throw this.failure
+		if (!this.leaseToken)
+			throw new HarnessSessionError('writer-missing', 'The harness session has no writer lease.')
+		if (this.leaseToken.expiresAt - Date.now() < this.ttlMs / 2) await this.renew()
+		const lease = await this.log.lease()
+		if (!lease || lease.fence !== this.leaseToken.fence || lease.holder !== this.holder)
+			throw new HarnessSessionError('writer-lost', 'The harness session writer lease was lost.')
+		return this.leaseToken
+	}
+
+	async start(binding: HarnessBinding): Promise<void> {
+		this.validateBinding(binding)
+		const previous = await this.inspect()
+		if (previous.binding) {
+			if (harnessDigest(previous.binding) !== harnessDigest(binding))
+				throw new HarnessSessionError(
+					'binding-mismatch',
+					'Native session binding changed on reconnect.',
+				)
+			return
+		}
+		await this.append({
+			type: 'session_started',
+			projectId: this.scope.projectId,
+			tenantId: this.scope.tenantId,
+			topicId: this.scope.topicId,
+			cwd: this.scope.cwd,
+			agent: { id: `harness:${binding.engineId}`, name: binding.engineId, type: 'harness' },
+			harness: binding,
+			origin: { protocol: 'sdk' },
+		})
+	}
+	async append(draft: SessionRecordDraft) {
+		return this.log.append(await this.current(), draft)
+	}
+	async transition(harness: HarnessJournalTransition): Promise<void> {
+		await this.append({
+			type: 'session_updated',
+			harness: HarnessJournalTransitionSchema.parse(harness),
+		})
+	}
+	async event(
+		event: SessionEvent,
+		publish: (event: SessionEvent) => void | Promise<void>,
+	): Promise<void> {
+		if (isEphemeralEvent(event)) {
+			await this.current()
+			await publish(event)
+			return
+		}
+		const {
+			sessionId: _session,
+			v: _v,
+			seq: _seq,
+			generation: _gen,
+			lineage: _lineage,
+			...draft
+		} = event
+		const entry = await this.append(draft as SessionRecordDraft)
+		await publish({ ...event, v: 1, seq: entry.record.seq, generation: entry.record.gen })
+	}
+	async release(): Promise<void> {
+		if (this.heartbeat) clearInterval(this.heartbeat)
+		this.heartbeat = undefined
+		await this.renewals
+		if (!this.leaseToken) return
+		await this.log.release(this.leaseToken)
+		this.leaseToken = undefined
+	}
+}

package/src/runtime/harness-session/saved-view.ts

@@ -0,0 +1,122 @@
+import type { ToolResultView } from '../../types/tool/presentation.js'
+
+const MAX = 200
+
+type Fields = Record<string, unknown>
+
+function fields(input: unknown): Fields {
+	return input && typeof input === 'object' && !Array.isArray(input) ? (input as Fields) : {}
+}
+
+function text(value: unknown): string | undefined {
+	if (typeof value === 'string') return value
+	// An engine may hand a command as an argv list.
+	if (Array.isArray(value) && value.every((part) => typeof part === 'string'))
+		return value.join(' ')
+	return undefined
+}
+
+function pick(input: Fields, keys: readonly string[]): string | undefined {
+	for (const key of keys) {
+		const value = text(input[key])?.trim()
+		if (value) return value
+	}
+	return undefined
+}
+
+function oneLine(value: string): string {
+	const line =
+		value
+			.split(/\r?\n/)
+			.find((candidate) => candidate.trim())
+			?.trim() ?? ''
+	const points = Array.from(line)
+	return points.length > MAX ? `${points.slice(0, MAX - 1).join('')}…` : line
+}
+
+function baseName(path: string): string {
+	return path.split(/[\\/]/).filter(Boolean).pop() ?? path
+}
+
+function humanize(name: string): string {
+	// `server.tool` and `mcp__server__tool` name the tool by their last segment.
+	const last = name.split(/\.|__/).filter(Boolean).pop() ?? name
+	return (
+		last
+			.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+			.replace(/[_-]+/g, ' ')
+			.trim()
+			.toLowerCase() || 'tool'
+	)
+}
+
+function activity(label: string): ToolResultView {
+	return { kind: 'generic', label: oneLine(label), presentation: 'activity' }
+}
+
+const SHELL = new Set(['bash', 'shell', 'exec_command', 'run_command', 'local_shell', 'exec'])
+const READ = new Set(['read', 'view', 'read_file'])
+const EDIT = new Set(['edit', 'multiedit', 'notebookedit', 'apply_patch', 'str_replace'])
+const WRITE = new Set(['write', 'write_file'])
+const SEARCH = new Set(['grep', 'glob', 'search', 'find', 'web_search', 'websearch'])
+const AGENT = new Set(['task', 'agent', 'spawnagent', 'spawn_agent'])
+const WAIT = new Set(['wait', 'wait_agent', 'waitagent'])
+const STOP = new Set([
+	'close_agent',
+	'closeagent',
+	'interrupt_agent',
+	'interruptagent',
+	'kill_agent',
+	'killagent',
+])
+const TASKS = new Set([
+	'todowrite',
+	'todo_write',
+	'update_plan',
+	'taskcreate',
+	'taskupdate',
+	'tasklist',
+	'taskget',
+])
+
+/**
+ * The label-only view a saved conversation keeps for an engine's own tool.
+ * Engines send their own names, so this is a name map with one fallback:
+ * an unknown tool is named, never called a saved action.
+ */
+export function engineSavedView(name: string, input: unknown): ToolResultView {
+	const args = fields(input)
+	const key = name.toLowerCase()
+	if (SHELL.has(key)) {
+		const command = pick(args, ['command', 'cmd'])
+		return command
+			? { kind: 'terminal', command: oneLine(command), output: '' }
+			: activity('Ran command')
+	}
+	if (READ.has(key)) {
+		const path = pick(args, ['file_path', 'path'])
+		return activity(path ? `Read ${baseName(path)}` : 'Read a file')
+	}
+	if (EDIT.has(key)) {
+		const path = pick(args, ['file_path', 'path', 'notebook_path'])
+		return activity(path ? `Edited ${baseName(path)}` : 'Edited files')
+	}
+	if (WRITE.has(key)) {
+		const path = pick(args, ['file_path', 'path'])
+		return activity(path ? `Wrote ${baseName(path)}` : 'Wrote a file')
+	}
+	if (SEARCH.has(key)) {
+		const subject = pick(args, ['pattern', 'query', 'q'])
+		return activity(subject ? `Searched for ${subject}` : 'Searched')
+	}
+	if (AGENT.has(key)) {
+		const type = pick(args, ['subagent_type', 'agent_type', 'type'])
+		const about = pick(args, ['description'])
+		const head = type ? `Ran agent ${type}` : 'Ran agent'
+		return activity(about ? `${head} · ${about}` : head)
+	}
+	if (WAIT.has(key)) return activity('Waited for agent')
+	if (STOP.has(key)) return activity('Stopped agent')
+	if (TASKS.has(key)) return activity('Updated tasks')
+	return activity(`Used ${humanize(name)}`)
+}

package/src/runtime/jobs/awaited-jobs.ts

@@ -35,7 +35,8 @@ export interface DeliverableJobExits {
  * job registry instead of the task gateway.
  *
  * **Intent is stated, never inferred.** A job is only outstanding here once
- * `wait_for_job` named it (see {@link expect}); job existence means nothing.
+ * the exit mode of `wait_for_job` named it (see {@link expect}); an output
+ * readiness observation and job existence mean nothing here.
  * That is the same distinction `CompletionInbox.expect` draws for a
  * background task, and it is what keeps a dev server or a file watcher —
  * started precisely so it would keep running — from holding every turn of the