@namzu/sdk 42.0.2 → 44.0.0

package/src/turn/index.ts

@@ -0,0 +1,38 @@
+export { createTurnReporter } from './reporter.js'
+export type { TurnReporter } from './reporter.js'
+
+export { DEFAULT_DRAIN_PAGE_SIZE, drainParkedTurns } from './drain.js'
+export type { DrainFailure, DrainTurn, DrainTurnsParams, DrainTurnsResult } from './drain.js'
+export {
+	DEFAULT_GATE_MAX_RETRIES,
+	DEFAULT_GATE_OUTPUT_CHARS,
+	DEFAULT_GATE_TIMEOUT_MS,
+	clipOutput,
+	createCommandGate,
+} from './command-gate.js'
+export type { CommandGateOptions, GateExec } from './command-gate.js'
+export {
+	FINGERPRINT_MAX_BYTES,
+	FINGERPRINT_TIMEOUT_MS,
+	fingerprintWorkspace,
+} from './workspace-fingerprint.js'
+export type { FingerprintExec, WorkspaceFingerprintOptions } from './workspace-fingerprint.js'
+
+export { checkLimitsDetailed, buildLimitConfig } from './LimitChecker.js'
+export type { LimitCheckerState, LimitCheckResult } from './LimitChecker.js'
+
+export { SESSION_MEMORY_TAG, createMemoryPromoter } from './memory-promoter.js'
+export type { MemoryPromoterOptions } from './memory-promoter.js'
+export { createMemoryRecallStep } from './memory-recall.js'
+export type { MemoryRecallOptions } from './memory-recall.js'
+export { createJsonClaimVerifier } from './json-claim-verifier.js'
+export type {
+	JsonClaimValue,
+	JsonClaimRequirement,
+	JsonClaimReadRequest,
+	JsonClaimObservation,
+	JsonClaimReceipt,
+	JsonClaimVerdict,
+	JsonClaimVerifierOptions,
+	JsonClaimVerifier,
+} from './json-claim-verifier.js'

