@namzu/sdk 27.0.0 → 27.1.0

package/src/registry/tool/screen.ts

@@ -0,0 +1,131 @@
+import type {
+	ToolResultGuardrailContext,
+	ToolResultGuardrailSpec,
+	ToolResultVerdict,
+} from '../../types/guardrail/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
+import { toErrorMessage } from '../../utils/error.js'
+import type { Logger } from '../../utils/logger.js'
+
+/**
+ * A tool result was refused terminally.
+ *
+ * Thrown rather than returned because the caller's failure path turns every
+ * exception into an ordinary tool failure the model then reads and works
+ * around — which is exactly what a terminal refusal must not become. The
+ * distinct type is what lets that path re-throw this one and convert the
+ * rest. A `halt` reported as a failed tool call would be a `refuse` with
+ * extra steps.
+ */
+export class ToolResultHalted extends Error {
+	readonly guardrail: string
+
+	constructor(guardrail: string, reason: string) {
+		super(`Tool result halted by guardrail "${guardrail}": ${reason}`)
+		this.name = 'ToolResultHalted'
+		this.guardrail = guardrail
+	}
+}
+
+function nameOf(spec: { name?: string }, index: number): string {
+	return spec.name ?? `tool-result-guardrail[${index}]`
+}
+
+function normalize<T>(spec: T | { name: string; check: T }): { name?: string; check: T } {
+	return typeof spec === 'function' ? { check: spec as T } : (spec as { name: string; check: T })
+}
+
+/**
+ * A guardrail that throws FAILS CLOSED, as the run-level ones do.
+ *
+ * `refuse` rather than `halt` for the same reason the tool boundary has a
+ * recoverable refusal at all: a broken screen means this result's safety is
+ * unknown, not that the run is unsalvageable. The model is told and can
+ * choose differently.
+ */
+async function safely(
+	run: () => ToolResultVerdict | Promise<ToolResultVerdict>,
+	name: string,
+	log: Logger,
+): Promise<ToolResultVerdict> {
+	try {
+		return await run()
+	} catch (err) {
+		const reason = `guardrail "${name}" threw: ${toErrorMessage(err)}`
+		log.error('Tool-result guardrail threw — failing closed', {
+			guardrail: name,
+			error: toErrorMessage(err),
+		})
+		return { action: 'refuse', reason }
+	}
+}
+
+/**
+ * Screen a tool's result before anything downstream reads it.
+ *
+ * Runs every guardrail in order and stops at the first refusal. Rewrites
+ * compose — each guardrail sees what the previous one produced — matching
+ * the output-guardrail path, so a redaction chain behaves the same at both
+ * boundaries.
+ *
+ * Returns the result to use. A refusal comes back as a failed `ToolResult`
+ * carrying the reason, because that is the shape the model already knows
+ * how to read: it is the same thing a tool that could not do its job
+ * returns, and the alternative — a blank result — tells the model the tool
+ * found nothing, which is a different claim and a false one.
+ */
+export async function screenToolResult(
+	guardrails: readonly ToolResultGuardrailSpec[] | undefined,
+	result: ToolResult,
+	ctx: Omit<ToolResultGuardrailContext, 'output' | 'success'>,
+	log: Logger,
+): Promise<ToolResult> {
+	if (!guardrails || guardrails.length === 0) return result
+
+	let current = result.output
+	let rewritten = false
+
+	for (const [index, spec] of guardrails.entries()) {
+		const { name, check } = normalize(spec)
+		const label = nameOf({ name }, index)
+		const verdict = await safely(
+			() => check({ ...ctx, output: current, success: result.success }),
+			label,
+			log,
+		)
+
+		if (verdict.action === 'halt') {
+			log.error('Tool-result guardrail halted the run', {
+				tool: ctx.toolName,
+				guardrail: label,
+				reason: verdict.reason,
+			})
+			throw new ToolResultHalted(label, verdict.reason)
+		}
+
+		if (verdict.action === 'refuse') {
+			log.warn('Tool-result guardrail refused the result', {
+				tool: ctx.toolName,
+				guardrail: label,
+				reason: verdict.reason,
+			})
+			return {
+				success: false,
+				output: '',
+				error: `Tool "${ctx.toolName}" produced a result that was refused by guardrail "${label}": ${verdict.reason}`,
+			}
+		}
+
+		if (verdict.action === 'rewrite') {
+			log.info('Tool-result guardrail rewrote the result', {
+				tool: ctx.toolName,
+				guardrail: label,
+				reason: verdict.reason,
+			})
+			current = verdict.output
+			rewritten = true
+		}
+	}
+
+	return rewritten ? { ...result, output: current } : result
+}

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

