diff --git a/docs/features/hosted-worker.md b/docs/features/hosted-worker.md index d7ba536..d43d2df 100644 --- a/docs/features/hosted-worker.md +++ b/docs/features/hosted-worker.md @@ -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" @@ -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. diff --git a/worker/src/mcp.ts b/worker/src/mcp.ts index bb4320a..853ec81 100644 --- a/worker/src/mcp.ts +++ b/worker/src/mcp.ts @@ -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"; @@ -181,6 +181,16 @@ async function markDisputed(store: D1Store, claims: Claim[]): Promise { 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 { const d = (await store.disputes([c.id])).get(c.id); return JSON.stringify(claimDict(c, d), null, 2); @@ -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; @@ -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); @@ -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. @@ -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); diff --git a/worker/src/memory.ts b/worker/src/memory.ts index 999941a..3fd631d 100644 --- a/worker/src/memory.ts +++ b/worker/src/memory.ts @@ -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 { + const fit = new Map(); + 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 = { pitfall: 0, decision: 1, procedure: 2 }; diff --git a/worker/test/briefing-budget.test.ts b/worker/test/briefing-budget.test.ts new file mode 100644 index 0000000..c5a1296 --- /dev/null +++ b/worker/test/briefing-budget.test.ts @@ -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) => { + 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, 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$/); +});