@namzu/sdk 38.1.0 → 39.0.0

package/src/types/run/prepare-step.ts

@@ -1,8 +1,28 @@
+import type { TokenUsage } from '../common/index.js'
 import type { RunId } from '../ids/index.js'
 import type { Message, UserMessage } from '../message/index.js'
 import type { ToolChoice } from '../provider/chat.js'
 import type { Skill } from '../skills/index.js'
 import type { StepResult } from './step.js'
+import type { StepProvenance } from './step.js'
+
+/** @experimental Bounded, tool-free inference shared by preparation and answer review. */
+export interface PreparationTextRequest {
+	readonly system: string
+	readonly prompt: string
+	/** Default 256; maximum 1,024. A provider limit, not a hard billing ceiling. */
+	readonly maxTokens?: number
+	/** Default and maximum 10,000ms, shortened by stage/run cancellation. */
+	readonly timeoutMs?: number
+	readonly signal?: AbortSignal
+}
+
+/** @experimental Side-call usage also contributes to the owning run's totals. */
+export interface PreparationTextResult {
+	readonly text: string
+	readonly usage: TokenUsage
+	readonly servedBy: StepProvenance
+}
 
 /**
  * What the loop knows before it calls the model again.
@@ -17,6 +37,25 @@ import type { StepResult } from './step.js'
  */
 export interface PrepareStepContext {
 	readonly runId: RunId
+	/**
+	 * Optional run-owned inference for context preparation. At most one call per
+	 * stage invocation; cannot be called after that stage returns. Uses the run's
+	 * metered provider/fallback chain and the model selected by preceding stages.
+	 * Only supplied text is sent (12,000 characters total); no tools or history
+	 * are implicitly attached. Returned text is bounded to 8,192 characters.
+	 * Absent in beforeStep and in hosts which do not supply this capability.
+	 */
+	readonly generateText?: (request: PreparationTextRequest) => Promise<PreparationTextResult>
+	/**
+	 * Optional writer-bound snapshot of this invocation's completed events.
+	 * Never discovers other runs or repeats tools. Unsupported stores return
+	 * undefined; cancellation or a settled invocation rejects capture. A local
+	 * signal can shorten, never extend, the run's lifetime.
+	 */
+	readonly captureRunEvidence?: (
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	) => Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined>
 	/** 1-based, matching the iteration number in events and traces. */
 	readonly stepNumber: number
 	/** Full history as it stands, so a decision can read what happened. */
@@ -31,7 +70,7 @@ export interface PrepareStepContext {
 	readonly signal?: AbortSignal
 	/**
 	 * Estimated room for additional step context after existing messages,
-	 * earlier stages' system/skills, and a response reserve. Recomputed for
+	 * earlier stages' system/skills/context, and a response reserve. Recomputed for
 	 * each stage and its selected model; not a billing limit or fit guarantee.
 	 * `beforeStep` observes its existing boundary before compaction runs.
 	 */
@@ -127,10 +166,9 @@ export interface PrepareStepResult {
 	 * research wants the search skill, writing wants the style guide, and
 	 * neither benefits from carrying the other.
 	 *
-	 * Rendered into the same ephemeral trailing system message `system`
-	 * uses, and for the same reason: appending leaves the cached prefix
-	 * intact, where rewriting the run's prompt would invalidate it every
-	 * iteration for what is usually one phase's worth of guidance.
+	 * Rendered into the same ephemeral system message `system` uses. Providers
+	 * may move that message before history, so changing skills can invalidate
+	 * reuse of the conversation prefix even though the run's prompt is unchanged.
 	 *
 	 * ADDITIVE to the run's skills, not a replacement. A skill the run
 	 * always carries is not something a step should be able to take away by
@@ -152,12 +190,25 @@ export interface PrepareStepResult {
 	 * Guidance for this step ONLY, appended as a system message that is not
 	 * retained afterwards.
 	 *
-	 * Kept separate from the run's system prompt on purpose: the prompt is
-	 * the cached prefix, and rewriting it per step would bust the cache on
-	 * every iteration for what is usually one sentence of phase direction.
+	 * Some providers collect all system messages before conversation history.
+	 * Changing this field can therefore invalidate reuse of the history prefix.
+	 * Use `context` for changing observations that do not require system authority.
 	 */
 	readonly system?: string
 
+	/**
+	 * Current observations for this request only, appended after history and any
+	 * step system guidance. Carried as a visibly labelled user-role message with
+	 * runtime provenance, not operator input or system authority. It never enters
+	 * durable conversation history or replaces `latestUserMessage`.
+	 *
+	 * Useful for changing inventories and retrieved data on providers that hoist
+	 * system messages. This preserves the history's placement, not a cache-hit
+	 * guarantee. Later stages may compose `prepared.context` or replace it; an
+	 * empty string clears it. The next step starts without it.
+	 */
+	readonly context?: string
+
 	readonly temperature?: number
 	readonly maxResponseTokens?: number
 }

package/src/types/run/store.ts

@@ -1,3 +1,4 @@
+import type { RunEvidenceScope, RunTextEvidenceSource } from '../../store/evidence/types.js'
 /**
  * RunStore — persistence contract for a run's own evidence.
  *
@@ -97,7 +98,38 @@ export interface CompletedToolRecord {
 	readonly isError: boolean
 }
 
+/** The latest recorded execution boundary of a tool call, not its inferred external effect. */
+export type ToolExecutionRecord =
+	| (CompletedToolRecord & { readonly status: 'completed' })
+	| { readonly toolUseId: string; readonly toolName: string; readonly status: 'started' }
+
+/** Absence proves no recorded start only when the whole selected log is complete. */
+export interface ToolExecutionSnapshot {
+	readonly complete: boolean
+	readonly records: ReadonlyMap<string, ToolExecutionRecord>
+}
+
 export interface RunStore {
+	/**
+	 * Optional bounded recovery scan for selected call IDs. A started call without
+	 * a completion has an unknown outcome and must not be automatically replayed.
+	 * The runtime falls back to strict readEvents for stores without this method.
+	 */
+	readToolExecutions?(
+		toolUseIds: readonly string[],
+		signal?: AbortSignal,
+	): Promise<ToolExecutionSnapshot>
+	/**
+	 * Optional bounded read capability anchored to this writer's completed event
+	 * boundary. Observe signal while waiting/reading; cancellation must not release
+	 * a writer lock before its pending operation settles.
+	 */
+	captureTextEvidence?(
+		scope: RunEvidenceScope,
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	): Promise<RunTextEvidenceSource | undefined>
+
 	/**
 	 * Bind this store to a run, before any other call.
 	 *
@@ -186,10 +218,9 @@ export interface RunStore {
 	 * already come back, and the resumed run re-executes those calls. For a
 	 * file write that is waste; for a payment or an email it is a second one.
 	 *
-	 * A backend that does not retain individual events answers with an empty
-	 * map, which costs re-execution and is honest. It must not answer with a
-	 * PARTIAL map: a caller reads a present entry as "this call is already
-	 * answered", so a half-remembered batch is worse than a forgotten one.
+	 * This completed-only view cannot distinguish an unstarted call from an
+	 * interrupted effect. It is not authority to execute an absent call. Runtime
+	 * recovery uses readToolExecutions or a strict readEvents scan instead.
 	 */
 	readCompletedTools(): Promise<Map<string, CompletedToolRecord>>
 

package/src/types/tool/index.ts

@@ -127,9 +127,17 @@ export interface FileReadTracker {
 	 * `content` lets the tracker fingerprint what was read, which is what
 	 * makes drift detectable later. Optional so a host that only needs the
 	 * read-before-overwrite guard can keep its existing implementation.
+	 * `fullWriteCallId` links a successfully written complete body to its
+	 * execution; pass ToolContext.toolUseId only after the write succeeds.
 	 */
-	recordRead(key: string, content?: string): void
+	recordRead(key: string, content?: string, fullWriteCallId?: string): void
 	hasRead(key: string): boolean
+	/**
+	 * Optional witness of a successful full-body write, supplied by the executing
+	 * tool through recordRead's third argument. An unchanged later observation
+	 * preserves it; different or unknown content clears it. Never infer from a name.
+	 */
+	writeCallId?(key: string): string | undefined
 	/**
 	 * Fingerprint of the body captured at the last read, when one was.
 	 *
@@ -223,6 +231,16 @@ export interface ToolDispatchOptions {
 }
 
 export interface ToolContext {
+	/**
+	 * Host-owned read snapshot. Bound to this tool call's lifetime, including its
+	 * deadline; an optional signal can cancel capture earlier. Never replays
+	 * effects. Unsupported stores return undefined.
+	 */
+	captureRunEvidence?: (
+		maxReadBytes?: number,
+		signal?: AbortSignal,
+	) => Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined>
+
 	runId: RunId
 	workingDirectory: string
 	/**

package/src/utils/await-with-abort.ts

@@ -0,0 +1,26 @@
+import { subscribeToAbort } from './abort.js'
+
+/**
+ * Stop waiting without releasing any lock owned by the operation. Its promise
+ * stays observed until settlement; cancellation cannot reorder queued work.
+ * The operation must also check the signal before starting work and pass it
+ * into cooperative I/O. This race cannot stop an uncooperative backend.
+ */
+export async function awaitWithAbort<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
+	if (!signal) return operation
+	if (signal.aborted) {
+		void operation.catch(() => {})
+		signal.throwIfAborted()
+	}
+	let dispose = () => {}
+	const cancelled = new Promise<never>((_resolve, reject) => {
+		dispose = subscribeToAbort(signal, () => reject(signal.reason))
+	})
+	try {
+		const result = await Promise.race([operation, cancelled])
+		signal.throwIfAborted()
+		return result
+	} finally {
+		dispose()
+	}
+}

package/src/utils/evidence-time.ts

@@ -0,0 +1,9 @@
+/** Stored event wall-clock time, not the time a statement became true. Zero is legacy unknown. */
+export function evidenceRecordedAt(value: unknown): number | undefined {
+	return typeof value === 'number' &&
+		Number.isSafeInteger(value) &&
+		value > 0 &&
+		value <= 8_640_000_000_000_000
+		? value
+		: undefined
+}

package/src/utils/evidence-tokens.ts

@@ -0,0 +1,32 @@
+/** The lexical units shared by evidence discovery and bounded relevance scoring. */
+export function evidenceTokens(text: string): string[] {
+	return Array.from(evidenceTokenEntries(text), (match) => match[0])
+}
+
+/** Iterate large stored text without materializing a token array. */
+export function evidenceTokenEntries(text: string): IterableIterator<RegExpExecArray> {
+	return text.matchAll(/[\p{L}\p{N}_]+/gu)
+}
+
+/** No stemming, locale-sensitive folding or accent normalization. */
+export function evidenceTokenKey(token: string, caseSensitive = false): string {
+	return caseSensitive ? token : token.toLowerCase()
+}
+
+export function isEvidenceToken(text: string): boolean {
+	return /^[\p{L}\p{N}_]+$/u.test(text)
+}
+
+/** `from` may lie inside a token; such a suffix must not become a new word. */
+export function evidenceTokenMatcher(terms: readonly string[], caseSensitive: boolean) {
+	const wanted = new Set(terms.map((term) => evidenceTokenKey(term, caseSensitive)))
+	const expression = /(?<![\p{L}\p{N}_])[\p{L}\p{N}_]+/gu
+	return (text: string, from: number): { index: number; length: number } | undefined => {
+		expression.lastIndex = from
+		for (let match = expression.exec(text); match; match = expression.exec(text)) {
+			if (wanted.has(evidenceTokenKey(match[0], caseSensitive)))
+				return { index: match.index, length: match[0].length }
+		}
+		return undefined
+	}
+}