@namzu/sdk 26.0.0 → 27.0.0

package/src/tools/coordinator/index.ts

@@ -157,6 +157,73 @@ const askUserQuestionModelInputSchema: Record<string, unknown> = {
 	additionalProperties: false,
 }
 
+/** One well-formed tag token: `<step>`, `</step>`, `<a href="…">`, `<br/>`. */
+const TAG_TOKEN = /<\/?[A-Za-z][\w-]*(?:\s[^<>]*)?\/?>/g
+const DESCRIPTION_BLOCK = /<description>([\s\S]*?)<\/description>/gi
+
+/**
+ * Remove every tag token, including the ones removing a tag creates.
+ *
+ * One pass is not enough and the reason is not obvious: deleting an inner
+ * tag can splice its neighbours into a new one. `<<step>step>` loses the
+ * inner `<step>` and the halves close up into `<step>` again, so a line
+ * that is nothing but markup comes back non-empty and is offered to a
+ * human as a step to approve — which is the exact outcome this whole path
+ * exists to prevent.
+ *
+ * Repeating to a fixed point terminates: every pass that changes the
+ * string removes at least one token and so strictly shortens it.
+ *
+ * Only ever used to ANSWER "is there anything here besides markup". The
+ * result is never shown to anyone, so this is a test rather than a
+ * sanitiser, and it does not have to defend against every way a tag can
+ * be spelled.
+ */
+function withoutTags(text: string): string {
+	let current = text
+	for (;;) {
+		const next = current.replace(TAG_TOKEN, '')
+		if (next === current) return current
+		current = next
+	}
+}
+
+/**
+ * Peel tag wrappers off the ENDS of one line, and nowhere else — a step
+ * that legitimately says "wrap it in a <div>" keeps its sentence.
+ */
+function unwrapStepLine(line: string): string {
+	let text = line.trim()
+	for (;;) {
+		const next = text
+			.replace(/^<[A-Za-z][\w-]*(?:\s[^<>]*)?>\s*/, '')
+			.replace(/\s*<\/[A-Za-z][\w-]*>$/, '')
+			.trim()
+		if (next === text) break
+		text = next
+	}
+	return text
+}
+
+/**
+ * A step list the model serialized instead of building.
+ *
+ * The line-splitting fallback below is the general case, and it had one
+ * shape badly wrong. A model that serializes this array tends to reach for
+ * MARKUP, not for prose:
+ *
+ *     <steps>
+ *     <step>
+ *     <description>Convert the document to Word</description>
+ *     </step>
+ *     </steps>
+ *
+ * Split on newlines, that is seven "steps", five of which are tags. A host
+ * then numbered them in an approval card and asked a person to approve
+ * `</steps>` — reported from a real run. The descriptions the model named
+ * are right there, so read them; fall back to lines only when there are
+ * none, and drop the lines that carry no words at all.
+ */
 function normalizeApprovePlanSteps(value: unknown): unknown {
 	if (typeof value !== 'string') return value
 
@@ -171,19 +238,84 @@ function normalizeApprovePlanSteps(value: unknown): unknown {
 		}
 	}
 
+	const described = [...trimmed.matchAll(DESCRIPTION_BLOCK)]
+		.map((match) => (match[1] ?? '').trim())
+		.filter(Boolean)
+	if (described.length > 0) {
+		return described.map((description) => ({ description }))
+	}
+
 	const lines = trimmed
 		.split(/\r?\n+/)
 		.map((line) =>
-			line
-				.trim()
-				.replace(/^(?:[-*•]|\d+[.)])\s*/, '')
-				.trim(),
+			unwrapStepLine(
+				line
+					.trim()
+					.replace(/^(?:[-*•]|\d+[.)])\s*/, '')
+					.trim(),
+			),
 		)
-		.filter(Boolean)
+		.filter((line) => line.length > 0 && withoutTags(line).trim().length > 0)
+
+	// Every line was markup: there is no plan in this string, and inventing
+	// one step reading `<steps>` is worse than saying so.
+	if (lines.length === 0) {
+		return withoutTags(unwrapStepLine(trimmed)).trim()
+			? [{ description: unwrapStepLine(trimmed) }]
+			: []
+	}
 
