@namzu/sdk 55.0.0 → 56.0.0

package/src/runtime/query/iteration/phases/per-call-review.ts

@@ -29,6 +29,25 @@ const NOT_THIS_QUESTION =
 	'That answer was not an answer to a question about a tool call, so this call was not run.'
 
 /** The audit trail keeps a person's reason, cut short and without control characters. */
+/**
+ * Whether a tool result is the answer to a call that never ran because the
+ * review did not let it: the person's No, a refusal that ended the turn, or a
+ * question that went unanswered. Such a result records a choice or an
+ * interruption, not a tool that failed, so a host counting failures leaves it
+ * out. Policy refusals and failed runs are not matched.
+ */
+export function isReviewRefusalResult(output: string): boolean {
+	if (!output.startsWith('Error: Tool "')) return false
+	return [
+		DECLINED_TOOL_CALL_FEEDBACK,
+		REFUSED_WITH_THE_TURN,
+		UNANSWERED_CALL,
+		EDIT_NOT_OFFERED,
+		PAUSED_CALL,
+		NOT_THIS_QUESTION,
+	].some((reason) => output.endsWith(` was not executed. ${reason}`) || output.endsWith(reason))
+}
+
 const AUDIT_NOTE_MAX_CHARS = 500
 
 /**

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -28,6 +28,7 @@ import {
 	formatMonitorNote,
 	takeNoticeMessage,
 	takeSteeringMessage,
+	takeWithheldEnvNotice,
 } from '../../steering.js'
 import { type IterationContext, awaitDecisionDurably } from './context.js'
 import { PerCallReview } from './per-call-review.js'
@@ -295,6 +296,8 @@ export async function* runToolReview(
 			},
 		)
 		if (monitorNotice) ctx.recorder.pushMessage(monitorNotice)
+		const credentialNotice = takeWithheldEnvNotice(ctx.recorder.messages, batch.observations)
+		if (credentialNotice) ctx.recorder.pushMessage(credentialNotice)
 		if (jobNoticeDelivered) ctx.onJobNoticeDelivered?.()
 		if (monitorNoticeDelivered) ctx.onMonitorNoticeDelivered?.()
 		// The complete tool-result batch is already in history before host policy

package/src/runtime/query/iteration/step-context.ts

@@ -44,3 +44,141 @@ export function placeBeforeLatestOperatorMessage(history: Message[], blocks: rea
 	}
 	history.splice(at, 0, ...blocks)
 }
+
+interface PlacedBlock {
+	readonly text: string
+	/** The operator message this block precedes, or the history message it follows. */
+	at: { readonly before: Message } | { readonly after: Message | undefined }
+}
+
+function textOf(message: Message): string {
+	return typeof message.content === 'string' ? message.content : JSON.stringify(message.content)
+}
+
+/** The operator message the model is about to answer, when there is one. */
+function pendingOperatorMessage(history: readonly Message[]): Message | undefined {
+	for (let i = history.length - 1; i >= 0; i--) {
+		const message = history[i] as Message
+		if (isOperatorUserMessage(message)) return message
+		if (message.role === 'assistant' || message.role === 'tool') return undefined
+	}
+	return undefined
+}
+
+/** A block whose own text says that a later one replaces it, under the name of what it reports. */
+export interface ReplaceableBlock {
+	readonly key: string
+	readonly message: Message
+}
+
+/** How many superseded versions of a replaceable block still go with the latest. */
+export const EARLIER_VERSIONS_KEPT = 2
+
+interface VersionedBlock extends PlacedBlock {
+	readonly message: Message
+}
+
+/**
+ * Where a turn's request-only data sits, so it stays put from call to call.
+ *
+ * What a block says is the step's own business: a block it offers again with
+ * the same text is the same block, and it keeps the place it first had; a
+ * block it no longer offers is withdrawn, so corrected data never lingers.
+ * A block seen for the first time goes before the operator's message when that
+ * message is what the model is answering, and otherwise after the history of
+ * that moment. So the requests of a turn share their opening up to the first
+ * block that changed, and a caching driver keeps reading the same prefix
+ * instead of re-reading the turn from the operator's message on.
+ *
+ * A block that says of itself that a later one replaces it (the file
+ * evidence) is never taken back. When its text changes, the earlier text stays
+ * where it went and the new text follows the history of that moment, which is
+ * how the block itself tells the model to read it; when it stops holding, a
+ * short block says so. Only the latest version and the last
+ * `EARLIER_VERSIONS_KEPT` before it are carried, and an earlier version whose
+ * place a compaction rewrote is dropped, so the stale text stays small. Until
+ * a version is dropped no request of the turn rewrites the one before it.
+ *
+ * One carry per turn. A position whose message has left the history (a
+ * compaction rewrote it) is given up and the block follows the history.
+ */
+export class TurnContextCarry {
+	private placed = new Map<string, PlacedBlock>()
+	private readonly versions = new Map<string, VersionedBlock[]>()
+
+	/**
+	 * Put `blocks` and the `replaceable` ones into `request`, the projected copy
+	 * of `history` (same length and order). `end` is the last message of the
+	 * turn's own history. `retractions` says, per replaceable key, what to
+	 * write when an earlier block of that key no longer holds.
+	 */
+	place(
+		request: Message[],
+		history: readonly Message[],
+		end: Message | undefined,
+		blocks: readonly Message[],
+		replaceable: readonly ReplaceableBlock[] = [],
+		retractions: Readonly<Record<string, Message>> = {},
+	): void {
+		const index = (message: Message | undefined) =>
+			message ? history.lastIndexOf(message) : history.length - 1
+		const operator = pendingOperatorMessage(history)
+		const positionOf = (slot: PlacedBlock) =>
+			'before' in slot.at ? index(slot.at.before) : index(slot.at.after) + 1
+		const anchorOf = (slot: PlacedBlock) => ('before' in slot.at ? slot.at.before : slot.at.after)
+		const next = new Map<string, PlacedBlock>()
+		const inserts: { at: number; message: Message }[] = []
+		for (const message of blocks) {
+			const text = textOf(message)
+			if (next.has(text)) continue
+			let slot: PlacedBlock | undefined = this.placed.get(text)
+			if (slot) {
+				const anchor = anchorOf(slot)
+				if (anchor && index(anchor) < 0) slot = { text, at: { after: end } }
+			} else {
+				slot = { text, at: operator ? { before: operator } : { after: end } }
+			}
+			next.set(text, slot)
+			inserts.push({ at: positionOf(slot), message })
+		}
+		this.placed = next
+
+		const offered = new Map(replaceable.map((block) => [block.key, block.message]))
+		for (const key of new Set([...this.versions.keys(), ...offered.keys()])) {
+			const held = this.versions.get(key) ?? []
+			const wanted = offered.get(key) ?? retractions[key]
+			const last = held.at(-1)
+			if (wanted !== undefined && (last === undefined || last.text !== textOf(wanted)))
+				held.push({
+					text: textOf(wanted),
+					message: wanted,
+					// The first version goes where the other blocks go; a later one
+					// follows the history, after the one it replaces.
+					at: last === undefined && operator ? { before: operator } : { after: end },
+				})
+			// An earlier version whose place a compaction rewrote is given up: the
+			// request is rewritten at that point anyway, and stacking stale copies
+			// at the end would only add bulk. The latest version is never given up.
+			const kept = held.filter((version, i) => {
+				if (i === held.length - 1) return true
+				const anchor = anchorOf(version)
+				return !anchor || index(anchor) >= 0
+			})
+			// Only the latest and a few earlier versions are carried, so a long turn
+			// does not grow by a full copy per change.
+			kept.splice(0, Math.max(0, kept.length - (EARLIER_VERSIONS_KEPT + 1)))
+			this.versions.set(key, kept)
+			for (const version of kept) {
+				const anchor = anchorOf(version)
+				if (anchor && index(anchor) < 0) version.at = { after: end }
+				inserts.push({ at: positionOf(version), message: version.message })
+			}
+		}
+
+		// Back to front, so an earlier position is not shifted by a later one;
+		// blocks at one position keep the order they were offered in.
+		const order = inserts.map((entry, position) => ({ ...entry, position }))
+		order.sort((a, b) => b.at - a.at || b.position - a.position)
+		for (const entry of order) request.splice(entry.at, 0, entry.message)
+	}
+}

