Turn services + agent DI: chat-handler becomes the composition root (stage 4)

The chat turn is now composed, not implemented, by chat-handler.ts: - src/server/turn-service.ts: one named, error-contained seam per turn responsibility — buildTeacherContext (W8 read channel), persistTurn (canonical state write), spawnTurnJobs (async protocol kick-off), foldTurnIntoGraph (session→graph consolidation; the extraction-pipeline stage swaps this body behind the same seam). Each takes its deps explicitly; failures log one [chat <id>] line and never touch the response. - chat-handler.ts wires: storage ports (stores), the job runner, the teacher tools (ctx = chatId + injected ChatStore), and the services. It no longer contains any logic beyond request validation. Agent layer now receives dependencies instead of importing them — a new lint zone enforces it (src/agent never imports src/server or src/store; verified to fire both ways): - runner.ts: createJobRunner({ chatStore, jobStore }) factory returning the spawn hook + the three job runners; the model-override test seam stays module-level. Bodies otherwise verbatim. - plan tools: persist through the ctx-injected ChatStore (TeacherToolContext = { chatId, chatStore }). - teacher-agent's dependency-free default registry is now the true client-side set: questionTools + jobTools (jobTools was ctx-parameter- shaped but never used its ctx — now honestly context-free). Production always passes createTeacherTools({ chatId, chatStore }); tests that drive a bare mock model get the client-side set unchanged. Zero behavior change: tsc clean, 190/190 tests, eslint clean, production build clean. Tests inject the same fs ports the chat-handler does.
2026-08-31 22:16:03 +03:00
parent 1167157c23
commit 59e1fee850
12 changed files with 383 additions and 282 deletions
@@ -1,10 +1,9 @@
 import { createAgentUIStreamResponse, type UIMessage } from "ai";
 import { createTeacherAgent, type TeacherAgent } from "../agent/teacher-agent.ts";
+import { createJobRunner } from "../agent/subagents/runner.ts";
 import { createTeacherTools } from "../agent/tools.ts";
-import { spawnPendingJobs } from "../agent/subagents/runner.ts";
-import { emitChat, getGraph } from "../core/graph.ts";
-import { buildGraphContext } from "../core/graph-context.ts";
 import { stores } from "./stores.ts";
+import { buildTeacherContext, foldTurnIntoGraph, persistTurn, spawnTurnJobs } from "./turn-service.ts";

 /**
 * One chat turn: run the teacher agent over the client's message list and
@@ -12,9 +11,14 @@ import { stores } from "./stores.ts";
 * so tests can drive it directly with a scripted mock model — the Next route
 * handler in app/api/chat is a one-line wrapper.
 *
- * The client owns the message list between turns (useChat); the server
- * persists the canonical state (client messages + agent response) onFinish.
+ * This module is the TURN COMPOSITION ROOT: it wires the storage ports, the
+ * job runner, the teacher tools, and the turn services (turn-service.ts)
+ * together — all actual work lives behind those seams. The background job
+ * runner closes over the same port objects the services see.
 */
+
+const jobRunner = createJobRunner(stores);
+
 export async function handleChatRequest(req: Request, agent?: TeacherAgent): Promise<Response> {
 	let body: { chatId?: unknown; messages?: unknown };
 	try {
@@ -30,48 +34,19 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
 		return Response.json({ error: "messages must be an array" }, { status: 400 });
 	}

-	// W8 (vision §1 "the graph as session context"): the learner's knowledge
-	// graph rides along as part of the teacher's instructions. Built per
-	// request — stateless, and self-updating as the graph grows mid-session
-	// (the emission hook below folds each turn). A read failure must never
-	// take the lesson down: the block is context, not a dependency.
-	let graphContext: string | null = null;
-	try {
-		graphContext = buildGraphContext(getGraph(stores.graphStore));
-	} catch (err) {
-		console.error(`[chat ${chatId}] graph context build failed:`, err);
-	}
-
 	return createAgentUIStreamResponse({
-		agent: agent ?? createTeacherAgent(undefined, createTeacherTools({ chatId }), graphContext),
+		agent:
+			agent ??
+			createTeacherAgent(
+				undefined,
+				createTeacherTools({ chatId, chatStore: stores.chatStore }),
+				buildTeacherContext(stores.graphStore, chatId),
+			),
 		uiMessages: body.messages as UIMessage[],
 		onFinish: ({ messages, isAborted }) => {
-			// Persist even when aborted: the partial transcript (including any
-			// pending question part) is what makes resume work.
-			try {
-				stores.chatStore.saveMessages(chatId, messages as UIMessage[]);
-			} catch (err) {
-				console.error(`[chat ${chatId}] persist failed:`, err, { isAborted });
-			}
-			// Async sub-agent protocol (contracts.ts): scan the last assistant
-			// message for pending job tool parts and fire the background runners —
-			// fire-and-forget, never awaited; the HTTP response is already gone.
-			try {
-				spawnPendingJobs(chatId, messages as UIMessage[]);
-			} catch (err) {
-				console.error(`[chat ${chatId}] job spawn failed:`, err);
-			}
-			// W4: fold this chat into the knowledge-graph ledgers (tree nodes /
-			// edges, quiz outcomes, taught events) — synchronous but tiny
-			// (append-only JSONL), and errors never touch the response.
-			// Skipped under tests: scripted chats are fixtures, not knowledge.
-			if (process.env.NODE_ENV !== "test") {
-				try {
-					emitChat(chatId, stores);
-				} catch (err) {
-					console.error(`[chat ${chatId}] graph emission failed:`, err);
-				}
-			}
+			persistTurn(stores.chatStore, chatId, messages as UIMessage[], isAborted);
+			spawnTurnJobs(jobRunner, chatId, messages as UIMessage[]);
+			foldTurnIntoGraph(stores, chatId);
 		},
 	});
 }
