Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/features/hosted-worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ tests:
- "worker/test/readonly.test.ts"
- "worker/test/feedback.test.ts"
- "worker/test/confirm.test.ts"
- "worker/test/briefing-budget.test.ts"
- "worker/test/dispute.test.ts"
- "worker/test/evidence.test.ts"
- "tests/test_usefulness.py"
Expand Down Expand Up @@ -228,6 +229,11 @@ TypeSafe API's shape, for GitHub Actions OIDC tokens (`worker/src/oidc.ts`) and
builds its own column list has to add it too. Agents read it, so the write gate and `judgeLate` judge
`gatedText(content, evidence)`, never the content alone. Purge resets `metadata`, which erases it.
Local claims have no evidence yet.
- Every briefing section's claim lines share `BRIEFING_CHARS` in render order (`fitBriefing`): full
lines while it lasts, then subject-only lines, then a count of what was left out. Only kept claims are
passed to `recordUsage`, so a slot's used rate is over what the reply showed. A new briefing section
goes through `fitted` with the others, or it escapes the budget. Unconfirmed user-scope lines
(`RECENT_USER`) are capped at 3 because they reach every repo's briefing.
- `initialize` instructions are built from `STEPS` in `mcp.ts`, keeping only the steps whose tool the
caller can see (`visibleTools`), so a read-only or `KYPP_CORRECT=off` caller is never told to call
a tool it lacks.
33 changes: 22 additions & 11 deletions worker/src/mcp.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// mcp.ts — kypp's agent tools as a stateless streamable-HTTP MCP endpoint (JSON responses, no SSE,
// no Durable Object). The same contract as kypp/mcp_server.py's briefing / recall / claim / expand /
// correct; consolidation is the scheduled pass in index.ts, not an agent tool.
import { type Claim, DEFAULT_POLICY, HUMAN_CORRECTION_CONFIDENCE, type Policy, TYPES, briefingOrder, gatedText, renderBriefing, renderClaims, resolveOrigin } from "./memory.ts";
import { type Claim, DEFAULT_POLICY, HUMAN_CORRECTION_CONFIDENCE, type Policy, TYPES, briefingOrder, compactLine, fitBriefing, gatedText, shortLine, renderBriefing, renderClaims, resolveOrigin } from "./memory.ts";
import { consolidate } from "./consolidate.ts";
import { fileClaim } from "./defrag.ts";
import { CONTROL_ABOVE, DROP_BELOW, type ProjectInfo, RERANK_POOL, type S1Client, judge, rankForQuery } from "./s1.ts";
Expand Down Expand Up @@ -181,6 +181,16 @@ async function markDisputed(store: D1Store, claims: Claim[]): Promise<void> {
for (const c of claims) if (d.has(c.id)) c.disputed = true;
}

// A briefing's sections, in render order, cut to the briefing budget; `more` says how many were left out.
function fitted(sections: Claim[][]) {
const fit = fitBriefing(sections.flat());
const keep = sections.map((cs) => cs.filter((c) => fit.has(c.id)));
const line = (c: Claim) => (fit.get(c.id) === "short" ? shortLine(c) : compactLine(c));
const left = sections.flat().length - keep.flat().length;
const more = left ? `\n(${left} more left out to keep the briefing short; \`recall\` finds them)` : "";
return { keep, line, more };
}

