Wave 0: shared contracts + extension points

- src/core/contracts.ts: plan tree / graph / ledger / job protocol / artifact
  registry types — the single source of truth for all workstreams
- tools: per-request factory createTeacherTools({chatId}) composing
  questionTools + planTools (stub) + jobTools (stub); quiz gains nodeId
- prompt composition: system-prompt.md + sorted src/agent/prompts/*.md
- ChatRecord.tree + saveTree; pending gate scoped to quiz/ask (+findPendingJobCall)
- chat.tsx: artifact renderer extension point + ChatActionsContext.syncFromServer

src/agent/prompts/README.md

@@ -0,0 +1,13 @@
+# Prompt fragments
+
+The teacher's system prompt is composed at agent creation:
+
+1. `src/agent/system-prompt.md` — the base (owned by the orchestrator; do not edit from a worker).
+2. Every `*.md` file in this directory, in **sorted filename order**, joined with `---` separators.
+
+Rules for adding a fragment:
+
+- Name it with a numeric order prefix: `10-plan-tree.md`, `20-jobs.md`, `30-phases.md`.
+- One fragment per workstream — your brief tells you which filename you own.
+- Document YOUR tools/behaviors exactly; reference tool input field names verbatim (they must match the zod schemas).
+- Keep it tight: fragments are always in context. No restating the base prompt.

src/agent/teacher-agent.ts

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
-import { ToolLoopAgent, stepCountIs, type LanguageModel } from "ai";
+import * as path from "node:path";
+import { ToolLoopAgent, stepCountIs, type LanguageModel, type ToolSet } from "ai";
 import { openrouter } from "@openrouter/ai-sdk-provider";
 import { PATHS } from "../../config.ts";
-import { teacherTools } from "./tools.ts";
+import { createTeacherTools } from "./tools.ts";
 
 /**
  * The teacher agent. Everything pi used to provide (agent loop, tool calling,
@@ -10,13 +11,32 @@ import { teacherTools } from "./tools.ts";
  *
  * The model is injectable so tests can pass a MockLanguageModelV4 and drive
  * deterministic scripted lessons (see tests/chat-flow.test.ts).
+ *
+ * The system prompt is COMPOSED: system-prompt.md is the base, then every
+ * src/agent/prompts/*.md fragment in sorted filename order (workers add
+ * fragments — nobody edits shared sections of the base prompt). Prefix
+ * fragments with a numeric order key: 10-plan-tree.md, 20-jobs.md, …
  */
 
 const DEFAULT_MODEL = process.env.LH_MODEL ?? "anthropic/claude-sonnet-4.5";
 
-const instructions = fs.readFileSync(PATHS.teacherPrompt, "utf-8");
+const PROMPTS_DIR = path.join(PATHS.root, "src", "agent", "prompts");
 
-export function createTeacherAgent(model?: LanguageModel) {
+function composeInstructions(): string {
+	const base = fs.readFileSync(PATHS.teacherPrompt, "utf-8");
+	if (!fs.existsSync(PROMPTS_DIR)) return base;
+	const fragments = fs
+		.readdirSync(PROMPTS_DIR)
+		.filter((f) => f.endsWith(".md"))
+		.sort()
+		.map((f) => fs.readFileSync(path.join(PROMPTS_DIR, f), "utf-8").trim())
+		.filter(Boolean);
+	return [base.trim(), ...fragments].join("\n\n---\n\n");
+}
+
+const instructions = composeInstructions();
+
+export function createTeacherAgent(model?: LanguageModel, tools?: ToolSet) {
 	return new ToolLoopAgent({
 		model:
 			model ??
@@ -26,9 +46,12 @@ export function createTeacherAgent(model?: LanguageModel) {
 				reasoning: { enabled: true, effort: "medium" },
 			}),
 		instructions,
-		tools: teacherTools,
-		// Both tools are client-side (no execute) — a tool call ends the server
-		// turn automatically. stepCountIs is just the safety net.
+		// Tools are per-request (plan tools close over chatId); chat-handler
+		// passes createTeacherTools({ chatId }). Tests pass a mock model and get
+		// the default question-only set.
+		tools: tools ?? createTeacherTools({ chatId: "" }),
+		// Question and job tools are client-side — a call ends the server turn
+		// automatically. stepCountIs is just the safety net.
 		stopWhen: stepCountIs(20),
 	});
 }

src/agent/tools.ts

