@namzu/sdk 43.0.0 → 44.1.0

package/src/run/index.ts

@@ -1,42 +0,0 @@
-export { RunPersistence } from '../manager/run/persistence.js'
-
-export { RunDiskStore } from '../store/run/disk.js'
-
-export { createRunReporter } from './reporter.js'
-export type { RunReporter } from './reporter.js'
-
-export { DEFAULT_DRAIN_PAGE_SIZE, drainRuns } from './drain.js'
-export type { DrainFailure, DrainRun, DrainRunsParams, DrainRunsResult } 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 { RUN_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/run/json-claim-verifier.ts

@@ -1,298 +0,0 @@
-import { createHash, randomUUID } from 'node:crypto'
-import { performance } from 'node:perf_hooks'
-import type { RunId } from '../types/ids/index.js'
-import type { AnswerReviewContext } from '../types/run/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 runId: RunId
-	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 runId: RunId
-	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 runId: RunId
-	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 runId: RunId
-	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, 'runId' | '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, runId, 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 runId !== 'string' ||
-		!runId ||
-		typeof observe !== 'function'
-	)
-		throw new Error('JSON claim verification requires a scope, run 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.runId !== runId ||
-				!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,
-						runId,
-						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.runId !== runId ||
-						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, runId, 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/run/memory-promoter.ts

@@ -1,147 +0,0 @@
-/**
- * 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 { createHash } from 'node:crypto'
-import type { MemoryStore } from '../types/memory/index.js'
-import type { PromoteMemory, RunMemoryCandidate } from '../types/run/memory-promotion.js'
-
-/**
- * The categories that make a run 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 run
- * 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 RunMemoryCandidate, string])[]
-
-/** Tag every record this promoter writes, so a host can find or prune them. */
-export const RUN_MEMORY_TAG = 'run-memory'
-
-export interface MemoryPromoterOptions {
-	/** Where records go. The same store `save_memory` writes through. */
-	readonly store: MemoryStore
-	/**
-	 * Extra tags on every record, beyond {@link RUN_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: RunMemoryCandidate,
-	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: RunMemoryCandidate,
-	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 run, not a
-	// complete one.
-	const evicted = Object.entries(candidate.evicted).filter(([, n]) => n > 0)
-	if (evicted.length > 0) {
-		body.push(
-			`## Dropped during the run\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 run 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 = [RUN_MEMORY_TAG, ...(options.tags ?? [])]
-
-	return async (candidate: RunMemoryCandidate): 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 = createHash('sha256').update(JSON.stringify(sections)).digest('hex')
-		const knowledgeTag = `knowledge:${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.
-		const existing = await options.store.list({
-			tags: [...tags, knowledgeTag],
-		})
-		for (const entry of existing.entries) {
-			const full = await options.store.get(entry.id)
-			if (full?.metadata?.source === RUN_MEMORY_TAG && full.metadata.knowledgeDigest === digest)
-				return
-		}
-
-		await options.store.create({
-			title: candidate.task.trim() || `Run ${candidate.runId}`,
-			summary: summarize(sections),
-			content: render(candidate, sections),
-			tags: [...tags, knowledgeTag],
-			format: 'markdown',
-			// The run id, so a record can be traced back to the run that formed
-			// it. Evidence rather than decoration: without it a surprising
-			// memory cannot be checked against what actually happened.
-			metadata: {
-				runId: candidate.runId,
-				source: RUN_MEMORY_TAG,
-				knowledgeDigest: digest,
-				verification: 'unverified',
-			},
-		})
-	}
-}