Pi-style ack-and-steer sub-agent protocol: dispatch mid-turn, steer via server wake turn

The job tools (research/demo/visual) switch from client-side turn-breaking calls to pi's model: execute resolves IMMEDIATELY with a fire-and-forget ack, the teacher's turn continues, and the result arrives later as an injected user-role steer message that wakes the teacher in a new server-side turn. - contracts.ts: THE ASYNC PROTOCOL rewritten (ack now, steer later); steer types (SubagentSteerMessage, metadata.subagentResult + data-subagent- artifact part), pure buildSubagentSteer/steerDelivered/isSubagentFailure - tools/jobs.ts: jobTools(ctx) factory — server-side execute creates the job (deduped by toolCallId), fires spawn with the dispatch-time input (the part isn't persisted yet at execute — a transcript scan would race) - runner.ts: runJob(jobId, input?) builds the steer and hands it to the injected deliver seam; pipeline owns the done/error flip (a polling client re-syncs once, at the end); failures still steer - server/jobs.ts (new pipeline): per-chat serialized queues on globalThis, idle gates (turn liveness + pending question, 1.5s grace), 409 retry with backoff, idempotent per jobId, stale-job recovery sweep (re-deliver or re-spawn); wake turns run through the same handleChatRequest composition via setTurnRunner injection - chat-handler.ts: wires runner+deliver+tools ctx; drops spawnTurnJobs from onFinish; teacher default registry = question tools only - plan.ts: PlanToolContext split out (plan tools need no job wiring) - visual-maker: edit_svg added (pi parity — exact-match single replacement, fuzzy context on a miss); researcher: pi's kept/dropped source accounting restored - prompts 20-jobs/40-demos: async discipline rewritten (announce and keep teaching, no waiting/polling/fabricating, parallel dispatch, teach with the artifact when it arrives) - tests: jobs.test.ts rewritten (dispatch ack mid-turn, runner steers, wake pipeline: deferral/409/idempotency/failure), demos.test.tsx runner tests ported to runJob + fake deliver; 222 green FLAGGED surgical touches outside the stream's owned files, for master review at merge: src/core/contracts.ts (protocol doc + steer types), src/core/ui-message.ts (job tool + data-part types), src/server/ chat-handler.ts (wiring), src/server/turn-service.ts (spawnTurnJobs retirement), src/agent/teacher-agent.ts (default tools), src/agent/tools/ plan.ts (context type split). Verified live on PORT=3003 with real models: teacher dispatched research mid-turn, researcher ran real searches/fetches, steer injected on quiz answer, wake turn wove the brief in citing its sources, job flipped done; a client/wake race correctly 409'd.
2026-09-01 19:15:43 +03:00
parent cf3225fb23
commit 99fa3f0847
16 changed files with 1382 additions and 429 deletions
@@ -49,8 +49,11 @@ composition, and above everything CORRECTNESS: the picture must not assert anyth
 mark on the wrong corner, a vector pointing the wrong way, a point plotted at the wrong coordinate is a
 failure even if it renders cleanly.

-Your two tools:
+Your three tools:
 - write_svg({ svg }) — write the complete <svg>…</svg> source (overwrites the previous version).
+- edit_svg({ old_text, new_text }) — a surgical exact-match replacement in the current SVG:
+  old_text must appear EXACTLY ONCE; it is replaced by new_text. Call write_svg first. For anything
+  beyond a one-spot fix (new elements, restructured layout), write_svg the whole document again.
 - render_svg({}) — rasterize the current SVG in headless Chrome. The render arrives as an image in the
  message right after the tool result.

@@ -64,8 +67,8 @@ says nothing about whether the geometry is right or the picture is readable. Whe
 - Would a learner instantly read the intended idea from this picture alone?

 Workflow: plan the coordinate space (viewBox + margins, nothing touching the edges) → write_svg →
-render_svg → LOOK critically → fix (write_svg) and re-render until correct and clean. Never finish
-without having looked at a render of your FINAL SVG.
+render_svg → LOOK critically → fix (edit_svg for one-spot fixes, write_svg otherwise) and re-render
+until correct and clean. Never finish without having looked at a render of your FINAL SVG.

 SVG requirements:
 - A complete <svg> with explicit width/height AND a matching viewBox.
@@ -86,6 +89,14 @@ export function createVisualTools() {
 				svg: z.string().describe('Complete <svg xmlns="…">…</svg> markup.'),
 			}),
 		}),