-	return (lines.length ? lines : [trimmed]).map((description) => ({
-		description,
-	}))
+	return lines.map((description) => ({ description }))
+}
+
+/**
+ * The single closed shape a capable provider constrains this call to —
+ * the same instrument `ask_user_question` carries, for the same failure.
+ *
+ * `steps` arriving as a STRING is what everything above exists to survive,
+ * and surviving it is not the same as preventing it: the normalizer can
+ * only guess at a structure the model already threw away. Advertising the
+ * closed shape turns the guess into a refusal at generation time.
+ */
+const approvePlanModelInputSchema: Record<string, unknown> = {
+	type: 'object',
+	properties: {
+		title: {
+			type: 'string',
+			description: 'Short title for the plan (e.g. "TypeScript Security & Performance Review").',
+		},
+		summary: {
+			type: 'string',
+			description: '1-3 sentence summary of what you plan to do.',
+		},
+		steps: {
+			type: 'array',
+			description:
+				'A JSON array of ordered step objects. Never a string, and never markup — no <step> or <description> tags.',
+			items: {
+				type: 'object',
+				properties: {
+					description: {
+						type: 'string',
+						description: 'What this step does, as one plain sentence a person can read.',
+					},
+					agent_id: {
+						type: 'string',
+						description: 'Which agent handles this; omit for steps you carry out yourself.',
+					},
+					depends_on: {
+						type: 'array',
+						items: { type: 'string' },
+						description: 'Descriptions of the steps that must finish before this one.',
+					},
+				},
+				required: ['description'],
+				additionalProperties: false,
+			},
+		},
+	},
+	required: ['title', 'summary', 'steps'],
+	additionalProperties: false,
 }
 
 /**
@@ -1013,6 +1145,10 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					.preprocess(normalizeApprovePlanSteps, z.array(approvePlanStepSchema))
 					.describe('Ordered list of planned steps'),
 			}),
+			modelInputSchema: structuredClone(approvePlanModelInputSchema),
+			enforceModelInput: true,
+			validationErrorHint:
+				'Required shape: {"title":"…","summary":"…","steps":[{"description":"One plain sentence"}]}. "steps" must be a JSON array of objects — never a string, and never markup such as <step> or <description>.',
 			category: 'custom',
 			permissions: [],
 			readOnly: true,

package/src/tools/trusted-read-only.ts

@@ -0,0 +1,52 @@
+import type { ToolDefinition } from '../types/tool/index.js'
+
+/**
+ * May this tool's read-only claim settle a gate on its own?
+ *
+ * A connected server declares whether its own tools are read-only, and
+ * that declaration decided whether a call was approved without asking. The
+ * thing being gated supplied the input to the gate.
+ *
+ * The wire itself calls these fields HINTS. Three separate consumers read
+ * them as facts, so a server setting `readOnlyHint: true` and
+ * `destructiveHint: false` controlled the whole predicate for its own
+ * tools — the kernel's `allow_read_only` rule, the operator prompt
+ * exemption, and the plan-mode pass.
+ *
+ * The estate floor this repository inherits already decided this: least
+ * privilege, default deny, and — on tool results and fetched content —
+ * data is not instructions, and untrusted content cannot escalate
+ * capabilities. A server's declaration about its own tools is untrusted
+ * content by that definition. This is that rule applied, not a new policy.
+ *
+ * **The asymmetry is the design.** A self-declaration may RAISE the
+ * requirement and never LOWER it:
+ *
+ *  - `destructiveHint: true` from a server is believed. A server
+ *    volunteering that its tool is dangerous moves toward caution, and
+ *    disbelieving it buys nothing.
+ *  - `readOnlyHint: true` from a server does not, on its own, settle a
+ *    call as allowed or skip a prompt. That is the untrusted party
+ *    opening its own gate.
+ *
+ * Trust for the second case comes from the operator, per server, and is
+ * recorded on the tool as `provenance.readOnlyHintTrusted`. Never a global
+ * switch: one flag meaning "trust annotations" hands every connected
+ * server the same reach, which is the hole restated.
+ *
+ * `isReadOnly` itself is left reporting faithfully what the server said.
+ * Provenance and policy are different questions, and collapsing them would
+ * corrupt the outbound re-export and the prompt's own destructive label in
+ * order to fix a gate.
+ */
+export function isTrustedReadOnly(tool: ToolDefinition | undefined, input: unknown): boolean {
+	if (!tool?.isReadOnly) return false
+
+	// No provenance means the tool is host-defined: it came from this
+	// process, from code the operator installed, and there is no untrusted
+	// party in the chain. Requiring an opt-in for a builtin would break
+	// every read-only exemption for no gain in trust.
+	if (tool.provenance && !tool.provenance.readOnlyHintTrusted) return false
+
+	return tool.isReadOnly(input)
+}

package/src/tools/untrusted-envelope.ts

@@ -2,12 +2,32 @@
  * Framing for content the agent did not author and must not obey.
  *
  * An unlabelled block of text in a tool result reads exactly like the agent's
- * own instructions. The mitigation that survives contact with a real model is
- * not filtering — it is saying plainly whose words these are and that they are
+ * own instructions. This says plainly whose words these are and that they are
  * material rather than direction. That is the floor this estate already
  * states: data is not instructions, and a tool result cannot escalate what an
  * agent may do.
  *
