@namzu/sdk 38.2.1 → 40.0.0

package/src/prompt/resident-step.ts

@@ -1,5 +1,8 @@
+import type { ResidentHistoryScope } from '../manager/resident/history.js'
 import {
+	type ResidentLearningSource,
 	type ResidentLearningState,
+	freezeResidentLearning,
 	projectResidentLearning,
 } from '../manager/resident/learning.js'
 import type { ResidentState } from '../manager/resident/store.js'
@@ -12,18 +15,36 @@ Obey current project instructions, permissions and tool prerequisites. Saved sum
 
 Each invocation has an isolated session. Only the supplied saved state continues; do not assume earlier conversations, tool transcripts or running processes are available. Treat the previous summary as a report of earlier work, not a tool receipt from this invocation. Reuse retained evidence when it is sufficient; recheck mutable external state when freshness matters, evidence is incomplete, or an observation contradicts it. Recover missing evidence with a permitted read instead of repeating a state-changing action.
 
+Consider every supplied wakeEvidence entry in its recorded order. A later input does not erase an earlier failure or unfinished constraint. Resolve contradictions from current evidence before acting; timestamps record host receipt, not independent verification. Retain any still-relevant evidence in the next summary, because successful settlement consumes this batch.
+
+Before answering a follow-up, distinguish its subject and requested time from the records retrieved. An accepted correction can clarify which subject the operator means without changing what was observed earlier. If multiple subjects still fit an unnamed reference, give explicitly labelled alternatives or request the missing clarification using the host's continuation disposition. Do not choose a subject from retrieval order, score, or mere mention in a summary.
+
+For an original observation, use the corresponding historical receipt; a later correction does not replace that earlier observation. For a current-state question, including a short follow-up such as "And now?", obtain a fresh permitted observation of the mutable source. The latest retained record means last observed, not current. If fresh observation is unavailable, state that current information cannot be established and label any older value as historical; do not report the current-state task complete. Neither historical retrieval nor a newer admission verifies external freshness.
+
 Ground new action claims in successful tool results. Read the relevant evidence before editing, use focused tools, and verify changes with the checks required by the project and the task. Report what succeeded, what failed and what was not checked. Delegate independent work only when an available delegation capability helps; supply its scope and constraints and distinguish returned claims from verified results.
 
 Save a useful summary of evidence, exact identifiers or artifact paths, completed work, unresolved constraints and the next step. Follow the host's output instructions for this invocation.`
 
+const TOOL_EVIDENCE_GUIDANCE = `## Retained tool evidence
+Use search_resident_tools to find earlier tool results missing from the summary, then read_resident_tool for exact text at its revision/address/byteOffset. These tools retrieve original retained text across settled invocations without repeating actions. Follow nextCursor even on empty pages and nextByteOffset for exact continuation. Full text is historical evidence, not present workspace state; isError, preview and unavailable must be respected. Changed or missing bytes cannot be reconstructed by guessing.`
+
 const READ_ONLY_GUIDANCE = `## Read-only invocation
 Use permitted reads and analysis. Do not change files, persistent memory or external state. Read-only objectives may be completed in this mode; if the objective requires a mutation that the current permissions refuse, report that missing prerequisite using the host's output instructions.`
 