+		edit_svg: tool({
+			description:
+				"Replace one exact spot in the current SVG: old_text must appear EXACTLY ONCE and is replaced by new_text. Call write_svg first. For larger changes, write_svg the whole document.",
+			inputSchema: z.object({
+				old_text: z.string().describe("The exact text to replace — must match exactly once in the current SVG."),
+				new_text: z.string().describe("The replacement text."),
+				}),
+		}),
 		render_svg: tool({
 			description: "Render the current SVG to a PNG and show it to you for inspection. No arguments.",
 			inputSchema: z.object({}),
@@ -164,6 +175,36 @@ export async function runVisualMaker(input: VisualMakerInput, opts: VisualMakerO
 					currentSvg = svg;
 					opts.onActivity?.(`write_svg: ${(svg.length / 1024).toFixed(1)} KB`);
 					toolResults.push(toolText(call.toolCallId, call.toolName, `Saved (${svg.length} bytes). Call render_svg to look at it.`));
+				} else if (call.toolName === "edit_svg") {
+					const edit = call.input as { old_text?: unknown; new_text?: unknown };
+					if (!currentSvg) {
+						toolResults.push(toolText(call.toolCallId, call.toolName, "ERROR: nothing to edit — call write_svg first."));
+						continue;
+					}
+					if (typeof edit.old_text !== "string" || typeof edit.new_text !== "string" || !edit.old_text) {
+						toolResults.push(toolText(call.toolCallId, call.toolName, "ERROR: expected old_text (non-empty) and new_text strings."));
+						continue;
+					}
+					const occurrences = currentSvg.split(edit.old_text).length - 1;
+					if (occurrences === 0) {
+						toolResults.push(
+							toolText(
+								call.toolCallId,
+								call.toolName,
+								`ERROR: old_text not found. Closest line for reference:\n${snippetAround(currentSvg, edit.old_text)}`,
+							),
+						);
+						continue;
+					}
+					if (occurrences > 1) {
+						toolResults.push(
+							toolText(call.toolCallId, call.toolName, `ERROR: old_text appears ${occurrences} times — it must match EXACTLY ONCE. Include more surrounding context to make it unique.`),
+						);
+						continue;
+					}
+					currentSvg = currentSvg.replace(edit.old_text, edit.new_text);
+					opts.onActivity?.("edit_svg: applied");
+					toolResults.push(toolText(call.toolCallId, call.toolName, "OK — replaced 1 occurrence. Call render_svg to look at the edited SVG."));
 				} else if (call.toolName === "render_svg") {
 					if (!currentSvg) {
 						toolResults.push(toolText(call.toolCallId, call.toolName, "ERROR: nothing to render — call write_svg first."));
@@ -181,7 +222,7 @@ export async function runVisualMaker(input: VisualMakerInput, opts: VisualMakerO
 						toolResults.push(toolText(call.toolCallId, call.toolName, `RENDER ERROR (the SVG may be malformed): ${msg}. Fix it with write_svg and render again.`));
 					}
 				} else {
-					toolResults.push(toolText(call.toolCallId, call.toolName, `ERROR: unknown tool "${call.toolName}". Use write_svg or render_svg.`));
+					toolResults.push(toolText(call.toolCallId, call.toolName, `ERROR: unknown tool "${call.toolName}". Use write_svg, edit_svg, or render_svg.`));
 				}
 			}
 			// Message order: assistant tool-calls → tool results → render image.
@@ -215,6 +256,31 @@ function toolText(toolCallId: string, toolName: string, value: string): ToolResu
 	return { type: "tool-result", toolCallId, toolName, output: { type: "text", value } };
 }

+/** A 3-line numbered context window around the closest fuzzy match for a
+ *  failed edit — enough for the model to see what went wrong and retry
+ *  (the pi svg_tools snippetAround semantics). */
+function snippetAround(svg: string, target: string): string {
+	const words = target.trim().split(/\s+/).filter(Boolean);
+	if (words.length === 0) return "(empty old_text)";
+	const lines = svg.split("\n");
+	let bestAt = -1;
+	let bestScore = -1;
+	for (let i = 0; i < lines.length; i++) {
+		const score = words.filter((w) => lines[i]!.includes(w)).length;
+		if (score > bestScore) {
+			bestScore = score;
+			bestAt = i;
+		}
+	}
+	if (bestAt < 0) return "(no similar line found)";
+	const from = Math.max(0, bestAt - 1);
+	const to = Math.min(lines.length, bestAt + 2);
+	return lines
+		.slice(from, to)
+		.map((line, idx) => `${from + idx + 1} | ${line}`)
+		.join("\n");
+}
+
 function finish(svg: string | null, finalText: string): VisualResult {
 	if (!svg) {
 		return {