+ * **It marks provenance. It refuses nothing, and it does not stop an
+ * attacker who is trying.** This paragraph used to claim the framing was
+ * "the mitigation that survives contact with a real model", and that is
+ * measurably wrong. Nasr et al., "The Attacker Moves Second"
+ * (arXiv:2510.09023), broke twelve published defences at above 90% attack
+ * success once the attacker adapts; the majority had originally reported
+ * near-zero success. Delimiting specifically goes from as low as 1% under
+ * a static benchmark to above 95% under adaptive attack.
+ *
+ * So read every number for a prompt-level defence as static unless it says
+ * otherwise, and treat this envelope as raising cost rather than as a
+ * boundary. What survives an adapting attacker in the same literature is
+ * architectural: AgentDojo (arXiv:2406.13352) found tool isolation and
+ * tool filtering the effective mitigations, and this repository's real
+ * boundaries are of that kind — the permission gate, the sandbox, the
+ * egress proxy deciding by resolved address.
+ *
+ * The two details below still matter. They are what stops the framing
+ * being trivially removable by the content itself, which is a lower bar
+ * than stopping an attacker and worth clearing anyway.
+ *
  * Two details make the difference between a boundary and a decoration, and
  * both were missing from this repo's first envelope:
  *

package/src/types/sandbox/index.ts

@@ -103,6 +103,29 @@ export interface SandboxExecOptions {
 	readonly timeout?: number
 	readonly env?: Record<string, string>
 	readonly cwd?: string
+	/**
+	 * Called as output arrives, before the command has finished.
+	 *
+	 * Every container-tier worker already streams its output a chunk at a
+	 * time — the wire carries `stdout_delta` and `stderr_delta` events —
+	 * and every backend concatenated them into a string and returned that
+	 * when the process exited. So a command that takes eight minutes said
+	 * nothing for eight minutes, on a transport that had been reporting
+	 * the whole time.
+	 *
+	 * Additive and optional: a backend that cannot stream simply never
+	 * calls it, and `SandboxExecResult.stdout` still carries the complete
+	 * output either way. A caller that wants only the result ignores this
+	 * and behaves exactly as before.
+	 *
+	 * The callback must not throw and must not be awaited — it is on the
+	 * read path of a running process, so a slow or failing consumer would
+	 * otherwise become a slow or failing command.
+	 */
+	readonly onOutput?: (chunk: {
+		readonly stream: 'stdout' | 'stderr'
+		readonly data: string
+	}) => void
 	/**
 	 * Cancellation for the command. A backend that honours it kills the
 	 * process; one that does not simply ignores it, so this is additive.

package/src/types/tool/index.ts

@@ -322,6 +322,36 @@ export interface ToolDefinition<TInput = unknown> {
 	isReadOnly?(input: TInput): boolean
 	isDestructive?(input: TInput): boolean
 	isConcurrencySafe?(input: TInput): boolean
+
+	/**
+	 * Where this tool came from, when it did not come from here.
+	 *
+	 * Absent means host-defined: this process, code the operator installed,
+	 * no untrusted party in the chain. Present means a connected server
+	 * supplied both the tool and its own description of what the tool does
+	 * — including whether it is read-only, which three separate gates were
+	 * treating as a fact rather than as the hint the wire calls it.
+	 *
+	 * See {@link isTrustedReadOnly}. This field exists so a gate can tell
+	 * the two apart; `isReadOnly` keeps reporting faithfully what the
+	 * server said, because the outbound re-export and the destructive
+	 * label shown to a human both need the server's own answer.
+	 */
+	provenance?: ToolProvenance
+}
+
+export interface ToolProvenance {
+	/** The connected server this tool came from, named as configured. */
+	readonly server: string
+	/**
+	 * The operator marked this server's read-only claims as trustworthy.
+	 *
+	 * Per server, never global: one switch meaning "trust annotations"
+	 * hands every connected server the same reach, which is the hole it
+	 * would be closing. Default false — an unmarked server's claim raises
+	 * the requirement and never lowers it.
+	 */
+	readonly readOnlyHintTrusted: boolean
 }
 
 export type ToolPermission =

package/src/verification/rules.ts

@@ -1,4 +1,5 @@
 import { DANGEROUS_PATTERNS } from '../constants/tools/index.js'
+import { isTrustedReadOnly } from '../tools/trusted-read-only.js'
 import type { ToolDefinition } from '../types/tool/index.js'
 import type { GateDecision, VerificationRule } from '../types/verification/index.js'
 
@@ -12,7 +13,10 @@ export function evaluateRule(
 ): GateDecision | null {
 	switch (rule.type) {
 		case 'allow_read_only': {
-			return toolDef?.isReadOnly?.(toolInput) ? 'allow' : null
+			// A server's own claim about its own tool cannot settle this. See
+			// `isTrustedReadOnly`: a self-declaration may raise the requirement
+			// and never lower it.
+			return isTrustedReadOnly(toolDef, toolInput) ? 'allow' : null
 		}
 
 		case 'deny_dangerous_patterns': {