feat: graph context injection — the session's prior knowledge, steered in at session start (vision-context-injection.md)
One shot per chat, fired at the first turn's onFinish: the session's topic (its only typed message) is embedded as an EmbeddingGemma retrieval query; the semantically closest graph propositions are selected under the session's token budget (pure budget, no similarity threshold — the decided doctrine) and delivered as a marker-only steer through the wake pipeline, queuing behind pending questions like every sub-agent result. - contracts: ChatSettings.graphContextTokens (default 1024, max 4096, step 128, 0 = off); GraphContextData + graphContextText; the graph-context JobKind + buildGraphContextSteer (id steer_ctx_<chatId>) - core/graph-context.ts: brute-force cosine top-K, greedy chars/4 fill under budget, most-recent UnderstandingLevel fold, count cap 64, parse-don't-cast at the marker seam - server: embedQuery (role-asymmetric query format, same warm singleton — vector-space parity by construction); the runner (startGraphContext- Injection one-shot gates; runGraphContextJob validates ledger parity); wake branches (chatIdOf/jobIdOf, finalizeJob done, recoverStaleJobs re-deliver or contextRespawn); abortJob kills context jobs SILENTLY (nothing was promised in the lesson); turn-service trigger seam - adapter: data-graph-context flattens to the canonical block (malformed parts have no model face) - UI: the budget slider (home dock + /chat/new draft, the session-data strip); the quiet SystemLine "~537 · 10 propositions"; dock kind "Knowledge context"; model-picker PUT now spreads settings (a model pick can no longer clear the sibling override) Live-smoked end to end on the real embedder + real GLM: seeded ledger (10 propositions), session on "modal logic: possible worlds and the necessity box" — job in the dock, queued behind the prober's question, delivered on the answer, SystemLine in the transcript, wake turn reads the block and continues the probe. Gates: tsc, lint, 459/459, build.
This commit is contained in:
amosblomqvist
@@ -0,0 +1,291 @@
|
||||
/**
|
||||
* Graph context injection — the pure core (docs/vision-context-injection.md):
|
||||
* selection doctrine, level fold, block text, the marker-part parser, and
|
||||
* the runner's pure gates (topic/budget/one-shot). Deterministic, zero
|
||||
* network, zero stores — hand-made vectors.
|
||||
*/
|
||||
|
||||
import assert from "node:assert/strict";
|
||||
import { describe, it } from "node:test";
|
||||
import type { UIMessage } from "ai";
|
||||
import {
|
||||
buildGraphContextSteer,
|
||||
steerDelivered,
|
||||
GRAPH_CONTEXT_TOKENS_DEFAULT,
|
||||
GRAPH_CONTEXT_TOKENS_MAX,
|
||||
GRAPH_CONTEXT_TOKENS_STEP,
|
||||
graphContextText,
|
||||
type GraphContextData,
|
||||
} from "../src/core/contracts.ts";
|
||||
import {
|
||||
currentUnderstanding,
|
||||
GRAPH_CONTEXT_MAX_PROPOSITIONS,
|
||||
graphContextOfMessage,
|
||||
hasContext,
|
||||
isUnderstandingLevel,
|
||||
selectGraphContext,
|
||||
} from "../src/core/graph-context.ts";
|
||||
import {
|
||||
contextToolCallId,
|
||||
effectiveContextBudget,
|
||||
topicOf,
|
||||
} from "../src/agent/subagents/graph-context.ts";
|
||||
import type { GraphNode, LedgerEvent } from "../src/core/contracts/graph.ts";
|
||||
|
||||
function unit(i: number): number[] {
|
||||
const v = new Array(8).fill(0);
|
||||
v[i] = 1;
|
||||
return v;
|
||||
}
|
||||
|
||||
function node(id: string, statement: string): GraphNode {
|
||||
return {
|
||||
id,
|
||||
name: id,
|
||||
statement,
|
||||
aliases: [],
|
||||
provenance: [],
|
||||
createdAt: "2026-09-14T00:00:00.000Z",
|
||||
};
|
||||
}
|
||||
|
||||
function obs(nodeId: string, level: string, at: string, chatId = "chat_x"): LedgerEvent {
|
||||
return { nodeId, kind: "observation", chatId, at, note: level };
|
||||
}
|
||||
|
||||
/** A text-bearing user message (the learner's typed speech). */
|
||||
function userText(text: string): UIMessage {
|
||||
return { id: `m_${text.length}`, role: "user", parts: [{ type: "text", text }] };
|
||||
}
|
||||
|
||||
/** A marker-only user message (steer scaffolding — no text). */
|
||||
function marker(type: string, data: unknown): UIMessage {
|
||||
return { id: `m_${type}`, role: "user", parts: [{ type, data } as never] };
|
||||
}
|
||||
|
||||
describe("currentUnderstanding — the most-recent fold", () => {
|
||||
it("latest observation wins, across chats, ledger order breaks ties", () => {
|
||||
const events = [
|
||||
obs("n1", "shaky", "2026-09-01T00:00:00Z", "chat_a"),
|
||||
obs("n1", "solid", "2026-09-10T00:00:00Z", "chat_b"),
|
||||
obs("n2", "resisted", "2026-09-05T00:00:00Z"),
|
||||
obs("n2", "accepted", "2026-09-05T00:00:00Z"), // same at → later line wins
|
||||
];
|
||||
const levels = currentUnderstanding(events);
|
||||
assert.equal(levels.get("n1"), "solid");
|
||||
assert.equal(levels.get("n2"), "accepted");
|
||||
assert.equal(levels.size, 2);
|
||||
});
|
||||
|
||||
it("off-scale notes never count (the closed list is the only vocabulary)", () => {
|
||||
assert.equal(isUnderstandingLevel("solid"), true);
|
||||
assert.equal(isUnderstandingLevel("pretty good"), false);
|
||||
const levels = currentUnderstanding([obs("n1", "confident", "2026-09-01T00:00:00Z")]);
|
||||
assert.equal(levels.size, 0);
|
||||
});
|
||||
|
||||
it("quiz outcome events and null nodes are not observations", () => {
|
||||
const events: LedgerEvent[] = [
|
||||
{ nodeId: "n1", kind: "correct", chatId: "c", at: "2026-09-01T00:00:00Z" },
|
||||
{ nodeId: null, kind: "observation", chatId: "c", at: "2026-09-01T00:00:00Z", note: "solid" },
|
||||
];
|
||||
assert.equal(currentUnderstanding(events).size, 0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("selectGraphContext — similarity orders, the budget is the only amount control", () => {
|
||||
const base = {
|
||||
chatId: "chat_1",
|
||||
query: unit(0),
|
||||
events: [] as LedgerEvent[],
|
||||
};
|
||||
|
||||
it("fills similarity-descending and stops before exceeding the budget", () => {
|
||||
const vectors = { a: unit(0), b: unit(0), c: unit(7) };
|
||||
const nodes = [
|
||||
node("a", "Water boils at 100°C at sea level."),
|
||||
node("b", "Evaporation cools the surrounding air."),
|
||||
node("c", "The Schrödinger equation is linear."),
|
||||
];
|
||||
// budget 55 (framing) + ~9 tokens for statement a ≈ fits exactly one line.
|
||||
const data = selectGraphContext({ ...base, vectors, nodes, budget: 66 });
|
||||
assert.deepEqual(
|
||||
data.propositions.map((p) => p.id),
|
||||
["a"],
|
||||
);
|
||||
assert.equal(data.tokens <= 66, true);
|
||||
assert.equal(data.budget, 66);
|
||||
});
|
||||
|
||||
it("an oversized line is skipped, a later smaller one may still fit (no threshold, pure budget)", () => {
|
||||
const vectors = { big: unit(0), small: unit(0), off: unit(7) };
|
||||
const big = "X".repeat(400); // ~100 tokens — bigger than the whole budget
|
||||
const nodes = [
|
||||
node("big", big),
|
||||
node("small", "Ice melts."),
|
||||
node("off", "Irrelevant."),
|
||||
];
|
||||
// budget 60: 'big' (~100 tokens) is skipped outright; 'small' (4 tokens
|
||||
// incl. the level slot + framing 55 = 59) fits; 'off' (63) doesn't.
|
||||
const data = selectGraphContext({ ...base, vectors, nodes, budget: 60 });
|
||||
assert.deepEqual(
|
||||
data.propositions.map((p) => p.id),
|
||||
["small"],
|
||||
);
|
||||
});
|
||||
|
||||
it("annotates each line with the folded current level (null when unobserved)", () => {
|
||||
const vectors = { a: unit(0), b: unit(0) };
|
||||
const nodes = [node("a", "A."), node("b", "B.")];
|
||||
const events = [obs("b", "shaky", "2026-09-10T00:00:00Z")];
|
||||
const data = selectGraphContext({ ...base, vectors, nodes, events, budget: 4096 });
|
||||
const byId = Object.fromEntries(data.propositions.map((p) => [p.id, p]));
|
||||
assert.equal(byId.a!.level, null);
|
||||
assert.equal(byId.b!.level, "shaky");
|
||||
});
|
||||
|
||||
it("the count cap bounds even a huge budget", () => {
|
||||
const vectors: Record<string, number[]> = {};
|
||||
const nodes: GraphNode[] = [];
|
||||
for (let i = 0; i < GRAPH_CONTEXT_MAX_PROPOSITIONS + 10; i++) {
|
||||
const id = `n${i}`;
|
||||
vectors[id] = unit(0);
|
||||
nodes.push(node(id, `Statement ${i}.`));
|
||||
}
|
||||
const data = selectGraphContext({ ...base, vectors, nodes, budget: GRAPH_CONTEXT_TOKENS_MAX });
|
||||
assert.equal(data.propositions.length, GRAPH_CONTEXT_MAX_PROPOSITIONS);
|
||||
});
|
||||
|
||||
it("dimension-mismatched vectors and duplicate node lines are handled", () => {
|
||||
const vectors = { ok: unit(0), stale: [1, 2, 3] };
|
||||
const nodes = [
|
||||
node("ok", "Fine."),
|
||||
node("dup", "First line."),
|
||||
node("dup", "Second line never redefines."),
|
||||
];
|
||||
// "dup" has no vector anyway; the pin is that the scan neither throws
|
||||
// nor scores the stale-dim vector.
|
||||
const data = selectGraphContext({ ...base, vectors, nodes, budget: 4096 });
|
||||
assert.deepEqual(
|
||||
data.propositions.map((p) => p.id),
|
||||
["ok"],
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("graphContextText + hasContext — the canonical block", () => {
|
||||
it("carries the counts in the header, the level tag per line, the gloss at the end", () => {
|
||||
const data: GraphContextData = {
|
||||
chatId: "c1",
|
||||
budget: 1024,
|
||||
tokens: 42,
|
||||
propositions: [
|
||||
{ id: "n1", statement: "Water boils at 100°C.", level: "solid" },
|
||||
{ id: "n2", statement: "Humidity slows evaporation.", level: null },
|
||||
],
|
||||
};
|
||||
const text = graphContextText(data);
|
||||
assert.match(text, /2 propositions, ~42 tokens/);
|
||||
assert.match(text, /- \[solid\] Water boils at 100°C\./);
|
||||
assert.match(text, /- Humidity slows evaporation\./);
|
||||
assert.match(text, /Do not re-teach solid ground\./);
|
||||
});
|
||||
|
||||
it("an empty selection has no text and no context", () => {
|
||||
const empty: GraphContextData = { chatId: "c1", budget: 1024, tokens: 55, propositions: [] };
|
||||
assert.equal(graphContextText(empty), "");
|
||||
assert.equal(hasContext(empty), false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("graphContextOfMessage — parse-don't-cast at the marker seam", () => {
|
||||
it("round-trips a well-formed part", () => {
|
||||
const msg = marker("data-graph-context", {
|
||||
chatId: "c1",
|
||||
budget: 512,
|
||||
tokens: 60,
|
||||
propositions: [{ id: "n1", statement: "S.", level: "shaky" }],
|
||||
});
|
||||
const data = graphContextOfMessage(msg);
|
||||
assert.equal(data?.chatId, "c1");
|
||||
assert.equal(data?.propositions[0]?.level, "shaky");
|
||||
});
|
||||
|
||||
it("rejects malformed shapes wholesale (bad level, bad budget, non-array)", () => {
|
||||
assert.equal(graphContextOfMessage(marker("data-graph-context", { chatId: "c" })), null);
|
||||
assert.equal(
|
||||
graphContextOfMessage(
|
||||
marker("data-graph-context", {
|
||||
chatId: "c",
|
||||
budget: 512,
|
||||
tokens: 1,
|
||||
propositions: [{ id: "n", statement: "s", level: "kinda" }],
|
||||
}),
|
||||
),
|
||||
null,
|
||||
);
|
||||
assert.equal(
|
||||
graphContextOfMessage(
|
||||
marker("data-graph-context", { chatId: "c", budget: 999999, tokens: 1, propositions: [] }),
|
||||
),
|
||||
null,
|
||||
);
|
||||
});
|
||||
|
||||
it("absent part → null", () => {
|
||||
assert.equal(graphContextOfMessage(userText("hello")), null);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildGraphContextSteer — the marker-only delivery", () => {
|
||||
it("id is deterministic per chat; metadata carries chat + job; one part", () => {
|
||||
const data: GraphContextData = {
|
||||
chatId: "chat_9",
|
||||
budget: 1024,
|
||||
tokens: 10,
|
||||
propositions: [{ id: "n1", statement: "S.", level: null }],
|
||||
};
|
||||
const steer = buildGraphContextSteer({ chatId: "chat_9", jobId: "job_1" }, data);
|
||||
assert.equal(steer.id, "steer_ctx_chat_9");
|
||||
assert.equal(steer.role, "user");
|
||||
assert.deepEqual(steer.metadata, { graphContext: { chatId: "chat_9", jobId: "job_1" } });
|
||||
assert.equal(steer.parts.length, 1);
|
||||
assert.equal(steer.parts[0]!.type, "data-graph-context");
|
||||
// steerDelivered keys on the id — the one-shot guard.
|
||||
assert.equal(steerDelivered([steer], "steer_ctx_chat_9"), true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("the runner's pure gates", () => {
|
||||
it("topicOf: exactly one typed message is the topic; steers and answers never count", () => {
|
||||
assert.equal(topicOf([userText("the water cycle")]), "the water cycle");
|
||||
assert.equal(topicOf([]), null);
|
||||
assert.equal(topicOf([userText("a"), userText("b")]), null);
|
||||
// A quiz answer: tool-output part, no text — probing never breaks the gate.
|
||||
const answer: UIMessage = {
|
||||
id: "m_ans",
|
||||
role: "user",
|
||||
parts: [{ type: "tool-quiz", toolCallId: "t1", state: "output-available", input: {}, output: {} } as never],
|
||||
};
|
||||
assert.equal(topicOf([userText("topic"), answer, marker("data-probe-handoff", { chatId: "c" })]), "topic");
|
||||
// Multi-part text joins into the topic.
|
||||
assert.equal(topicOf([userText("a"), userText("")]), "a");
|
||||
});
|
||||
|
||||
it("effectiveContextBudget: absent = the default (on), 0 = off, set = set", () => {
|
||||
assert.equal(effectiveContextBudget(undefined), GRAPH_CONTEXT_TOKENS_DEFAULT);
|
||||
assert.equal(effectiveContextBudget({}), GRAPH_CONTEXT_TOKENS_DEFAULT);
|
||||
assert.equal(effectiveContextBudget({ graphContextTokens: 0 }), 0);
|
||||
assert.equal(effectiveContextBudget({ graphContextTokens: 2048 }), 2048);
|
||||
});
|
||||
|
||||
it("the decided knobs: default 1024, max 4096, step 128", () => {
|
||||
assert.equal(GRAPH_CONTEXT_TOKENS_DEFAULT, 1024);
|
||||
assert.equal(GRAPH_CONTEXT_TOKENS_MAX, 4096);
|
||||
assert.equal(GRAPH_CONTEXT_TOKENS_STEP, 128);
|
||||
});
|
||||
|
||||
it("contextToolCallId is deterministic per chat (the one-shot dedup key)", () => {
|
||||
assert.equal(contextToolCallId("chat_abc"), "ctx_chat_abc");
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user