package/src/turn/json-claim-verifier.ts

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+import type { TurnId } from '../types/ids/index.js'
+import type { AnswerReviewContext } from '../types/session/answer-review.js'
+
+/** Numbers are restricted to safe integers; use strings for exact decimal values. */
+export type JsonClaimValue = string | number | boolean | null
+
+export interface JsonClaimRequirement {
+	readonly id: string
+	/** Host-selected source identifier, never an address supplied by the candidate. */
+	readonly source: string
+	/** RFC 6901 pointer to a scalar in the complete JSON document. */
+	readonly pointer: string
+	/** Optional postcondition in addition to candidate/source equality. */
+	readonly expected?: JsonClaimValue
+}
+
+export interface JsonClaimReadRequest {
+	readonly scope: string
+	readonly turnId: TurnId
+	readonly iteration: number
+	readonly requestId: string
+	readonly startedAt: number
+	/** Remaining total allowance. The host must bound capture, not only the returned buffer. */
+	readonly maxBytes: number
+	readonly signal: AbortSignal
+}
+
+export interface JsonClaimObservation {
+	readonly scope: string
+	readonly turnId: TurnId
+	readonly iteration: number
+	readonly requestId: string
+	readonly source: string
+	readonly observedAt: number
+	readonly complete: boolean
+	readonly kind: 'current' | 'historical'
+	readonly bytes: Uint8Array
+}
+
+export interface JsonClaimReceipt {
+	readonly scope: string
+	readonly turnId: TurnId
+	readonly iteration: number
+	readonly claims: Readonly<Record<string, JsonClaimValue>>
+	readonly observations: readonly {
+		readonly source: string
+		readonly requestId: string
+		readonly observedAt: number
+		readonly bytes: number
+		readonly sha256: string
+	}[]
+}
+
+export type JsonClaimVerdict =
+	| { readonly accept: true; readonly receipt: JsonClaimReceipt }
+	| { readonly accept: false; readonly feedback: string }
+
+export interface JsonClaimVerifierOptions {
+	/** Host-owned authorization scope, including the admitted revision/claim where applicable. */
+	readonly scope: string
+	readonly turnId: TurnId
+	readonly requirements: readonly JsonClaimRequirement[]
+	/**
+	 * Trusted, read-only adapter. Enforce access, capture bounds and cancellation;
+	 * observe during this call. A matching envelope is not authentication against
+	 * a dishonest adapter. Do not replay an action or relabel an archive as current.
+	 */
+	readonly observe: (source: string, request: JsonClaimReadRequest) => Promise<JsonClaimObservation>
+	/** Total captured source bytes per verification; default 1 MiB, at most 8 MiB. */
+	readonly maxBytes?: number
+	/** Whole verification deadline; default 2 seconds, at most 30 seconds. */
+	readonly timeoutMs?: number
+}
+
+export interface JsonClaimVerifier {
+	/** False while an observer is outstanding, including after timeout/cancellation. */
+	isDrained(): boolean
+	/** No success cache. Every call observes the configured sources again. */
+	verify(
+		claims: unknown,
+		context: Pick<AnswerReviewContext, 'turnId' | 'iteration' | 'signal'>,
+	): Promise<JsonClaimVerdict>
+}
+
+function scalar(value: unknown): value is JsonClaimValue {
+	return (
+		value === null ||
+		typeof value === 'boolean' ||
+		(typeof value === 'string' && value.length <= 2_000) ||
+		(typeof value === 'number' && Number.isSafeInteger(value))
+	)
+}
+
+function reject(reason: string): JsonClaimVerdict {
+	return {
+		accept: false,
+		feedback: `Claim verification failed: ${reason} Do not claim verified completion. Correct the claims using a permitted observation, or report that completion is unavailable.`,
+	}
+}
+
+function pointerParts(pointer: string): string[] {
+	if (pointer === '') return []
+	if (!pointer.startsWith('/') || pointer.length > 512 || /~(?:[^01]|$)/u.test(pointer))
+		throw new Error('Invalid JSON claim pointer.')
+	return pointer
+		.slice(1)
+		.split('/')
+		.map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+}
+
+function select(document: unknown, parts: readonly string[]): unknown {
+	let value = document
+	for (const part of parts) {
+		if (value === null || typeof value !== 'object' || !Object.hasOwn(value, part)) return undefined
+		if (Array.isArray(value) && !/^(0|[1-9]\d*)$/u.test(part)) return undefined
+		value = (value as Record<string, unknown>)[part]
+	}
+	return value
+}
+
+/**
+ * Compare explicit candidate fields with fresh, host-authorized JSON observations.
+ * This does not judge prose or prove the broader task complete. A receipt describes
+ * observation time, not an atomic snapshot or continuing truth after the read.
+ */
+export function createJsonClaimVerifier(options: JsonClaimVerifierOptions): JsonClaimVerifier {
+	const { scope, turnId, observe } = options
+	const maxBytes = options.maxBytes ?? 1_048_576
+	const timeoutMs = options.timeoutMs ?? 2_000
+	if (
+		typeof scope !== 'string' ||
+		!scope ||
+		scope.length > 2_000 ||
+		typeof turnId !== 'string' ||
+		!turnId ||
+		typeof observe !== 'function'
+	)
+		throw new Error('JSON claim verification requires a scope, turn ID and observer.')
+	if (
+		!Number.isSafeInteger(maxBytes) ||
+		maxBytes < 1 ||
+		maxBytes > 8_388_608 ||
+		!Number.isSafeInteger(timeoutMs) ||
+		timeoutMs < 1 ||
+		timeoutMs > 30_000
+	)
+		throw new Error('Invalid JSON claim verification bounds.')
+	if (!options.requirements.length || options.requirements.length > 32)
+		throw new Error('JSON claim verification requires 1–32 requirements.')
+	const ids = new Set<string>()
+	const requirements = options.requirements.map((item) => {
+		if (
+			!/^[a-zA-Z][a-zA-Z0-9_-]{0,99}$/u.test(item.id) ||
+			ids.has(item.id) ||
+			typeof item.source !== 'string' ||
+			!item.source ||
+			item.source.length > 512 ||
+			typeof item.pointer !== 'string' ||
+			(Object.hasOwn(item, 'expected') && !scalar(item.expected))
+		)
+			throw new Error('Invalid or duplicate JSON claim requirement.')
+		ids.add(item.id)
+		return { ...item, parts: pointerParts(item.pointer) }
+	})
+	let active = false
+	let pending = 0
+	return {
+		isDrained: () => !active && pending === 0,
+		async verify(claims, context) {
+			context.signal?.throwIfAborted()
+			if (
+				context.turnId !== turnId ||
+				!Number.isSafeInteger(context.iteration) ||
+				context.iteration < 0
+			)
+				return reject('The review belongs to a different run or invalid iteration.')
+			if (active || pending) return reject('A previous observation has not drained.')
+			if (
+				!claims ||
+				typeof claims !== 'object' ||
+				Array.isArray(claims) ||
+				Object.keys(claims).length !== requirements.length ||
+				Object.keys(claims).some((id) => !ids.has(id))
+			)
+				return reject('Supply exactly the configured claim IDs and scalar values.')
+			const values: Record<string, JsonClaimValue> = Object.create(null)
+			for (const item of requirements) {
+				if (!Object.hasOwn(claims, item.id)) return reject('A required claim is missing.')
+				const value = (claims as Record<string, unknown>)[item.id]
+				if (!scalar(value)) return reject(`Claim ${item.id} is not a supported scalar.`)
+				values[item.id] = value
+			}
+			active = true
+			const controller = new AbortController()
+			const expiresAt = performance.now() + timeoutMs
+			const ensureActive = () => {
+				// A synchronous adapter can delay timers; late bytes still cannot pass.
+				if (performance.now() >= expiresAt) controller.abort(new Error('Verification timed out.'))
+				controller.signal.throwIfAborted()
+			}
+			const onAbort = () => controller.abort(context.signal?.reason)
+			context.signal?.addEventListener('abort', onAbort, { once: true })
+			const timer = setTimeout(
+				() => controller.abort(new Error('Verification timed out.')),
+				timeoutMs,
+			)
+			const observations: JsonClaimReceipt['observations'][number][] = []
+			let remaining = maxBytes
+			let removeAbort: (() => void) | undefined
+			try {
+				for (const source of new Set(requirements.map((item) => item.source))) {
+					ensureActive()
+					if (remaining < 1) return reject('The source byte allowance is exhausted.')
+					const request = Object.freeze({
+						scope,
+						turnId,
+						iteration: context.iteration,
+						requestId: randomUUID(),
+						startedAt: Date.now(),
+						maxBytes: remaining,
+						signal: controller.signal,
+					})
+					pending++
+					const work = Promise.resolve()
+						.then(() => {
+							ensureActive()
+							return observe(source, request)
+						})
+						.finally(() => {
+							pending--
+						})
+					const aborted = new Promise<never>((_, fail) => {
+						const listener = () => fail(controller.signal.reason)
+						controller.signal.addEventListener('abort', listener, { once: true })
+						removeAbort = () => controller.signal.removeEventListener('abort', listener)
+					})
+					const observation = await Promise.race([work, aborted])
+					removeAbort?.()
+					ensureActive()
+					if (
+						!observation ||
+						observation.scope !== scope ||
+						observation.turnId !== turnId ||
+						observation.iteration !== context.iteration ||
+						observation.requestId !== request.requestId ||
+						observation.source !== source ||
+						observation.complete !== true ||
+						observation.kind !== 'current' ||
+						!Number.isSafeInteger(observation.observedAt) ||
+						observation.observedAt < request.startedAt ||
+						observation.observedAt > Date.now() ||
+						!(observation.bytes instanceof Uint8Array)
+					)
+						return reject('The observation is incomplete, historical or outside this review scope.')
+					if (observation.bytes.byteLength > remaining)
+						return reject('A source exceeded the byte allowance.')
+					const bytes = Buffer.from(observation.bytes)
+					remaining -= bytes.byteLength
+					const document: unknown = JSON.parse(
+						new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+					)
+					for (const item of requirements.filter((item) => item.source === source)) {
+						const actual = select(document, item.parts)
+						if (!scalar(actual) || actual !== values[item.id])
+							return reject(`Claim ${item.id} does not match the selected source field.`)
+						if (Object.hasOwn(item, 'expected') && actual !== item.expected)
+							return reject(`Claim ${item.id} does not satisfy the configured postcondition.`)
+					}
+					observations.push({
+						source,
+						requestId: request.requestId,
+						observedAt: observation.observedAt,
+						bytes: bytes.byteLength,
+						sha256: createHash('sha256').update(bytes).digest('hex'),
+					})
+				}
+				ensureActive()
+				return {
+					accept: true,
+					receipt: { scope, turnId, iteration: context.iteration, claims: values, observations },
+				}
+			} catch {
+				context.signal?.throwIfAborted()
+				return reject(
+					'A current source could not be fully observed and parsed within the deadline.',
+				)
+			} finally {
+				clearTimeout(timer)
+				removeAbort?.()
+				context.signal?.removeEventListener('abort', onAbort)
+				controller.abort()
+				active = false
+			}
+		},
+	}
+}

