@namzu/sdk 38.1.0 → 39.0.0

package/src/manager/resident/history.ts

@@ -0,0 +1,312 @@
+import { z } from 'zod'
+import type { ResidentAgendaState } from './agenda.js'
+import { ResidentHistoryPageLimit, type ResidentHistoryReadBudget } from './history-disk.js'
+
+const SCAN_BYTES = 8 * 1024 * 1024
+const SCAN_REVISIONS = 32
+const TEXT_PAGE_CHARS = 6_000
+
+/** @experimental Host-bound historical scope; the upper revision never advances implicitly. */
+export interface ResidentHistoryScope {
+	readonly tenantId: string
+	readonly agentKey: string
+	readonly pursuitId: string
+	readonly throughRevision: number
+}
+
+/** @experimental Revision plus part identifies retained text within one pursuit. */
+export interface ResidentHistoryAddress {
+	readonly revision: number
+	readonly part: number
+}
+
+/** @experimental Summary or accepted wake input from a settled historical step. */
+export interface ResidentHistoryMatch extends ResidentHistoryAddress {
+	readonly step: number
+	readonly claimId: string
+	readonly kind: 'wait' | 'complete' | 'blocked'
+	readonly source: 'summary' | 'wake'
+	readonly excerpt: string
+	readonly matchingParts: readonly number[]
+}
+
+/** @experimental Empty query browses recent steps; cursor is the next inclusive revision. */
+export interface ResidentHistorySearchOptions {
+	/** Optional per-call ceiling, 1 byte–8 MiB. Defaults to 8 MiB. */
+	readonly maxReadBytes?: number
+	readonly query?: string
+	readonly cursor?: number
+	readonly limit?: number
+}
+
+/** @experimental Counts describe this page, not the whole history. */
+export interface ResidentHistorySearchResult {
+	readonly matches: readonly ResidentHistoryMatch[]
+	readonly nextCursor: number | null
+	readonly scannedRevisions: number
+	readonly scannedBytes: number
+	readonly unavailableRevisions: readonly number[]
+	readonly incomplete: boolean
+}
+
+/** @experimental Use the returned nextOffset to continue exact Unicode-safe text. */
+export interface ResidentHistoryReadOptions extends ResidentHistoryAddress {
+	readonly offset?: number
+	/** Optional per-call ceiling, 1 byte–8 MiB. Defaults to 8 MiB. */
+	readonly maxReadBytes?: number
+}
+
+/** @experimental A recorded claim remains historical evidence, not proof of current validity. */
+export interface ResidentHistoryText extends ResidentHistoryAddress {
+	readonly step: number
+	readonly claimId: string
+	readonly kind: 'wait' | 'complete' | 'blocked'
+	readonly source: 'summary' | 'wake'
+	readonly receivedAt?: number
+	readonly text: string
+	readonly offset: number
+	readonly totalChars: number
+	readonly nextOffset: number | null
+}
+
+/** @experimental Null with unavailable revisions means unreadable evidence, not proven absence. */
+export interface ResidentHistoryReadResult {
+	readonly entry: ResidentHistoryText | null
+	readonly scannedRevisions: number
+	readonly scannedBytes: number
+	readonly unavailableRevisions: readonly number[]
+}
+
+/** @experimental A backend must enforce its bound scope and bounded reads. */
+export interface ResidentHistorySource {
+	readonly scope: ResidentHistoryScope
+	search(
+		options?: ResidentHistorySearchOptions,
+		signal?: AbortSignal,
+	): Promise<ResidentHistorySearchResult>
+	read(
+		options: ResidentHistoryReadOptions,
+		signal?: AbortSignal,
+	): Promise<ResidentHistoryReadResult>
+}
+
+type LoadRevision = (
+	revision: number,
+	budget: ResidentHistoryReadBudget,
+) => Promise<ResidentAgendaState>
+interface Part {
+	source: 'summary' | 'wake'
+	text: string
+	receivedAt?: number
+}
+interface Episode {
+	step: number
+	claimId: string
+	kind: 'wait' | 'complete' | 'blocked'
+	parts: Part[]
+}
+
+function episode(
+	before: ResidentAgendaState | null,
+	after: ResidentAgendaState | null,
+	id: string,
+): Episode | null {
+	const previous = before?.pursuits.find((p) => p.id === id)?.state
+	const current = after?.pursuits.find((p) => p.id === id)?.state
+	if (
+		!before ||
+		!after ||
+		!previous ||
+		!current ||
+		previous.phase !== 'running' ||
+		!previous.claimId ||
+		current.phase === 'running' ||
+		current.claimId !== null ||
+		current.summary === null ||
+		current.stepsAdmitted !== previous.stepsAdmitted ||
+		current.revision !== previous.revision + 1
+	)
+		return null
+	return {
+		step: current.stepsAdmitted,
+		claimId: previous.claimId,
+		kind: current.phase === 'waiting' ? 'wait' : current.phase,
+		parts: [
+			{ source: 'summary', text: current.summary },
+			...(previous.wakeEvidence ?? []).map((entry) => ({
+				source: 'wake' as const,
+				text: entry.reason,
+				receivedAt: entry.receivedAt,
+			})),
+		],
+	}
+}
+
+function boundary(text: string, offset: number): boolean {
+	const current = text.charCodeAt(offset)
+	const previous = text.charCodeAt(offset - 1)
+	return !(current >= 0xdc00 && current <= 0xdfff && previous >= 0xd800 && previous <= 0xdbff)
+}
+
+function textSlice(text: string, offset: number, maxChars: number): string {
+	let end = Math.min(text.length, offset + maxChars)
+	if (!boundary(text, end)) end--
+	return text.slice(offset, end)
+}
+
+/** Internal disk adapter. Other backends may implement ResidentHistorySource directly. */
+export function createResidentHistorySource(
+	scopeInput: ResidentHistoryScope,
+	identity: { identity: string; objective: string },
+	load: LoadRevision,
+): ResidentHistorySource {
+	const scope = Object.freeze({ ...scopeInput })
+	const expected = { ...identity }
+	const revisionSchema = z.number().int().min(1).max(scope.throughRevision).safe()
+	function page(signal: AbortSignal | undefined, requestedBytes: number | undefined) {
+		const limit = z
+			.number()
+			.int()
+			.min(1)
+			.max(SCAN_BYTES)
+			.parse(requestedBytes ?? SCAN_BYTES)
+		const budget: ResidentHistoryReadBudget = { remaining: limit, bytesRead: 0, signal }
+		const unavailable = new Set<number>()
+		let scanned = 0
+		const cache = new Map<number, ResidentAgendaState | null>()
+		return {
+			budget,
+			async load(revision: number) {
+				signal?.throwIfAborted()
+				if (cache.has(revision)) return cache.get(revision) ?? null
+				if (scanned >= SCAN_REVISIONS) throw new ResidentHistoryPageLimit()
+				scanned++
+				let record: ResidentAgendaState | null = null
+				try {
+					record = await load(revision, budget)
+					const pursuit = record.pursuits.find((p) => p.id === scope.pursuitId)
+					if (
+						record.revision !== revision ||
+						record.tenantId !== scope.tenantId ||
+						record.agentKey !== scope.agentKey ||
+						(pursuit &&
+							(pursuit.state.identity !== expected.identity ||
+								pursuit.state.objective !== expected.objective))
+					)
+						throw new Error('History identity does not match its bound pursuit.')
+				} catch (error) {
+					signal?.throwIfAborted()
+					if (error instanceof ResidentHistoryPageLimit) throw error
+					unavailable.add(revision)
+					record = null
+				}
+				// Adjacent revisions are reused on the next scan iteration, without
+				// keeping the whole archive in memory.
+				if (cache.size >= 2) cache.delete(cache.keys().next().value as number)
+				cache.set(revision, record)
+				return record
+			},
+			counts: () => ({
+				scannedRevisions: scanned,
+				scannedBytes: budget.bytesRead,
+				unavailableRevisions: [...unavailable],
+			}),
+		}
+	}
+	return Object.freeze({
+		scope,
+		async search(options: ResidentHistorySearchOptions = {}, signal?: AbortSignal) {
+			signal?.throwIfAborted()
+			const query = z
+				.string()
+				.max(256)
+				.parse(options.query ?? '')
+			const limit = z
+				.number()
+				.int()
+				.min(1)
+				.max(8)
+				.parse(options.limit ?? 5)
+			let revision = revisionSchema.parse(options.cursor ?? scope.throughRevision)
+			const reader = page(signal, options.maxReadBytes)
+			const matches: ResidentHistoryMatch[] = []
+			while (revision >= 2 && matches.length < limit) {
+				let found: Episode | null
+				try {
+					const after = await reader.load(revision)
+					const before = await reader.load(revision - 1)
+					found = episode(before, after, scope.pursuitId)
+				} catch (error) {
+					if (!(error instanceof ResidentHistoryPageLimit)) throw error
+					break
+				}
+				if (found) {
+					const matchingParts = found.parts.flatMap((part, index) =>
+						part.text.includes(query) ? [index] : [],
+					)
+					const part = matchingParts[0]
+					const matched = part === undefined ? undefined : found.parts[part]
+					if (matched && part !== undefined) {
+						let start = Math.max(0, matched.text.indexOf(query) - 120)
+						if (!boundary(matched.text, start)) start--
+						matches.push({
+							revision,
+							part,
+							step: found.step,
+							claimId: found.claimId,
+							kind: found.kind,
+							source: matched.source,
+							excerpt: textSlice(matched.text, start, 512),
+							matchingParts,
+						})
+					}
+				}
+				revision--
+			}
+			const nextCursor = revision >= 2 ? revision : null
+			const counts = reader.counts()
+			return {
+				matches,
+				nextCursor,
+				...counts,
+				incomplete: nextCursor !== null || counts.unavailableRevisions.length > 0,
+			}
+		},
+		async read(options: ResidentHistoryReadOptions, signal?: AbortSignal) {
+			const revision = revisionSchema.parse(options.revision)
+			const part = z.number().int().min(0).max(16).parse(options.part)
+			const offset = z
+				.number()
+				.int()
+				.nonnegative()
+				.safe()
+				.parse(options.offset ?? 0)
+			const reader = page(signal, options.maxReadBytes)
+			const after = await reader.load(revision)
+			const before = revision >= 2 ? await reader.load(revision - 1) : null
+			const found = episode(before, after, scope.pursuitId)
+			const selected = found?.parts[part]
+			if (!selected || !found) return { entry: null, ...reader.counts() }
+			if (offset > selected.text.length || !boundary(selected.text, offset))
+				throw new Error('Invalid retained text offset; use nextOffset from the previous page.')
+			const text = textSlice(selected.text, offset, TEXT_PAGE_CHARS)
+			const end = offset + text.length
+			return {
+				entry: {
+					revision,
+					part,
+					step: found.step,
+					claimId: found.claimId,
+					kind: found.kind,
+					source: selected.source,
+					...(selected.receivedAt !== undefined ? { receivedAt: selected.receivedAt } : {}),
+					text,
+					offset,
+					totalChars: selected.text.length,
+					nextOffset: end < selected.text.length ? end : null,
+				},
+				...reader.counts(),
+			}
+		},
+	})
+}