package/src/runtime/query/iteration/step-shaping.ts

@@ -20,7 +20,11 @@ import { toErrorMessage } from '../../../utils/error.js'
 import { createCallbackInference } from '../callback-inference.js'
 import { measureContext } from './phases/compaction.js'
 import type { IterationContext } from './phases/index.js'
-import { placeBeforeLatestOperatorMessage, stepContextMessage } from './step-context.js'
+import {
+	type ReplaceableBlock,
+	placeBeforeLatestOperatorMessage,
+	stepContextMessage,
+} from './step-context.js'
 
 /**
  * How the next request is shaped: admission, preparation, and the context
@@ -51,28 +55,50 @@ export function appendWorkContext(
 	stepNumber: number,
 	prepared: PrepareStepResult,
 ): void {
+	// Per-turn data goes in front of the operator's new message while that is
+	// what the model is answering, like the other blocks of request-only data.
+	placeBeforeLatestOperatorMessage(
+		messages,
+		workContextBlocks(shaping, messages, stepNumber, prepared).map((block) => block.message),
+	)
+}
+
+/** What the two work-context blocks report; each tells the model a later one replaces it. */
+export const OWNED_WORK_KEY = 'owned-work'
+export const FILE_EVIDENCE_KEY = 'file-evidence'
+
+/**
+ * The work-context blocks for a request whose projected messages are
+ * `messages`, each under the name of what it reports.
+ */
+export function workContextBlocks(
+	shaping: StepShaping,
+	messages: readonly Message[],
+	stepNumber: number,
+	prepared: PrepareStepResult,
+): ReplaceableBlock[] {
 	const { ctx } = shaping
 
-	const contributions = [
-		ctx.completionInbox?.describeOwnedWork(),
-		ctx.toolExecutor.describeFileEvidence(messages),
-	].filter((content): content is string => Boolean(content))
-	if (contributions.length === 0) return
-	const placed: Message[] = []
+	const contributions = (
+		[
+			[OWNED_WORK_KEY, ctx.completionInbox?.describeOwnedWork()],
+			[FILE_EVIDENCE_KEY, ctx.toolExecutor.describeFileEvidence(messages)],
+		] as [string, string | undefined][]
+	).filter((entry): entry is [string, string] => Boolean(entry[1]))
+	if (contributions.length === 0) return []
+	const placed: ReplaceableBlock[] = []
 	let room = stepContext(shaping, stepNumber, prepared).contextBudget?.remainingTokens ?? 0
 	// Leave room for the actual task; admit whole contributions, never dangling partial references.
-	if (room < 1_500) return
-	for (const content of contributions) {
+	if (room < 1_500) return []
+	for (const [key, content] of contributions) {
 		if (!content || content.length > 8_000) continue
 		const message = stepContextMessage(content)
 		const tokens = estimateMessageTokens(message)
 		if (tokens > Math.min(2_000, room - 1_000)) continue
-		placed.push(message)
+		placed.push({ key, message })
 		room -= tokens
 	}
-	// Per-turn data goes in front of the operator's new message while that is
-	// what the model is answering, like the other blocks of request-only data.
-	placeBeforeLatestOperatorMessage(messages, placed)
+	return placed
 }
 
 export function stepContext(

package/src/runtime/query/steering.ts

@@ -1,3 +1,4 @@
+import { withheldEnvNoticeText } from '../../tools/env-scrub.js'
 import { createRuntimeContextMessage } from '../../types/message/index.js'
 import type { Message, UserMessage } from '../../types/message/index.js'
 import { NOTICE_TAG, frameNotice, readOperatorNotice } from '../../types/message/notice-frame.js'
@@ -377,3 +378,53 @@ export function attachSteering(
 	onDelivered?.(guidance)
 	return next
 }
+
+/**
+ * The count of credential-shaped variables a settled batch's shell results
+ * report as removed, or 0. The count rides in a result's `data`, never in the
+ * text the model reads.
+ */
+function withheldEnvCount(
+	observations: readonly { readonly result: { readonly data?: unknown } }[],
+) {
+	let count = 0
+	for (const { result } of observations) {
+		const data = result.data
+		if (typeof data !== 'object' || data === null) continue
+		const n = (data as { withheldEnv?: unknown }).withheldEnv
+		if (typeof n === 'number' && Number.isInteger(n) && n > count) count = n
+	}
+	return count
+}
+
+/**
+ * The credential notice for a settled tool batch, as a user-role message of its
+ * own, or `undefined` when the batch removed nothing or the conversation
+ * already carries this very notice. It is sent once, and again only when the
+ * number of removed variables changes, so a run of failing commands does not
+ * repeat it. The conversation is the record, so a resumed or compacted one
+ * needs no counter of its own.
+ */
+export function takeWithheldEnvNotice(
+	history: readonly Message[],
+	observations: readonly { readonly result: { readonly data?: unknown } }[],
+): UserMessage | undefined {
+	const count = withheldEnvCount(observations)
+	if (count === 0) return undefined
+	const body = withheldEnvNoticeText(count)
+	const said = history.some(
+		(message) =>
+			message.role === 'user' &&
+			message.source?.type === 'runtime-context' &&
+			message.source.kind === 'reminder' &&
+			typeof message.content === 'string' &&
+			message.content.startsWith(`<${NOTICE_TAG}-`) &&
+			message.content.includes(' kind="credentials">') &&
+			message.content.includes(body),
+	)
+	if (said) return undefined
+	return createRuntimeContextMessage(
+		frameNotice('credentials', '[Command environment]', body),
+		'reminder',
+	)
+}

package/src/scheduler/completion-inbox.ts

@@ -479,7 +479,7 @@ export class CompletionInbox {
 			stillRunningNotShown > 0
 				? ` ${shownRunning.length} running tasks are shown below, and ${stillRunningNotShown} more still running.`
 				: ''
-		return `Owned delegated work (current scheduler observations).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
+		return `Owned delegated work (current scheduler observations; a later block with this heading replaces this one).${overflow} Result delivery is not proof that you answered the original request. Answer the latest operator message and complete the requested synthesis of available results unless the operator cancelled or changed that request. Reuse delivered results when sufficient; do not relaunch completed work. If a delivered result is no longer visible, retrieve it by task ID. A terminal state with a non-end_turn stop reason is not successful task completion. Do not repeat a synthesis already given.\n${JSON.stringify({ tasks, omitted: this.ours.size - ids.length })}`
 	}
 
 	/**

package/src/tools/builtins/bash.ts

@@ -20,7 +20,7 @@ import {
 	withoutBashStartup,
 } from '../command-shell.js'
 import { defineTool } from '../defineTool.js'
-import { scrubInheritedEnv } from '../env-scrub.js'
+import { scrubInheritedEnv, withheldEnvNoticeText } from '../env-scrub.js'
 import { createHostOutputDecoder } from '../host-output.js'
 import { looksBinary, windowText } from '../text-window.js'
 import { judgeExit } from './exit-semantics.js'
@@ -802,10 +802,10 @@ const BashToolBase = defineTool({
 				failure.stdoutTruncated ? 'stdout' : '',
 				failure.stderrTruncated ? 'stderr' : '',
 			].filter(Boolean)
-			// Only on the failure path. A successful command did not need to know,
-			// and appending this to every result would make the common case noisy
-			// to buy nothing. A failing one is exactly where "authentication
-			// failed" has to be distinguishable from "the variable was withheld".
+			// Only the failure path reports removed variables (in `data`, for the
+			// kernel's notice). A successful command did not need to know; a failing
+			// one is where "authentication failed" has to be distinguishable from
+			// "the variable was withheld".
 			// A status the command uses to answer (no match, files differ) is a
 			// result, not a failure; the model sees it as an ordinary call.
 			const judged =
@@ -816,7 +816,6 @@ const BashToolBase = defineTool({
 				clipped.length > 0
 					? `[${clipped.join(' and ')} ${clipped.length === 1 ? 'was' : 'were'} truncated by the host output cap. The omitted output is unavailable in this result.]`
 					: '',
-				answered ? '' : describeWithheldEnv(inherited.dropped),
 			]
 				.filter(Boolean)
 				.join('\n\n')
@@ -827,6 +826,11 @@ const BashToolBase = defineTool({
 				data: {
 					...(exitCode !== undefined ? { exitCode } : {}),
 					...(judged?.note ? { exitNote: judged.note } : {}),
+					// How many variables were removed, for the kernel's own notice; the
+					// model's result stays what the command printed.
+					...(!answered && inherited.dropped.length > 0
+						? { withheldEnv: inherited.dropped.length }
+						: {}),
 					...(leaveSandbox ? { sandboxed: false, sandboxEscape: true } : {}),
 					timedOut,
 					stdoutTruncated: failure.stdoutTruncated ?? false,
@@ -904,16 +908,12 @@ function formatShellOutput(stdout: string | undefined, stderr: string | undefine
 }
 
 /**
- * Say that credential-shaped variables were left out of this command's
- * environment. The count is enough: the model needs to know a missing
- * credential is deliberate and who to ask, and the names are the user's data.
- * A command that failed because it wanted one otherwise reports an
- * authentication error pointing nowhere.
+ * The notice text for the credential-shaped variables left out of a command's
+ * environment (see {@link withheldEnvNoticeText}). It is sent as a notice after
+ * the tool batch, never written into the command's result.
  */
 export function describeWithheldEnv(dropped: readonly string[]): string {
-	if (dropped.length === 0) return ''
-	const one = dropped.length === 1
-	return `NOTE: ${dropped.length} credential-shaped environment ${one ? 'variable was' : 'variables were'} removed from this command's environment, so ${one ? 'it reads' : 'they read'} as unset. Ask the user if the command needs ${one ? 'it' : 'one'}.`
+	return withheldEnvNoticeText(dropped.length)
 }
 
 /**

package/src/tools/builtins/edit.ts

@@ -428,7 +428,7 @@ function refusedEdit(result: EditApplyFailure, path: string) {
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
-		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Self-budget new_string/newStr under 12000 characters before emitting the tool call; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits`: a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed.',
+		'Makes targeted edits to a file using exact string find-and-replace or line insertion. To change an existing file, use `edit`: `write` overwrites the whole body and discards earlier work on partial failure, while `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Keep new_string/newStr under 12000 characters, because a longer payload can be cut off mid-call and fail; use repeated bounded edits for long sections. Preserves file formatting and indentation. To make several changes to one file that only make sense together, send them as `edits`: a list of {old_string, new_string} applied in order and committed as one write — if any of them does not apply, nothing is written and the reply names which one, so the file is never left half-changed.',
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,

package/src/tools/env-scrub.ts

@@ -91,3 +91,16 @@ export function scrubInheritedEnv(source: NodeJS.ProcessEnv = process.env): Scru
 	dropped.sort()
 	return { env, dropped }
 }
+
+/**
+ * What the model is told, once, when shell commands run with credential-shaped
+ * variables removed. The count is enough: the model needs to know a missing
+ * credential is deliberate and who to ask, and the names are the user's data.
+ * The kernel sends this as a notice of its own after the tool batch; a command's
+ * result carries only what the command printed.
+ */
+export function withheldEnvNoticeText(count: number): string {
+	if (count <= 0) return ''
+	const one = count === 1
+	return `A shell command that just ran had ${count} credential-shaped environment ${one ? 'variable' : 'variables'} removed from its environment, so ${one ? 'it reads' : 'they read'} as unset. When a failure looks like a missing credential, ask the user to provide ${one ? 'it' : 'one'}, because the user decides what a command may see.`
+}

package/src/tools/resident-history.ts

@@ -8,6 +8,8 @@ import { defineTool } from './defineTool.js'
  * Read-only tools over an explicitly authorized historical source. The host
  * resolves and checks the executing turn's scope; models choose no paths,
  * tenant, resident, pursuit or upper-history boundary.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function buildResidentHistoryTools(
 	resolveSource: (context: ToolContext) => ResidentHistorySource,

package/src/tools/resident-tool-evidence.ts

@@ -3,7 +3,11 @@ import type { ResidentToolEvidenceSource } from '../manager/resident/tool-eviden
 import type { ToolContext, ToolDefinition } from '../types/tool/index.js'
 import { defineTool } from './defineTool.js'
 
-/** @experimental The host must authorize each executing turn before returning its bound source. */
+/**
+ * @experimental The host must authorize each executing turn before returning its bound source.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export function buildResidentToolEvidenceTools(
 	resolveSource: (context: ToolContext) => ResidentToolEvidenceSource,
 ): ToolDefinition[] {