@@ -2,6 +2,8 @@ import type {
 	GuardrailVerdict,
 	NamedGuardrail,
 	OutputGuardrail,
+	ToolResultGuardrail,
+	ToolResultVerdict,
 } from '../../types/guardrail/index.js'
 
 /**
@@ -100,6 +102,12 @@ const INJECTION_PATTERNS: readonly RegExp[] = [
  * Input-side because it is cheapest there — nothing has been spent — and
  * because the same text reaching the model is the thing you are trying to
  * prevent.
+ *
+ * It cannot see an INDIRECT injection, and that is not a limitation of the
+ * patterns: an injection carried in a web page or a connected server's
+ * answer never appears in the run's input at all. See
+ * {@link toolResultInjectionGuardrail}, which is the same list at the other
+ * boundary.
  */
 export function promptInjectionGuardrail(): NamedGuardrail<
 	(ctx: { messages: readonly { readonly content: unknown }[] }) => GuardrailVerdict
@@ -122,3 +130,45 @@ export function promptInjectionGuardrail(): NamedGuardrail<
 		},
 	}
 }
+
+/**
+ * Flag likely instruction-override attempts in what a TOOL returned.
+ *
+ * The case the input-side screen structurally cannot reach. An indirect
+ * injection arrives in a fetched page or a connected server's answer, so it
+ * is never in the run's input — by the time it matters the run is
+ * legitimate and the payload is riding on a result the model asked for.
+ *
+ * `refuse`, not `halt`: a hostile result is a reason to abandon that call,
+ * not the run. The model is told the answer was refused and can choose
+ * something else, which is the behaviour that keeps the control switched on
+ * — a screen that ends a run on a false positive gets removed, and then it
+ * protects nothing.
+ *
+ * **Detection is partial and this says so rather than implying coverage.**
+ * The pattern list is shared with the input-side screen, so the same caveat
+ * holds: an injection phrased as ordinary prose, or written in a language
+ * the list does not cover, passes. Pattern-matching and delimiting both
+ * measure poorly against an attacker who adapts. This raises the cost of
+ * the lazy attack; it is not a boundary, and nothing here should be
+ * described as one.
+ */
+export function toolResultInjectionGuardrail(): NamedGuardrail<ToolResultGuardrail> {
+	return {
+		name: 'tool-result-injection',
+		check: ({ output, provenance }): ToolResultVerdict => {
+			for (const pattern of INJECTION_PATTERNS) {
+				if (!pattern.test(output)) continue
+				// Naming the source is most of what the model needs in order
+				// to act. "A result was refused" is not something it can route
+				// around; "the answer from weather-co was refused" is.
+				const source = provenance ? `the connected server "${provenance.server}"` : 'this tool'
+				return {
+					action: 'refuse',
+					reason: `the result from ${source} matched a known instruction-override pattern`,
+				}
+			}
+			return { action: 'pass' }
+		},
+	}
+}

package/src/types/guardrail/index.ts

