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

wave 7: the prober reads its map — graph-context injection dies whole

Browse Source 
The owner's zero-configuration ruling (2026-09-23): nothing configures
the graph beyond chat models. The prior-knowledge injection — its budget
dial, its runner, its marker part, its dock/dispatch entries — is
removed across all bands; the prober now reads the learner's persistent
knowledge map on demand through two gated tools instead:

- list_sessions: every birth session, names + kinds + counts + dates
  (graphSessionIndex, Platform's core seam)
- list_propositions(session): what was born there + the session's own
  latest understanding level + that evaluation's date
  (graphSessionPropositions) — names/levels/dating ONLY, no statement
  text (owner ruling: the map's organization is the prober's business,
  its prose is not)

Registered via createProberTools when chat-handler passes graphStore
(the graphToolsEnabled gate decided server-side, per-turn fresh); the
prober doctrine gains the map-review nudge at session start.

Also: runner's JobKind special-casing collapses (KIND_ROLE/KIND_RUNNERS
are plain records again), semantic-clusters.ts dies with its test, the
embedder dep's doc tells the wave-7 stub story, and ports.ts's
readClusterLabels/readNamingRuns surface stays untouched for Platform's
ledger-port interlude.

848/848 tests, typecheck/lint/build green.
This commit is contained in:
amosblomqvist
2026-09-23 15:24:48 +03:00
parent a72753b059
commit 6b13583e96
40 changed files with 373 additions and 1990 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/agent/prompts/prober/10-probe-doctrine.md
+2 -1
View File
@@ -23,4 +23,5 @@ Find out what he actually wants taught. With a subject he doesn't know yet, the
Your questions are the substance of the session right now: they **open instantly** in the learner's dock, front and center — that immediacy is exactly what probing needs. Ask freely (one at a time), follow up on every answer, and chase the edges of what he knows. The probe is working when the questions are getting sharper, not easier.
If the learner references a local file (notes, a syllabus, code he's working on), the `read` tool can inspect it directly — ground your assessment in his actual material instead of asking him to paste contents. For his PDF material, the `pdf` tool dispatches a sub-agent that reads it for you and returns a cited brief — same grounding, no copy-pasting. And if pinning down a fact would genuinely sharpen a probe question (a date, a formula, a term you're not sure of), the `research` tool can verify it — but sparingly: probing is measurement, not exploration, and waiting on a research brief is never a reason to stall the questions.
If the learner references a local file (notes, a syllabus, code he's working on), the `read` tool can inspect it directly — ground your assessment in his actual material instead of asking him to paste contents. For his PDF material, the `pdf` tool dispatches a sub-agent that reads it for you and returns a cited brief — same grounding, no copy-pasting. And if pinning down a fact would genuinely sharpen a probe question (a date, a formula, a term you're not sure of), the `research` tool can verify it — but sparingly: probing is measurement, not exploration, and waiting on a research brief is never a reason to stall the questions.
Before your first question, review what he already knows that the session itself cannot show you: his persistent knowledge map, read through `list_sessions` and `list_propositions` — the propositions he carries from earlier sessions change which edges are worth locating, and a strand he already holds at "solid" needs no re-probing. Re-check after your merges add new propositions. If the tools aren't there, the map is off — just probe.
src/agent/subagents/extraction.ts
+15 -21
View File
@@ -482,12 +482,12 @@ function runNotesAuditor(
// ─── the pipeline status registry ─────────────────────────────────────────────
/** The pipeline phases, in order — what the home status endpoint shows.
* `embedding` is its own phase (accuracy wave, 2026-09-19): the post-batch
* tail — embed every uncovered proposition, re-cluster, settle the layout
* — used to hide inside `merging`, so a run that had already merged every
* batch sat on "merging" for the whole embedding tail (model load +
* cold-start backfill on first runs = minutes). The phases must tell the
* truth about what the loop is actually waiting on. */
* `embedding` was its own phase (accuracy wave, 2026-09-19): the post-batch
* embed-re-cluster tail used to hide inside `merging`. Wave 7 stubbed the
* tail to a no-op — the phase survives only until Platform's
* ledger-port interlude deletes the seam wholesale; it transitions
* instantly today. The phases must tell the truth about what the loop is
* actually waiting on. */
export type ExtractionPhase = "extracting" | "auditing" | "merging" | "embedding";
/** One in-flight pipeline run. Module-level: one process, one registry.
@@ -575,16 +575,12 @@ export interface ExtractionModels {
}
export interface ExtractionPipelineDeps extends GraphDeps, ExtractionModels {
/** The post-merge embedding batch (semantic clusters run on it).
* INJECTED by the composition root (the agent layer never imports
* the server layer — architecture law): production passes the
* provider-embedder batch (server/embeddings.ts embedNewNodes — BYOK
* wave 6; null model = it skips itself with an info log), tests fake
* it. Failure inside it is non-fatal by contract, and since 02bd1b0
* it fails BY RESULT — landed vectors + partial usage ride the
* return value instead of a throw. When the result carries a
* `usage` stage (the EmbedBatchResult contract), it is recorded
* into the run's money-channel capture. */
/** The post-merge embedding batch — WAVE 7 STUB: the provider
* embedder and semantic clustering are dead (birth-session clusters
* + session-name labels), so production injects a no-op that
* reports skipped; tests fake writes to the (still-live) ledger
* port. The whole seam dies with Platform's ledger-port interlude
* — kept one round so that removal is a pure deletion. */
embedder: (graphStore: GraphStore) => Promise<unknown>;
}
@@ -863,11 +859,9 @@ export function createExtractionPipeline(deps: ExtractionPipelineDeps): Extracti
// The embedding tail gets its own phase — the honest label for what
// the run is waiting on here (see ExtractionPhase above).
setPhase(chatId, "embedding", "chat");
// Semantic embeddings (DECIDED 2026-09-13): topics come from
// MEANING, so embed the new propositions BEFORE the settle and
// the namer look at clusters. Failure is non-fatal — the landed
// vectors persist (pay-once, 02bd1b0) and clustering runs with
// them; the next merge's retry embeds only what remains.
// The embedding tail (wave 7 stub — see ExtractionPipelineDeps):
// the seam stays until Platform's ledger-port interlude; the
// failure contract is unchanged (non-fatal, by-result).
await captureEmbedUsage(chatId, await embed(graphStore).catch(recordEmbedFailure(chatId)));
// Option A: the layout ledger evolves with the merge (sync — the
// next snapshot fetch must already reflect the new nodes).
src/agent/subagents/graph-context.ts
-222
View File
@@ -1,222 +0,0 @@
/**
* Graph context injection — the background runner
* (docs/vision-context-injection.md, settled 2026-09-14).
*
* One shot per chat, at session start: the first learner message is the
* session's TOPIC; it is embedded as a retrieval QUERY (the embedder's
* model-card format), the semantically closest graph propositions are
* selected under the session's token budget (pure core: selectGraphContext),
* and delivered as a marker-only STEER through the wake pipeline — the same
* gates as sub-agent results: it queues behind a pending quiz and rides the
* turn after the learner's answer. The prober typically opens with a run of
* quiz/ask calls, so delivery lands mid-probing, before plan_init — where
* prior knowledge matters most.
*
* No teacher-model call: the job's only model spend is ONE embedding
* query (the local embedder was free, provider ones are not — wave 6
* records its prompt tokens on the job record). It still carries a
* JobRecord (kind "graph-context") so the dock shows it, and it
* registers its AbortController so the dock's END kills it — but an abort
* steers NOTHING: nothing was ever promised in the lesson (the injection is
* server-initiated scaffolding, unlike a teacher-dispatched sub-agent).
*
* The topic gate is structural: injection fires only while the session has
* EXACTLY ONE text-bearing user message — the topic. Old in-flight sessions
* (several typed messages) never inject (no retroactive injection), and a
* session whose first turn happened with injection off stays off even if
* the budget is raised later (set per-session, before the session starts).
*/
import {
accumulateJobUsage,
buildGraphContextSteer,
steerDelivered,
type JobRecord,
type SteerMessage,
} from "../../core/contracts.ts";
import {
GRAPH_CONTEXT_TOKENS_DEFAULT,
type ChatSettings,
} from "../../core/contracts/chat.ts";
import { hasContext, selectGraphContext } from "../../core/graph-context.ts";
import type { UIMessage } from "ai";
import { registerJobAbort, unregisterJobAbort } from "./aborts.ts";
import type { ChatStore, GraphStore, JobStore } from "../../core/ports.ts";
/** The embedder as the runner needs it (BYOK wave 6): the model slug the
* ledger must match (parity: one vector space) + the query seam.
* Resolved FRESH per run by the composition root (deps.embedder) so a
* settings PUT or a key save between dispatch and spawn lands; null
* model = no embedding configured — the run skips honestly. The query
* carries its prompt-token count so the job records its spend (the
* local embedder was free; provider ones are not). */
export interface GraphContextEmbedder {
model: string | null;
embedQuery: (text: string) => Promise<{ vector: number[]; promptTokens?: number }>;
}
export interface GraphContextDeps {
chatStore: Pick<ChatStore, "getChat">;
jobStore: Pick<JobStore, "createJob" | "getJob" | "updateJob" | "findJobByToolCallId">;
graphStore: Pick<GraphStore, "readNodes" | "readEvents" | "readEmbeddings">;
/** The embedder RESOLVER (wave 6): called once at run start — fresh
* setting + key reads each run. null = no embedding model configured. */
embedder: () => GraphContextEmbedder | null;
/** The wake seam — jobs.ts deliverJobResult (resolves on delivery). */
deliver: (steer: SteerMessage) => Promise<void>;
}
/** The injection job's synthetic toolCallId — no tool part exists; the id
* is deterministic per chat so findJobByToolCallId doubles as the one-shot
* guard, mirroring the spawn-dedup the tool jobs get for free. */
export function contextToolCallId(chatId: string): string {
return `ctx_${chatId}`;
}
/** The session's effective budget: settings override, else the default.
* Absent ≠ 0 — the decided default is ON (1024 tokens). */
export function effectiveContextBudget(settings: ChatSettings | undefined): number {
return settings?.graphContextTokens ?? GRAPH_CONTEXT_TOKENS_DEFAULT;
}
/** The session's topic: its ONLY text-bearing user message, if exactly one
* exists. Steers (verdicts, handoffs, answers) carry no text part, so
* quiz rounds during probing never break the gate. */
export function topicOf(messages: UIMessage[]): string | null {
let topic: string | null = null;
let count = 0;
for (const m of messages) {
if (m.role !== "user") continue;
const text = m.parts
.filter((p) => p.type === "text")
.map((p) => (p as { text?: unknown }).text)
.filter((t): t is string => typeof t === "string" && t.trim().length > 0)
.join("\n");
if (text.length === 0) continue;
count++;
topic = text;
}
return count === 1 ? topic : null;
}
/**
* The one-shot trigger (fire-and-forget, called from turn-service at every
* turn's onFinish): starts the injection job if and only if the session is
* at its start (exactly one typed message — the topic), the budget is on,
* and nothing was injected before (delivered steer OR any prior context
* job — success or failure: one shot means one shot). Returns the created
* job for tests; null when nothing was started.
*/
export function startGraphContextInjection(deps: GraphContextDeps, chatId: string): JobRecord | null {
const { chatStore, jobStore } = deps;
const chat = chatStore.getChat(chatId);
if (!chat) return null;
if (effectiveContextBudget(chat.settings) <= 0) return null;
if (topicOf(chat.messages) === null) return null;
// One per chat, ever: a delivered steer OR a prior job (any status).
if (steerDelivered(chat.messages, `steer_ctx_${chatId}`)) return null;
if (jobStore.findJobByToolCallId(chatId, contextToolCallId(chatId))) return null;
const job = jobStore.createJob({
kind: "graph-context",
chatId,
toolCallId: contextToolCallId(chatId),
activity: "searching knowledge graph",
});
void runGraphContextJob(deps, job.id).catch((err: unknown) => {
console.error(`[chat ${chatId}] graph-context injection crashed:`, err);
});
return job;
}
/** Run one injection job to completion (background; never throws). Also the
* crash-recovery respawn seam: a job record orphaned "running" by a
* process crash re-runs from here (the record is the only input needed). */
export async function runGraphContextJob(deps: GraphContextDeps, jobId: string): Promise<void> {
const { chatStore, jobStore, graphStore, deliver } = deps;
const job = jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
const fail = (reason: string) => {
jobStore.updateJob(jobId, { status: "error", error: reason, activity: "failed" });
};
const chat = chatStore.getChat(job.chatId);
if (!chat) return fail(`chat not found: ${job.chatId}`);
// BYOK (wave 6): fresh resolution per run; null = honestly off (the
// dispatch gate already skips unconfigured sessions — this only fires
// on a config change racing a respawn, and the error says exactly why).
// The resolver returns null for BOTH an unset model and a set model
// whose key vanished, so the message names both, never a false "null".
const embedder = deps.embedder();
if (!embedder || embedder.model === null) {
return fail("no embedding model available — injection skipped (graph.embeddingModel unset, or its provider key is missing)");
}
const topic = topicOf(chat.messages);
if (topic === null) return fail("no injectable topic (session past its start)");
const budget = effectiveContextBudget(chat.settings);
// Real-kill wiring: the dock's END fires this controller; the runner
// checks it before every phase transition and unwinds silently.
const controller = new AbortController();
registerJobAbort(jobId, controller);
try {
jobStore.updateJob(jobId, { activity: "embedding topic" });
const ledger = graphStore.readEmbeddings();
// Staleness is the MODEL identity (wave 6): a given model serves one
// dim by default, so model parity is space parity; the dim is checked
// defensively against the served vector below.
if (ledger.model !== embedder.model) {
return fail("embeddings ledger is stale (model mismatch) — injection skipped");
}
if (Object.keys(ledger.vectors).length === 0) {
return fail("the knowledge graph has no embeddings yet — nothing to inject");
}
const query = await embedder.embedQuery(topic);
if (controller.signal.aborted) return;
// The defensive dim half of the old parity check: a provider-side dim
// change (rare) must fail the query, never silently mismatch.
if (query.vector.length !== ledger.dim) {
return fail(
`embedding dim mismatch: query is ${query.vector.length}, ledger holds ${ledger.dim}`,
);
}
// Money channel (wave 6): the one embedding call's prompt tokens fold
// into the job record — priced via the EMBEDDING_PRICES overlay.
if (query.promptTokens !== undefined) {
jobStore.updateJob(jobId, {
usage: accumulateJobUsage(job.usage, embedder.model, {
inputTokens: query.promptTokens,
outputTokens: 0,
}),
});
}
jobStore.updateJob(jobId, { activity: "selecting propositions" });
const data = selectGraphContext({
chatId: job.chatId,
query: query.vector,
vectors: ledger.vectors,
nodes: graphStore.readNodes(),
events: graphStore.readEvents(),
budget,
});
if (!hasContext(data)) return fail("nothing relevant fit the budget");
if (controller.signal.aborted) return;
// The result rides the record (crash recovery re-delivers it); the
// wake pipeline flips the job done when the lesson has resumed.
jobStore.updateJob(jobId, { result: data, activity: "delivering context" });
try {
await deliver(buildGraphContextSteer({ chatId: job.chatId, jobId }, data));
} catch (err) {
console.error(`[chat ${job.chatId}] graph-context steer delivery failed:`, err);
fail("context delivery failed");
}
} catch (err) {
if (controller.signal.aborted) return; // the abort path owns the record
console.error(`[chat ${job.chatId}] graph-context injection failed:`, err);
fail(err instanceof Error ? err.message : String(err));
} finally {
unregisterJobAbort(jobId);
}
}
src/agent/subagents/runner.ts
+6 -16
View File
@@ -107,7 +107,7 @@ interface LoopContext {
/** The kind→role table (model slots wave, 2026-09-20): which ModelRole's
* engine each sub-agent kind runs — the engineFor injection key. */
const KIND_ROLE: Record<Exclude<JobKind, "graph-context">, ModelRole> = {
const KIND_ROLE: Record<JobKind, ModelRole> = {
research: "researcher",
demo: "demoBuilder",
visual: "visualMaker",
@@ -148,18 +148,14 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
return jobStore.getJob(jobId)?.status === "running";
}
/** The kind→runner map: one sub-agent loop per SUB-AGENT kind.
* graph-context is deliberately absent: injection jobs are not
* sub-agent loops (no model, graph deps instead) — their spawn and
* crash-respawn seam is subagents/graph-context.ts, and runJob refuses
* them below rather than guessing wrong. */
// Each kind's runner narrows the union input itself (dispatch-time inputs
// are kind-correct by construction; transcript fallbacks are cast after).
/** The kind→runner map: one sub-agent loop per kind. Each kind's
* runner narrows the union input itself (dispatch-time inputs are
* kind-correct by construction; transcript fallbacks are cast after). */
/** The engine one job runs on: test override first (the old seam —
* tests swap scripted engines without touching deps), then the injected
* settings-resolved engineFor. undefined = the BYOK chain came up
* empty (owner, 2026-09-22) — runJob refuses below, honestly. */
function pickEngine(kind: Exclude<JobKind, "graph-context">): PiEngine | undefined {
function pickEngine(kind: JobKind): PiEngine | undefined {
const testOverride: Record<string, { current?: PiEngine } | undefined> = {
researcher: researchModelOverride,
demoBuilder: demoModelOverride,
@@ -170,7 +166,7 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
}
const KIND_RUNNERS: Record<
Exclude<JobKind, "graph-context">,
JobKind,
(jobId: string, engine: PiEngine, input: JobToolInput | undefined, loop: LoopContext) => Promise<void>
> = {
research: (jobId, engine, input, loop) => runResearchJob(jobId, engine, input, loop),
@@ -186,12 +182,6 @@ export function createJobRunner(deps: JobRunnerDeps): JobRunner {
return;
}
if (job.status !== "running") return; // already finished / re-run after crash recovery
if (job.kind === "graph-context") {
// Not a sub-agent: the injection's own respawn seam
// (setContextRespawn → runGraphContextJob) owns these records.
console.error(`[job ${jobId}] graph-context job reached the sub-agent runner — wrong seam`);
return;
}
const run = KIND_RUNNERS[job.kind];
if (!run) {
console.error(`[job ${jobId}] unknown kind: ${job.kind}`);
src/agent/tools.ts
+18 -5
View File
@@ -11,10 +11,12 @@ import type { JobStore } from "../core/ports.ts";
import { jobTools, type DemoInput, type PdfInput, type ResearchInput, type VisualInput } from "./tools/jobs.ts";
import { planTools, type PlanToolContext } from "./tools/plan.ts";
import { probeDoneTool, type ProbeDoneContext } from "./tools/probe.ts";
import { proberGraphTools } from "./tools/graph.ts";
import { readTool } from "./tools/read.ts";
import { lsTool } from "./tools/ls.ts";
import { findTool } from "./tools/find.ts";
import { grepTool } from "./tools/grep.ts";
import type { GraphStore } from "../core/ports.ts";
export { jobTools };
export type { ProbeDoneContext } from "./tools/probe.ts";
@@ -78,14 +80,20 @@ export interface ProberToolContext extends ProbeDoneContext {
/** Search availability — the research dispatch tool's honest-disable
* signal (same gate as the teacher's). Absent = available. */
searchAvailable?: () => boolean;
/** The prober's graph-map reader (wave 7): present = the two map tools
* (list_sessions / list_propositions) are registered. The composition
* root passes it only when graphToolsEnabled(effective) — the graph
* master switch AND the agent.graphTools toggle (settings-resolution).
* Absent = the gate is closed, no map tools (tests drive this seam). */
graphStore?: GraphStore;
}
/** The prober's tool set: probe quiz (no nodeId) + ask + the learner-fs
* set + probe_done + the two phase-omnipresent job dispatch tools.
* `enabled` is the resolved settings seam (core/pending.ts): any tool
* explicitly false is dropped from the registry. probe_done stays
* always-on regardless — it is how the phase ENDS; a prober that can
* never conclude is a lockout. */
* set + probe_done + the two phase-omnipresent job dispatch tools +
* (wave 7, gated) the graph-map reader. `enabled` is the resolved
* settings seam (core/pending.ts): any tool explicitly false is dropped
* from the registry. probe_done stays always-on regardless — it is how
* the phase ENDS; a prober that can never conclude is a lockout. */
export function createProberTools(
ctx: ProberToolContext,
enabled?: EnabledTools,
@@ -122,6 +130,11 @@ export function createProberTools(
// when no engine is live).
...(jobs.research ? { research: jobs.research } : {}),
pdf: jobs.pdf!,
// The map reader (wave 7): present only when the settings gate
// opened — same registration-time drop as the search gate.
...(ctx.graphStore
? proberGraphTools({ chatStore: ctx.chatStore, graphStore: ctx.graphStore })
: {}),
...done,
},
enabled,
src/agent/tools/graph.ts
+75
View File
@@ -0,0 +1,75 @@
import { z } from "zod";
import { lhTool, type LhTool } from "../lh-tool.ts";
import { graphSessionIndex, graphSessionPropositions } from "../../core/graph.ts";
import type { ChatStore, GraphStore } from "../../core/ports.ts";
/**
* THE PROBER'S GRAPH TOOLS (wave 7, owner-locked 2026-09-23): context
* injection is dead — zero configuration beyond chat models. The prober
* reads the learner's persistent knowledge map through two tools instead,
* replacing the old injected block with on-demand eyes.
*
* Names + levels + dating ONLY — no statement text, no session contents
* (owner ruling: the map's ORGANIZATION is the prober's business, its
* prose is not). The data comes from Platform's pure core seams
* (graphSessionIndex / graphSessionPropositions) over the same ports the
* snapshot reads, so the prober and the learner's graph view can never
* disagree.
*
* Registered on the prober ONLY when the settings gate opens
* (graphToolsEnabled — the graph master switch AND the agent.graphTools
* toggle); the composition root decides, the factory just receives the
* store (absent = the gate is closed, no map tools — tests drive this).
*/
/** What the graph tools close over: the stores the session views read. */
export interface GraphToolContext {
chatStore: ChatStore;
graphStore: GraphStore;
}
export function proberGraphTools(ctx: GraphToolContext): Record<string, LhTool<any, any>> {
const deps = { chatStore: ctx.chatStore, graphStore: ctx.graphStore };
return {
list_sessions: lhTool({
name: "list_sessions",
description:
"List the sessions of the learner's persistent knowledge graph — every chat or imported-notes file that ever contributed a proposition, most recent first. The map is organized into birth-session clusters (propositions grouped by the session they were first learned in), and session names are those clusters' labels. " +
"Each line: the session's name, kind (chat/file), how many propositions were born in it, its dates, and its id — use that id with list_propositions. " +
"Reading this first shows what he has already covered and when, before you probe anything.",
schema: z.object({}),
execute: async (): Promise<string> => {
const sessions = graphSessionIndex(deps);
if (sessions.length === 0) return "The knowledge graph is empty — no session has contributed propositions yet.";
const lines = sessions.map((s, i) =>
`${i + 1}. ${s.name} (${s.kind}, ${s.propositions} proposition${s.propositions === 1 ? "" : "s"}, ` +
`born ${s.createdAt ?? "unknown date"}${s.updatedAt ? `, last active ${s.updatedAt}` : ""}) — id: ${s.id}`,
);
return `${sessions.length} session(s) in the knowledge graph, most recent first:\n${lines.join("\n")}`;
},
}),
list_propositions: lhTool({
name: "list_propositions",
description:
"List the propositions BORN in one knowledge-graph session — what was first learned there — each with his latest understanding level on the scale solid / shaky / accepted / resisted / not yet engaged, and the date that level was set. " +
"Names, levels, and dating only — no statement text, no session contents. " +
"The level is that session's own latest evaluation; other sessions may have moved it since, so cross-session levels can differ.",
schema: z.object({
session: z
.string()
.min(1)
.describe("The session's id exactly as list_sessions reported it (a chat id or a notes source id)"),
}),
execute: async ({ session }): Promise<string> => {
const propositions = graphSessionPropositions(deps, session);
if (propositions.length === 0) {
return `No propositions born in session "${session}". Call list_sessions for the current ids.`;
}
const lines = propositions.map(
(p) => `- ${p.name} — ${p.understanding ?? "never evaluated"}${p.evaluatedAt ? ` (as of ${p.evaluatedAt})` : ""}`,
);
return `${propositions.length} proposition(s) born in this session:\n${lines.join("\n")}`;
},
}),
};
}
src/core/clusters.ts
+4 -5
View File
@@ -1,9 +1,8 @@
/**
* CLUSTER LABEL MATCHING (vision §1). DETECTION moved to semantic topic
* clustering over embeddings (core/semantic-clusters.ts, DECIDED
* 2026-09-13) — Louvain over the edge structure is retired: it only ever
* found the reasoning chains (the graph is disconnected by nature), and
* edge-orphans could never join anything. What REMAINS here is the
* CLUSTER LABEL MATCHING (vision §1). DETECTION is birth-session
* clustering since wave 7 (core/session-clusters.ts; the semantic
* embedder and its Louvain predecessor are both dead). What REMAINS here
* is the
* cluster contract + core-survival label matching, which is
* detection-agnostic: it consumes the same { members } shape semantic
* clustering emits.
src/core/contracts/chat.ts
-66
View File
@@ -58,27 +58,8 @@ export interface ChatSettings {
/** pi thinking level — must be in the chosen model's supported list
* (getSupportedThinkingLevels; enforced by the settings route). */
thinkingLevel?: ThinkingLevel;
/** Graph context injection (vision-context-injection.md): the session's
* token budget for the prior-knowledge block — the top semantically
* closest propositions from the knowledge graph, injected once, at
* session start, as a steer. Absent = the default (on); 0 = off. The
* settings route enforces the range; the trigger (turn-service →
* subagents/graph-context.ts) is one-shot, so a mid-session change
* affects only sessions that haven't injected yet. */
graphContextTokens?: number;
}
/** The injection budget's decided knobs (2026-09-14; scale revised
* 2026-09-15, owner): default 1024 (a meaningful, modest slice of prior
* knowledge), hard max 16384, 0 = off. The UI is a DISCRETE slider over
* these stops — powers of four from 64 (the fine-grained low end was
* theater: a 128-token budget is ~2 propositions, nobody wants that
* dial); the server still accepts any integer in range (a stale client
* can't brick settings), the stops only govern what the slider sends. */
export const GRAPH_CONTEXT_TOKENS_DEFAULT = 1024;
export const GRAPH_CONTEXT_TOKENS_MAX = 16384;
/** The slider's positions, left to right: off, then powers of four. */
export const GRAPH_CONTEXT_TOKENS_STOPS = [0, 64, 256, 1024, 4096, 16384] as const;
// ─── Background-extraction usage (the money channel, extraction side) ────────
@@ -202,53 +183,6 @@ export const HANDOFF_TEXT =
"The probe is concluded — the learner assessment is recorded. " +
"Author the session's plan map now (call plan_init) and present it, then begin teaching.";
// ─── Graph context injection (vision-context-injection.md, 2026-09-14) ────────
/** One selected prior-knowledge proposition: similarity-ranked, annotated
* with the learner's CURRENT understanding level — the fold is MOST
* RECENT extraction instance (levels are per-instance, tied to moments in
* time; the latest evidence is the best estimate of current understanding).
* null = the node has no observation event at all. */
export interface GraphContextProposition {
id: string;
statement: string;
level: UnderstandingLevel | null;
}
/** The data-graph-context part payload: what the UI renders (the counts)
* AND the audit trail (the full block content — the transcript shows
* exactly what was injected, and when). The model-facing text is derived
* from this by graphContextText below — the adapter flattens the marker
* part to it (the custom-message scheme: no authored human speech). */
export interface GraphContextData {
chatId: string;
/** The session's budget at injection time (for the card's readout). */
budget: number;
/** Estimated tokens of the injected block — chars/4 heuristic. */
tokens: number;
/** The selected propositions, similarity-descending. */
propositions: GraphContextProposition[];
}
/** The model-facing block text — single-sourced (the adapter, the tests,
* and reality can't drift). The level word travels with each line: the
* closing gloss tells the agent what to do with each. */
export function graphContextText(data: GraphContextData): string {
const n = data.propositions.length;
if (n === 0) return "";
const lines = data.propositions.map(
(p) => `- ${p.level ? `[${p.level}] ` : ""}${p.statement}`,
);
return [
`Prior-knowledge context — what this learner already knows (from their knowledge graph, ` +
`${n} proposition${n === 1 ? "" : "s"}, ~${data.tokens} tokens):`,
"",
...lines,
"",
"Treat this as reliable prior knowledge: build on what is solid, firm up what is shaky, " +
"and teach around anything resisted. Do not re-teach solid ground.",
].join("\n");
}
export interface PlanBlockData {
/** Only "full" survives (the 2026-09-11 pivot): the plan renders IN
src/core/contracts/jobs.ts
+3 -32
View File
@@ -7,11 +7,11 @@
* of "ai" (safe everywhere: server, client, tests). See docs/vision.md.
*/
import type { UIMessage } from "ai";
import type { CallUsage, GraphContextData } from "./chat.ts";
import type { CallUsage } from "./chat.ts";
// ─── Async sub-agent jobs (vision §2.5; plan.md Wave 0 protocol) ────────────
export type JobKind = "research" | "demo" | "visual" | "pdf" | "graph-context";
export type JobKind = "research" | "demo" | "visual" | "pdf";
export type JobStatus = "running" | "done" | "error";
export interface JobRecord {
@@ -295,8 +295,7 @@ export interface AbortSteerMessage extends UIMessage {
export type SteerMessage =
| SubagentSteerMessage
| AbortSteerMessage
| ProbeHandoffSteerMessage
| GraphContextSteerMessage;
| ProbeHandoffSteerMessage;
/** Whether a result is the failure shape (html/svg empty, failure brief). */
export function isSubagentFailure(
@@ -426,34 +425,6 @@ export function buildProbeHandoffSteer(chatId: string): ProbeHandoffSteerMessage
};
}
// ─── the graph-context steer (vision-context-injection.md) ───────────────────
//
// The injection's delivery: same wake pipeline, same gates — it queues
// behind a pending quiz and rides the turn after the learner's answer, or
// fires in the pump's idle window. Marker-only (the custom-message scheme):
// no text part; the adapter flattens data-graph-context to graphContextText
// (core/contracts/chat.ts owns the wording). One per chat, ever — the id is
// deterministic per chat, so re-delivery is idempotent.
export interface GraphContextSteerMessage extends UIMessage {
id: `steer_ctx_${string}`;
role: "user";
metadata: { graphContext: { chatId: string; jobId: string } };
parts: [{ type: "data-graph-context"; data: GraphContextData }];
}
export function buildGraphContextSteer(
meta: { chatId: string; jobId: string },
data: GraphContextData,
): GraphContextSteerMessage {
return {
id: `steer_ctx_${meta.chatId}`,
role: "user",
metadata: { graphContext: meta },
parts: [{ type: "data-graph-context", data }],
};
}
/** True when the transcript already carries this steer — idempotent
* delivery for ANY steer kind: every steer id is deterministic per its
* event (steer_<jobId> for jobs, steer_probe_<chatId> for the handoff). */
src/core/graph-context.ts
-184
View File
@@ -1,184 +0,0 @@
/**
* Graph context injection — the pure selection core
* (docs/vision-context-injection.md, settled 2026-09-14).
*
* The heavy lifting is deliberately tiny: embedding the topic is the only
* slow step (the embedder singleton), and SEARCH IS BRUTE-FORCE COSINE —
* ~1M multiply-adds at 2k propositions, exact top-K from the in-memory
* ledger, no ANN index until ~10⁶ scale (far away).
*
* Selection doctrine (owner-decided): the token budget is the ONLY control
* on amount — there is NO similarity threshold. Similarity decides ORDER
* (which propositions fill the budget first); irrelevant-but-cheap content
* rides along harmlessly. Levels fold MOST RECENT: UnderstandingLevel lives
* per extraction instance (tied to moments in time), and the latest evidence
* is the best estimate of current understanding — an optimistic fold risks
* stale claims, a pessimistic fold wastes covered ground.
*/
import {
GRAPH_CONTEXT_TOKENS_MAX,
type GraphContextData,
type GraphContextProposition,
graphContextText,
} from "./contracts/chat.ts";
import type { UnderstandingLevel } from "./contracts/graph.ts";
import type { GraphNode, LedgerEvent } from "./contracts/graph.ts";
/** Belt-and-braces count cap — the budget is the primary control; a huge
* budget still can't pour hundreds of lines into the block. */
export const GRAPH_CONTEXT_MAX_PROPOSITIONS = 64;
/** The block's framing (header + gloss) in estimated tokens — reserved so
* the composed block, not just the proposition lines, stays under budget. */
const FRAMING_TOKENS = 55;
const LEVELS: ReadonlySet<string> = new Set([
"solid",
"shaky",
"accepted",
"resisted",
"not yet engaged",
]);
export function isUnderstandingLevel(word: unknown): word is UnderstandingLevel {
return typeof word === "string" && LEVELS.has(word);
}
/**
* Fold each node's CURRENT understanding level: the level word of its most
* recent observation event (latest `at`; ledger order breaks ties — the
* same rule the snapshot's nodeObservations uses, but across ALL sessions,
* not per chat). Malformed notes (not on the scale) never count.
*/
export function currentUnderstanding(events: LedgerEvent[]): Map<string, UnderstandingLevel> {
const latest = new Map<string, { at: string; level: UnderstandingLevel; index: number }>();
events.forEach((event, index) => {
if (event.kind !== "observation" || event.nodeId === null) return;
if (!isUnderstandingLevel(event.note)) return;
const current = latest.get(event.nodeId);
if (!current || event.at > current.at || (event.at === current.at && index > current.index)) {
latest.set(event.nodeId, { at: event.at, level: event.note, index });
}
});
const levels = new Map<string, UnderstandingLevel>();
for (const [nodeId, { level }] of latest) levels.set(nodeId, level);
return levels;
}
/** Estimated tokens for one proposition line: chars/4 (the agreed
* heuristic — no server-side tokenizer) + one for the level tag. */
function lineTokens(p: GraphContextProposition): number {
return Math.ceil(p.statement.length / 4) + (p.level ? 1 : 0);
}
export interface SelectGraphContextInput {
chatId: string;
/** The topic's query embedding (same model + dim as the ledger — the
* caller asserts parity; dimension-mismatched vectors are skipped). */
query: number[];
/** The embeddings ledger's vectors: nodeId → truncated, L2-normalized
* (cosine = dot product). */
vectors: Record<string, number[]>;
/** Raw node lines (append order; first line per id defines — the
* ledger merge rule, mirrored from core/graph.ts). */
nodes: GraphNode[];
/** The event ledger — for the most-recent level fold. */
events: LedgerEvent[];
/** The session's token budget (estimated tokens, chars/4). */
budget: number;
}
/**
* Select the prior-knowledge block: similarity-descending greedy fill under
* the token budget, capped by count, each line annotated with its folded
* current level. Pure — server composes it with the embedder; tests drive
* it with hand-made vectors.
*/
export function selectGraphContext(input: SelectGraphContextInput): GraphContextData {
const { chatId, query, vectors, nodes, events, budget } = input;
const levels = currentUnderstanding(events);
// Score every embedded node: dot product (vectors are normalized). A
// dimension mismatch (a stale ledger, a foreign query) never scores.
const scored: Array<{ id: string; statement: string; score: number }> = [];
const seen = new Set<string>();
for (const node of nodes) {
if (seen.has(node.id)) continue; // first line defines (merge rule)
seen.add(node.id);
const vec = vectors[node.id];
if (!vec || vec.length !== query.length) continue;
let dot = 0;
for (let i = 0; i < query.length; i++) dot += query[i]! * vec[i]!;
scored.push({ id: node.id, statement: node.statement, score: dot });
}
scored.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
// Greedy fill: similarity order decides WHICH propositions enter; the
// budget decides WHEN to stop. No similarity threshold, by design.
const propositions: GraphContextProposition[] = [];
let used = FRAMING_TOKENS;
for (const { id, statement } of scored) {
if (propositions.length >= GRAPH_CONTEXT_MAX_PROPOSITIONS) break;
const p: GraphContextProposition = {
id,
statement,
level: levels.get(id) ?? null,
};
const cost = lineTokens(p);
if (used + cost > budget) continue; // too big for the budget — a later, smaller one may still fit
used += cost;
propositions.push(p);
}
return { chatId, budget, tokens: used, propositions };
}
/** True when the selection would inject anything (guards the runner: an
* empty block is never delivered — no steer, the job errors instead). */
export function hasContext(data: GraphContextData): boolean {
return data.propositions.length > 0 && graphContextText(data).length > 0;
}
// ─── The marker-part parser (parse-don't-cast — tool-parts doctrine) ──────────
function parseProposition(raw: unknown): GraphContextProposition | null {
if (typeof raw !== "object" || raw === null) return null;
const { id, statement, level } = raw as Record<string, unknown>;
if (typeof id !== "string" || typeof statement !== "string") return null;
if (level !== null && level !== undefined && !isUnderstandingLevel(level)) return null;
return { id, statement, level: (level as UnderstandingLevel | null | undefined) ?? null };
}
function parseGraphContextData(raw: unknown): GraphContextData | null {
if (typeof raw !== "object" || raw === null) return null;
const { chatId, budget, tokens, propositions } = raw as Record<string, unknown>;
if (typeof chatId !== "string") return null;
if (typeof budget !== "number" || budget < 0 || budget > GRAPH_CONTEXT_TOKENS_MAX) return null;
if (typeof tokens !== "number" || tokens < 0) return null;
if (!Array.isArray(propositions)) return null;
const parsed: GraphContextProposition[] = [];
for (const item of propositions) {
const p = parseProposition(item);
if (!p) return null; // malformed content: the whole part is untrusted
parsed.push(p);
}
return { chatId, budget, tokens, propositions: parsed };
}
/**
* The data-graph-context part of a message, validated — or null when the
* part is absent or malformed. The seam the adapter and the chat view read
* the marker through (never a raw cast: the part's data crossed a
* serialization boundary).
*/
export function graphContextOfMessage(
message: { parts: ReadonlyArray<{ type: string; data?: unknown }> },
): GraphContextData | null {
for (const part of message.parts) {
if (part.type === "data-graph-context") {
return parseGraphContextData((part as { data?: unknown }).data);
}
}
return null;
}
src/core/graph.ts
+4 -5
View File
@@ -399,11 +399,10 @@ const QUIZ_EVENT_KINDS: ReadonlySet<string> = new Set(["correct", "miss", "dont-
/**
* The latest quiz outcome per node — a raw EVENT FACT, not a node state
* (the transitional node-state classes were removed 2026-09-08: nothing
* colors nodes by quiz results anymore). Used by the teacher's
* graph-as-context selection (graph-context.ts) to find diagnostic
* hotspots; the home renderer does not consume it. Nodes with no quiz
* events have no entry. (The graph-as-context consumer is shelved —
* docs/probe-teach-split.md §5 — but the event fact stays.)
* colors nodes by quiz results anymore). Its last consumer, the
* graph-as-context selection, died in wave 7 (the injection is gone —
* the prober reads its map through tools now); the event fact stays as
* raw ledger truth. Nodes with no quiz events have no entry.
*/
export function latestQuizOutcomes(nodes: GraphNode[], events: LedgerEvent[]): Map<string, LedgerEventKind> {
const latest = new Map<string, { at: string; kind: LedgerEventKind; index: number }>();
src/core/index.ts
-1
View File
@@ -55,4 +55,3 @@ export * from "./auth-keys.ts";
// keyboard.ts: the shortcut registry + binding normalization (pure, browser-safe).
export * from "./keyboard.ts";
export * from "./coverage.ts";
export * from "./graph-context.ts";
src/core/ports.ts
+4 -5
View File
@@ -130,11 +130,10 @@ export interface GraphStore {
/** The embeddings ledger (config.EMBEDDINGS_FILE) — INERT DATA since
* wave 7 (owner ruling 2026-09-23: the provider embedder is dead;
* clustering is birth-session, labels are session names). Kept ONLY
* because the graph-context injection (agent band, Teacher's pass
* removes it) still reads it for vector-space staleness — the seam
* dies with it in the follow-up interlude. graph-deletion keeps
* pruning dead vectors meanwhile (harmless housekeeping). */
* clustering is birth-session, labels are session names; the
* graph-context injection is gone with it). The whole seam dies in
* the follow-up interlude; graph-deletion's vector pruning is
* harmless housekeeping meanwhile. */
readEmbeddings(): EmbeddingsLedger;
/** Replace the whole ledger (graph-deletion's vector pruning only). */
writeEmbeddings(ledger: EmbeddingsLedger): void;
src/core/semantic-clusters.ts
-141
View File
@@ -1,141 +0,0 @@
// Semantic topic clustering — the REPLACEMENT for Louvain community
// detection (DECIDED 2026-09-13): structural clusters were just the
// reasoning chains (the graph is disconnected by nature — every connected
// component became its own "cluster"), and edge-orphans could never join
// anything. Clusters are now RELATED TOPICS: nodes whose proposition
// MEANING is close, computed over the embedding ledger
// (config.EMBEDDINGS_FILE). This pulls orphans into topics by meaning
// and groups small chains with the large chains they discuss.
//
// Algorithm: threshold AGGLOMERATIVE (average linkage over cosine
// similarity). No JS HDBSCAN is trustworthy (the npm package is an
// abandoned alpha), and at proposition scale (~100s-1000s of short texts)
// brute-force pairwise cosine is sub-second — so the honest ~60-line
// hand-roll wins. "Stragglers" (nodes that fit nothing) fall out
// naturally: they simply never merge, and stay singletons.
/** The default similarity threshold, SWEPT ON THE REAL GRAPH
* (2026-09-13): 0.60 → 26 topics of ~20 propositions, 74 of the 90
* edge-orphans land in real topics, stragglers 10. Higher (0.65-0.68)
* gives tighter micro-topics with far more stragglers; lower (0.55)
* collapses into ~13 mega-topics. */
export const SEMANTIC_SIM_THRESHOLD = 0.6;
/** Cosine similarity of two vectors (defensively normalizes inputs;
* ledger vectors are already L2-normalized, so this is a dot product). */
export function cosineSimilarity(a: readonly number[], b: readonly number[]): number {
let dot = 0;
let ma = 0;
let mb = 0;
for (let i = 0; i < a.length; i++) {
dot += a[i]! * b[i]!;
ma += a[i]! * a[i]!;
mb += b[i]! * b[i]!;
}
if (ma === 0 || mb === 0) return 0;
return dot / (Math.sqrt(ma) * Math.sqrt(mb));
}
export interface SemanticClusterOptions {
/** Merge while the best cluster pair's average-linkage similarity is
* >= this (default SEMANTIC_SIM_THRESHOLD). */
similarityThreshold?: number;
/** After the cut, force every singleton into its nearest topic
* ("all-in" mode) instead of leaving stragglers loose. Default
* false: some propositions genuinely fit nothing. */
attachStragglers?: boolean;
}
/** Average-linkage agglomerative clustering over embedding vectors.
* Pure and deterministic (stable Map iteration, greedy by best
* similarity, first-found wins ties). Returns clusters size-desc — the
* same { members } shape Louvain produced, so label matching and the
* renderer contract are unchanged. An empty/missing ledger returns []
* (nothing embedded yet: no clusters, every node loose — the snapshot
* degrades gracefully until the first embed). */
export function semanticClusters(
vectors: Readonly<Record<string, readonly number[]>>,
options: SemanticClusterOptions = {},
): Array<{ members: string[] }> {
const ids = Object.keys(vectors);
if (ids.length === 0) return [];
const simThreshold = options.similarityThreshold ?? SEMANTIC_SIM_THRESHOLD;
const attach = options.attachStragglers ?? false;
// Sum vectors per cluster: average-linkage similarity between clusters
// A and B is dot(sumA, sumB) / (|A|·|B|) — the exact mean of pairwise
// dots — so the merge loop never revisits the raw O(n²) matrix.
const sums = new Map<number, number[]>();
const members = new Map<number, string[]>();
ids.forEach((id, i) => {
sums.set(i, [...vectors[id]!]);
members.set(i, [id]);
});
// Greedy merge: repeatedly join the pair with the highest
// average-linkage similarity until it drops below the threshold.
// O(k²) pair scan per merge — trivial at proposition scale.
for (;;) {
let bestA = -1;
let bestB = -1;
let bestSim = -Infinity;
for (const [a, sumA] of sums) {
for (const [b, sumB] of sums) {
if (a >= b) continue;
let dot = 0;
for (let i = 0; i < sumA.length; i++) dot += sumA[i]! * sumB[i]!;
const sim = dot / (members.get(a)!.length * members.get(b)!.length);
if (sim > bestSim) {
bestSim = sim;
bestA = a;
bestB = b;
}
}
}
if (bestA < 0 || bestSim < simThreshold) break;
// Merge B into A (deterministic direction: lower cluster index).
const sumA = sums.get(bestA)!;
const sumB = sums.get(bestB)!;
for (let i = 0; i < sumA.length; i++) sumA[i] = sumA[i]! + sumB[i]!;
members.get(bestA)!.push(...members.get(bestB)!);
sums.delete(bestB);
members.delete(bestB);
}
// Optional all-in pass: singletons join their nearest topic regardless
// of threshold — exactly the "forced membership" mode. The difference
// from stragglers mode is this one pass. Singleton-vs-cluster
// average-linkage similarity is dot(sumS, sumK) / |K|.
if (attach) {
const singletons = [...members.entries()].filter(([, m]) => m.length === 1).map(([k]) => k);
for (const s of singletons) {
if (!members.has(s)) continue; // absorbed by an earlier attach
let bestTarget = -1;
let bestSim = -Infinity;
for (const [k, m] of members) {
if (k === s || m.length < 2) continue;
let dot = 0;
const sumS = sums.get(s)!;
const sumK = sums.get(k)!;
for (let i = 0; i < sumS.length; i++) dot += sumS[i]! * sumK[i]!;
const sim = dot / m.length;
if (sim > bestSim) {
bestSim = sim;
bestTarget = k;
}
}
if (bestTarget >= 0) {
const sumT = sums.get(bestTarget)!;
const sumS = sums.get(s)!;
for (let i = 0; i < sumT.length; i++) sumT[i] = sumT[i]! + sumS[i]!;
members.get(bestTarget)!.push(...members.get(s)!);
sums.delete(s);
members.delete(s);
}
}
}
return [...members.values()]
.map((m) => ({ members: [...m].sort() }))
.sort((a, b) => b.members.length - a.members.length || (a.members[0] ?? "").localeCompare(b.members[0] ?? ""));
}
src/core/ui-message.ts
-5
View File
@@ -1,7 +1,6 @@
import type { UIMessage } from "ai";
import type {
DemoToolInput,
GraphContextData,
PdfToolInput,
PlanVerdictData,
PlanBlockData,
@@ -68,10 +67,6 @@ export type TeacherUIDataParts = {
/** The probe→teach handoff wake: the wake pipeline's steer message,
* carrying ONLY this part (the model-facing text lives in the adapter). */
"probe-handoff": { chatId: string };
/** The prior-knowledge injection's delivery (vision-context-injection.md):
* the marker-only steer — the counts for the UI, the full block content
* for the audit trail; the adapter flattens it to graphContextText. */
"graph-context": GraphContextData;
/** The abort steer's message-type marker (the abort badge renders off it). */
"subagent-aborted": SubagentResultMeta & { aborted: true };
};
src/server/chat-handler.ts
+5
View File
@@ -12,6 +12,7 @@ import { effectiveSettings, stores } from "./stores.ts";
import { searchAvailable, searchProvider } from "./search.ts";
import {
extractionEnabled,
graphToolsEnabled,
resolveConversationSpec,
resolveRoleSpec,
} from "../core/settings-resolution.ts";
@@ -274,6 +275,10 @@ export async function handleChatRequest(
jobStore: stores.jobStore,
spawn: (job, input) => void jobRunner.runJob(job.id, input),
searchAvailable,
// The map reader (wave 7): the prober reads the learner's
// knowledge graph through tools when the gate opens —
// graph master switch AND the agent.graphTools toggle.
...(graphToolsEnabled(effective) ? { graphStore: stores.graphStore } : {}),
},
agentOpts,
);
src/server/jobs.ts
+6 -55
View File
@@ -34,7 +34,6 @@
import type { UIMessage } from "ai";
import {
buildAbortSteer,
buildGraphContextSteer,
buildSubagentSteer,
isSubagentFailure,
steerDelivered,
@@ -61,9 +60,6 @@ interface QueuedSteer {
interface WakeState {
turnRunner?: TurnRunner;
respawn?: JobRespawn;
/** Crash recovery for context-injection jobs (they are not sub-agent
* loops — their runner takes the graph deps; chat-handler wires it). */
contextRespawn?: (jobId: string) => void;
/** chatId → steers awaiting delivery, in arrival order. */
queues: Map<string, QueuedSteer[]>;
/** Chats whose pump loop is currently active (serialization per chat). */
@@ -91,13 +87,6 @@ export function setJobRespawn(respawn: JobRespawn): void {
state().respawn = respawn;
}
/** chat-handler wires this at module init: the graph-context runner
* (subagents/graph-context.ts runGraphContextJob — re-runnable from the
* job record alone, which is all crash recovery has). */
export function setContextRespawn(respawn: (jobId: string) => void): void {
state().contextRespawn = respawn;
}
const POLL_MS = 400;
/** After the gates open, wait a beat before firing — a client that just
* answered a question is about to send its continuation; don't 409 it.
@@ -124,11 +113,7 @@ function delay(ms: number): Promise<void> {
/** The job a steer belongs to, if it is a job steer (result/abort/context);
* probe-handoff steers have no job — null. */
function jobIdOf(steer: SteerMessage): string | null {
const meta = steer.metadata as {
subagentResult?: { jobId: string };
graphContext?: { jobId: string };
};
return meta.subagentResult?.jobId ?? meta.graphContext?.jobId ?? null;
return (steer.metadata as { subagentResult?: { jobId: string } }).subagentResult?.jobId ?? null;
}
/** Finalize a delivered steer's job bookkeeping — job steers only. */
@@ -250,12 +235,6 @@ export function abortJob(jobId: string): AbortOutcome {
if (!job) return { ok: false, reason: "not_found" };
if (job.status !== "running") return { ok: false, reason: "not_running" };
// Context-injection jobs abort SILENTLY: nothing was ever promised in the
// lesson (server-initiated scaffolding, unlike a teacher-dispatched
// sub-agent), so no abort steer — flipping the record and killing the
// run is the whole story. Steps 1–3 below are shared; step 4 is skipped.
const isContext = job.kind === "graph-context";
fireJobAbort(jobId); // no-op when the loop already returned (delivering)
// Drop any queued steers for this job (their deliver() resolves unfired).
@@ -270,22 +249,17 @@ export function abortJob(jobId: string): AbortOutcome {
}
stores.jobStore.updateJob(jobId, { status: "error", error: "Aborted by learner", activity: "aborted" });
if (!isContext) {
void deliverJobResult(buildAbortSteer(job)).catch(() => {
/* deliverJobResult marks the job error on unrecoverable failure */
});
}
void deliverJobResult(buildAbortSteer(job)).catch(() => {
/* deliverJobResult marks the job error on unrecoverable failure */
});
return { ok: true };
}
function chatIdOf(steer: SteerMessage): string {
// The probe handoff and the context injection carry their chat directly
// (the context steer's job record would say it too, but the metadata is
// the cheap path — same rule as the handoff).
// The probe handoff carries its chat directly (the job record would
// say it too, but the metadata is the cheap path).
const handoff = (steer.metadata as { probeHandoff?: { chatId: string } }).probeHandoff;
if (handoff) return handoff.chatId;
const injected = (steer.metadata as { graphContext?: { chatId: string } }).graphContext;
if (injected) return injected.chatId;
// The chat is resolvable from the job record; the steer's metadata
// carries jobId, which indexes the store.
const jobId = jobIdOf(steer);
@@ -394,12 +368,6 @@ async function pump(chatId: string): Promise<void> {
function finalizeJob(jobId: string): void {
const job = stores.jobStore.getJob(jobId);
if (!job || job.status !== "running") return;
// Context-injection jobs have no sub-agent result shape — a delivered
// block is a success, full stop (isSubagentFailure would misread it).
if (job.kind === "graph-context") {
stores.jobStore.updateJob(jobId, { status: "done", activity: "delivered" });
return;
}
const result = job.result;
const failed = result ? isSubagentFailure(job.kind, result as never) : true;
stores.jobStore.updateJob(jobId, {
@@ -474,23 +442,6 @@ export function recoverStaleJobs(): void {
if (isJobLive(job.id)) continue; // provably executing here — never re-run beside it
if (!stores.chatStore.getChat(job.chatId)) continue;
if (isTurnRunning(job.chatId)) continue; // a wake turn may be delivering it right now
if (job.kind === "graph-context") {
// Context-injection orphans: a stored block re-delivers in its own
// steer shape; a job that died before selecting re-runs from the
// record (the graph runner — not the sub-agent respawn seam).
if (job.result) {
stores.jobStore.updateJob(job.id, { activity: "recovering: re-delivering" });
void deliverJobResult(
buildGraphContextSteer({ chatId: job.chatId, jobId: job.id }, job.result as never),
).catch(() => {
/* deliverJobResult marks the job error on failure */
});
} else if (s.contextRespawn) {
stores.jobStore.updateJob(job.id, { activity: "recovering: re-running" });
s.contextRespawn(job.id);
}
continue;
}
if (job.result) {
// The wake never fired (or crashed mid-flight): re-deliver.
const steer = buildSubagentSteer(job, job.result as never);
src/server/pi/record-adapter.ts
+1 -9
View File
@@ -1,8 +1,7 @@
import type { UIMessage } from "ai";
import type { AgentMessage } from "@earendil-works/pi-agent-core";
import type { AssistantMessage, Message, ToolResultMessage } from "@earendil-works/pi-ai";
import { graphContextOfMessage } from "../../core/graph-context.ts";
import { graphContextText, HANDOFF_TEXT, verdictText } from "../../core/contracts/chat.ts";
import { HANDOFF_TEXT, verdictText } from "../../core/contracts/chat.ts";
/**
* The record → pi-ai transcript adapter (docs/pi-engine-swap.md §4). The
@@ -62,13 +61,6 @@ function systemTextOf(message: { parts: ReadonlyArray<{ type: string; data?: unk
return verdictText((part.data as { accepted?: unknown } | undefined)?.accepted === true);
}
if (part.type === "data-probe-handoff") return HANDOFF_TEXT;
// Graph context injection: the block text derives from the part's
// validated data (parse-don't-cast — a malformed part has no model
// face, and the message then never reaches the provider).
if (part.type === "data-graph-context") {
const data = graphContextOfMessage({ parts: message.parts });
return data ? graphContextText(data) : null;
}
}
return null;
}
src/server/settings-body.ts
+5 -19
View File
@@ -12,7 +12,7 @@
*/
import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
import { GRAPH_CONTEXT_TOKENS_MAX, isHexColor, type ChatSettings } from "../core";
import { isHexColor, type ChatSettings } from "../core";
import type {
AgentSettings,
AppearanceSettings,
@@ -37,7 +37,6 @@ export function parseSettingsBody(body: unknown): SettingsBodyResult<ChatSetting
const raw = body as {
model?: { provider?: unknown; id?: unknown };
thinkingLevel?: unknown;
graphContextTokens?: unknown;
};
const settings: ChatSettings = {};
if (raw.model !== undefined) {
@@ -57,23 +56,10 @@ export function parseSettingsBody(body: unknown): SettingsBodyResult<ChatSetting
}
settings.thinkingLevel = raw.thinkingLevel as ThinkingLevel;
}
// Graph context injection budget (vision-context-injection.md): integer
// tokens, 0 (off) to GRAPH_CONTEXT_TOKENS_MAX, no silent clamping — the
// slider is the only writer, and it only ever sends multiples of the step.
if (raw.graphContextTokens !== undefined) {
if (
typeof raw.graphContextTokens !== "number" ||
!Number.isInteger(raw.graphContextTokens) ||
raw.graphContextTokens < 0 ||
raw.graphContextTokens > GRAPH_CONTEXT_TOKENS_MAX
) {
return {
ok: false,
error: `graphContextTokens must be an integer between 0 and ${GRAPH_CONTEXT_TOKENS_MAX}`,
};
}
settings.graphContextTokens = raw.graphContextTokens;
}
// Wave 7 killed the graph-context injection (owner: zero configuration
// beyond chat models — the prober reads its map through tools now); its
// budget dial is gone with it. A stale client sending the old key has
// it silently dropped here (forward-compatible, like any unknown key).
return { ok: true, settings };
}