async function expanded(store: D1Store, c: Claim): Promise<string> {
const d = (await store.disputes([c.id])).get(c.id);
return JSON.stringify(claimDict(c, d), null, 2);
Expand Down Expand Up @@ -233,7 +243,7 @@ export async function verifySession(key: string | undefined, header: string | nu

const RECENT = 3; // other agents' unconfirmed claims shown at the end of a briefing
const ORG_RULES = 8; // accepted claims at the caller's org, listed first in a briefing
const RECENT_USER = 5; // the user's own unconfirmed process and preferences, from their other sessions
const RECENT_USER = 3; // the user's own unconfirmed process and preferences, from their other sessions
const known = (projects: ProjectInfo[]) => projects.map((p) => p.name).join(", ") || "none registered";

const NEAR_SUBJECTS = 3;
Expand Down Expand Up @@ -285,16 +295,16 @@ async function roomTool(store: D1Store, name: string, a: Args, ctx: ToolCtx, key
const limit = Math.min(a.limit ?? 12, 30);
// Why a read of its own, as in a repo briefing: recall ranks the org last, so a busy room's
// capped list would crowd its rules out.
const [settled, { orgs, org }, yours] = await Promise.all([
const [settled, { orgs, org: allOrg }, allYours] = await Promise.all([
store.recall("", null, null, { room, candidates: "none", limit: limit * 3, undisputed: true }),
orgRules(store, groups),
store.recentUserCandidates(identity, ctx.session, RECENT_USER, "room"),
]);
const isOrg = (c: Claim) => c.scope === "group" && orgs.has(c.project ?? "");
const claims = briefingOrder(settled.filter((c) => !isOrg(c)), limit);
const { keep: [org, claims, yours], line, more } = fitted([allOrg, briefingOrder(settled.filter((c) => !isOrg(c)), limit), allYours]);
await store.recordUsage(ctx.session, [["org", org], ["settled", claims], ["yours", yours]], "briefing", null);
return (org.length ? `# how this org works\n${renderClaims(org)}\n` : "") + (claims.length || !org.length ? renderBriefing(claims) : "")
+ (yours.length ? `\n# unconfirmed in this room\n${renderClaims(yours)}` : "");
return (org.length ? `# how this org works\n${renderClaims(org, undefined, line)}\n` : "") + (claims.length || !org.length ? renderBriefing(claims, line) : "")
+ (yours.length ? `\n# unconfirmed in this room\n${renderClaims(yours, undefined, line)}` : "") + more;
}
case "recall": {
const query = String(a.query ?? ""), limit = recallLimit(a.limit);
Expand Down Expand Up @@ -439,7 +449,7 @@ async function repoTool(store: D1Store, name: string, a: Args, ctx: ToolCtx,
case "briefing": {
const limit = Math.min(a.limit ?? 12, 30);
// An org's rules apply to every contributor, so they come first under their own heading.
const [settled, { orgs, org }, recent, yours] = await Promise.all([
const [settled, { orgs, org: allOrg }, allRecent, allYours] = await Promise.all([
store.recall("", project, user, { candidates: "none", groups, limit: limit * 3, undisputed: true }),
orgRules(store, groups),
// Why: the briefing stays settled memory; others' unconfirmed claims get a short, labelled section.
Expand All @@ -448,12 +458,13 @@ async function repoTool(store: D1Store, name: string, a: Args, ctx: ToolCtx,
user ? store.recentUserCandidates(user, ctx.session, RECENT_USER) : [],
]);
const isOrg = (c: Claim) => c.scope === "group" && orgs.has(c.project ?? "");
const claims = briefingOrder(settled.filter((c) => !isOrg(c)), limit);
// In the order the reply renders them: yours comes before recent.
const { keep: [org, claims, yours, recent], line, more } = fitted([allOrg,
briefingOrder(settled.filter((c) => !isOrg(c)), limit), allYours, allRecent]);
await store.recordUsage(ctx.session, [["org", org], ["settled", claims], ["yours", yours], ["recent", recent]], "briefing", project);
return note + (org.length ? `# how this org works\n${renderClaims(org)}\n` : "") + (claims.length || !org.length ? renderBriefing(claims) : "")
+ (yours.length ? `\n# how you work, from your other sessions (unconfirmed)\n${renderClaims(yours)}` : "")
+ (recent.length ? `\n# recent from other agents (unconfirmed)\n${renderClaims(recent)}` : "");
return note + (org.length ? `# how this org works\n${renderClaims(org, undefined, line)}\n` : "") + (claims.length || !org.length ? renderBriefing(claims, line) : "")
+ (yours.length ? `\n# how you work, from your other sessions (unconfirmed)\n${renderClaims(yours, undefined, line)}` : "")
+ (recent.length ? `\n# recent from other agents (unconfirmed)\n${renderClaims(recent, undefined, line)}` : "") + more;
}
case "recall": {
const query = String(a.query ?? ""), limit = recallLimit(a.limit);
Expand Down
27 changes: 23 additions & 4 deletions worker/src/memory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -226,22 +226,41 @@ export function compactLine(c: Claim): string {
return line;
}

export function renderClaims(claims: Claim[], empty = "(no matching memory)"): string {
return claims.map(compactLine).join("\n") || empty;
export function renderClaims(claims: Claim[], empty = "(no matching memory)", line: (c: Claim) => string = compactLine): string {
return claims.map(line).join("\n") || empty;
}

// The briefing, one heading per type in briefingOrder's order.
export function renderBriefing(claims: Claim[]): string {
export function renderBriefing(claims: Claim[], line: (c: Claim) => string = compactLine): string {
if (!claims.length) return "(no accepted memory yet)";
const out: string[] = [];
for (const c of claims) {
const head = `# ${c.type}`;
if (!out.includes(head)) out.push(head);
out.push(compactLine(c));
out.push(line(c));
}
return out.join("\n");
}

// The briefing loads into every session, so its claim lines share one budget: a longer briefing is
// followed less, and a wrong line in it misleads every session.
export const BRIEFING_CHARS = 4000;
export const shortLine = (c: Claim) =>
`${c.id.slice(0, 8)} [${c.type} ${c.status === "accepted" ? "✓" : "?"}${c.confidence.toFixed(1)} @${level(c)}] ${c.subject} (expand for the lesson)`;

// Lines in render order: full while the budget lasts, then subject-only, then left out. Returns how each
// kept claim renders; a claim not in the map was left out.
export function fitBriefing(claims: Claim[], budget = BRIEFING_CHARS): Map<string, "full" | "short"> {
const fit = new Map<string, "full" | "short">();
let left = budget;
for (const c of claims) {
const full = compactLine(c).length + 1, short = shortLine(c).length + 1;
if (full <= left) { fit.set(c.id, "full"); left -= full; }
else if (short <= left) { fit.set(c.id, "short"); left -= short; }
}
return fit;
}

// view.briefing_claims ordering: traps first, then choices made, then how-tos. Stable sort keeps
// the store's strength order within a type.
const BRIEFING_PRIORITY: Record<string, number> = { pitfall: 0, decision: 1, procedure: 2 };
Expand Down
52 changes: 52 additions & 0 deletions worker/test/briefing-budget.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
// The briefing's claim lines share one budget: full lines while it lasts, then subject-only lines,
// then a count of what was left out. Only what the reply shows is recorded as shown.
import assert from "node:assert/strict";
import { test } from "node:test";
import { type Caller, handleMcp } from "../src/mcp.ts";
import { BRIEFING_CHARS, type Claim, compactLine, fitBriefing, shortLine } from "../src/memory.ts";
import { memoryD1 } from "./d1.ts";

const OWNER: Caller = { user: "owner", agent: "claude" };

const claim = (id: string, content: string): Claim => ({
id, type: "pitfall", subject: `subject ${id}`, content, scope: "project", project: "kypp", agent: null, user: null,
status: "accepted", authority: "human", confidence: 1, source_ids: [], code_refs: [], created_at: "", updated_at: "",
});

test("fitBriefing keeps full lines, then short ones, then leaves the rest out", () => {
const cs = ["a", "b", "c", "d"].map((id) => claim(id.repeat(8), "x".repeat(200)));
const [full, short] = [compactLine(cs[0]).length + 1, shortLine(cs[0]).length + 1];
const fit = fitBriefing(cs, 2 * full + short + short - 1);
assert.deepEqual([...fit.values()], ["full", "full", "short"]);
assert.equal(fit.has("dddddddd"), false);
});

test("a briefing over budget shortens and then drops its last lines, and records only what it shows", async () => {
const db = memoryD1();
await db.prepare("INSERT INTO projects(name, description, created_at) VALUES('kypp', '', '2026-11-06T00:00:00Z')").run();
const call = async (session: string, name: string, args: Record<string, unknown>) => {
const req = new Request("https://k/mcp", { method: "POST", headers: { "X-Kypp-Project": "kypp", "Mcp-Session-Id": session },
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }) });
return ((await (await handleMcp(req, db, OWNER, { s1: null })).json()) as any).result.content[0].text as string;
};
for (let i = 0; i < 30; i++) await call("w", "correct", { subject: `trap ${i}`, content: `${i} `.repeat(110), type: "pitfall" });

const out = await call("r", "briefing", { limit: 30 });
const lines = out.split("\n").filter((l) => /^[0-9a-f]{8} \[/.test(l));
assert.ok(lines.reduce((n, l) => n + l.length + 1, 0) <= BRIEFING_CHARS);
assert.match(out, /\(expand for the lesson\)/);
const left = Number(/\n\((\d+) more left out to keep the briefing short; `recall` finds them\)$/.exec(out)?.[1]);
assert.equal(lines.length + left, 30);
const shown = await db.prepare("SELECT COUNT(*) AS n FROM claim_usages WHERE consumer = 'r' AND surface = 'briefing'").first<{ n: number }>();
assert.equal(shown!.n, lines.length);
});

test("a briefing under budget is unchanged", async () => {
const db = memoryD1();
await db.prepare("INSERT INTO projects(name, description, created_at) VALUES('kypp', '', '2026-11-06T00:00:00Z')").run();
const req = (args: Record<string, unknown>, name: string) => new Request("https://k/mcp", { method: "POST", headers: { "X-Kypp-Project": "kypp", "Mcp-Session-Id": "s" },
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }) });
await handleMcp(req({ subject: "port", content: "wrangler dev listens on 8787", type: "pitfall" }, "correct"), db, OWNER, { s1: null });
const out = ((await (await handleMcp(req({}, "briefing"), db, OWNER, { s1: null })).json()) as any).result.content[0].text as string;
assert.match(out, /^# pitfall\n[0-9a-f]{8} \[pitfall ✓0\.9 @kypp\] port — wrangler dev listens on 8787$/);
});
Loading