sorokin.oleg.edu/learnharness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Storage ports: ChatStore/GraphStore/JobStore + adapters + core inversion (stage 3)

Browse Source 
Per-entity semantic ports (src/core/ports.ts), one adapter family
(src/store/*, fs JSON/JSONL), exactly one composition point
(src/server/stores.ts). Dependency direction is now machine-checked:
adapters implement core interfaces; core never imports an adapter.

The inversion:
- core/graph.ts (emitChat/getGraph/graphSnapshot/foldStaleChats) is now
  pure — it takes the storage ports as explicit parameters (GraphDeps).
  No store imports; newGraphNodeId is local; node id format unchanged.
- core/graph-context.ts buildGraphContext() no longer defaults to the
  live ledgers: the chat-handler hands in getGraph(graphStore) per turn.
- store adapters export exactly one object each implementing their port
  (chatStore/graphStore/jobStore); bodies otherwise verbatim.
  NodeMapping + SessionCheckpoint moved store/graph -> core/contracts
  (they ARE contract shapes); CreateJobInit/JobPatch live in ports.
- titleFromPrompt moved store/chats -> core/contracts (pure helper,
  planNodeStatus precedent). Store modules now contain persistence only.
- server/stores.ts is the composition root; server/{chats,graph,jobs}.ts
  and chat-handler wire from it; agent (plan tools, sub-agent runner)
  call the port objects. The shell surface (@/src/server exports) is
  unchanged.

Lint law extended: the whole of src/core is now a purity zone (was a
file glob with a graph/graph-context exemption). Verified it fires on
core->store imports; tsc clean, 190/190 tests, eslint clean, prod build
clean (prerender 6/6). Tests pass deps explicitly — graph.test uses the
same fs-adapter pair stores.ts wires in production; graph-context.test
keeps its in-memory ledgers as a GraphStore implementation.
This commit is contained in:
Amos
2026-08-31 20:00:12 +03:00
parent e92140f993
commit 1167157c23
24 changed files with 434 additions and 282 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+7 -2
View File
@@ -71,7 +71,7 @@ graph TB
VIS["visual-maker<br/>write → render → look"]
end
subgraph STORE["File stores (data/, never in git)"]
subgraph STORE["File stores (src/store adapters → data/, never in git)"]
CHATS[("data/chats/*.json<br/>UIMessages + plan tree")]
JOBS[("data/jobs/*.json")]
LEDG[("data/graph/*.jsonl<br/>nodes/edges/events/mappings/sessions")]
@@ -126,10 +126,15 @@ src/
subagents/ researcher · demo-builder · visual-maker,
runner (async protocol), headless Chrome helper
server/chat-handler.ts one chat turn: stream, persist, spawn, emit
server/stores.ts THE composition root — the one place adapters wire in
core/contracts.ts THE contracts file — types + protocol docs
core/ports.ts storage ports — ChatStore · GraphStore · JobStore
(core code depends on these types only)
core/ question-core, plan-tree, phases, pending,
graph (emission/derivation), graph-context, math delims
store/ chats · graph ledgers · jobs (plain fs, no framework)
— all pure: storage arrives as parameters
store/ fs adapters implementing the ports: chats ·
graph ledgers · jobs (plain fs, no framework)
scripts/bench-graph.ts sigma/forceAtlas2 layout benchmark
data/ chats/ · graph/ · jobs/ — runtime state, git-ignored
```
eslint.config.mjs
+4 -3
View File
@@ -10,7 +10,8 @@ import importPlugin from "eslint-plugin-import";
*
* components/** → "@/src/core" (the pure core barrel) — ONLY
* app/** → "@/src/core" + "@/src/server" (the server barrel) — ONLY
* pure core → never imports src/agent, src/server, src/store
* src/core/** → never imports src/agent, src/server, src/store (pure
* core: adapters implement core/ports.ts, never the reverse)
*
* tests/ and scripts/ are internal — unrestricted.
*/
@@ -49,10 +50,10 @@ export default defineConfig([
"app/ (transport + server components) imports ONLY the barrels: `@/src/core` and `@/src/server` (architecture: docs/architecture.md).",
},
{
target: "./src/core/{index,contracts,question-core,plan-tree,phases,pending,math-delims,ui-message}.ts",
target: "./src/core",
from: ["./src/agent", "./src/server", "./src/store"],
message:
"Pure core modules never import IO layers (agent/server/store). IO-bound core (graph.ts, graph-context.ts) is exempt until the storage-port stage inverts it.",
"Pure core never imports IO layers (agent/server/store): adapters implement core/ports.ts, and the composition root (src/server/stores.ts) passes them in (architecture: docs/architecture.md).",
},
],
},
src/agent/subagents/runner.ts
+30 -30
View File
@@ -1,8 +1,8 @@
import { isToolUIPart, type LanguageModel, type UIMessage } from "ai";
import type { DemoResult, DemoToolInput, JobKind, ResearchResult, ResearchToolInput, VisualResult, VisualToolInput } from "../../core/contracts.ts";
import { JOB_TOOLS } from "../../core/pending.ts";
import { getChat, saveMessages } from "../../store/chats.ts";
import { createJob, findJobByToolCallId, getJob, updateJob } from "../../store/jobs.ts";
import { chatStore } from "../../store/chats.ts";
import { jobStore } from "../../store/jobs.ts";
import { runDemoBuilder } from "./demo-builder.ts";
import { createResearcherAgent } from "./researcher.ts";
import { runVisualMaker } from "./visual-maker.ts";
@@ -60,22 +60,22 @@ export function spawnPendingJobs(chatId: string, messages: UIMessage[]): void {
if (!(JOB_TOOLS as readonly string[]).includes(tool)) continue;
const runner = KIND_RUNNERS[tool as JobKind];
if (!runner) continue;
if (findJobByToolCallId(chatId, part.toolCallId)) continue; // already has a job
const job = createJob({ kind: tool as JobKind, chatId, toolCallId: part.toolCallId });
if (jobStore.findJobByToolCallId(chatId, part.toolCallId)) continue; // already has a job
const job = jobStore.createJob({ kind: tool as JobKind, chatId, toolCallId: part.toolCallId });
void runner(job.id).catch((err) => {
console.error(`[job ${job.id}] ${tool} runner crashed:`, err);
updateJob(job.id, { status: "error", error: String(err), activity: "failed" });
jobStore.updateJob(job.id, { status: "error", error: String(err), activity: "failed" });
});
}
}
export async function runResearchJob(jobId: string, opts: RunResearchJobOptions = {}): Promise<void> {
const job = getJob(jobId);
const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
const chat = getChat(job.chatId);
const chat = chatStore.getChat(job.chatId);
if (!chat) {
updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
return;
}
const input = findToolPart(chat.messages, job.toolCallId)?.input as ResearchToolInput | undefined;
@@ -94,7 +94,7 @@ export async function runResearchJob(jobId: string, opts: RunResearchJobOptions
const agent = createResearcherAgent(opts.model);
try {
updateJob(jobId, { activity: "researching" });
jobStore.updateJob(jobId, { activity: "researching" });
const result = await agent.generate({
prompt,
onToolExecutionStart: ({ toolCall }) => {
@@ -102,7 +102,7 @@ export async function runResearchJob(jobId: string, opts: RunResearchJobOptions
if (toolCall.toolName === "web_fetch" && typeof input?.url === "string") {
fetchedUrls.push(input.url);
}
updateJob(jobId, { activity: activityLine(toolCall.toolName, input) });
jobStore.updateJob(jobId, { activity: activityLine(toolCall.toolName, input) });
},
});
@@ -111,11 +111,11 @@ export async function runResearchJob(jobId: string, opts: RunResearchJobOptions
const research: ResearchResult = { brief, sources: parseSources(brief, fetchedUrls) };
fulfillPart(job.chatId, job.toolCallId, research);
updateJob(jobId, { status: "done", result: research }); // activity line kept: the last tool call is the record
jobStore.updateJob(jobId, { status: "done", result: research }); // activity line kept: the last tool call is the record
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
fulfillPart(job.chatId, job.toolCallId, { brief: `Research failed: ${reason}`, sources: [] });
updateJob(jobId, { status: "error", activity: "failed", error: reason });
jobStore.updateJob(jobId, { status: "error", activity: "failed", error: reason });
}
}
@@ -135,12 +135,12 @@ function isVisualFailure(result: VisualResult): boolean {
}
export async function runDemoJob(jobId: string, opts: RunDemoJobOptions = {}): Promise<void> {
const job = getJob(jobId);
const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
const chat = getChat(job.chatId);
const chat = chatStore.getChat(job.chatId);
if (!chat) {
updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
return;
}
const input = findToolPart(chat.messages, job.toolCallId)?.input as DemoToolInput | undefined;
@@ -148,25 +148,25 @@ export async function runDemoJob(jobId: string, opts: RunDemoJobOptions = {}): P
const brief = typeof input?.brief === "string" ? input.brief : "";
try {
updateJob(jobId, { activity: "building demo" });
jobStore.updateJob(jobId, { activity: "building demo" });
const result = await runDemoBuilder(
{ title, brief },
{
model: opts.model,
onActivity: (line) => updateJob(jobId, { activity: line }),
onActivity: (line) => jobStore.updateJob(jobId, { activity: line }),
},
);
fulfillPart(job.chatId, job.toolCallId, result);
if (isDemoFailure(result)) {
updateJob(jobId, { status: "error", error: result.notes ?? "demo build failed", activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: result.notes ?? "demo build failed", activity: "failed" });
} else {
updateJob(jobId, { status: "done", result });
jobStore.updateJob(jobId, { status: "done", result });
}
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const failure: DemoResult = { title, html: "", tested: true, notes: `FAILED: ${reason}` };
fulfillPart(job.chatId, job.toolCallId, failure);
updateJob(jobId, { status: "error", error: reason, activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: reason, activity: "failed" });
}
}
@@ -175,37 +175,37 @@ export interface RunVisualJobOptions {
}
export async function runVisualJob(jobId: string, opts: RunVisualJobOptions = {}): Promise<void> {
const job = getJob(jobId);
const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
const chat = getChat(job.chatId);
const chat = chatStore.getChat(job.chatId);
if (!chat) {
updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: `Chat not found: ${job.chatId}`, activity: "failed" });
return;
}
const input = findToolPart(chat.messages, job.toolCallId)?.input as VisualToolInput | undefined;
const brief = typeof input?.brief === "string" ? input.brief : "";
try {
updateJob(jobId, { activity: "drawing figure" });
jobStore.updateJob(jobId, { activity: "drawing figure" });
const result = await runVisualMaker(
{ brief },
{
model: opts.model,
onActivity: (line) => updateJob(jobId, { activity: line }),
onActivity: (line) => jobStore.updateJob(jobId, { activity: line }),
},
);
fulfillPart(job.chatId, job.toolCallId, result);
if (isVisualFailure(result)) {
updateJob(jobId, { status: "error", error: result.notes ?? "visual build failed", activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: result.notes ?? "visual build failed", activity: "failed" });
} else {
updateJob(jobId, { status: "done", result });
jobStore.updateJob(jobId, { status: "done", result });
}
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
const failure: VisualResult = { svg: "", notes: `FAILED: ${reason}` };
fulfillPart(job.chatId, job.toolCallId, failure);
updateJob(jobId, { status: "error", error: reason, activity: "failed" });
jobStore.updateJob(jobId, { status: "error", error: reason, activity: "failed" });
}
}
@@ -241,7 +241,7 @@ function hostOf(url: string | undefined): string {
* Synchronous read-modify-write (no awaits) — atomic within the event loop.
*/
function fulfillPart(chatId: string, toolCallId: string, output: ResearchResult | DemoResult | VisualResult): void {
const chat = getChat(chatId);
const chat = chatStore.getChat(chatId);
if (!chat) return;
let found = false;
const messages = chat.messages.map((m) =>
@@ -260,7 +260,7 @@ function fulfillPart(chatId: string, toolCallId: string, output: ResearchResult
);
if (!found) return;
try {
saveMessages(chatId, messages);
chatStore.saveMessages(chatId, messages);
} catch (err) {
console.error(`[chat ${chatId}] fulfilling job part ${toolCallId} failed:`, err);
}
src/agent/tools/plan.ts
+4 -4
View File
@@ -13,7 +13,7 @@ import {
setCurrent,
updateNode,
} from "../../core/plan-tree.ts";
import { getChat, saveTree } from "../../store/chats.ts";
import { chatStore } from "../../store/chats.ts";
import type { TeacherToolContext } from "../tools.ts";
/**
@@ -52,12 +52,12 @@ async function runPlanOp(
chatId: string,
op: (tree: PlanTree) => PlanTree,
): Promise<PlanToolResult> {
const record = getChat(chatId);
const record = chatStore.getChat(chatId);
if (!record) return { ok: false, error: `Chat not found: ${chatId}`, tree: emptyTree() };
const current = record.tree ?? emptyTree();
try {
const next = op(current);
saveTree(chatId, next);
chatStore.saveTree(chatId, next);
return { ok: true, tree: next };
} catch (err) {
if (err instanceof PlanTreeError) return { ok: false, error: err.message, tree: current };
@@ -81,7 +81,7 @@ export function planTools(ctx: TeacherToolContext): ToolSet {
.describe("Initial `requires` edges between the nodes. Edge direction: from = prerequisite, to = dependent."),
}),
execute: async ({ nodes, edges }): Promise<PlanToolResult> => {
const record = getChat(ctx.chatId);
const record = chatStore.getChat(ctx.chatId);
if (!record) return { ok: false, error: `Chat not found: ${ctx.chatId}`, tree: emptyTree() };
const existing = record.tree;
if (existing && existing.nodes.length > 0) {
src/core/contracts.ts
+26 -2
View File
@@ -1,7 +1,7 @@
/**
* Shared contracts — the single source of truth every component codes against.
* Pure types + protocol docs; no runtime code, type-only imports (safe
* everywhere: server, client, tests). See docs/vision.md (§ refs).
* Pure types + protocol docs + tiny pure helpers; type-only imports of "ai"
* (safe everywhere: server, client, tests). See docs/vision.md (§ refs).
*/
import type { UIMessage } from "ai";
@@ -83,6 +83,23 @@ export interface GraphEdge {
provenance: string[];
}
/** mappings.jsonl line — the naive-union identity map: a chat's tree node →
* the graph node it folded into (the merge audit trail; v1 never merges two
* sessions' tree nodes — W8 exact-title match aside). */
export interface NodeMapping {
chatId: string;
treeNodeId: string;
graphNodeId: string;
}
/** sessions.jsonl line — the emission checkpoint for one chat (which chats
* have been folded, and through which updatedAt — never fold twice). */
export interface SessionCheckpoint {
chatId: string;
/** The chat record's `updatedAt` at the time of the fold. */
foldedAt: string;
}
export type LedgerEventKind =
| "probe-correct"
| "probe-miss"
@@ -136,6 +153,13 @@ export interface GraphSnapshot {
nodeSessions: Record<string, string[]>;
}
/** Derive a short chat title from the learner's first message (pure).
* Used on chat creation; deterministic so tests can pin it. */
export function titleFromPrompt(prompt: string): string {
const oneLine = prompt.replace(/\s+/g, " ").trim();
return oneLine.length > 72 ? `${oneLine.slice(0, 72)}…` : oneLine;
}
// ─── Chat records (the session store's on-disk format) ───────────────────────
/** One persisted session: data/chats/<id>.json. The stored messages are full
src/core/graph-context.ts
+6 -6
View File
@@ -22,7 +22,7 @@
*/
import type { GraphEdge, GraphNode } from "./contracts.ts";
import { deriveNodeStates, getGraph, type DerivedGraph } from "./graph.ts";
import { deriveNodeStates, type DerivedGraph } from "./graph.ts";
import type { NodeStateClass } from "./contracts.ts";
/** The section header the teacher is taught to recognize (50-graph-context.md). */
@@ -59,7 +59,7 @@ function isHotspot(node: GraphNode, state: NodeStateClass): boolean {
* Render the context block, or null when there is nothing worth injecting
* (no nodes; or a truncated graph whose selection came out empty).
*
* Pure: callers hand in exactly what getGraph() + deriveNodeStates() produce.
* Pure: callers hand in exactly what getGraph(graphStore) + deriveNodeStates() produce.
*/
export function renderGraphContext(
nodes: GraphNode[],
@@ -162,11 +162,11 @@ function edgeChains(edges: GraphEdge[]): string[][] {
// ─── the per-request entry point ─────────────────────────────────────────────
/**
* Build the graph context block for one request. Stateless — re-reads the
* ledgers every call, so it self-updates as the graph grows mid-session.
* Accepts an injected derived graph (tests); defaults to the live one.
* Build the graph context block for one request. Pure: the caller hands in
* the derived graph (production: getGraph(graphStore) per request in the
* chat-handler, so it self-updates as the graph grows mid-session).
*/
export function buildGraphContext(graph: DerivedGraph = getGraph()): string | null {
export function buildGraphContext(graph: DerivedGraph): string | null {
const states = deriveNodeStates(graph.nodes, graph.events);
return renderGraphContext(graph.nodes, graph.edges, states);
}
src/core/graph.ts
+32 -24
View File
@@ -16,10 +16,12 @@
* Idempotent + incremental: mappings dedupe nodes, (from,to,type) dedupes
* edge assertions, chat-scoped refs dedupe events, and sessions.jsonl
* checkpoints which chats have been folded. Re-emitting a chat appends
* nothing. The store (src/store/graph.ts) holds the append-only ledgers;
* everything here derives from them.
* nothing. Every function takes the storage ports (core/ports.ts) as
* explicit parameters — pure core, no adapter imports; the composition
* root (src/server/stores.ts) wires the fs adapters in.
*/
import { randomBytes } from "node:crypto";
import { isToolUIPart, type UIMessage } from "ai";
import type {
GraphEdge,
@@ -32,13 +34,18 @@ import type {
PlanToolResult,
} from "./contracts.ts";
import type { QuestionAnswerData } from "./question-core.ts";
import { getChat, listChats } from "../store/chats.ts";
import { graphLedgers, newGraphNodeId } from "../store/graph.ts";
import type { ChatStore, GraphStore } from "./ports.ts";
/** The ledger surface emitChat needs (the real one is src/store/graph.ts).
* Injectable so tests can fold fixtures into an in-memory ledger instead of
* the live data/graph files. */
export type GraphLedgers = typeof graphLedgers;
/** The storage ports every graph operation needs, passed explicitly. */
export interface GraphDeps {
chatStore: ChatStore;
graphStore: GraphStore;
}
/** "n_" + 12 hex chars (contracts.ts GraphNode.id — store-assigned). */
function newGraphNodeId(): string {
return `n_${randomBytes(6).toString("hex")}`;
}
// ─── transcript scanning ─────────────────────────────────────────────────────
@@ -109,11 +116,12 @@ export interface EmissionStats {
* turn (chat-handler onFinish) and again on catch-up (GET /api/graph). Sync
* and fast: a handful of small-file reads plus one append per new record.
*
* `ledgers` is injectable for tests (in-memory ledger); production always
* uses the live store.
* The storage ports are explicit (tests pass in-memory ledgers; production
* passes the fs adapters from src/server/stores.ts).
*/
export function emitChat(chatId: string, ledgers: GraphLedgers = graphLedgers): EmissionStats {
const record = getChat(chatId);
export function emitChat(chatId: string, deps: GraphDeps): EmissionStats {
const { graphStore: ledgers } = deps;
const record = deps.chatStore.getChat(chatId);
if (!record) return { nodes: 0, edges: 0, events: 0 };
const stats: EmissionStats = { nodes: 0, edges: 0, events: 0 };
@@ -297,11 +305,11 @@ export interface DerivedGraph {
* edges are merged by (from,to,type) with unioned provenance, first-seen
* order. `store events, derive state` — this is the only reader that matters.
*/
export function getGraph(): DerivedGraph {
const nodes = graphLedgers.readNodes();
export function getGraph(graphStore: GraphStore): DerivedGraph {
const nodes = graphStore.readNodes();
const merged: GraphEdge[] = [];
const byKey = new Map<string, GraphEdge>();
for (const line of graphLedgers.readEdges()) {
for (const line of graphStore.readEdges()) {
const key = `${line.from}\u0000${line.to}\u0000${line.type}`;
const existing = byKey.get(key);
if (existing) {
@@ -314,7 +322,7 @@ export function getGraph(): DerivedGraph {
merged.push(edge);
}
}
return { nodes, edges: merged, events: graphLedgers.readEvents() };
return { nodes, edges: merged, events: graphStore.readEvents() };
}
const QUIZ_EVENT_KINDS: ReadonlySet<string> = new Set([
@@ -366,8 +374,8 @@ export function deriveNodeStates(nodes: GraphNode[], events: LedgerEvent[]): Rec
// ─── the /api/graph payload ──────────────────────────────────────────────────
/** Everything the home graph view needs, in one fetch (shape: contracts). */
export function graphSnapshot(): GraphSnapshot {
const { nodes, edges, events } = getGraph();
export function graphSnapshot(deps: GraphDeps): GraphSnapshot {
const { nodes, edges, events } = getGraph(deps.graphStore);
const nodeStates = deriveNodeStates(nodes, events);
const nodeChats = new Map<string, Set<string>>();
@@ -379,7 +387,7 @@ export function graphSnapshot(): GraphSnapshot {
}
chats.add(chatId);
};
for (const m of graphLedgers.readMappings()) touch(m.graphNodeId, m.chatId);
for (const m of deps.graphStore.readMappings()) touch(m.graphNodeId, m.chatId);
for (const edge of edges) {
for (const chatId of edge.provenance) {
touch(edge.from, chatId);
@@ -397,7 +405,7 @@ export function graphSnapshot(): GraphSnapshot {
}
const sessions: Record<string, string> = {};
for (const id of chatIds) {
const chat = getChat(id);
const chat = deps.chatStore.getChat(id);
if (chat) sessions[id] = chat.title;
}
@@ -417,9 +425,9 @@ export function graphSnapshot(): GraphSnapshot {
* sessions deposit value — vision §1 "frequent updates"). Called at the top
* of GET /api/graph; the chat-handler onFinish hook covers the live path.
*/
export function foldStaleChats(): number {
export function foldStaleChats(deps: GraphDeps): number {
const checkpoints = new Map<string, string>();
for (const checkpoint of graphLedgers.readCheckpoints()) {
for (const checkpoint of deps.graphStore.readCheckpoints()) {
const previous = checkpoints.get(checkpoint.chatId);
if (previous === undefined || checkpoint.foldedAt > previous) {
checkpoints.set(checkpoint.chatId, checkpoint.foldedAt);
@@ -427,11 +435,11 @@ export function foldStaleChats(): number {
}
let folded = 0;
for (const chat of listChats()) {
for (const chat of deps.chatStore.listChats()) {
const foldedAt = checkpoints.get(chat.id);
if (foldedAt !== undefined && chat.updatedAt <= foldedAt) continue;
try {
emitChat(chat.id);
emitChat(chat.id, deps);
folded++;
} catch (err) {
console.error(`[graph] fold failed for chat ${chat.id}:`, err);
src/core/index.ts
+7 -4
View File
@@ -9,13 +9,16 @@
* components/** → "@/src/core" (this barrel, ONLY)
* app/** → "@/src/core" + "@/src/server"
*
* IO-bound modules (core/graph.ts, core/graph-context.ts read the ledgers
* via the store) stay internal to the server side until the storage-port
* stage inverts their dependency; they are deliberately NOT re-exported
* here.
* Server-only core modules (core/graph.ts emission/derivation,
* core/graph-context.ts) are pure but need storage ports passed in by a
* server caller, so they are deliberately NOT re-exported here — the
* server imports them directly. The storage PORT TYPES are types-only and
* browser-safe, hence re-exported.
*/
export * from "./contracts.ts";
export * from "./ports.ts";
export * from "./question-core.ts";
export * from "./plan-tree.ts";
export * from "./phases.ts";
src/core/ports.ts
+95
View File
@@ -0,0 +1,95 @@
/**
* Storage ports (the hexagonal seams — vision §1 "storage stays swappable").
*
* One port per ENTITY, with domain operations — never one generic
* key/value interface. Core and the service layer that orbits it code
* against these types only; concrete adapters live in src/store/ (fs
* JSON/JSONL today, SQLite drop-in later) and are wired exactly once, in
* the composition root (src/server/stores.ts). Dependencies point one way:
* adapters may import core; core NEVER imports an adapter.
*/
import type { UIMessage } from "ai";
import type {
ChatRecord,
ChatSummary,
GraphEdge,
GraphNode,
JobKind,
JobRecord,
LedgerEvent,
NodeMapping,
PlanTree,
SessionCheckpoint,
} from "./contracts.ts";
// ─── ChatStore — the session record's home (data/chats) ─────────────────────
export interface ChatStore {
/** Create a session record (persisted immediately). */
createChat(title: string): ChatRecord;
/** The full record, or null if unknown id / corrupt file. */
getChat(id: string): ChatRecord | null;
/** All sessions, newest activity first (the sidebar's list view). */
listChats(): ChatSummary[];
/** Persist the full message list (client state + new response) after a turn. */
saveMessages(id: string, messages: UIMessage[]): void;
/** Persist the session plan tree (plan tools call this in execute). */
saveTree(id: string, tree: PlanTree): void;
}
// ─── GraphStore — the append-only evidence ledgers (data/graph) ──────────────
// v1 surface = the five JSONL ledgers (nodes / edges / events / mappings /
// sessions). Reads return the raw append-order lines; merging edge assertions
// by (from, to, type) is DERIVED in core/graph.ts — the store never decides.
// The extraction pipeline (next stage) becomes the sole writer; this read
// surface stays.
export interface GraphStore {
/** Append one GraphNode (ids are unique — no merging needed). */
appendNode(node: GraphNode): void;
/** Raw node lines in append order. */
readNodes(): GraphNode[];
/** Append one edge ASSERTION (a second session asserting the same
* (from, to, type) appends another line; readers merge). */
appendEdge(assertion: GraphEdge): void;
readEdges(): GraphEdge[];
/** Append one quiz outcome / taught event. */
appendEvent(event: LedgerEvent): void;
readEvents(): LedgerEvent[];
/** Append one identity-map line (chat's tree node → graph node). */
appendMapping(mapping: NodeMapping): void;
readMappings(): NodeMapping[];
/** Append one emission checkpoint. */
appendCheckpoint(checkpoint: SessionCheckpoint): void;
readCheckpoints(): SessionCheckpoint[];
}
// ─── JobStore — background sub-agent jobs (data/jobs) ─────────────────────────
export interface CreateJobInit {
kind: JobKind;
chatId: string;
toolCallId: string;
/** First activity line (defaults to "starting"). */
activity?: string;
}
/** Mergeable fields — identity (id, kind, chatId, toolCallId, createdAt) is immutable. */
export type JobPatch = Partial<Omit<JobRecord, "id" | "kind" | "chatId" | "toolCallId" | "createdAt">>;
export interface JobStore {
/** Create a running job (keyed by toolCallId for spawn dedup). */
createJob(init: CreateJobInit): JobRecord;
getJob(id: string): JobRecord | null;
/** Merge a patch into the record; null if unknown id. */
updateJob(id: string, patch: JobPatch): JobRecord | null;
/** All jobs for a chat, newest activity first. */
listJobs(chatId: string): JobRecord[];
/** The job fulfilling a given tool part, if any (spawn-hook dedup). */
findJobByToolCallId(chatId: string, toolCallId: string): JobRecord | null;
}
src/server/chat-handler.ts
+6 -6
View File
@@ -2,9 +2,9 @@ import { createAgentUIStreamResponse, type UIMessage } from "ai";
import { createTeacherAgent, type TeacherAgent } from "../agent/teacher-agent.ts";
import { createTeacherTools } from "../agent/tools.ts";
import { spawnPendingJobs } from "../agent/subagents/runner.ts";
import { emitChat } from "../core/graph.ts";
import { emitChat, getGraph } from "../core/graph.ts";
import { buildGraphContext } from "../core/graph-context.ts";
import { getChat, saveMessages } from "../store/chats.ts";
import { stores } from "./stores.ts";
/**
* One chat turn: run the teacher agent over the client's message list and
@@ -23,7 +23,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
return Response.json({ error: "Invalid JSON body" }, { status: 400 });
}
const chatId = typeof body.chatId === "string" ? body.chatId : "";
if (!chatId || !getChat(chatId)) {
if (!chatId || !stores.chatStore.getChat(chatId)) {
return Response.json({ error: "Unknown chat" }, { status: 404 });
}
if (!Array.isArray(body.messages)) {
@@ -37,7 +37,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
// take the lesson down: the block is context, not a dependency.
let graphContext: string | null = null;
try {
graphContext = buildGraphContext();
graphContext = buildGraphContext(getGraph(stores.graphStore));
} catch (err) {
console.error(`[chat ${chatId}] graph context build failed:`, err);
}
@@ -49,7 +49,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
// Persist even when aborted: the partial transcript (including any
// pending question part) is what makes resume work.
try {
saveMessages(chatId, messages as UIMessage[]);
stores.chatStore.saveMessages(chatId, messages as UIMessage[]);
} catch (err) {
console.error(`[chat ${chatId}] persist failed:`, err, { isAborted });
}
@@ -67,7 +67,7 @@ export async function handleChatRequest(req: Request, agent?: TeacherAgent): Pro
// Skipped under tests: scripted chats are fixtures, not knowledge.
if (process.env.NODE_ENV !== "test") {
try {
emitChat(chatId);
emitChat(chatId, stores);
} catch (err) {
console.error(`[chat ${chatId}] graph emission failed:`, err);
}
src/server/chats.ts
+5 -3
View File
@@ -1,9 +1,11 @@
import { createChat, getChat, listChats, titleFromPrompt } from "../store/chats.ts";
import { stores } from "./stores.ts";
import { titleFromPrompt } from "../core/contracts.ts";
/**
* Server-side chat entries for the transport layer (app/api/chats*,
* app/chat/[id]). Today these delegate straight to the fs store; the
* app/chat/[id]). Today these delegate straight to the ChatStore port; the
* services stage carves the real orchestration behind this same surface.
*/
export { createChat, getChat, listChats, titleFromPrompt };
export const { createChat, getChat, listChats } = stores.chatStore;
export { titleFromPrompt };
src/server/graph.ts
+3 -2
View File
@@ -1,5 +1,6 @@
import type { GraphSnapshot } from "../core/contracts.ts";
import { foldStaleChats, graphSnapshot } from "../core/graph.ts";
import { stores } from "./stores.ts";
/**
* Server-side graph entry for the home view (GET /api/graph): fold any chat
@@ -9,6 +10,6 @@ import { foldStaleChats, graphSnapshot } from "../core/graph.ts";
* same read surface.
*/
export function graphView(): GraphSnapshot {
foldStaleChats();
return graphSnapshot();
foldStaleChats(stores);
return graphSnapshot(stores);
}
src/server/index.ts
+1
View File
@@ -8,3 +8,4 @@ export * from "./chat-handler.ts";
export * from "./chats.ts";
export * from "./graph.ts";
export * from "./jobs.ts";
export * from "./stores.ts";
src/server/jobs.ts
+2 -2
View File
@@ -1,4 +1,4 @@
import { listJobs } from "../store/jobs.ts";
import { stores } from "./stores.ts";
/**
* Server-side job-status entry (GET /api/jobs?chatId=…, contracts.ts
@@ -7,4 +7,4 @@ import { listJobs } from "../store/jobs.ts";
* re-syncs the chat when the job flips to done/error.
*/
export { listJobs };
export const { listJobs } = stores.jobStore;
src/server/stores.ts
+19
View File
@@ -0,0 +1,19 @@
/**
* THE COMPOSITION ROOT for storage — the single place concrete store
* adapters are wired. Everything else (core, services, agents) codes against
* the port types in core/ports.ts and receives instances through this
* module. Swapping the fs adapter for SQLite later changes exactly this
* file (and the adapter implementations in src/store/).
*/
import { chatStore } from "../store/chats.ts";
import { graphStore } from "../store/graph.ts";
import { jobStore } from "../store/jobs.ts";
/** The wired adapters. Satisfies core/graph.ts's GraphDeps structurally. */
export const stores = {
chatStore,
graphStore,
jobStore,
};
export type Stores = typeof stores;
src/store/chats.ts
+23 -17
View File
@@ -1,21 +1,25 @@
/**
* ChatStore — the fs JSON adapter (one file per chat in data/chats/).
*
* Implements core/ports.ts ChatStore; the record shapes live in
* core/contracts.ts (ChatRecord/ChatSummary). Idioms: sync fs, tiny
* records, id-guarded filenames, JSON with tab indentation. Wired in the
* composition root (src/server/stores.ts); nothing else constructs it.
*/
import * as fs from "node:fs";
import * as path from "node:path";
import type { UIMessage } from "ai";
import { PATHS } from "../../config.ts";
import type { ChatStore } from "../core/ports.ts";
import type { ChatRecord, ChatSummary, PlanTree } from "../core/contracts.ts";
/**
* Chat store — one JSON file per chat in data/chats/. The record shape lives
* in core/contracts (ChatRecord/ChatSummary); this module is the fs adapter's
* implementation (the storage port formalizes this in a later stage).
*/
import type { UIMessage } from "ai";
function chatFile(id: string): string {
if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`Invalid chat id: ${id}`);
return path.join(PATHS.chats, `${id}.json`);
}
export function createChat(title: string): ChatRecord {
function createChat(title: string): ChatRecord {
const now = new Date().toISOString();
const record: ChatRecord = {
id: `chat_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`,
@@ -29,7 +33,7 @@ export function createChat(title: string): ChatRecord {
return record;
}
export function getChat(id: string): ChatRecord | null {
function getChat(id: string): ChatRecord | null {
try {
return JSON.parse(fs.readFileSync(chatFile(id), "utf-8")) as ChatRecord;
} catch {
@@ -37,7 +41,7 @@ export function getChat(id: string): ChatRecord | null {
}
}
export function listChats(): ChatSummary[] {
function listChats(): ChatSummary[] {
try {
fs.mkdirSync(PATHS.chats, { recursive: true });
return fs
@@ -53,7 +57,7 @@ export function listChats(): ChatSummary[] {
}
/** Persist the full message list (client state + new response) after a turn. */
export function saveMessages(id: string, messages: UIMessage[]): void {
function saveMessages(id: string, messages: UIMessage[]): void {
const record = getChat(id);
if (!record) throw new Error(`Chat not found: ${id}`);
record.messages = messages;
@@ -62,7 +66,7 @@ export function saveMessages(id: string, messages: UIMessage[]): void {
}
/** Persist the session plan tree (plan tools call this in execute). */
export function saveTree(id: string, tree: PlanTree): void {
function saveTree(id: string, tree: PlanTree): void {
const record = getChat(id);
if (!record) throw new Error(`Chat not found: ${id}`);
record.tree = tree;
@@ -71,8 +75,10 @@ export function saveTree(id: string, tree: PlanTree): void {
fs.writeFileSync(chatFile(id), JSON.stringify(record, null, "\t"), "utf-8");
}
/** Derive a short title from the first user message. */
export function titleFromPrompt(prompt: string): string {
const oneLine = prompt.replace(/\s+/g, " ").trim();
return oneLine.length > 72 ? `${oneLine.slice(0, 72)}…` : oneLine;
}
export const chatStore: ChatStore = {
createChat,
getChat,
listChats,
saveMessages,
saveTree,
};
src/store/graph.ts
+21 -35
View File
@@ -1,9 +1,8 @@
/**
* Graph ledger store (W4; vision §1, contracts.ts "v1 emission").
*
* Five append-only JSONL ledgers at config.LEDGER_FILES:
* GraphStore — the fs JSONL adapter: five append-only ledgers at
* config.LEDGER_FILES (contracts.ts "v1 emission").
* nodes.jsonl GraphNode — one line per graph node
* edges.jsonl GraphEdge — one line per edge ASSERTION (a second
* edges.jsonl GraphEdge — one line per edge ASSERTION (a second
* session asserting the same (from,to,type)
* appends another line; reads merge)
* events.jsonl LedgerEvent — quiz outcomes + taught events
@@ -11,38 +10,25 @@
* (chatId, treeNodeId) → graphNodeId
* sessions.jsonl SessionCheckpoint— emission checkpoints (foldedAt)
*
* data/graph/* is exclusively this store's (the legacy V0 scaffold lives in
* data/legacy-graph). Reads are strict against the contracts.ts shapes:
* corrupt lines are skipped, never guessed at — the ledgers are the source of
* truth and everything else is derived (src/core/graph.ts).
*
* Same idioms as src/store/chats.ts: sync fs, tiny records, no framework.
* Implements core/ports.ts GraphStore. data/graph/* is exclusively this
* adapter's. Reads are strict against the contracts.ts shapes: corrupt lines
* are skipped, never guessed at — the ledgers are the source of truth and
* everything else is derived (core/graph.ts, which takes this port as a
* parameter). Same idioms as src/store/chats.ts: sync fs, no framework.
*/
import * as fs from "node:fs";
import * as path from "node:path";
import { randomBytes } from "node:crypto";
import { LEDGER_FILES } from "../../config.ts";
import type { GraphEdge, GraphNode, LedgerEvent, LedgerEventKind } from "../core/contracts.ts";
/** The naive-union identity map line: a chat's tree node → graph node. */
export interface NodeMapping {
chatId: string;
treeNodeId: string;
graphNodeId: string;
}
/** sessions.jsonl line — the emission checkpoint for one chat. */
export interface SessionCheckpoint {
chatId: string;
/** The chat record's `updatedAt` at the time of the fold. */
foldedAt: string;
}
/** "n_" + nanoid-like (contracts.ts GraphNode.id). */
export function newGraphNodeId(): string {
return `n_${randomBytes(6).toString("hex")}`;
}
import type {
GraphEdge,
GraphNode,
LedgerEvent,
LedgerEventKind,
NodeMapping,
SessionCheckpoint,
} from "../core/contracts.ts";
import type { GraphStore } from "../core/ports.ts";
// ─── JSONL primitives ────────────────────────────────────────────────────────
@@ -124,9 +110,9 @@ const isNodeMapping = (v: unknown): v is NodeMapping =>
const isCheckpoint = (v: unknown): v is SessionCheckpoint =>
isRecord(v) && isString(v.chatId) && isString(v.foldedAt);
// ─── typed ledger access ─────────────────────────────────────────────────────
// ─── the port implementation ────────────────────────────────────────────────
export const graphLedgers = {
export const graphStore: GraphStore = {
appendNode(node: GraphNode): void {
appendLine(LEDGER_FILES.nodes, node);
},
@@ -136,8 +122,8 @@ export const graphLedgers = {
},
/** Append one edge ASSERTION; readers merge lines by (from,to,type). */
appendEdge(edge: GraphEdge): void {
appendLine(LEDGER_FILES.edges, edge);
appendEdge(assertion: GraphEdge): void {
appendLine(LEDGER_FILES.edges, assertion);
},
readEdges(): GraphEdge[] {
return readValid(LEDGER_FILES.edges, isGraphEdge);
src/store/jobs.ts
+26 -28
View File
@@ -1,18 +1,19 @@
/**
* JobStore — the fs JSON adapter: one file per background sub-agent job in
* data/jobs/ (contracts.ts "THE ASYNC PROTOCOL"). Keyed by toolCallId for
* dedup: the chat-handler spawn hook never creates two jobs for the same
* tool part. Implements core/ports.ts JobStore. Idioms: sync fs, id-guarded
* filenames, JSON with tab indentation. Writes are small and rare (activity
* line updates); the read-modify-write sections in the runner contain no
* awaits, so they are atomic within the single-threaded event loop.
*/
import * as fs from "node:fs";
import * as path from "node:path";
import { PATHS } from "../../config.ts";
import type { JobKind, JobRecord } from "../core/contracts.ts";
/**
* Job store — one JSON file per background sub-agent job in data/jobs/
* (contracts.ts "THE ASYNC PROTOCOL"). Keyed by toolCallId for dedup: the
* chat-handler spawn hook never creates two jobs for the same tool part.
*
* Follows src/store/chats.ts idioms: sync fs, id-guarded filenames, JSON
* with tab indentation. Writes are small and rare (activity line updates);
* the read-modify-write sections in the runner contain no awaits, so they
* are atomic within the single-threaded event loop.
*/
import type { JobStore } from "../core/ports.ts";
import type { CreateJobInit, JobPatch } from "../core/ports.ts";
import type { JobRecord } from "../core/contracts.ts";
/** Background jobs (data/jobs). Not in config.ts PATHS (orchestrator-owned). */
const JOBS_DIR = path.join(PATHS.data, "jobs");
@@ -22,15 +23,7 @@ function jobFile(id: string): string {
return path.join(JOBS_DIR, `${id}.json`);
}
export interface CreateJobInit {
kind: JobKind;
chatId: string;
toolCallId: string;
/** First activity line (defaults to "starting"). */
activity?: string;
}
export function createJob(init: CreateJobInit): JobRecord {
function createJob(init: CreateJobInit): JobRecord {
const now = new Date().toISOString();
const record: JobRecord = {
id: `job_${Date.now().toString(36)}_${crypto.randomUUID().slice(0, 8)}`,
@@ -47,7 +40,7 @@ export function createJob(init: CreateJobInit): JobRecord {
return record;
}
export function getJob(id: string): JobRecord | null {
function getJob(id: string): JobRecord | null {
try {
return JSON.parse(fs.readFileSync(jobFile(id), "utf-8")) as JobRecord;
} catch {
@@ -56,10 +49,7 @@ export function getJob(id: string): JobRecord | null {
}
/** Merge a partial patch into the record (identity fields are immutable). */
export function updateJob(
id: string,
patch: Partial<Omit<JobRecord, "id" | "kind" | "chatId" | "toolCallId" | "createdAt">>,
): JobRecord | null {
function updateJob(id: string, patch: JobPatch): JobRecord | null {
const record = getJob(id);
if (!record) return null;
const next: JobRecord = { ...record, ...patch, updatedAt: new Date().toISOString() };
@@ -68,7 +58,7 @@ export function updateJob(
}
/** All jobs for a chat, newest activity first. */
export function listJobs(chatId: string): JobRecord[] {
function listJobs(chatId: string): JobRecord[] {
try {
fs.mkdirSync(JOBS_DIR, { recursive: true });
return fs
@@ -83,6 +73,14 @@ export function listJobs(chatId: string): JobRecord[] {
}
/** The job fulfilling a given tool part, if any (spawn-hook dedup). */
export function findJobByToolCallId(chatId: string, toolCallId: string): JobRecord | null {
function findJobByToolCallId(chatId: string, toolCallId: string): JobRecord | null {
return listJobs(chatId).find((j) => j.toolCallId === toolCallId) ?? null;
}
export const jobStore: JobStore = {
createJob,
getJob,
updateJob,
listJobs,
findJobByToolCallId,
};
tests/chat-flow.test.ts
+10 -10
View File
@@ -19,7 +19,7 @@ import { MockLanguageModelV4, simulateReadableStream } from "ai/test";
import type { LanguageModelV4StreamPart } from "@ai-sdk/provider";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
import { createChat, getChat, saveMessages } from "../src/store/chats.ts";
import { chatStore } from "../src/store/chats.ts";
import { buildAnswer, coerceCorrectAnswer, normalizeOptions, resolveCorrect, type QuestionData } from "../src/core/question-core.ts";
import { findPendingToolCall } from "../src/core/pending.ts";
import { PATHS } from "../config.ts";
@@ -113,14 +113,14 @@ describe("teacher chat flow (scripted model)", () => {
it("quiz tool call persists as a pending part; the answer continues the lesson", async () => {
const calls: string[][] = [];
const agent = createTeacherAgent(scriptedModel(calls));
const chat = createChat("Test: solar system");
const chat = chatStore.createChat("Test: solar system");
createdChats.push(chat.id);
// ── Turn 1: learner opens with a topic; teacher probes with a quiz ──
const firstUser = { id: "u1", role: "user", parts: [{ type: "text", text: "teach me the solar system" }] };
await drain(await handleChatRequest(post(chat.id, [firstUser]), agent));
const saved1 = getChat(chat.id)!;
const saved1 = chatStore.getChat(chat.id)!;
assert.equal(saved1.messages.length, 2, "user message + assistant response persisted");
const assistantMsg = saved1.messages[1]!;
assert.equal(assistantMsg.role, "assistant");
@@ -170,7 +170,7 @@ describe("teacher chat flow (scripted model)", () => {
// ── The teacher reacts — as a CONTINUATION of the same assistant message
// (the last client message is the assistant message carrying the tool
// output, so the new text appends to that message's parts). ──
const saved2 = getChat(chat.id)!;
const saved2 = chatStore.getChat(chat.id)!;
assert.equal(saved2.messages.length, 2, "the reaction continues the same assistant message");
const finalParts = saved2.messages[1]!.parts;
const textPart = finalParts.find((p) => p.type === "text");
@@ -200,7 +200,7 @@ describe("teacher chat flow (scripted model)", () => {
// tool-input-start chunk. If a transport change ever stopped emitting
// it, the indicator would silently die — pin the protocol.
const agent = createTeacherAgent(scriptedModel([]));
const chat = createChat("Test: protocol pin");
const chat = chatStore.createChat("Test: protocol pin");
createdChats.push(chat.id);
const firstUser = { id: "u1", role: "user", parts: [{ type: "text", text: "quiz me" }] };
const body = await drain(await handleChatRequest(post(chat.id, [firstUser]), agent));
@@ -214,7 +214,7 @@ describe("teacher chat flow (scripted model)", () => {
it("persists even when the stream is aborted (resume keeps partial state)", async () => {
const calls: string[][] = [];
const agent = createTeacherAgent(scriptedModel(calls));
const chat = createChat("Test: abort");
const chat = chatStore.createChat("Test: abort");
createdChats.push(chat.id);
const req = post(chat.id, [{ id: "u1", role: "user", parts: [{ type: "text", text: "quiz me" }] }]);
@@ -226,17 +226,17 @@ describe("teacher chat flow (scripted model)", () => {
await reader.cancel();
// Give onFinish a tick to fire.
await new Promise((r) => setTimeout(r, 50));
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
assert.ok(saved.messages.length >= 1, "partial transcript persisted");
});
});
describe("chat store", () => {
it("round-trips and lists chats", async () => {
const chat = createChat("Store test");
const chat = chatStore.createChat("Store test");
createdChats.push(chat.id);
saveMessages(chat.id, [{ id: "m1", role: "user", parts: [{ type: "text", text: "hi" }] }]);
const loaded = getChat(chat.id)!;
chatStore.saveMessages(chat.id, [{ id: "m1", role: "user", parts: [{ type: "text", text: "hi" }] }]);
const loaded = chatStore.getChat(chat.id)!;
assert.equal(loaded.messages.length, 1);
assert.equal(loaded.title, "Store test");
});
tests/demos.test.tsx
+18 -18
View File
@@ -43,8 +43,8 @@ import { runDemoBuilder } from "../src/agent/subagents/demo-builder.ts";
import { headlessOverride, type DemoRunResult, type HeadlessApi } from "../src/agent/subagents/headless.ts";
import { demoModelOverride, runDemoJob, runVisualJob, spawnPendingJobs, visualModelOverride } from "../src/agent/subagents/runner.ts";
import { runVisualMaker } from "../src/agent/subagents/visual-maker.ts";
import { createChat, getChat, saveMessages } from "../src/store/chats.ts";
import { createJob, findJobByToolCallId, getJob, listJobs } from "../src/store/jobs.ts";
import { chatStore } from "../src/store/chats.ts";
import { jobStore } from "../src/store/jobs.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { artifactRenderers } from "../components/artifacts/index.ts";
@@ -447,9 +447,9 @@ async function drain(res: Response): Promise<string> {
describe("demo/visual job runners", () => {
it("runDemoJob fulfills the part with a tested DemoResult and marks the job done", async () => {
const chat = createChat("Test: demo runner");
const chat = chatStore.createChat("Test: demo runner");
createdChats.push(chat.id);
saveMessages(chat.id, [
chatStore.saveMessages(chat.id, [
{ id: "u1", role: "user", parts: [{ type: "text", text: "show me compounding" }] },
{
id: "a1",
@@ -458,7 +458,7 @@ describe("demo/visual job runners", () => {
},
] as never);
const job = createJob({ kind: "demo", chatId: chat.id, toolCallId: "call-d1" });
const job = jobStore.createJob({ kind: "demo", chatId: chat.id, toolCallId: "call-d1" });
createdJobs.push(job.id);
// runDemoJob has no headless injection point — the module override is the seam.
@@ -475,14 +475,14 @@ describe("demo/visual job runners", () => {
headlessOverride.current = undefined;
}
const done = getJob(job.id)!;
const done = jobStore.getJob(job.id)!;
assert.equal(done.status, "done");
assert.equal(done.activity, "run_demo: clean", "final activity line recorded");
const result = done.result as { title: string; html: string; tested: boolean };
assert.equal(result.title, "Compound interest");
assert.equal(result.tested, true);
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-demo");
assert.ok(part && part.type === "tool-demo", "demo tool part persisted");
assert.equal(part.state, "output-available", "part fulfilled");
@@ -490,9 +490,9 @@ describe("demo/visual job runners", () => {
});
it("runVisualJob fulfills the part even on failure and marks the job error", async () => {
const chat = createChat("Test: visual runner failure");
const chat = chatStore.createChat("Test: visual runner failure");
createdChats.push(chat.id);
saveMessages(chat.id, [
chatStore.saveMessages(chat.id, [
{ id: "u1", role: "user", parts: [{ type: "text", text: "draw it" }] },
{
id: "a1",
@@ -501,16 +501,16 @@ describe("demo/visual job runners", () => {
},
] as never);
const job = createJob({ kind: "visual", chatId: chat.id, toolCallId: "call-v1" });
const job = jobStore.createJob({ kind: "visual", chatId: chat.id, toolCallId: "call-v1" });
createdJobs.push(job.id);
await runVisualJob(job.id, { model: scriptedModel([{ text: "cannot" }]) });
const errored = getJob(job.id)!;
const errored = jobStore.getJob(job.id)!;
assert.equal(errored.status, "error");
assert.match(errored.error ?? "", /never wrote an SVG/);
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-visual");
assert.ok(part && part.type === "tool-visual", "visual tool part persisted");
assert.equal(part.state, "output-available", "failure still fulfills the part");
@@ -520,7 +520,7 @@ describe("demo/visual job runners", () => {
});
it("the spawn hook dispatches a demo part to the demo runner (kind→runner map)", async () => {
const chat = createChat("Test: demo spawn dispatch");
const chat = chatStore.createChat("Test: demo spawn dispatch");
createdChats.push(chat.id);
// A teacher that calls demo on turn 1 (scripted stream, like jobs.test.ts).
@@ -571,25 +571,25 @@ describe("demo/visual job runners", () => {
),
);
const job = findJobByToolCallId(chat.id, "call-d2");
const job = jobStore.findJobByToolCallId(chat.id, "call-d2");
assert.ok(job, "spawn hook created a job for the demo part");
assert.equal(job!.kind, "demo");
createdJobs.push(job!.id);
// The background runner (fire-and-forget) completes with the overrides.
await waitFor(() => getJob(job!.id)!.status !== "running", 5000, "demo job completion");
const done = getJob(job!.id)!;
await waitFor(() => jobStore.getJob(job!.id)!.status !== "running", 5000, "demo job completion");
const done = jobStore.getJob(job!.id)!;
assert.equal(done.status, "done");
assert.equal(done.activity, "run_demo: clean");
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-demo");
assert.ok(part && part.type === "tool-demo", "demo tool part persisted");
assert.equal(part.state, "output-available", "demo part fulfilled by the background runner");
// Idempotency: re-running the spawn hook creates no second job.
spawnPendingJobs(chat.id, saved.messages);
assert.equal(listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
assert.equal(jobStore.listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
} finally {
demoModelOverride.current = undefined;
headlessOverride.current = undefined;
tests/graph-context.test.ts
+25 -23
View File
@@ -23,7 +23,8 @@ import { MockLanguageModelV4, simulateReadableStream } from "ai/test";
import type { LanguageModelV4StreamPart } from "@ai-sdk/provider";
import type { GraphEdge, GraphNode, LedgerEvent } from "../src/core/contracts.ts";
import type { NodeStateClass } from "../src/core/contracts.ts";
import { emitChat, type GraphLedgers } from "../src/core/graph.ts";
import { emitChat, getGraph } from "../src/core/graph.ts";
import type { GraphStore } from "../src/core/ports.ts";
import {
buildGraphContext,
GRAPH_CONTEXT_HEADER,
@@ -32,8 +33,9 @@ import {
} from "../src/core/graph-context.ts";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
import { createChat, getChat, saveMessages, saveTree } from "../src/store/chats.ts";
import { type NodeMapping, type SessionCheckpoint } from "../src/store/graph.ts";
import { chatStore } from "../src/store/chats.ts";
import type { NodeMapping, SessionCheckpoint } from "../src/core/contracts.ts";
import { graphStore } from "../src/store/graph.ts";
import { createTree } from "../src/core/plan-tree.ts";
import { PATHS } from "../config.ts";
@@ -176,9 +178,9 @@ describe("buildGraphContext", () => {
it("reads the live ledgers without throwing (read-only integration)", () => {
// Other suites (graph.test.ts) mutate data/graph concurrently, so only
// assert the shape of the result, never its content. Read-only is
// structural: buildGraphContext only ever calls getGraph().
const out = buildGraphContext();
// assert the shape of the result, never its content. Structural note:
// the caller now hands in getGraph(graphStore) — the entry point is pure.
const out = buildGraphContext(getGraph(graphStore));
assert.ok(out === null || out.includes(GRAPH_CONTEXT_HEADER));
});
});
@@ -248,10 +250,10 @@ describe("graph-context injection (chat-flow style)", () => {
assert.ok(context, "fixture graph renders a block");
// Exactly what chat-handler does per request when no agent is passed:
// createTeacherAgent(model, tools, buildGraphContext()).
// createTeacherAgent(model, tools, buildGraphContext(getGraph(graphStore))).
const prompts: string[] = [];
const agent = createTeacherAgent(capturingModel(prompts), undefined, context);
const chat = createChat("Test: graph context injection");
const chat = chatStore.createChat("Test: graph context injection");
createdChats.push(chat.id);
await drain(
@@ -279,7 +281,7 @@ describe("graph-context injection (chat-flow style)", () => {
it("no block is injected when the context is null (new learner)", async () => {
const prompts: string[] = [];
const agent = createTeacherAgent(capturingModel(prompts));
const chat = createChat("Test: no graph context");
const chat = chatStore.createChat("Test: no graph context");
createdChats.push(chat.id);
await drain(
await handleChatRequest(
@@ -295,7 +297,7 @@ describe("graph-context injection (chat-flow style)", () => {
// ─── exact-match merge (emitChat dedup) ─────────────────────────────────────
/** An in-memory stand-in for the five ledgers (see GraphLedgers in graph.ts). */
/** An in-memory stand-in for the five ledgers (the GraphStore port, core/ports.ts). */
function memoryLedgers() {
const nodes: GraphNode[] = [];
const edges: GraphEdge[] = [];
@@ -313,31 +315,31 @@ function memoryLedgers() {
readMappings: () => mappings.map((m) => ({ ...m })),
appendCheckpoint: (c: SessionCheckpoint) => void checkpoints.push(c),
readCheckpoints: () => checkpoints.map((c) => ({ ...c })),
// Test accessors (not part of the GraphLedgers surface).
// Test accessors (not part of the GraphStore surface).
counts: { get nodes() { return nodes.length; }, get mappings() { return mappings.length; } },
} satisfies GraphLedgers & { counts: { nodes: number; mappings: number } };
} satisfies GraphStore & { counts: { nodes: number; mappings: number } };
}
/** A real chat record with a stored tree (emitChat reads the real chat store). */
function fixtureChat(title: string, tree: ReturnType<typeof createTree>) {
const chat = createChat(title);
const chat = chatStore.createChat(title);
createdChats.push(chat.id);
saveTree(chat.id, tree);
saveMessages(chat.id, [{ id: "u1", role: "user", parts: [{ type: "text", text: "go" }] }]);
return getChat(chat.id)!;
chatStore.saveTree(chat.id, tree);
chatStore.saveMessages(chat.id, [{ id: "u1", role: "user", parts: [{ type: "text", text: "go" }] }]);
return chatStore.getChat(chat.id)!;
}
describe("exact-match merge (emitChat)", () => {
it("maps a case/whitespace-identical title onto the existing node instead of duplicating", () => {
const ledgers = memoryLedgers();
const chat1 = fixtureChat("Merge A", createTree([{ id: "cr", title: "Chain rule intuition" }], []));
let stats = emitChat(chat1.id, ledgers);
let stats = emitChat(chat1.id, { chatStore, graphStore: ledgers });
assert.deepEqual(stats, { nodes: 1, edges: 0, events: 0 });
const firstId = ledgers.readNodes()[0]!.id;
// Second session, same proposition: different casing + padding.
const chat2 = fixtureChat("Merge B", createTree([{ id: "cr2", title: " chain Rule INTUITION " }], []));
stats = emitChat(chat2.id, ledgers);
stats = emitChat(chat2.id, { chatStore, graphStore: ledgers });
assert.deepEqual(stats, { nodes: 0, edges: 0, events: 0 }, "no duplicate node appended");
assert.equal(ledgers.counts.nodes, 1, "still exactly one graph node");
@@ -357,7 +359,7 @@ describe("exact-match merge (emitChat)", () => {
createdAt: "2026-08-22T00:00:00.000Z",
});
const chat = fixtureChat("Merge alias", createTree([{ id: "d", title: "The Derivative" }], []));
const stats = emitChat(chat.id, ledgers);
const stats = emitChat(chat.id, { chatStore, graphStore: ledgers });
assert.deepEqual(stats, { nodes: 0, edges: 0, events: 0 }, "alias match → no new node");
assert.deepEqual(ledgers.readMappings(), [{ chatId: chat.id, treeNodeId: "d", graphNodeId: "n_alias" }]);
});
@@ -365,12 +367,12 @@ describe("exact-match merge (emitChat)", () => {
it("does NOT fuzzy-match near-identical titles (that stays deferred)", () => {
const ledgers = memoryLedgers();
const chat1 = fixtureChat("Fuzzy A", createTree([{ id: "cr", title: "Chain rule intuition" }], []));
emitChat(chat1.id, ledgers);
emitChat(chat1.id, { chatStore, graphStore: ledgers });
const chat2 = fixtureChat(
"Fuzzy B",
createTree([{ id: "cr2", title: "Chain rules intuition" }], []),
);
const stats = emitChat(chat2.id, ledgers);
const stats = emitChat(chat2.id, { chatStore, graphStore: ledgers });
assert.equal(stats.nodes, 1, "near-miss titles stay separate nodes");
assert.equal(ledgers.counts.nodes, 2);
});
@@ -387,7 +389,7 @@ describe("exact-match merge (emitChat)", () => {
[{ from: "base", to: "chain" }],
),
);
emitChat(chat1.id, ledgers);
emitChat(chat1.id, { chatStore, graphStore: ledgers });
// Second session re-teaches the same two propositions (exact titles)
// and asserts the same edge — it must dedupe onto the existing nodes.
@@ -401,7 +403,7 @@ describe("exact-match merge (emitChat)", () => {
[{ from: "base", to: "chain" }],
),
);
const stats = emitChat(chat2.id, ledgers);
const stats = emitChat(chat2.id, { chatStore, graphStore: ledgers });
// A new ASSERTION line is appended (provenance is honest) — reads merge
// by (from,to,type), so the derived graph still has one edge with both
// sessions in its provenance.
tests/graph.test.ts
+29 -26
View File
@@ -15,11 +15,14 @@ import type { UIMessage } from "ai";
import type { PlanTree, PlanToolResult } from "../src/core/contracts.ts";
import type { QuestionAnswerData } from "../src/core/question-core.ts";
import { createTree, markDone, removeNode } from "../src/core/plan-tree.ts";
import { emitChat, foldStaleChats, getGraph, graphSnapshot } from "../src/core/graph.ts";
import { graphLedgers } from "../src/store/graph.ts";
import { createChat, getChat, saveMessages, saveTree } from "../src/store/chats.ts";
import { emitChat, foldStaleChats, getGraph, graphSnapshot, type GraphDeps } from "../src/core/graph.ts";
import { graphStore } from "../src/store/graph.ts";
import { chatStore } from "../src/store/chats.ts";
import { LEDGER_FILES, PATHS } from "../config.ts";
/** The wired fs adapters, exactly what src/server/stores.ts passes in production. */
const graphDeps = { chatStore, graphStore } as const satisfies GraphDeps;
// ─── ledger isolation (backup-and-clear of data/graph/*.jsonl) ──────────────
const LEDGER_PATHS = Object.values(LEDGER_FILES);
@@ -95,11 +98,11 @@ function answer(over: Partial<QuestionAnswerData>): QuestionAnswerData {
/** Create a chat in the real store with a tree and messages; returns the record. */
function fixtureChat(title: string, tree: PlanTree | null, messages: UIMessage[]) {
const chat = createChat(title);
const chat = chatStore.createChat(title);
createdChats.push(chat.id);
if (tree) saveTree(chat.id, tree);
saveMessages(chat.id, messages);
return getChat(chat.id)!;
if (tree) chatStore.saveTree(chat.id, tree);
chatStore.saveMessages(chat.id, messages);
return chatStore.getChat(chat.id)!;
}
/** The fixture tree: alpha → beta, gamma free-floating, alpha done. */
@@ -188,9 +191,9 @@ let chat2Id = "";
/** Everything the graph holds for a set of chats (other processes' test
* emissions run concurrently against the same files — scope, never assume). */
function scopedGraph(chatIds: string[]) {
const graph = getGraph();
const graph = getGraph(graphStore);
const nodeIds = new Set(
graphLedgers
graphStore
.readMappings()
.filter((m) => chatIds.includes(m.chatId))
.map((m) => m.graphNodeId),
@@ -204,7 +207,7 @@ function scopedGraph(chatIds: string[]) {
describe("graph emission (emitChat)", () => {
it("folds tree nodes/edges and quiz/mark_done events with the probe/check boundary", () => {
const stats = emitChat(chat1.id);
const stats = emitChat(chat1.id, graphDeps);
assert.deepEqual(stats, { nodes: 3, edges: 1, events: 6 });
const graph = scopedGraph([chat1.id]);
@@ -262,14 +265,14 @@ describe("graph emission (emitChat)", () => {
});
it("is idempotent — re-emission appends nothing", () => {
const stats = emitChat(chat1.id);
const stats = emitChat(chat1.id, graphDeps);
assert.deepEqual(stats, { nodes: 0, edges: 0, events: 0 });
const graph = scopedGraph([chat1.id]);
assert.equal(graph.nodes.length, 3);
assert.equal(graph.edges.length, 1);
assert.equal(graph.events.length, 6);
// exactly one checkpoint line per fold, though — checkpoints are a log
assert.equal(graphLedgers.readCheckpoints().filter((c) => c.chatId === chat1.id).length, 2);
assert.equal(graphStore.readCheckpoints().filter((c) => c.chatId === chat1.id).length, 2);
});
it("accumulates edge provenance when another chat maps onto the same nodes", () => {
@@ -288,13 +291,13 @@ describe("graph emission (emitChat)", () => {
assistant("a1", [planPart("p1", "plan_init", { nodes: [], edges: [] }, tree2)]),
]);
const before = getGraph();
const before = getGraph(graphStore);
const gAlpha = before.nodes.find((n) => n.statement === "Alpha intuition")!.id;
const gBeta = before.nodes.find((n) => n.statement === "Beta rule")!.id;
graphLedgers.appendMapping({ chatId: chat2.id, treeNodeId: "alpha", graphNodeId: gAlpha });
graphLedgers.appendMapping({ chatId: chat2.id, treeNodeId: "beta", graphNodeId: gBeta });
graphStore.appendMapping({ chatId: chat2.id, treeNodeId: "alpha", graphNodeId: gAlpha });
graphStore.appendMapping({ chatId: chat2.id, treeNodeId: "beta", graphNodeId: gBeta });
const stats = emitChat(chat2.id);
const stats = emitChat(chat2.id, graphDeps);
assert.deepEqual(stats, { nodes: 0, edges: 1, events: 0 });
chat2Id = chat2.id;
@@ -305,7 +308,7 @@ describe("graph emission (emitChat)", () => {
});
it("derives node states, sessions, and node provenance in graphSnapshot", () => {
const snap = graphSnapshot();
const snap = graphSnapshot(graphDeps);
const idByStatement = new Map(snap.nodes.map((n) => [n.statement, n.id]));
assert.equal(snap.nodeStates[idByStatement.get("Alpha intuition")!], "taught");
assert.equal(snap.nodeStates[idByStatement.get("Beta rule")!], "missed");
@@ -336,7 +339,7 @@ describe("graph emission (emitChat)", () => {
assistant("a2", [planPart("p2", "plan_remove_node", { id: "y" }, prunedTree)]),
]);
const stats = emitChat(chat.id);
const stats = emitChat(chat.id, graphDeps);
assert.deepEqual(stats, { nodes: 1, edges: 0, events: 0 }); // y pruned, edge cascaded away
const graph = scopedGraph([chat.id]);
@@ -345,7 +348,7 @@ describe("graph emission (emitChat)", () => {
});
it("returns zeros for unknown chats", () => {
assert.deepEqual(emitChat("chat_does_not_exist"), { nodes: 0, edges: 0, events: 0 });
assert.deepEqual(emitChat("chat_does_not_exist", graphDeps), { nodes: 0, edges: 0, events: 0 });
});
});
@@ -366,11 +369,11 @@ describe("catch-up (foldStaleChats)", () => {
]),
]);
const folded = foldStaleChats();
const folded = foldStaleChats(graphDeps);
assert.ok(folded >= 1, "the catch-up fixture was folded");
assert.equal(graphLedgers.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
assert.equal(graphStore.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
const snap = graphSnapshot();
const snap = graphSnapshot(graphDeps);
const solo = snap.nodes.find((n) => n.statement === "Solo node");
assert.ok(solo, "solo node was emitted by the catch-up fold");
assert.equal(snap.nodeStates[solo.id], "known"); // correct check, no taught event
@@ -378,8 +381,8 @@ describe("catch-up (foldStaleChats)", () => {
// Already checkpointed → not folded again (other test files' chats may
// legitimately fold here, so assert on THIS chat only).
foldStaleChats();
assert.equal(graphLedgers.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
foldStaleChats(graphDeps);
assert.equal(graphStore.readCheckpoints().filter((c) => c.chatId === chat.id).length, 1);
});
});
@@ -388,14 +391,14 @@ describe("catch-up (foldStaleChats)", () => {
describe("graph ledger store", () => {
it("round-trips lines and skips corrupt / foreign-shaped lines (strict reads)", () => {
const node = { id: "n_storetest", statement: "Store test", aliases: [], kind: "truth" as const, createdAt: "2026-08-22T00:00:00.000Z" };
graphLedgers.appendNode(node);
graphStore.appendNode(node);
// A torn append and a legacy V0-shaped node (different schema) — both skipped.
fs.appendFileSync(
LEDGER_FILES.nodes,
`{not json}\n${JSON.stringify({ id: "legacy", statement: "Legacy shape", domain: "x", state: "known" })}\n`,
"utf-8",
);
const nodes = graphLedgers.readNodes().filter((n) => n.id === "n_storetest" || n.id === "legacy");
const nodes = graphStore.readNodes().filter((n) => n.id === "n_storetest" || n.id === "legacy");
assert.equal(nodes.length, 1);
assert.equal(nodes[0]!.statement, "Store test");
});
tests/jobs.test.ts
+24 -26
View File
@@ -24,8 +24,8 @@ import { MockLanguageModelV4, simulateReadableStream } from "ai/test";
import type { LanguageModelV4StreamPart } from "@ai-sdk/provider";
import { createTeacherAgent } from "../src/agent/teacher-agent.ts";
import { handleChatRequest } from "../src/server/chat-handler.ts";
import { createChat, getChat } from "../src/store/chats.ts";
import { createJob, findJobByToolCallId, getJob, listJobs, updateJob } from "../src/store/jobs.ts";
import { chatStore } from "../src/store/chats.ts";
import { jobStore } from "../src/store/jobs.ts";
import { researchModelOverride, runResearchJob, spawnPendingJobs } from "../src/agent/subagents/runner.ts";
import { createResearcherAgent } from "../src/agent/subagents/researcher.ts";
import { PATHS } from "../config.ts";
@@ -86,32 +86,32 @@ function post(chatId: string, messages: unknown[]): Request {
describe("job store", () => {
it("create → get → update → list round-trips", () => {
const job = createJob({ kind: "research", chatId: "chat_storetest", toolCallId: "call-store" });
const job = jobStore.createJob({ kind: "research", chatId: "chat_storetest", toolCallId: "call-store" });
trackJob(job.id);
assert.match(job.id, /^job_/);
assert.equal(job.status, "running");
assert.equal(job.activity, "starting");
const loaded = getJob(job.id)!;
const loaded = jobStore.getJob(job.id)!;
assert.equal(loaded.toolCallId, "call-store");
assert.equal(loaded.kind, "research");
const updated = updateJob(job.id, { activity: 'web_search: "test"', status: "done", result: { brief: "b" } })!;
const updated = jobStore.updateJob(job.id, { activity: 'web_search: "test"', status: "done", result: { brief: "b" } })!;
assert.equal(updated.activity, 'web_search: "test"');
assert.equal(updated.status, "done");
assert.ok(updated.updatedAt >= job.updatedAt);
// immutable identity fields survive a patch
assert.equal(updated.toolCallId, "call-store");
assert.equal(getJob(updated.id)!.toolCallId, "call-store");
assert.equal(jobStore.getJob(updated.id)!.toolCallId, "call-store");
const listed = listJobs("chat_storetest");
const listed = jobStore.listJobs("chat_storetest");
assert.ok(listed.some((j) => j.id === job.id));
assert.equal(listJobs("chat_other").some((j) => j.id === job.id), false, "jobs are scoped to their chat");
assert.equal(jobStore.listJobs("chat_other").some((j) => j.id === job.id), false, "jobs are scoped to their chat");
const byTool = findJobByToolCallId("chat_storetest", "call-store");
const byTool = jobStore.findJobByToolCallId("chat_storetest", "call-store");
assert.equal(byTool?.id, job.id);
assert.equal(findJobByToolCallId("chat_storetest", "call-missing"), null);
assert.equal(jobStore.findJobByToolCallId("chat_storetest", "call-missing"), null);
});
});
@@ -155,7 +155,7 @@ function researchCallingTeacher(): MockLanguageModelV4 {
describe("spawn hook (async protocol §2)", () => {
it("a pending research part in the final assistant message spawns exactly one job", async () => {
const chat = createChat("Test: research spawn");
const chat = chatStore.createChat("Test: research spawn");
trackChat(chat.id);
const agent = createTeacherAgent(researchCallingTeacher());
@@ -163,13 +163,13 @@ describe("spawn hook (async protocol §2)", () => {
await drain(await handleChatRequest(post(chat.id, [firstUser]), agent));
// The research part is pending (input-available) in the stored chat.
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-research");
assert.ok(part && part.type === "tool-research", "research tool part persisted");
assert.equal(part.state, "input-available", "job tool part stays pending until the runner fulfills it");
// A job record exists for it.
const job = findJobByToolCallId(chat.id, "call-r1");
const job = jobStore.findJobByToolCallId(chat.id, "call-r1");
assert.ok(job, "spawn hook created a job record");
assert.equal(job!.kind, "research");
assert.equal(job!.status, "running");
@@ -177,7 +177,7 @@ describe("spawn hook (async protocol §2)", () => {
// Re-running the spawn hook (idempotency) does not create a second job.
spawnPendingJobs(chat.id, saved.messages);
assert.equal(listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
assert.equal(jobStore.listJobs(chat.id).length, 1, "no duplicate job for the same tool part");
});
});
@@ -249,7 +249,7 @@ describe("research runner (async protocol §3)", () => {
it("fulfills the part with a ResearchResult and marks the job done with activity recorded", async () => {
const restoreFetch = stubFetch();
try {
const chat = createChat("Test: runner completion");
const chat = chatStore.createChat("Test: runner completion");
trackChat(chat.id);
// A pending research part, as the spawn hook would find it.
@@ -265,23 +265,22 @@ describe("research runner (async protocol §3)", () => {
},
] as never;
// saveMessages requires the chat to exist; use the store directly.
const { saveMessages } = await import("../src/store/chats.ts");
saveMessages(chat.id, messages);
chatStore.saveMessages(chat.id, messages);
const job = createJob({ kind: "research", chatId: chat.id, toolCallId: "call-run1" });
const job = jobStore.createJob({ kind: "research", chatId: chat.id, toolCallId: "call-run1" });
trackJob(job.id);
await runResearchJob(job.id, { model: researcherModel() });
// The job is done, with the activity line from the tool call.
const done = getJob(job.id)!;
const done = jobStore.getJob(job.id)!;
assert.equal(done.status, "done");
assert.equal(done.activity, 'web_search: "sigma.js latest version"', "activity line recorded");
assert.ok(done.result, "result stored on the job");
// The stored chat's part flipped to output-available with a
// ResearchResult-shaped output.
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-research");
assert.ok(part && part.type === "tool-research");
assert.equal(part.state, "output-available");
@@ -300,10 +299,9 @@ describe("research runner (async protocol §3)", () => {
throw new Error("model exploded");
},
});
const chat = createChat("Test: runner failure");
const chat = chatStore.createChat("Test: runner failure");
trackChat(chat.id);
const { saveMessages } = await import("../src/store/chats.ts");
saveMessages(chat.id, [
chatStore.saveMessages(chat.id, [
{ id: "u1", role: "user", parts: [{ type: "text", text: "hi" }] },
{
id: "a1",
@@ -312,16 +310,16 @@ describe("research runner (async protocol §3)", () => {
},
] as never);
const job = createJob({ kind: "research", chatId: chat.id, toolCallId: "call-err1" });
const job = jobStore.createJob({ kind: "research", chatId: chat.id, toolCallId: "call-err1" });
trackJob(job.id);
await runResearchJob(job.id, { model: failing });
const errored = getJob(job.id)!;
const errored = jobStore.getJob(job.id)!;
assert.equal(errored.status, "error");
assert.match(errored.error ?? "", /model exploded/);
const saved = getChat(chat.id)!;
const saved = chatStore.getChat(chat.id)!;
const part = saved.messages[1]!.parts.find((p) => p.type === "tool-research");
assert.ok(part && part.type === "tool-research");
assert.equal(part.state, "output-available", "failure still fulfills the part");
tests/plan-tree.test.ts
+11 -11
View File
@@ -26,7 +26,7 @@ import {
updateNode,
} from "../src/core/plan-tree.ts";
import { planTools } from "../src/agent/tools/plan.ts";
import { createChat, getChat } from "../src/store/chats.ts";
import { chatStore } from "../src/store/chats.ts";
import { PATHS } from "../config.ts";
const N = (id: string, title = id, summary?: string) => ({ id, title, ...(summary ? { summary } : {}) });
@@ -228,7 +228,7 @@ async function exec(tools: ReturnType<typeof planTools>, name: string, input: un
}
function newChat(title: string): string {
const chat = createChat(title);
const chat = chatStore.createChat(title);
createdChats.push(chat.id);
return chat.id;
}
@@ -251,7 +251,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(res.tree.nodes.length, 2);
assert.deepEqual(res.tree.edges, [{ from: "truth", to: "goal" }]);
const saved = getChat(chatId)!.tree;
const saved = chatStore.getChat(chatId)!.tree;
assert.ok(saved, "tree persisted to the chat record");
assert.deepEqual(saved, res.tree);
});
@@ -268,7 +268,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(res.error, "Tree already initialized — use the mutation tools");
assert.deepEqual(res.tree.nodes.map((n: { id: string }) => n.id), ["a"], "existing tree returned, not wiped");
const saved = getChat(chatId)!.tree!;
const saved = chatStore.getChat(chatId)!.tree!;
assert.deepEqual(saved.nodes.map((n) => n.id), ["a"]);
});
@@ -288,7 +288,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(res.ok, false);
assert.match(res.error!, /cycle/);
assert.deepEqual(res.tree, emptyTree());
assert.equal(getChat(chatId)!.tree, undefined, "nothing persisted on failure");
assert.equal(chatStore.getChat(chatId)!.tree, undefined, "nothing persisted on failure");
});
it("mutation round-trip: add node with parents, set current, mark done — each persists", async () => {
@@ -315,17 +315,17 @@ describe("plan tools (execute against the real store)", () => {
["ratelimit→burst", "ratelimit→detour"],
);
assert.equal(added.tree.version, 2);
assert.deepEqual(getChat(chatId)!.tree!, added.tree, "add_node persisted");
assert.deepEqual(chatStore.getChat(chatId)!.tree!, added.tree, "add_node persisted");
const current = await exec(tools, "plan_set_current", { id: "detour" });
assert.equal(current.ok, true);
assert.equal(current.tree.currentNodeId, "detour");
assert.equal(getChat(chatId)!.tree!.currentNodeId, "detour", "set_current persisted");
assert.equal(chatStore.getChat(chatId)!.tree!.currentNodeId, "detour", "set_current persisted");
const done = await exec(tools, "plan_mark_done", { id: "ratelimit" });
assert.equal(done.ok, true);
assert.deepEqual(done.tree.doneNodeIds, ["ratelimit"]);
assert.deepEqual(getChat(chatId)!.tree!.doneNodeIds, ["ratelimit"], "mark_done persisted");
assert.deepEqual(chatStore.getChat(chatId)!.tree!.doneNodeIds, ["ratelimit"], "mark_done persisted");
assert.equal(done.tree.version, 4);
});
@@ -333,7 +333,7 @@ describe("plan tools (execute against the real store)", () => {
const chatId = newChat("Plan tools: invalid ops");
const tools = planTools({ chatId });
await exec(tools, "plan_init", { nodes: [{ id: "a", title: "A" }] });
const before = getChat(chatId)!.tree!;
const before = chatStore.getChat(chatId)!.tree!;
const dup = await exec(tools, "plan_add_node", { id: "a", title: "Impostor" });
assert.equal(dup.ok, false);
@@ -348,7 +348,7 @@ describe("plan tools (execute against the real store)", () => {
assert.equal(badEdge.ok, false);
assert.match(badEdge.error!, /self-loop/);
assert.deepEqual(getChat(chatId)!.tree!, before, "record untouched by failed ops");
assert.deepEqual(chatStore.getChat(chatId)!.tree!, before, "record untouched by failed ops");
});
it("mutation tools work on a fresh (uninitialized) chat: the tree seeds from empty", async () => {
@@ -357,7 +357,7 @@ describe("plan tools (execute against the real store)", () => {
const res = await exec(tools, "plan_add_node", { id: "a", title: "A" });
assert.equal(res.ok, true);
assert.equal(res.tree.nodes.length, 1);
assert.ok(getChat(chatId)!.tree, "tree seeded without plan_init");
assert.ok(chatStore.getChat(chatId)!.tree, "tree seeded without plan_init");
});
it("unknown chat returns ok:false with the empty tree", async () => {