@namzu/sdk 26.0.0 → 26.1.0

package/src/tools/coordinator/agent.ts

@@ -7,6 +7,7 @@ import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
 import { failureLabel, taskSucceeded } from './outcome.js'
 
+import { DELEGATION_TIMEOUT_MS } from './index.js'
 import type { TaskLaunchedCallback } from './index.js'
 
 /**
@@ -107,6 +108,17 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
+		// Declaring nothing here does not mean "no deadline"; it means the
+		// executor's 120-second default, which is a bound for a tool call and
+		// absurd for a whole agent run. `create_task` in the sibling module
+		// carries the same reasoning and the same hour, and the measurement
+		// behind that number is in its docblock: three delegated children took
+		// 4m21s, 5m58s and 8m04s, and all three parents gave up at 120s.
+		//
+		// This surface did not get that fix when its twin did, and the file's
+		// own note above records the pair doing exactly this before. The two
+		// tools are twins; a bound applied to one of them is not applied.
+		timeoutMs: DELEGATION_TIMEOUT_MS,
 		...(opts.terminal !== undefined ? { terminal: opts.terminal } : {}),
 		async execute({ description, prompt, subagent_type }, context) {
 			// With a single registered subagent the type is optional — default to

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/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.