@namzu/sdk 46.0.0 → 48.1.0

package/src/runtime/query/executor.ts

@@ -1,6 +1,7 @@
 import { join } from 'node:path'
 import type { Span } from '@opentelemetry/api'
 import type { AuthorizationGate } from '../../authorization/gate.js'
+import { unknownProgramInLine } from '../../authorization/program.js'
 import { type SkillGrantSet, compileSkillGrant } from '../../authorization/skill-grant.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
@@ -15,6 +16,8 @@ import { sandboxShellSpawn, withoutBashStartup } from '../../tools/command-shell
 import { isAlwaysDestructive } from '../../tools/defineTool.js'
 import { createFileReadTracker } from '../../tools/file-read-tracker.js'
 import { pathOutsideRoots, toolRoots } from '../../tools/paths.js'
+import type { ToolManager } from '../../toolsets/manager.js'
+import type { ToolSourceRef } from '../../toolsets/types.js'
 import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
 import type { ToolCallEscalation } from '../../types/hitl/index.js'
 import type { SessionId, ToolUseId, TurnId } from '../../types/ids/index.js'
@@ -23,6 +26,7 @@ import {
 	type Message,
 	type ToolCall,
 	type ToolResultContent,
+	type ToolRevealReceipt,
 	createToolMessage,
 } from '../../types/message/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
@@ -38,9 +42,9 @@ import type {
 	ShellDialect,
 	SkillRegistryRef,
 	ToolContext,
+	ToolDefinition,
 	ToolDispatchOptions,
 	ToolHandoff,
-	ToolRegistryContract,
 	ToolResult,
 } from '../../types/tool/index.js'
 import type { RepairToolCall } from '../../types/tool/repair.js'
@@ -60,8 +64,8 @@ import {
 	repairTruncatedCall,
 	resolveCall,
 	runPreToolHook,
-	truncatedToolInputMessage,
 	unknownToolMessage,
+	unreadableToolCallMessage,
 } from './executor/tool-call-admission.js'
 import { describeVisibleFileEvidence } from './file-evidence-context.js'
 import { seedObservationLedger } from './file-evidence-seed.js'