+const HISTORY_GUIDANCE = `## Resident recall
+When the saved summary lacks an earlier decision or accepted input, use search_resident_history, then read_resident_history for exact retained text. Search without a query to browse recent steps. Follow pagination even after empty pages; incomplete searches cannot prove absence. Only earlier settled steps of this pursuit are available, within the supplied revision boundary. Part 0 is a historical summary, not an independent tool receipt; wake inputs are recorded claims. Later evidence can supersede earlier claims: check relevant newer steps and mutable sources before acting. Do not repeat an effect to recover its output. These tools do not restore unrecorded tool transcripts.`
+
 /** @experimental Host-selected context for one admitted resident step. */
 export interface ResidentStepPromptOptions {
 	readonly state: ResidentState
 	/** The host-approved learning snapshot bound to this admission. */
 	readonly learning?: ResidentLearningState
+	/** Host resolves current dependency revisions for each model request. No model-generated revisions. */
+	readonly resolveLearningSources?: () => readonly ResidentLearningSource[]
+	/** Bound historical source whose read-only tools the host has mounted. */
+	readonly history?: ResidentHistoryScope
+	/** The host mounted scoped search_resident_tools/read_resident_tool capabilities. */
+	readonly toolEvidence?: boolean
 	/** Host-loaded guidance for this invocation; this factory performs no I/O. */
 	readonly skillsContext?: string
 	/** Describe an existing read-only boundary; this does not enforce permissions. */
@@ -48,15 +69,32 @@ export function createResidentStepContributions(
 	options: ResidentStepPromptOptions,
 ): readonly PromptContribution[] {
 	const { state } = options
-	const learning = projectResidentLearning(options.learning, {
+	if (
+		options.history &&
+		(options.history.tenantId !== state.tenantId ||
+			options.history.agentKey !== state.agentKey ||
+			options.history.pursuitId !== state.pursuitId)
+	)
+		throw new Error('Resident history context belongs to a different pursuit.')
+	const admittedLearning = options.learning ? freezeResidentLearning(options.learning) : undefined
+	const boundNames =
+		admittedLearning?.skills.filter((skill) => skill.sources?.length).map((skill) => skill.name) ??
+		[]
+	const learning = projectResidentLearning(admittedLearning, {
 		maxChars: 12_000,
-		skillNames: options.learning?.skills.map((skill) => skill.name) ?? [],
+		skillNames:
+			admittedLearning?.skills
+				.filter((skill) => !skill.sources?.length)
+				.map((skill) => skill.name) ?? [],
 	})
+	const resolveSources = options.resolveLearningSources
 	// Capture literals now. An admitted invocation must not borrow the next
 	// invocation's mutable options, state or learning through a render closure.
 	const guidance = [
 		RESIDENT_WORK_GUIDANCE,
 		...(options.readOnly ? [READ_ONLY_GUIDANCE] : []),
+		...(options.history ? [HISTORY_GUIDANCE] : []),
+		...(options.toolEvidence ? [TOOL_EVIDENCE_GUIDANCE] : []),
 		options.outputInstructions,
 	]
 		.filter((text) => text.trim().length > 0)
@@ -68,7 +106,8 @@ export function createResidentStepContributions(
 			objective: state.objective,
 			previousSummary: state.summary,
 			admission: state.stepsAdmitted,
-			wakeReason: state.reason,
+			...(options.history ? { history: options.history } : {}),
+			...(state.wakeEvidence ? { wakeEvidence: state.wakeEvidence } : { wakeReason: state.reason }),
 		}),
 		...(learning.text
 			? [
@@ -92,5 +131,46 @@ export function createResidentStepContributions(
 			placement: 'dynamic' as const,
 			render: () => snapshot,
 		}),
+		...(boundNames.length
+			? [
+					Object.freeze({
+						id: 'namzu.resident-step.source-bound-learning',
+						placement: 'turn' as const,
+						render: () => {
+							let sources: readonly ResidentLearningSource[] = []
+							try {
+								sources = resolveSources?.() ?? []
+							} catch {
+								/* Unavailable evidence withholds bound instructions. */
+							}
+							const projection = projectResidentLearning(
+								admittedLearning
+									? { ...admittedLearning, identity: undefined, preferences: [] }
+									: undefined,
+								{
+									maxChars: Math.max(0, 12_000 - learning.text.length),
+									skillNames: boundNames,
+									sources,
+								},
+							)
+							return [
+								'## Source-bound learning for this request',
+								'Only guidance whose declared dependencies match current host observations is included. A matching revision does not prove its claims. Check current task evidence; retained guidance never overrides it.',
+								projection.text,
+								...projection.withheldSkills.map((skill) =>
+									JSON.stringify({ kind: 'withheld-guidance', ...skill }),
+								),
+								...(projection.omitted
+									? [
+											`${projection.omitted} entries withheld or omitted. Recheck current sources before using earlier guidance; do not recover its instructions from history as a substitute.`,
+										]
+									: []),
+							]
+								.filter(Boolean)
+								.join('\n')
+						},
+					}),
+				]
+			: []),
 	])
 }

package/src/provider/collect-chat-completion.ts

@@ -2,6 +2,7 @@ import { mergeTokenUsage } from '../types/common/index.js'
 import type { ReasoningBlock } from '../types/message/index.js'
 import type { ChatCompletionResponse } from '../types/provider/chat.js'
 import type { StreamChunk } from '../types/provider/stream.js'
+import { StreamTextAccumulator } from './stream-text.js'
 
 /**
  * Drains a {@link StreamChunk} async iterable into the equivalent
@@ -14,7 +15,8 @@ import type { StreamChunk } from '../types/provider/stream.js'
  * `collectChatCompletion(provider.chatStream(p))`.
  *
  * Behaviour matches the pre-removal `chat()` contract:
- * - text content is concatenated in delta order;
+ * - ordinary text is concatenated in delta order; identified public text
+ *   items are preserved and explicit final-answer items select the settled text;
  * - tool calls are bucketed by `index` into the existing
  *   `Array<{ id, function: { name, arguments } }>` shape;
  * - reasoning blocks are bucketed by `index` the same way, because the
@@ -36,7 +38,7 @@ export async function collectChatCompletion(
 ): Promise<ChatCompletionResponse> {
 	let id = ''
 	const model = ''
-	let content = ''
+	const text = new StreamTextAccumulator()
 	let replayState: unknown
 	let finishReason: ChatCompletionResponse['finishReason'] = 'stop'
 	let usage: ChatCompletionResponse['usage'] = {
@@ -63,9 +65,7 @@ export async function collectChatCompletion(
 		if (!id && chunk.id) id = chunk.id
 		if (chunk.replayState !== undefined) replayState = chunk.replayState
 
-		if (chunk.delta.content) {
-			content += chunk.delta.content
-		}
+		text.push(chunk)
 
 		const reasoning = chunk.delta.reasoning
 		if (reasoning) {
@@ -115,7 +115,8 @@ export async function collectChatCompletion(
 		model,
 		message: {
 			role: 'assistant',
-			content: content.length > 0 ? content : null,
+			content: text.text || null,
+			...(text.textParts ? { textParts: text.textParts } : {}),
 			toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
 			...(reasoningBlocks.length > 0 ? { reasoning: reasoningBlocks } : {}),
 			...(replayState !== undefined ? { replayState } : {}),

package/src/provider/fallback.ts

@@ -220,7 +220,8 @@ function isOutputChunk(chunk: StreamChunk): boolean {
 			toolCallEnd ||
 			reasoning !== undefined ||
 			citation !== undefined ||
-			hostedTool !== undefined,
+			hostedTool !== undefined ||
+			chunk.textParts !== undefined,
 	)
 }
 

package/src/provider/stream-text.ts

@@ -0,0 +1,56 @@
+import { type AssistantTextPart, selectAssistantText } from '../types/message/index.js'
+import type { StreamChunk } from '../types/provider/stream.js'
+
+/** Shared aggregation for the run loop, collected calls and bounded auxiliary inference. */
+export class StreamTextAccumulator {
+	private raw = ''
+	private receivedCharacters = 0
+	private parts: AssistantTextPart[] = []
+	private identified = false
+	private snapshot = false
+
+	push(chunk: StreamChunk): void {
+		if (chunk.textParts !== undefined) {
+			this.parts = chunk.textParts.map((part) => ({ ...part }))
+			this.identified = true
+			this.snapshot = true
+			this.raw = ''
+		}
+		const text = chunk.delta.content
+		if (!text) return
+		if (this.snapshot) throw new Error('Content arrived after the completed text snapshot.')
+		this.receivedCharacters += text.length
+		const part = chunk.delta.textPart
+		if (!this.identified && !part) {
+			this.raw += text
+			return
+		}
+		if (!this.identified) {
+			if (this.raw) this.parts.push({ id: '', text: this.raw })
+			this.raw = ''
+			this.identified = true
+		}
+		const previous = this.parts.at(-1)
+		if (previous && previous.id === (part?.id ?? '') && previous.phase === part?.phase)
+			this.parts[this.parts.length - 1] = { ...previous, text: previous.text + text }
+		else
+			this.parts.push({ id: part?.id ?? '', ...(part?.phase ? { phase: part.phase } : {}), text })
+	}
+
+	get text(): string {
+		return this.identified ? selectAssistantText(this.parts) : this.raw
+	}
+
+	/** Include commentary in auxiliary output limits even when only the final answer is selected. */
+	get characters(): number {
+		return Math.max(
+			this.receivedCharacters,
+			this.parts.reduce((sum, part) => sum + part.text.length, 0) +
+				Math.max(0, this.parts.length - 1) * 2,
+		)
+	}
+
+	get textParts(): readonly AssistantTextPart[] | undefined {
+		return this.identified ? this.parts.map((part) => ({ ...part })) : undefined
+	}
+}

package/src/public-runtime.ts

@@ -274,9 +274,17 @@ export {
 // parses, which is the wire's property. Rendered once, converted at the driver.
 export { findDraft07Only, toSchemaDialect } from './registry/tool/dialect.js'
 export type { JsonSchemaDialect } from './registry/tool/dialect.js'
+// Better than converting per wire: emit the INTERSECTION of the dialects, so
+// there is nothing left for a driver to convert and an unmeasured wire is safe
+// by construction. Exported so a driver or a CI gate can assert it.
+export {
+	findPortableSchemaViolations,
+	toPortableToolSchema,
+} from './registry/tool/portable.js'
+export type { PortableSchemaViolation } from './registry/tool/portable.js'
 // The renderer itself, so a driver or a contract test can ask what a tool will
 // actually put on the wire without reaching into the registry.
-export { renderToolSchema } from './registry/tool/schema.js'
+export { renderToolSchema, toolWireSchema } from './registry/tool/schema.js'
 export type { StrictSchemaViolation } from './provider/strict-schema.js'
 export type { ModelIdGrammar, ModelVersion } from './provider/model-version.js'
 export { drainQuery, query } from './runtime/query/index.js'
@@ -363,6 +371,7 @@ export {
 	FINGERPRINT_TIMEOUT_MS,
 	clipOutput,
 	createCommandGate,
+	createJsonClaimVerifier,
 	fingerprintWorkspace,
 } from './run/index.js'
 export type {
@@ -382,6 +391,14 @@ export { RUN_MEMORY_TAG, createMemoryPromoter } from './run/index.js'
 export type { MemoryPromoterOptions } from './run/index.js'
 export { createMemoryRecallStep } from './run/memory-recall.js'
 export type { MemoryRecallOptions } from './run/memory-recall.js'
+export { createEvidenceRecallStep, refineEvidenceRecallTerms } from './run/evidence-recall.js'
+export type {
+	EvidenceRecallOptions,
+	EvidenceRecallRequest,
+	EvidenceRecallBatch,
+	EvidenceRecallCandidate,
+	EvidenceRecallContinuation,
+} from './run/evidence-recall.js'
 
 // ─── personas, skills, advisory ──────────────────────────────────────────
 
@@ -1002,6 +1019,7 @@ export { deriveChildState } from './types/invocation/index.js'
 export { assertMemoryStatus } from './types/memory/index.js'
 export {
 	createAssistantMessage,
+	selectAssistantText,
 	createProjectInstructionMessage,
 	createRuntimeContextMessage,
 	createSystemMessage,
@@ -1218,6 +1236,7 @@ export {
 	SKILLS_CONTRIBUTION_ID,
 	codingAgentDoctrineContribution,
 	createResidentStepContributions,
+	createResidentStepContext,
 	skillsContribution,
 } from './prompt/index.js'
 
@@ -1346,6 +1365,7 @@ export { snapshotRequestContext, diffRequestContext } from './runtime/query/requ
 export { DiskResidentStore, ResidentConflictError } from './manager/resident/store.js'
 export { runResident, stepResident } from './manager/resident/loop.js'
 export { DiskResidentAgenda } from './manager/resident/agenda.js'
+export { inspectResidentConsumption } from './manager/resident/consumption.js'
 export { ResidentHost } from './manager/resident/host.js'
 
 export { createResidentSelector } from './manager/resident/initiative.js'
@@ -1355,3 +1375,21 @@ export { deliverResidentMessage } from './manager/resident/outbox.js'
 export { createResidentDeliveryWindow } from './manager/resident/delivery-window.js'
 
 export { hashResidentSkill, projectResidentLearning } from './manager/resident/learning.js'
+export { runResidentLearningCycle } from './manager/resident/learning-cycle.js'
+
+export { SqliteSessionStore } from './store/session/sqlite.js'
+
+export {
+	createDiskRunEvidenceSource,
+	createDiskRunTextEvidenceSource,
+} from './store/evidence/disk.js'
+export { classifyEvidenceSource, EVIDENCE_RECORD_GUIDANCE } from './store/evidence/source-kind.js'
+export { createResidentToolEvidenceSource } from './manager/resident/tool-evidence.js'
+
+export { createResidentEvidenceRecallStep } from './manager/resident/evidence-recall.js'
+
+export {
+	SqliteResidentLearningStore,
+	runStoredResidentLearningCycle,
+	runStoredResidentLearningFromObservations,
+} from './manager/resident/learning-store.js'

package/src/public-tools.ts

@@ -25,6 +25,7 @@ export type { UntrustedEnvelope } from './tools/untrusted-envelope.js'
 // ─── Built-in tools ──────────────────────────────────────────────────────
 
 export { getBuiltinTools } from './tools/builtins/index.js'
+export { buildResidentHistoryTools } from './tools/resident-history.js'
 // A host compiling operator permissions has a tool name and needs an argument
 // to attach a pattern to. Without one it can only match against the serialised
 // input, which is how an `allow` for `git status*` came to approve
@@ -42,6 +43,11 @@ export { GrepTool } from './tools/builtins/grep.js'
 // capability: an id with nothing that reads it is the unbacked suggestion
 // that was removed from bash's schema.
 export { JobTool } from './tools/builtins/job.js'
+// Blocks until a job `JobTool` started ends, instead of reading it in a
+// loop. Ships in the default builtin set alongside `job` and `bash`, for
+// the same reason `job` does: a job with nothing that can block on it is
+// the same unbacked suggestion `job` itself exists to fix.
+export { WaitForJobTool } from './tools/builtins/wait-for-job.js'
 // Loads a skill's instructions, and adopts the tool scope it declares.
 // NOT in the default builtin set: a run with no skills has nothing for it
 // to do, and offering a tool that can only refuse is worse than not
@@ -127,3 +133,18 @@ export {
 } from './connector/tools/index.js'
 
 export { createFileReadTracker } from './tools/file-read-tracker.js'
+export type { LedgerReplayReport } from './runtime/query/file-evidence-replay.js'
+/**
+ * Rebuild a tracker from a conversation's own history, for a host that keeps
+ * one per conversation across turns and has just restored one from a store.
+ * Reads no file's content — only the paths the history names, canonicalized
+ * the way the built-in tools canonicalize them so that the entries land where
+ * those tools will look for them. See the SDK's tool-execution documentation
+ * for what a replayed observation does and does not establish.
+ */
+export {
+	type ObservationSeedContext,
+	seedObservationLedger,
+} from './runtime/query/file-evidence-seed.js'
+
+export { buildResidentToolEvidenceTools } from './tools/resident-tool-evidence.js'

package/src/public-types.ts

@@ -111,6 +111,7 @@ export type {
 
 export type {
 	AdvisoryCallContext,
+	AdvisoryTurnContext,
 	AdvisoryExecutionResult,
 } from './advisory/index.js'
 
@@ -379,6 +380,8 @@ export type {
 	PromptContributionContext,
 	PromptPlacement,
 	ResidentStepPromptOptions,
+	ResidentStepContextOptions,
+	ResidentStepContextBundle,
 } from './prompt/index.js'
 
 export type {
@@ -449,6 +452,32 @@ export type {
 } from './runtime/query/request-context.js'
 
 export type { ResidentDecision, ResidentState, ResidentStore } from './manager/resident/store.js'
+export type {
+	ResidentActivityScope,
+	ResidentAdmission,
+	ResidentSettlement,
+	ResidentActivityOptions,
+	ResidentActivityPage,
+	ResidentActivitySource,
+} from './manager/resident/activity.js'
+export type {
+	ResidentConsumptionReceipt,
+	ResidentConsumptionResolver,
+	ResidentConsumptionOptions,
+	ResidentConsumptionAttempt,
+	ResidentConsumptionReport,
+} from './manager/resident/consumption.js'
+export type {
+	ResidentHistoryScope,
+	ResidentHistoryAddress,
+	ResidentHistoryMatch,
+	ResidentHistorySearchOptions,
+	ResidentHistorySearchResult,
+	ResidentHistoryReadOptions,
+	ResidentHistoryText,
+	ResidentHistoryReadResult,
+	ResidentHistorySource,
+} from './manager/resident/history.js'
 export type {
 	ResidentStep,
 	ResidentStepResult,
@@ -503,8 +532,22 @@ export type {
 	ResidentProfileUpdate,
 	ResidentSkillEvaluation,
 	ResidentLearningProjectionOptions,
+	ResidentLearningSource,
 	ResidentLearningProjection,
 } from './manager/resident/learning.js'
+export type {
+	ResidentLearningStage,
+	ResidentLearningReceipt,
+	ResidentLearningConsumption,
+	ResidentLearningCycleEvent,
+	ResidentLearningCycleContext,
+	ResidentLearningGenerationContext,
+	ResidentLearningExplorationContext,
+	ResidentLearningExploration,
+	ResidentLearningEvaluationContext,
+	ResidentLearningCycleOptions,
+	ResidentLearningCycleResult,
+} from './manager/resident/learning-cycle.js'
 
 export type {
 	ResidentArchiveRequest,
@@ -512,3 +555,58 @@ export type {
 	ResidentArchivePage,
 	ResidentArchiveListOptions,
 } from './manager/resident/agenda.js'
+
+export type { SqliteSessionStoreConfig } from './store/session/sqlite.js'
+
+export type {
+	RunEvidenceScope,
+	DiskRunEvidenceOptions,
+	RunEvidenceSearchOptions,
+	RunEvidenceMatch,
+	RunEvidenceSearchResult,
+	RunEvidenceReadOptions,
+	RunEvidenceReadResult,
+	RunEvidenceSource,
+	RunTextEvidenceSearchOptions,
+	RunTextEvidenceMatch,
+	RunTextEvidenceSearchResult,
+	RunTextEvidenceReadResult,
+	RunTextEvidenceSource,
+} from './store/evidence/types.js'
+export type { EvidenceRecordKind } from './store/evidence/source-kind.js'
+export type {
+	ResidentToolEvidenceScope,
+	ResidentSettledInvocation,
+	ResidentToolEvidenceOptions,
+	ResidentToolEvidenceSearchOptions,
+	ResidentToolEvidenceSearchResult,
+	ResidentToolEvidenceReadOptions,
+	ResidentToolEvidenceReadResult,
+	ResidentToolEvidenceSource,
+} from './manager/resident/tool-evidence.js'
+
+export type { ResidentEvidenceRecallOptions } from './manager/resident/evidence-recall.js'
+export type {
+	JsonClaimValue,
+	JsonClaimRequirement,
+	JsonClaimReadRequest,
+	JsonClaimObservation,
+	JsonClaimReceipt,
+	JsonClaimVerdict,
+	JsonClaimVerifierOptions,
+	JsonClaimVerifier,
+} from './run/json-claim-verifier.js'
+
+export type {
+	SqliteResidentLearningStoreOptions,
+	ResidentLearningArtifact,
+	ResidentLearningRecordedUsage,
+	ResidentLearningCycleSummary,
+	ResidentLearningDiscoveryOptions,
+	ResidentLearningDiscoveryResult,
+} from './manager/resident/learning-store.js'
+export type {
+	ResidentLearningObservation,
+	ResidentLearningObservationRecord,
+	ResidentLearningTarget,
+} from './manager/resident/learning-observation.js'

package/src/registry/tool/execute.ts

@@ -20,7 +20,7 @@ import type {
 import { toErrorMessage } from '../../utils/error.js'
 import { cloneJsonValue as clonePreparedInput } from '../../utils/json-snapshot.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
-import { renderToolSchema } from './schema.js'
+import { renderToolSchema, toolWireSchema } from './schema.js'
 import { ToolResultHalted, screenToolResult } from './screen.js'
 
 export type { ToolExecutionResult }
@@ -461,9 +461,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				function: {
 					name: tool.name,
 					description: describeWithOutput(description, tool.outputSchema),
-					parameters:
-						(tool.modelInputSchema ? structuredClone(tool.modelInputSchema) : undefined) ??
-						renderToolSchema(tool.inputSchema),
+					parameters: toolWireSchema(tool),
 				},
 			}
 		})