@@ -1,5 +1,6 @@
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { ToolProvenance } from '../tool/index.js'
 
 /**
  * Guardrails inspect what goes INTO a run and what comes OUT of it.
@@ -58,5 +59,75 @@ export interface NamedGuardrail<T> {
 	readonly check: T
 }
 
+/**
+ * What a guardrail sees when a tool has produced a result.
+ *
+ * The two above bracket the RUN. This one sits at the tool boundary, which
+ * is the only place a result can be examined before the model reads it:
+ * the registry returns to the executor, the executor applies the output
+ * budget and spills what is over it, and compaction summarises later still.
+ * So screening here is upstream of both by construction rather than by
+ * ordering — a summariser does not distinguish trusted from untrusted text,
+ * and content carried into a summary outlives the result it came from.
+ *
+ * `provenance` is the point. A connector's result is framed with the
+ * server's name (see `wrapUntrusted`), and a screen that can only read the
+ * value cannot tell a remote server's words from a first-party tool's.
+ */
+export interface ToolResultGuardrailContext {
+	/** The tool as the registry knows it. */
+	readonly toolName: string
+	/** Validated input the tool was called with. */
+	readonly input: unknown
+	/** The text the model would read. */
+	readonly output: string
+	/** Whether the tool itself reported success. */
+	readonly success: boolean
+	/**
+	 * Who produced the tool, when it was not this process. Absent means
+	 * host-defined; present names the connected server.
+	 */
+	readonly provenance?: ToolProvenance
+}
+
+/**
+ * What a guardrail decided about a tool result.
+ *
+ * Deliberately NOT {@link GuardrailVerdict}. There, `block` ends the run —
+ * it is the only thing it can mean when the subject is the run's input or
+ * its final answer. At a tool boundary the useful refusal is usually the
+ * other one: fail this call, tell the model why, and let it choose
+ * something else. Reusing the word would give one spelling two meanings
+ * across boundaries, and a host that shared a function between them would
+ * get the wrong one silently.
+ *
+ * Hence two refusals rather than one:
+ *
+ *  - `refuse` — recoverable. The `tool_use` fails with the reason in place
+ *    of the output. Not blank and not dropped: a model shown an empty
+ *    result concludes the tool found nothing, which is a different fact and
+ *    invites the retry loop the refusal was meant to prevent.
+ *  - `halt` — terminal, for what must not be survived.
+ *
+ * `rewrite` is for REDACTION — a credential or an account number that
+ * should not enter context — and this is the last boundary where it can be
+ * removed before it does. It is **not** for neutralising an injection:
+ * editing an attack presumes you understood the payload well enough to
+ * defang it, and the systems that screen for attacks block instead. The two
+ * are the same mechanism and only the discipline separates them, which is
+ * why it is written here rather than left to be inferred.
+ */
+export type ToolResultVerdict =
+	| { readonly action: 'pass' }
+	| { readonly action: 'refuse'; readonly reason: string }
+	| { readonly action: 'halt'; readonly reason: string }
+	| { readonly action: 'rewrite'; readonly output: string; readonly reason?: string }
+
+export type ToolResultGuardrail = (
+	ctx: ToolResultGuardrailContext,
+) => ToolResultVerdict | Promise<ToolResultVerdict>
+
+export type ToolResultGuardrailSpec = ToolResultGuardrail | NamedGuardrail<ToolResultGuardrail>
+
 export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>
 export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>

package/src/types/tool/index.ts

@@ -1,5 +1,10 @@
 import type { z } from 'zod'
 import type { Logger } from '../../utils/logger.js'
+// Type-only, and circular by design: a tool-result guardrail is described in
+// terms of the tool that produced the result, and the registry that holds
+// the guardrails is described here. Erased at compile time, so neither
+// module exists at runtime to depend on the other.
+import type { ToolResultGuardrailSpec } from '../guardrail/index.js'
 import type { RunId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { PermissionMode } from '../permission/index.js'
@@ -390,6 +395,16 @@ export interface ToolTierConfig {
 export interface ToolRegistryConfig {
 	logger?: Logger
 	tierConfig?: ToolTierConfig
+	/**
+	 * Screens run against every tool result before anything downstream
+	 * reads it — the output budget, compaction, and the model itself are
+	 * all past this point.
+	 *
+	 * Absent means no screening, which is what shipped before this existed:
+	 * a connected server's text reached the model unexamined. See
+	 * {@link ToolResultGuardrailSpec}.
+	 */
+	resultGuardrails?: readonly ToolResultGuardrailSpec[]
 }
 
 export interface ToolExecutionResult extends ToolResult {