@@ -0,0 +1,81 @@
+/**
+ * The chat-turn services — one named, error-contained seam per turn
+ * responsibility, extracted from the chat-handler so it composes instead of
+ * implementing. Each takes its dependencies explicitly (storage ports, the
+ * job runner) — no module here imports an adapter.
+ *
+ *   buildTeacherContext — graph → instructions block (the W8 read channel)
+ *   persistTurn        — the canonical state write (client + agent messages)
+ *   spawnTurnJobs      — the async sub-agent protocol kick-off
+ *   foldTurnIntoGraph  — session → graph consolidation (the write channel;
+ *                        the extraction-pipeline stage swaps this body for
+ *                        the extractor/auditor/merger trigger behind the
+ *                        same seam)
+ *
+ * Logs are the minimal-observability baseline: one line per failure, tagged
+ * [chat <id>] — structured logging lands behind these seams later.
+ */
+
+import type { UIMessage } from "ai";
+import { buildGraphContext } from "../core/graph-context.ts";
+import { emitChat, getGraph, type GraphDeps } from "../core/graph.ts";
+import type { ChatStore, GraphStore } from "../core/ports.ts";
+import type { JobRunner } from "../agent/subagents/runner.ts";
+
+/**
+ * W8 (vision §1 "the graph as session context"): the learner's knowledge
+ * graph rides along as part of the teacher's instructions. Built per request
+ * — stateless, and self-updating as the graph grows mid-session. A read
+ * failure must never take the lesson down: the block is context, not a
+ * dependency.
+ */
+export function buildTeacherContext(graphStore: GraphStore, chatId: string): string | null {
+	try {
+		return buildGraphContext(getGraph(graphStore));
+	} catch (err) {
+		console.error(`[chat ${chatId}] graph context build failed:`, err);
+		return null;
+	}
+}
+
+/**
+ * The canonical state write: the client owns the message list between turns
+ * (useChat); this persists client messages + the agent response. Persists
+ * even when aborted — the partial transcript (including any pending
+ * question part) is what makes resume work.
+ */
+export function persistTurn(chatStore: ChatStore, chatId: string, messages: UIMessage[], isAborted: boolean): void {
+	try {
+		chatStore.saveMessages(chatId, messages);
+	} catch (err) {
+		console.error(`[chat ${chatId}] persist failed:`, err, { isAborted });
+	}
+}
+
+/**
+ * The async sub-agent protocol (contracts.ts): scan the last assistant
+ * message for pending job tool parts and fire the background runners —
+ * fire-and-forget, never awaited; the HTTP response is already gone.
+ */
+export function spawnTurnJobs(jobRunner: JobRunner, chatId: string, messages: UIMessage[]): void {
+	try {
+		jobRunner.spawnPendingJobs(chatId, messages);
+	} catch (err) {
+		console.error(`[chat ${chatId}] job spawn failed:`, err);
+	}
+}
+
+/**
+ * W4: fold this chat into the knowledge-graph ledgers (tree nodes / edges,
+ * quiz outcomes, taught events) — synchronous but tiny (append-only JSONL),
+ * and errors never touch the response. Skipped under tests: scripted chats
+ * are fixtures, not knowledge.
+ */
+export function foldTurnIntoGraph(deps: GraphDeps, chatId: string): void {
+	if (process.env.NODE_ENV === "test") return;
+	try {
+		emitChat(chatId, deps);
+	} catch (err) {
+		console.error(`[chat ${chatId}] graph emission failed:`, err);
+	}
+}