package/src/turn/memory-promoter.ts

@@ -0,0 +1,160 @@
+/**
+ * Select useful extracted claims for durable recall. Exact repeated claim sets
+ * are suppressed when already stored; archived claims are not reactivated.
+ * This deterministic filter does not verify truth or reconcile paraphrases.
+ */
+
+import {
+	KNOWLEDGE_TAG_PREFIX,
+	holdsKnowledgeDigest,
+	knowledgeDigest,
+} from '../store/memory/digest.js'
+import { SESSION_MEMORY_SOURCE } from '../store/memory/origin.js'
+import type { MemoryStore } from '../types/memory/index.js'
+import type { PromoteMemory, SessionMemoryCandidate } from '../types/session/memory-promotion.js'
+
+/**
+ * The categories that make a turn worth remembering.
+ *
+ * Ordered as they are rendered. `userRequirements` first because it is the
+ * most durable of the five — a constraint the user stated outlives the turn
+ * that heard it, whereas a discovery about a codebase expires when the
+ * codebase moves.
+ */
+const KNOWLEDGE = [
+	['userRequirements', 'What the user requires'],
+	['decisions', 'Decisions'],
+	['discoveries', 'Discoveries'],
+	['failures', 'What did not work'],
+	['environment', 'Environment'],
+] as const satisfies readonly (readonly [keyof SessionMemoryCandidate, string])[]
+
+/**
+ * Tag every record this promoter writes, so a host can find or prune them.
+ * Also its `metadata.source`, which keeps the record out of a Markdown
+ * store's generated index: a record written after every turn is not one
+ * anybody chose to load into every prompt.
+ */
+export const SESSION_MEMORY_TAG = SESSION_MEMORY_SOURCE
+
+export interface MemoryPromoterOptions {
+	/** Where records go. The same store `save_memory` writes through. */
+	readonly store: MemoryStore
+	/**
+	 * Extra tags on every record, beyond {@link SESSION_MEMORY_TAG}.
+	 *
+	 * A host running several agents against one store uses this to tell whose
+	 * memory is whose; without it a later search cannot.
+	 */
+	readonly tags?: readonly string[]
+	/**
+	 * Cap on entries rendered per category. Defaults to 20.
+	 *
+	 * The extractor already caps its lists, and this is the second cap for
+	 * the same reason the first exists: a record nobody will read is a record
+	 * that costs context every time it is retrieved.
+	 */
+	readonly maxPerCategory?: number
+}
+
+/** Everything the candidate knows, as `[heading, items]`, empties dropped. */
+function knowledge(
+	candidate: SessionMemoryCandidate,
+	cap: number,
+): readonly (readonly [string, readonly string[]])[] {
+	const out: (readonly [string, readonly string[]])[] = []
+	for (const [key, heading] of KNOWLEDGE) {
+		const items = [
+			...new Set((candidate[key] as readonly string[]).map((item) => item.trim()).filter(Boolean)),
+		]
+		if (items.length > 0) out.push([heading, items.slice(0, cap)])
+	}
+	return out
+}
+
+/** Carry actual claims into search results, with their category attribution. */
+function summarize(sections: readonly (readonly [string, readonly string[]])[]): string {
+	const text = sections.map(([heading, items]) => `${heading}: ${items[0]}`).join('; ')
+	return text.length <= 600 ? text : `${text.slice(0, 599).replace(/[\uD800-\uDBFF]$/, '')}…`
+}
+
+function render(
+	candidate: SessionMemoryCandidate,
+	sections: readonly (readonly [string, readonly string[]])[],
+): string {
+	const body = sections.map(
+		([heading, items]) => `## ${heading}\n\n${items.map((i) => `- ${i}`).join('\n')}`,
+	)
+	// The eviction counts, when there are any. Carried rather than hidden for
+	// the reason the candidate carries them: somebody reading this record
+	// should know they are reading a truncated account of the turn, not a
+	// complete one.
+	const evicted = Object.entries(candidate.evicted).filter(([, n]) => n > 0)
+	if (evicted.length > 0) {
+		body.push(
+			`## Dropped during the turn\n\n${evicted
+				.map(([category, n]) => `- ${category}: ${n} entr${n === 1 ? 'y' : 'ies'} evicted`)
+				.join('\n')}`,
+		)
+	}
+	if (candidate.files.length > 0) {
+		body.push(`## Files touched\n\n${candidate.files.map((f) => `- ${f}`).join('\n')}`)
+	}
+	return `# ${candidate.task}\n\n${body.join('\n\n')}\n`
+}
+
+/**
+ * Build a promoter that writes one record per turn that learned something.
+ *
+ * Never throws out to the runtime — but it does not swallow either: the
+ * runtime already catches and logs a promoter's failure at settle, and
+ * catching here as well would hide a broken store from the one place that
+ * reports it.
+ */
+export function createMemoryPromoter(options: MemoryPromoterOptions): PromoteMemory {
+	const cap = options.maxPerCategory ?? 20
+	if (!Number.isSafeInteger(cap) || cap < 1)
+		throw new Error('maxPerCategory must be a positive integer')
+	const tags = [SESSION_MEMORY_TAG, ...(options.tags ?? [])]
+
+	return async (candidate: SessionMemoryCandidate): Promise<void> => {
+		const sections = knowledge(candidate, cap)
+		// Nothing learned, nothing written. Not an empty record: a store full
+		// of rows describing runs that discovered nothing is a store whose
+		// search results are mostly noise, and the model reads that store.
+		if (sections.length === 0) return
+		const digest = knowledgeDigest(sections)
+		const knowledgeTag = `${KNOWLEDGE_TAG_PREFIX}${digest}`
+		// A prior exact claim, including one deliberately archived, need not be
+		// saved again. This is not a cross-process uniqueness guarantee: the
+		// store's individual operations are atomic, not this read/create pair.
+		if (
+			await holdsKnowledgeDigest(
+				options.store,
+				tags,
+				digest,
+				(metadata) => metadata?.source === SESSION_MEMORY_TAG,
+			)
+		)
+			return
+
+		await options.store.create({
+			title: candidate.task.trim() || `Turn ${candidate.turnId}`,
+			summary: summarize(sections),
+			content: render(candidate, sections),
+			tags: [...tags, knowledgeTag],
+			type: 'project',
+			format: 'markdown',
+			// The turn id, so a record can be traced back to the turn that formed
+			// it. Evidence rather than decoration: without it a surprising
+			// memory cannot be checked against what actually happened.
+			metadata: {
+				sessionId: candidate.sessionId,
+				turnId: candidate.turnId,
+				source: SESSION_MEMORY_TAG,
+				knowledgeDigest: digest,
+				verification: 'unverified',
+			},
+		})
+	}
+}