@@ -1,16 +1,21 @@
-import { tool } from "ai";
+import { tool, type ToolSet } from "ai";
 import { z } from "zod";
+import { jobTools } from "./tools/jobs.ts";
+import { planTools } from "./tools/plan.ts";
 
 /**
- * The teacher's interaction tools — CLIENT-SIDE tools (no `execute`).
+ * The teacher's tools, composed per request by createTeacherTools.
  *
- * The model's tool call is not executed on the server; it streams to the
- * browser as a typed tool part in `input-available` state. The learner
- * answers in the rendered card; the client grades (quiz) via
- * src/core/question-core.ts and sends the verdict back with addToolOutput.
+ * - questionTools (quiz / ask_user_question): CLIENT-SIDE tools (no `execute`).
+ *   The tool call streams to the browser in `input-available` state; the
+ *   learner answers in the dock; the client grades via question-core and
+ *   sends the verdict with addToolOutput.
+ * - planTools (src/agent/tools/plan.ts): SERVER-SIDE, mutate the chat's plan
+ *   tree (needs the chatId closure — hence the per-request factory).
+ * - jobTools (src/agent/tools/jobs.ts): CLIENT-SIDE semantics, server-side
+ *   fulfillment by background sub-agents (see src/core/contracts.ts).
  *
- * Parameter names mirror src/agent/system-prompt.md exactly — the prompt
- * documents these fields to the model. Keep them in sync.
+ * Parameter names mirror the prompt docs exactly — keep them in sync.
  */
 
 const optionSchema = z.object({
@@ -41,6 +46,13 @@ export const quizInputSchema = z.object({
 		.describe("Explanation revealed AFTER the learner answers. Always say why the correct answer is correct."),
 	multiSelect: z.boolean().optional().describe("Set true only when more than one option is correct"),
 	details: z.string().optional().describe("Optional extra context or instructions shown under the question"),
+	nodeId: z
+		.string()
+		.optional()
+		.describe(
+			"Optional plan-tree node id this question assesses. Set whenever the question targets a tree node — " +
+				"the outcome feeds the learner's knowledge graph. Omit for ad-hoc probes.",
+		),
 });
 
 export const askInputSchema = z.object({
@@ -76,10 +88,26 @@ export const askUserQuestionTool = tool({
 	inputSchema: askInputSchema,
 });
 
-export const teacherTools = {
+export const questionTools = {
 	quiz: quizTool,
 	ask_user_question: askUserQuestionTool,
 };
 
+export interface TeacherToolContext {
+	chatId: string;
+}
+
+/**
+ * Per-request tool registry. Plan tools close over chatId for persistence;
+ * question and job tools are context-free.
+ */
+export function createTeacherTools(ctx: TeacherToolContext): ToolSet {
+	return {
+		...questionTools,
+		...planTools(ctx),
+		...jobTools(ctx),
+	};
+}
+
 export type QuizToolInput = z.infer<typeof quizInputSchema>;
 export type AskToolInput = z.infer<typeof askInputSchema>;

src/agent/tools/jobs.ts

@@ -0,0 +1,13 @@
+import type { ToolSet } from "ai";
+import type { TeacherToolContext } from "../tools.ts";
+
+/**
+ * Async sub-agent job tools — W2 workstream (research; W6 adds demo + visual).
+ * CLIENT-SIDE semantics (no execute): the turn ends with the part pending, a
+ * background runner fulfills it, and the client continuation resumes the
+ * teacher. See src/core/contracts.ts "THE ASYNC PROTOCOL" — read it first.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function jobTools(ctx: TeacherToolContext): ToolSet {
+	return {};
+}

src/agent/tools/plan.ts

@@ -0,0 +1,16 @@
+import type { ToolSet } from "ai";
+import type { TeacherToolContext } from "../tools.ts";
+
+/**
+ * Plan-tree tools — W1 workstream (docs/plan.md Wave 1; src/core/contracts.ts
+ * "Plan tree" section). Server-side tools WITH execute that mutate the chat's
+ * stored PlanTree and return the full updated tree (PlanToolResult).
+ *
+ * Tool names to implement: plan_init, plan_add_node, plan_update_node,
+ * plan_remove_node, plan_add_edge, plan_remove_edge, plan_set_current,
+ * plan_mark_done.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export function planTools(ctx: TeacherToolContext): ToolSet {
+	return {};
+}