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
15 changes: 15 additions & 0 deletions docs/features/hosted-worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ tests:
- "worker/test/keycard.test.ts"
- "worker/test/readonly.test.ts"
- "worker/test/feedback.test.ts"
- "worker/test/confirm.test.ts"
---
# Hosted Worker

Expand Down Expand Up @@ -182,6 +183,20 @@ TypeSafe API's shape, for GitHub Actions OIDC tokens (`worker/src/oidc.ts`) and
and the feedback insert drops the note itself when the claim carries `metadata.purged_at`. One
call keeps only the last rating per claim, so `created_at` orders a session's verdicts.
The local `kypp serve` has no `feedback` yet.
- A `used` rating confirms: consolidate loads each candidate's newest-verdict `used` raters
(`store.confirmations`) and `recurs` counts each as that session's support at the rating's time, so
the recurrence gap still applies. The claim's own writer never confirms it. A session's verdict is
its newest rating, and it confirms only if that rating is `used` and marked `writable`. `feedback`
marks a rating writable only when the current caller could write at the claim's level (`mayWrite`
in `mcp.ts`: not read-only, inside a pin, the caller's own user or room lane, or a repo the room is linked to), because a session id
is not bound to a credential and read visibility alone would let a reader confirm another lane's
claim. Rows from before the mark never confirm, and a later unmarked `wrong` still withdraws. An unstamped survivor (an echo) never supersedes a stamped candidate until the group
promotes, so the claim the echo reply tells the agent to rate stays live. The plan
carries the ratings it counted (`GroupPlan.confirmed`) and `apply` refuses it if any is no longer
that session's newest verdict at the same time (`created_at`, then `rowid`), because a rating never touches the
claim rows the version guard reads. This is the only way a session that was
shown a candidate can help accept it: its re-claim is an echo, and the claim reply says so. The
Python arbiter doesn't count ratings, so local and hosted promote differently here.
- `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.
3 changes: 2 additions & 1 deletion worker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,8 @@ a remote MCP server with OAuth. Local kypp is unchanged; this is the optional ho
- **Categories:** the claim types (pitfall, decision, procedure, preference, fact, artifact,
hypothesis). The briefing is grouped by type.
- **Promotion:** a claim is accepted once it recurs in two sessions at least
`KYPP_RECUR_GAP_MINUTES` (default 60) apart. That measures repetition, not independent evidence:
`KYPP_RECUR_GAP_MINUTES` (default 60) apart. A session that was shown the claim and rated it
`used` with `feedback` counts as one of them; re-claiming what it was shown doesn't. That measures repetition, not independent evidence:
one client can open two sessions, so the gap just makes faking it slow. Session ids are signed,
so a client can't invent one. A newer claim on an accepted subject waits as a pending update and
replaces the old answer once it recurs.
Expand Down
14 changes: 11 additions & 3 deletions worker/src/consolidate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,15 @@ export async function planWithJudge(live: Claim[], policy: Policy, s1: S1Client
return plans;
}

export async function consolidate(store: D1Store, policy: Policy, s1: S1Client | null,
filter?: Parameters<D1Store["liveClaims"]>[0]) {
return store.apply(await planWithJudge(await store.liveClaims({ ...filter, filed: true }), policy, s1));
type Filter = Parameters<D1Store["liveClaims"]>[0];

// Live filed claims, each candidate carrying the sessions whose current verdict on it is `used`.
export async function plan(store: D1Store, policy: Policy, s1: S1Client | null, filter?: Filter): Promise<GroupPlan[]> {
const live = await store.liveClaims({ ...filter, filed: true });
const confirmed = await store.confirmations(live.filter((c) => c.status === "candidate").map((c) => c.id));
Comment thread
vu1n marked this conversation as resolved.
Resolved
return planWithJudge(live.map((c) => confirmed.has(c.id) ? { ...c, confirmations: confirmed.get(c.id) } : c), policy, s1);
}

export async function consolidate(store: D1Store, policy: Policy, s1: S1Client | null, filter?: Filter) {
return store.apply(await plan(store, policy, s1, filter));
}
35 changes: 27 additions & 8 deletions worker/src/mcp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ const STEPS: { tool?: string; text: string }[] = [
{ text: "BEFORE non-trivial work — `recall(\"<what you're about to touch>\")`; `expand(handle)` for the full claim." },
{ tool: "claim", text: `WHEN YOU LEARN SOMETHING DURABLE — \`claim\` a distilled, model-agnostic lesson. \`subject\` is its
identity: reuse a subject to update it. Claims land as candidates; one is accepted once a second
session claims the same subject. Don't store status ("shipped", "PR merged") — git holds that.
session claims the same subject or rates it \`used\` with \`feedback\`. Don't store status
("shipped", "PR merged") — git holds that.
WHERE IT GOES: you don't choose. Say which repo you are in and the server files and shares the
lesson. Set \`scope: "user"\` only for how this person works, in every repo.
Reads show other agents' unconfirmed (?) claims in this repo: weigh them. Don't re-claim a lesson
Expand All @@ -35,7 +36,7 @@ const STEPS: { tool?: string; text: string }[] = [
{ tool: "feedback", text: `BEFORE YOU FINISH — \`feedback\` on the handles you were shown: \`used\` if it held up in
your work (say what you checked in \`note\`), \`not_used\` if it didn't bear on the task, \`wrong\` if it
misled you (say how in \`note\`, and claim the fix under the same subject). One call with every
handle; the ratings tune what memory shows.` },
handle; the ratings tune what memory shows, and a \`used\` from another session confirms a claim.` },
];
const INTRO = `kypp is shared memory for coding agents — durable lessons governed by status
(candidate → accepted), authority (human > verified > agent) and provenance.`;
Expand Down Expand Up @@ -235,6 +236,11 @@ async function afterClaim(store: D1Store, at: Lane, id: string, subject: string,
+ (near.length ? `\nnearby subjects here: ${near.map((n) => JSON.stringify(n)).join(", ")}. If one is the same lesson, claim it again with the same content under that subject; this claim is then withdrawn.` : "");
}