package/src/manager/resident/host.ts

@@ -0,0 +1,356 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+import type { ResidentAgendaState, ResidentAgendaStore, ResidentPursuit } from './agenda.js'
+import {
+	type ResidentObservation,
+	type ResidentSelection,
+	type ResidentSelector,
+	residentObservationSchema,
+} from './initiative.js'
+import { type ResidentLearningState, freezeResidentLearning } from './learning.js'
+import { type ResidentStep, stepResident } from './loop.js'
+import { type ResidentMessageInput, residentMessageInputSchema } from './outbox.js'
+import { ResidentConflictError, type ResidentDecision, residentDecisionSchema } from './store.js'
+
+/** @experimental Host result describes execution, not external-effect rollback. */
+export interface ResidentHostResult {
+	readonly status: 'idle' | 'paused' | 'unresolved' | 'cancelled' | 'limit' | 'contended'
+	readonly stepsSettled: number
+	readonly nextWakeAt: number | null
+	readonly selection?: ResidentSelection
+}
+
+/** @experimental Explicit authorization to drive a finite number of background steps. */
+export interface ResidentHostRunOptions {
+	readonly signal: AbortSignal
+	readonly maxSteps: number
+	/** Maximum single idle wait; with keepAlive, also bounds local agenda polling. */
+	readonly maxIdleMs?: number
+	/** Keep waiting for useful work within this invocation's finite step cap. Default false. */
+	readonly keepAlive?: boolean
+}
+
+/** @experimental Immutable context from the agenda snapshot that authorized this admission. */
+export interface ResidentStepContext {
+	readonly agendaRevision: number
+	readonly learning?: ResidentLearningState
+}
+
+/** @experimental A developer callback may bind a different SDK run for each pursuit. */
+export type ResidentPursuitStep = (
+	pursuit: ResidentPursuit,
+	signal: AbortSignal,
+) => ReturnType<ResidentStep>
+
+/** @experimental Context-aware callback; existing two-argument steps remain assignable. */
+export type ResidentContextualStep = (
+	pursuit: ResidentPursuit,
+	signal: AbortSignal,
+	context: ResidentStepContext,
+) => ReturnType<ResidentStep>
+
+/** @experimental Inspect actual outcomes and resource receipts independently of model prose. */
+export type ResidentObserver = (
+	pursuit: ResidentPursuit,
+	decision: ResidentDecision,
+	signal: AbortSignal,
+) => Promise<ResidentObservation>
+
+/** @experimental Host validates content and destination; null means no communication. */
+export type ResidentMessageFactory = (
+	pursuit: ResidentPursuit,
+	decision: ResidentDecision,
+	signal: AbortSignal,
+) => Promise<ResidentMessageInput | null>
+
+/** @experimental Opt-in local selection, observed settlement and atomic outbound intent. */
+export interface ResidentHostOptions {
+	readonly select?: ResidentSelector
+	readonly observe?: ResidentObserver
+	readonly prepareMessage?: ResidentMessageFactory
+	/** Bind approved learning to the exact admission snapshot. Default false. */
+	readonly learning?: boolean
+}
+
+/**
+ * @experimental Local driver for one durable agenda. Shared agenda admission
+ * prevents overlapping pursuits across processes. Notifications are local;
+ * opt-in keepAlive also rereads durable state on bounded idle timers.
+ */
+export class ResidentHost {
+	private controller: AbortController | undefined
+	private active: Promise<ResidentHostResult> | undefined
+	private idle: AbortController | undefined
+	private generation = 0
+	private controls: Promise<void> = Promise.resolve()
+	private controlsPending = 0
+	private readonly options: ResidentHostOptions
+
+	constructor(
+		private readonly agenda: ResidentAgendaStore,
+		private readonly step: ResidentContextualStep,
+		options: ResidentHostOptions = {},
+	) {
+		if (options.learning !== undefined && typeof options.learning !== 'boolean')
+			throw new TypeError('Resident learning must be explicitly enabled with a boolean.')
+		if ((options.select || options.learning) && !agenda.executionAt)
+			throw new TypeError('Resident selection or learning requires atomic executionAt support.')
+		if (options.observe && !agenda.settleObserved)
+			throw new TypeError('Resident observation requires atomic settleObserved support.')
+		if (options.prepareMessage && !agenda.settleWithMessage)
+			throw new TypeError('Resident messages require atomic settleWithMessage support.')
+		this.options = Object.freeze({ ...options })
+	}
+
+	/** Interrupt local idle waiting after the host learns of new durable state. */
+	notify(): void {
+		this.generation++
+		this.idle?.abort()
+	}
+
+	private async snapshot(): Promise<ResidentAgendaState> {
+		const state = await this.agenda.read()
+		if (!state) throw new Error('Create the resident agenda before running the host.')
+		return state
+	}
+
+	private async paused(value: boolean): Promise<void> {
+		for (let attempt = 0; attempt < 8; attempt++) {
+			const state = await this.snapshot()
+			if (state.paused === value) return
+			try {
+				await this.agenda.setPaused(state, value)
+				return
+			} catch (error) {
+				if (!(error instanceof ResidentConflictError) || attempt === 7) throw error
+			}
+		}
+	}
+
+	private control(update: () => Promise<void>): Promise<void> {
+		this.controlsPending++
+		const pending = this.controls.then(update)
+		this.controls = pending.catch(() => {})
+		return pending.finally(() => {
+			this.controlsPending--
+		})
+	}
+
+	/**
+	 * Signal current work and durably close future admission. Resolving this method
+	 * is NOT quiescence: await the run promise before claiming the callback stopped.
+	 * An interrupted admitted pursuit remains unresolved until reconciled explicitly.
+	 */
+	async pause(): Promise<void> {
+		this.controller?.abort()
+		this.notify()
+		await this.control(() => this.paused(true))
+	}
+
+	/** Reauthorize future work only after this host's previous invocation drained. */
+	async resume(): Promise<void> {
+		if (this.controlsPending) throw new Error('Wait for pending resident controls before resuming.')
+		if (this.active)
+			throw new Error('Wait for the active resident invocation to drain before resuming.')
+		await this.control(() => this.paused(false))
+		this.notify()
+	}
+
+	/** Persist fresh evidence and interrupt this host's idle timer. */
+	async wake(id: string, reason: string): Promise<void> {
+		const state = await this.snapshot()
+		const pursuit = state.pursuits.find((p) => p.id === id)
+		if (!pursuit) throw new Error('Unknown resident pursuit.')
+		await this.agenda.wake(id, pursuit.state, reason, Date.now())
+		this.notify()
+	}
+
+	run(options: ResidentHostRunOptions): Promise<ResidentHostResult> {
+		if (this.controlsPending) throw new Error('Wait for pending resident controls before running.')
+		if (this.active) throw new Error('A resident host invocation is already active.')
+		const maxIdleMs = options.maxIdleMs ?? 60_000
+		const keepAlive = options.keepAlive ?? false
+		if (options.keepAlive !== undefined && typeof options.keepAlive !== 'boolean')
+			throw new TypeError('Resident keepAlive must be explicitly enabled with a boolean.')
+		if (
+			!Number.isSafeInteger(options.maxSteps) ||
+			options.maxSteps < 1 ||
+			!Number.isSafeInteger(maxIdleMs) ||
+			maxIdleMs < 0 ||
+			maxIdleMs > 2_147_483_647 ||
+			(keepAlive && maxIdleMs === 0)
+		)
+			throw new TypeError('Invalid resident host limits.')
+		const controller = new AbortController()
+		this.controller = controller
+		const signal = AbortSignal.any([controller.signal, options.signal])
+		this.active = this.drive(options.maxSteps, maxIdleMs, keepAlive, signal).finally(() => {
+			this.active = undefined
+			this.controller = undefined
+			this.idle = undefined
+		})
+		return this.active
+	}
+
+	private async drive(
+		maxSteps: number,
+		maxIdleMs: number,
+		keepAlive: boolean,
+		signal: AbortSignal,
+	): Promise<ResidentHostResult> {
+		let stepsSettled = 0
+		try {
+			while (true) {
+				signal.throwIfAborted()
+				const observed = this.generation
+				const state = await this.snapshot()
+				signal.throwIfAborted()
+				if (state.paused) return { status: 'paused', stepsSettled, nextWakeAt: null }
+				if (state.pursuits.some((p) => p.state.phase === 'running'))
+					return { status: 'unresolved', stepsSettled, nextWakeAt: null }
+				const waiting = state.pursuits.filter(
+					(p) => p.state.phase === 'waiting' && p.state.wakeAt !== null,
+				)
+				const now = Date.now()
+				// Fair, deterministic baseline; this is not model-authored initiative.
+				let due = waiting
+					.filter((p) => (p.state.wakeAt ?? 0) <= now)
+					.sort(
+						(a, b) =>
+							a.state.stepsAdmitted - b.state.stepsAdmitted ||
+							(a.state.wakeAt ?? 0) - (b.state.wakeAt ?? 0) ||
+							a.id.localeCompare(b.id),
+					)[0]
+				let selection: ResidentSelection | undefined
+				if (due && this.options.select) {
+					selection = this.options.select(state, now)
+					signal.throwIfAborted()
+					if (selection.agendaRevision !== state.revision)
+						throw new Error('Resident selector returned a stale agenda revision.')
+					if (selection.pursuitId === null) due = undefined
+					else {
+						const selectedId = selection.pursuitId
+						due = waiting.find((p) => p.id === selectedId && (p.state.wakeAt ?? 0) <= now)
+						if (!due) throw new Error('Resident selector chose an ineligible pursuit.')
+					}
+				}
+
+				if (due) {
+					const selected = due
+					const context: ResidentStepContext = Object.freeze({
+						agendaRevision: state.revision,
+						...(this.options.learning && state.learning
+							? { learning: freezeResidentLearning(state.learning) }
+							: {}),
+					})
+					const execution =
+						this.options.select || this.options.learning
+							? this.agenda.executionAt?.(selected.id, state)
+							: this.agenda.execution(selected.id)
+					if (!execution) throw new Error('Resident executionAt support was removed.')
+					const observe = this.options.observe
+					const prepareMessage = this.options.prepareMessage
+					const observedExecution =
+						observe || prepareMessage
+							? {
+									read: () => execution.read(),
+									claim: (...args: Parameters<typeof execution.claim>) => execution.claim(...args),
+									settle: async (
+										current: Parameters<typeof execution.settle>[0],
+										decision: ResidentDecision,
+										at: number,
+									) => {
+										const disposition = Object.freeze(residentDecisionSchema.parse(decision))
+										const observed = await observe?.(
+											{ ...selected, state: current },
+											disposition,
+											signal,
+										)
+										signal.throwIfAborted()
+										const observation = observe
+											? Object.freeze(residentObservationSchema.parse(observed))
+											: undefined
+										const prepared = await prepareMessage?.(
+											{ ...selected, state: current },
+											disposition,
+											signal,
+										)
+										signal.throwIfAborted()
+										const message =
+											prepareMessage && prepared !== null
+												? Object.freeze(residentMessageInputSchema.parse(prepared))
+												: null
+										if (message !== null) {
+											if (!this.agenda.settleWithMessage)
+												throw new Error('Resident settleWithMessage support was removed.')
+											return this.agenda.settleWithMessage(
+												selected.id,
+												current,
+												disposition,
+												message,
+												at,
+												observation,
+											)
+										}
+										if (observation) {
+											if (!this.agenda.settleObserved)
+												throw new Error('Resident settleObserved support was removed.')
+											return this.agenda.settleObserved(
+												selected.id,
+												current,
+												disposition,
+												observation,
+												at,
+											)
+										}
+										return execution.settle(current, disposition, at)
+									},
+								}
+							: execution
+					const result = await stepResident(
+						observedExecution,
+						(current, abort) => this.step({ ...selected, state: current }, abort, context),
+						signal,
+					)
+					if (result.status === 'idle')
+						return {
+							status: result.reason === 'unresolved' ? 'unresolved' : 'contended',
+							stepsSettled,
+							nextWakeAt: null,
+						}
+					stepsSettled++
+					if (stepsSettled >= maxSteps) return { status: 'limit', stepsSettled, nextWakeAt: null }
+					continue
+				}
+				const scheduled =
+					selection?.pursuitId === null
+						? waiting.filter((p) => (p.state.wakeAt ?? 0) > now)
+						: waiting
+				const nextWakeAt =
+					scheduled.length === 0 ? null : Math.min(...scheduled.map((p) => p.state.wakeAt ?? now))
+				if (observed !== this.generation) continue
+				if (!keepAlive && (nextWakeAt === null || nextWakeAt - now > maxIdleMs))
+					return { status: 'idle', stepsSettled, nextWakeAt, ...(selection ? { selection } : {}) }
+				const delay =
+					nextWakeAt === null
+						? maxIdleMs
+						: keepAlive
+							? Math.min(maxIdleMs, nextWakeAt - now)
+							: nextWakeAt - now
+				const idle = new AbortController()
+				this.idle = idle
+				try {
+					await sleep(Math.max(1, delay), undefined, {
+						signal: AbortSignal.any([signal, idle.signal]),
+					})
+				} catch (error) {
+					if (!idle.signal.aborted || signal.aborted) throw error
+				} finally {
+					if (this.idle === idle) this.idle = undefined
+				}
+			}
+		} catch (error) {
+			if (!signal.aborted) throw error
+			return { status: 'cancelled', stepsSettled, nextWakeAt: null }
+		}
+	}
+}