@@ -304,7 +308,7 @@ export const DEFAULT_TOOL_RETRY_BACKOFF: BackoffPolicy = {
 
 export interface ToolExecutorConfig {
 	fileReadTracker?: FileReadTracker
-	tools: ToolRegistryContract
+	tools: ToolManager
 	sessionId: SessionId
 	turnId: TurnId
 	workingDirectory: string
@@ -494,6 +498,15 @@ export interface ToolCallOutcome {
 	isError?: boolean
 	/** The tool asked for a person; see `ToolResult.handoff`. */
 	handoff?: ToolHandoff
+	/**
+	 * Source-bound receipts for names this successful call revealed
+	 * (`ToolResult.reveals`, filtered to deferred names inside any active
+	 * allow-list). Carried onto the persisted tool message
+	 * (`ToolMessage.revealedTools`) so `ToolManager.availability`
+	 * (`toolsets/manager.ts`) can derive activation from history instead of
+	 * a mutable map.
+	 */
+	revealedTools?: readonly ToolRevealReceipt[]
 }
 
 export interface ToolExecutionBatch {
@@ -797,6 +810,7 @@ export class ToolExecutor {
 			toolInput: input,
 			toolDef: this.config.tools.get(toolName),
 			commandDialect: this.commandDialect(toolName),
+			toolSource: this.toolSource(toolName),
 		})
 	}
 
@@ -807,7 +821,22 @@ export class ToolExecutor {
 	 */
 	commandDialect(toolName: string): ShellDialect {
 		const tool = this.config.tools.get(toolName)
-		return tool?.commandDialect?.({ sandboxed: this.config.sandbox !== undefined }) ?? 'sh'
+		return (
+			tool?.commandDialect?.({
+				sandboxed: this.config.sandbox !== undefined,
+			}) ?? 'sh'
+		)
+	}
+
+	/**
+	 * Where `toolName` came from, for the gate's `allow_read_only` rule to
+	 * tell an operator-trusted MCP server's `readOnlyHint` from an untrusted
+	 * one's. `sourceOf` throws for a name the manager does not have, so this
+	 * checks first rather than let an unknown nested-call name throw here
+	 * instead of being refused by the gate itself.
+	 */
+	toolSource(toolName: string): ToolSourceRef | undefined {
+		return this.config.tools.has(toolName) ? this.config.tools.sourceOf(toolName) : undefined
 	}
 
 	/**
@@ -863,13 +892,37 @@ export class ToolExecutor {
 			sandboxed &&
 			tool.sandboxEscapeArgument !== undefined &&
 			input[tool.sandboxEscapeArgument] === true
-		if (!outsidePaths && !sandboxEscape) return undefined
+		const unknownProgram = this.unknownProgramOf(tool, input, sandboxed)
+		if (!outsidePaths && !sandboxEscape && unknownProgram === undefined) return undefined
 		return {
 			...(outsidePaths ? { outsidePaths } : {}),
 			...(sandboxEscape ? { sandboxEscape: true as const } : {}),
+			...(unknownProgram !== undefined ? { unknownProgram } : {}),
 		}
 	}
 
+	/**
+	 * Why a command's own program name is not knowable ahead of running it,
+	 * in a tool's `commandArgument`, or undefined. Delegates to
+	 * {@link unknownProgramInLine} — the SDK's one answer to this question,
+	 * shared with that function's own tests so they cannot drift from what
+	 * this method actually calls the way an independent test mirror once
+	 * did. Checked whether or not the turn is sandboxed: a program nobody
+	 * can name before it runs is exactly as unverifiable inside a sandbox as
+	 * outside one.
+	 */
+	private unknownProgramOf(
+		tool: { commandArgument?: string; commandDialect?: ToolDefinition['commandDialect'] },
+		input: Record<string, unknown>,
+		sandboxed: boolean,
+	): string | undefined {
+		if (tool.commandArgument === undefined) return undefined
+		const value = input[tool.commandArgument]
+		if (typeof value !== 'string') return undefined
+		const dialect = tool.commandDialect?.({ sandboxed }) ?? 'sh'
+		return unknownProgramInLine(value, dialect)
+	}
+
 	/** Re-prepare only calls whose raw input a reviewer actually changed. */
 	async reprepareBatchForReview(
 		response: ChatCompletionResponse,
@@ -1155,7 +1208,7 @@ export class ToolExecutor {
 		// so the failure signal and any image block were structurally lost at
 		// the last possible moment.
 		const messages: Message[] = results.map((r) =>
-			createToolMessage(r.content ?? r.output, r.toolCallId, r.isError),
+			createToolMessage(r.content ?? r.output, r.toolCallId, r.isError, r.revealedTools),
 		)
 
 		return { messages, results, observations }
@@ -1261,6 +1314,7 @@ export class ToolExecutor {
 			toolInput: preparedInput,
 			toolDef: this.config.tools.get(name),
 			commandDialect: this.commandDialect(name),
+			toolSource: this.toolSource(name),
 		})
 		if (gateResult && gateResult.decision !== 'allow') {
 			const reason =
@@ -1358,7 +1412,10 @@ export class ToolExecutor {
 				input: preparedInput,
 				...(via ? { via } : {}),
 			},
-			buildProbeContext({ sessionId: this.config.sessionId, turnId: this.config.turnId }),
+			buildProbeContext({
+				sessionId: this.config.sessionId,
+				turnId: this.config.turnId,
+			}),
 		)
 		if (vetoOutcome.action === 'deny') {
 			const probeName = vetoOutcome.probeName ?? 'unnamed'
@@ -1458,7 +1515,13 @@ export class ToolExecutor {
 			// cannot tell apart from the result text alone.
 			if (!result.success) {
 				return view?.kind === 'generic' && view.outcome === 'cancelled'
-					? { presentation: { kind: 'generic', label: view.label, outcome: 'cancelled' } as const }
+					? {
+							presentation: {
+								kind: 'generic',
+								label: view.label,
+								outcome: 'cancelled',
+							} as const,
+						}
 					: {}
 			}
 			if (view?.kind !== 'diff') return {}
@@ -1606,7 +1669,7 @@ export class ToolExecutor {
 					: null
 
 			if (toolCall.metadata?.inputTruncated === true && !truncationRepair) {
-				const message = truncatedToolInputMessage(toolName)
+				const message = unreadableToolCallMessage(this.admissionHost(), toolCall, toolName)
 				await this.emitEvent({
 					type: 'tool_executing',
 					turnId: this.config.turnId,
@@ -1724,7 +1787,10 @@ export class ToolExecutor {
 				toolName,
 				input,
 			},
-			buildProbeContext({ sessionId: this.config.sessionId, turnId: this.config.turnId }),
+			buildProbeContext({
+				sessionId: this.config.sessionId,
+				turnId: this.config.turnId,
+			}),
 		)
 		if (vetoOutcome.action === 'deny') {
 			const probeName = vetoOutcome.probeName ?? 'unnamed'
@@ -1930,7 +1996,10 @@ export class ToolExecutor {
 		const modelContent =
 			selectedContent === undefined
 				? undefined
-				: this.budgetContent(selectedContent, toolName, toolCall.id, { sourceOutput, budgeted })
+				: this.budgetContent(selectedContent, toolName, toolCall.id, {
+						sourceOutput,
+						budgeted,
+					})
 
 		// A failed call, or an override that says the call failed. A `replace`
 		// says the opposite, and reading it as a failure is what made redaction
@@ -1945,6 +2014,30 @@ export class ToolExecutor {
 			}
 		}
 
+		// A reveal loads a deferred schema after a successful call. Host-owned
+		// readiness remains a separate gate: a suspended tool cannot be found
+		// or revealed, and a prior receipt cannot make it ready. Bind the
+		// receipt to the current owner so a later source reusing the same name
+		// does not inherit it.
+		//
+		// `revealedTools` is written onto the persisted tool message; nothing
+		// here mutates the manager itself, because `ToolManager.availability`
+		// (`toolsets/manager.ts`) DERIVES availability from this field the
+		// next time it reads the turn's post-compaction history — compaction
+		// is the one boundary that resets it. There is no `activate()` call
+		// to make: the manager has no mutable membership to activate.
+		let revealedTools: readonly ToolRevealReceipt[] | undefined
+		if (!this.config.abortSignal.aborted && !effectiveIsError && result.reveals?.length) {
+			const revealed = result.reveals.filter(
+				(name) =>
+					this.config.tools.availability(name) === 'deferred' &&
+					(toolContext.allowedTools === undefined || toolContext.allowedTools.includes(name)),
+			)
+			if (revealed.length > 0) {
+				revealedTools = revealed.map((name) => this.config.tools.revealReceipt(name))
+			}
+		}
+
 		if (result.success) {
 			this.log.debug('Tool executed successfully', {
 				[NAMZU.TURN_ID]: this.config.turnId,
@@ -2022,6 +2115,7 @@ export class ToolExecutor {
 			...(result.handoff !== undefined && !this.config.abortSignal.aborted
 				? { handoff: result.handoff }
 				: {}),
+			...(revealedTools !== undefined ? { revealedTools } : {}),
 		}
 	}
 
@@ -2311,7 +2405,11 @@ export class ToolExecutor {
 				isError: true,
 			}
 		}
-		return { kind: 'ready', input: modified.prepared.input, prepared: modified.prepared }
+		return {
+			kind: 'ready',
+			input: modified.prepared.input,
+			prepared: modified.prepared,
+		}
 	}
 
 	/**

package/src/runtime/query/file-evidence-replay.ts

@@ -242,12 +242,13 @@ export function collectObservedPaths(
  * The recorded arguments and nothing else. A receipt names the path too, but it
  * names it inside a sentence a path may itself contain, in a spelling that
  * differs between the host and sandbox branches, and compaction clears receipts
- * while it never clears a call. A call the provider stream cut off mid-JSON
- * carries `{}` here: `function.arguments` is normalized to that and the raw
- * buffer moves to `metadata.partialArguments`, which is what the model was
- * saying rather than what ran — a `repairToolCall` hook may have rewritten the
- * arguments before execution. So a truncated call is attributable to nothing,
- * and the walk treats it as such. So is a call whose arguments run past
+ * while it never clears a call. A call whose arguments could not be read, cut
+ * off mid-JSON or malformed, carries `{}` here: `function.arguments` is
+ * normalized to that and the raw buffer moves to `metadata.partialArguments`,
+ * which is what the model was saying rather than what ran — a
+ * `repairToolCall` hook may have rewritten the arguments before execution. So
+ * an unreadable call is attributable to nothing, and the walk treats it as
+ * such. So is a call whose arguments run past
  * {@link MAX_ATTRIBUTION_UNITS}, which this does not read at all.
  *
  * Answered once per pass and remembered. The path collection and the walk ask
@@ -270,7 +271,7 @@ function declaredPath(call: ToolCall, attributions: PathAttributions): string |
  *
  * One function because a middle hop is not a lesser claim than the last one.
  * A chain whose second edit was cleared by compaction, or came back an error,
- * or arrived truncated, reconstructs nothing at all — so the whole path is
+ * or arrived with arguments that could not be read, reconstructs nothing at all — so the whole path is
  * withheld rather than emitted as the part still visible, which would name a
  * body the model cannot rebuild.
  *

package/src/runtime/query/fork/prepare.ts

@@ -1,6 +1,8 @@
+import { assertSessionLogAttribution } from '../../../manager/session/attribution.js'
 import type { CheckpointScope, SessionCheckpointStore } from '../../../store/checkpoint/index.js'
 import type { SessionLog } from '../../../store/session-log/index.js'
 import type { CheckpointId } from '../../../types/hitl/index.js'
+import type { TopicId } from '../../../types/ids/index.js'
 import type { Message } from '../../../types/message/index.js'
 import type { Checkpoint } from '../../../types/session/checkpoint.js'
 import type { Mutation } from '../../../types/session/fork.js'
@@ -18,7 +20,7 @@ export interface PrepareForkInput {
 	/** The store the source turn's checkpoints are in. */
 	readonly checkpointStore: SessionCheckpointStore
 	/** The source turn, across the full attribution. */
-	readonly scope: CheckpointScope
+	readonly scope: CheckpointScope & { readonly topicId: TopicId }
 	/** Which checkpoint to fork at. */
 	readonly fromCheckpoint: CheckpointSelector
 	/** Mutations applied at the fork point before the caller hands the state to `query()`. */
@@ -55,6 +57,9 @@ export interface PreparedForkState {
  * covers must be intact.
  */
 export async function prepareForkState(input: PrepareForkInput): Promise<PreparedForkState> {
+	// A checkpoint address alone cannot authorize reading the source session's
+	// conversation. The log owner must agree before touching its checkpoints.
+	await assertSessionLogAttribution(input.sessionLog, input.scope, { requireStarted: true })
 	const sourceCheckpoint = await resolveCheckpoint(input)
 	const restored = await restoreCheckpointContext(input.sessionLog, sourceCheckpoint)
 	const mutations = input.mutate ?? []

package/src/runtime/query/guardrail-presets.ts

@@ -497,9 +497,10 @@ export function toolResultCorrespondenceGuardrail(
  * The screens a turn installs on itself when its host configured none.
  *
  * A DEFAULT, and the reason it is here rather than on
- * {@link ToolRegistryConfig.resultGuardrails}: a host assembles a registry
- * and hands it to `runAgent`, so a registry-constructor default would be the
- * host's to write and this repository's default would reach nobody. The turn
+ * `ToolManagerConfig.resultGuardrails` (`toolsets/manager.ts`): a host
+ * assembles its toolsets and hands them to `query()`, so a manager-construction
+ * default would be the host's to write and this repository's default would
+ * reach nobody. The turn
  * is the thing that has to carry it, and a turn that wants none says so with
  * an empty array — which is the escape hatch, and it exists precisely because
  * the screen below can refuse a result.