// Why: an echo used to be stored with no sign it earned nothing, so agents kept re-claiming to agree.
const echoNote = (echoOf: string[]) => echoOf.length
? `\necho: this session was shown another session's unconfirmed claim on this subject, so this one doesn't count toward accepting it. If that claim held up in your work, rate it \`used\` with \`feedback\`; that does count.`
: "";

// What this claim counts as: an echo when the session was shown the subject, or when it renames a
// claim that was itself an echo (a rename must not launder relayed content into recurrence).
// A session shown another session's candidate on this subject doesn't count toward accepting it.
Expand Down Expand Up @@ -300,7 +306,7 @@ async function roomTool(store: D1Store, name: string, a: Args, ctx: ToolCtx, key
confidence: a.confidence ?? 0.7, sourceIds: stamp, codeRefs: [],
accept: false, agent: identity, user: identity, metadata, ...(share !== null ? { sharedFrom: key } : {}),
});
return id + await afterClaim(store, at, id, subject, content, ctx.session, prior);
return id + echoNote(echoOf) + await afterClaim(store, at, id, subject, content, ctx.session, prior);
}
case "expand": {
const c = await store.get(String(a.handle ?? ""), identity, ctx.session, room);
Expand All @@ -315,7 +321,18 @@ async function roomTool(store: D1Store, name: string, a: Args, ctx: ToolCtx, key
const VERDICTS: Record<string, number> = { used: 1, not_used: 0, wrong: -1 };
const MAX_RATINGS = 50, MAX_NOTE = 300;

async function feedback(store: D1Store, a: Args, session: string | null): Promise<string> {
// Whether this caller could have written a claim at `c`'s level: only such a caller's `used` can confirm it.
// Read visibility is not enough, because one session id can be carried across credentials.
// A room writes its own lane, and project claims only in the repos it is linked to (share_to).
function mayWrite(caller: Caller, c: { scope: string; project: string | null; user: string | null }, roomLinks: string[]): boolean {
if (caller.readOnly) return false;
if (caller.room) return c.scope === "room" ? c.user === caller.user : c.scope === "project" && c.project !== null && roomLinks.includes(c.project);
if (c.scope === "user") return c.user !== null && c.user === caller.user;
if (c.scope !== "project") return false;
return !caller.projects || (c.project !== null && caller.projects.includes(c.project));
}

async function feedback(store: D1Store, a: Args, session: string | null, caller: Caller): Promise<string> {
if (!session) throw new Error("feedback needs the session id from initialize: it rates what this session was shown");
const ratings: unknown[] = Array.isArray(a.ratings) ? a.ratings : [];
if (!ratings.length) throw new Error("ratings must list at least one {handle, verdict}");
Expand All @@ -332,9 +349,11 @@ async function feedback(store: D1Store, a: Args, session: string | null): Promis
return shown ? { ...shown, score: VERDICTS[verdict], verdict, note } : `${handle}: not shown to this session`;
}));
// Two ratings of one claim in a call (a prefix and the full id, say): the last one listed wins.
const rated = [...new Map(checked.filter((c) => typeof c !== "string").map((c) => [c.id, c])).values()];
const shown = [...new Map(checked.filter((c) => typeof c !== "string").map((c) => [c.id, c])).values()];
const skipped = checked.filter((c) => typeof c === "string");
await store.recordFeedback(session, rated);
const [lanes, links] = await Promise.all([store.lanes(shown.map((r) => r.id)), caller.room ? store.roomLinks(caller.room) : []]);
const rated = shown.map((r) => ({ ...r, writable: !!lanes.get(r.id) && mayWrite(caller, lanes.get(r.id)!, links) }));
Comment thread
vu1n marked this conversation as resolved.
Resolved
await store.recordFeedback(session, rated, caller.room ?? null);
return `recorded ${rated.length} rating${rated.length === 1 ? "" : "s"}` + (skipped.length ? `\nskipped:\n${skipped.join("\n")}` : "");
}

Expand All @@ -345,7 +364,7 @@ const visibleTools = (ctx: ToolCtx) => ctx.caller.room ? ROOM_TOOLS

export async function callTool(store: D1Store, name: string, a: Args, ctx: ToolCtx): Promise<string> {
// Feedback reaches only claims a read already showed this session, so every lane's visibility rule still holds.
if (name === "feedback") return feedback(store, a, ctx.session);
if (name === "feedback") return feedback(store, a, ctx.session, ctx.caller);
if (ctx.caller.room) return roomTool(store, name, a, ctx, ctx.caller.room);
if (ctx.caller.readOnly && WRITES.has(name)) throw new Error(`this token is read-only: ${name} is not available`);
// The caller says where it is; only a registered project is a place, so an unknown name can't start a separate memory.
Expand Down Expand Up @@ -450,7 +469,7 @@ async function repoTool(store: D1Store, name: string, a: Args, ctx: ToolCtx,
accept: false, agent: ctx.caller.agent, user, metadata,
});
// Why: clients that can't send a header shouldn't wait an hour for defrag to file their claim.
if (at) return id + await afterClaim(store, at, id, subject, content, ctx.session, prior);
if (at) return id + echoNote(echoOf) + await afterClaim(store, at, id, subject, content, ctx.session, prior);
try {
if (await fileClaim(store, ctx.s1, { id, subject, content, origin }, projects)) return id;
} catch (e) {
Expand Down
33 changes: 27 additions & 6 deletions worker/src/memory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,8 +61,12 @@ export interface Claim {
updated_at: string;
verify?: string | null; // the operator's freshness command; set only through POST /v1/operator
pointer?: boolean; // set by recall when a path, anchor or doc:// ref in the query matched the claim, not its words
confirmations?: Confirmation[]; // set by consolidate: other sessions whose newest feedback on this claim is `used`
}

// A session that was shown the claim, acted on it, and rated it `used` with a note on what it checked.
export interface Confirmation { session: string; at: string }

// Rank survivors by authority first; agent < verified < human.
export function rank(c: Claim): [number, number, number, number, string] {
return [AUTHORITIES.indexOf(c.authority), c.status === "accepted" ? 1 : 0, c.confidence ?? 0,
Expand Down Expand Up @@ -91,12 +95,16 @@ export function corroboration(members: Claim[]): number {
// The two-session rule measures recurrence, not independent evidence: one client can open two
// sessions. Requiring the supporting sessions to span `minGapMs` makes "it came up again later" the
// thing being counted, and makes faking it slow.
// A `used` rating counts as its session's support at the rating's time, because the rater checked the
// claim against its own work; re-claiming what it was shown (an echo) still counts for nothing.
export function recurs(members: Claim[], k: number, minGapMs: number): boolean {
if (members.length < k) return false;
const firstSeen = new Map<string, number>();
const seen = (s: string, t: number) => firstSeen.set(s, Math.min(firstSeen.get(s) ?? t, t));
for (const m of members) {
const t = Date.parse(m.created_at);
for (const s of m.source_ids) firstSeen.set(s, Math.min(firstSeen.get(s) ?? t, t));
for (const s of m.source_ids) seen(s, t);
// A session never confirms its own claim.
for (const c of m.confirmations ?? []) if (c.session !== m.session) seen(`session:${c.session}`, Date.parse(c.at));
}
if (firstSeen.size < k) return false;
const times = [...firstSeen.values()];
Expand All @@ -116,7 +124,12 @@ export interface GroupKey { subject: string; scope: Scope; project: string | nul
// `version` is the group's live-row count and newest updated_at at read time; apply() refuses a plan
// whose group changed since (a correction or new claim landed), so a stale plan can't undo it.
// `support` is the claims whose recurrence justifies the promotion, for an agreement check.
export interface GroupPlan { key: GroupKey; version: string; supersede: string[]; promote: string[]; support: string[] }
// `confirmed` is the (claim, session) `used` ratings the promotion counted; apply() refuses the plan if one was withdrawn since.
export interface GroupPlan { key: GroupKey; version: string; supersede: string[]; promote: string[]; support: string[]; confirmed?: Rated[] }
export interface Rated { claim: string; session: string; at: string }

const countedConfirmations = (members: Claim[]): Rated[] =>
members.flatMap((m) => (m.confirmations ?? []).filter((c) => c.session !== m.session).map((c) => ({ claim: m.id, session: c.session, at: c.at })));

export function groupVersion(members: Claim[]): string {
return `${members.length}:${members.reduce((m, c) => (c.updated_at > m ? c.updated_at : m), "")}`;
Expand Down Expand Up @@ -145,15 +158,23 @@ export function planGroup(members: Claim[], policy: Policy = DEFAULT_POLICY): Gr
const winner = survivor(updates);
plan.promote.push(winner.id);
plan.support = updates.map((u) => u.id);
plan.confirmed = countedConfirmations(updates);
plan.supersede.push(...members.filter((m) => m.id !== winner.id).map((m) => m.id));
return plan;
}
const pending = new Set(updates.map((u) => u.id));
plan.supersede.push(...members.filter((m) => m.id !== best.id && !pending.has(m.id)).map((m) => m.id));
// Why: accept only when >= K distinct claims from distinct sessions agree; one session's guess must not become the swarm's truth.
if (best.status === "candidate" && recurs(members, policy.k, policy.minGapMs) && policy.autoAccept(best)) {
const promoting = best.status === "candidate" && recurs(members, policy.k, policy.minGapMs) && policy.autoAccept(best);
// An unstamped survivor (an echo) never retires a stamped candidate: that claim is the subject's evidence, and the
// one a later `used` rating names.
const keep = new Set(updates.map((u) => u.id));
if (!promoting && best.status === "candidate" && !best.source_ids.length) {
for (const m of members) if (m.status === "candidate" && m.source_ids.length) keep.add(m.id);
}
plan.supersede.push(...members.filter((m) => m.id !== best.id && !keep.has(m.id)).map((m) => m.id));
if (promoting) {
plan.promote.push(best.id);
plan.support = members.map((m) => m.id);
plan.confirmed = countedConfirmations(members);
}
return plan;
}
Expand Down
Loading
Loading