diff --git a/.github/workflows/closura-arc-ci.yml b/.github/workflows/closura-arc-ci.yml index bb5a8f791935..eba1434433d8 100644 --- a/.github/workflows/closura-arc-ci.yml +++ b/.github/workflows/closura-arc-ci.yml @@ -152,6 +152,8 @@ jobs: vp test run \ apps/server/src/speech/CloudSpeech.test.ts \ packages/contracts/src/threadInbox.test.ts \ + packages/contracts/src/threadInbox.invariants.test.ts \ + packages/contracts/src/threadInbox.upgrade.test.ts \ packages/contracts/src/threadMetadataMcp.test.ts \ apps/web/src/components/threadActionMenu.logic.test.ts \ apps/web/src/components/sidebar/threadListFilter.logic.test.ts \ diff --git a/docs/inbox-sync-verification.md b/docs/inbox-sync-verification.md new file mode 100644 index 000000000000..095f0211bf3c --- /dev/null +++ b/docs/inbox-sync-verification.md @@ -0,0 +1,38 @@ +# Inbox and sync verification + +How the founder inbox is checked, and what to do when a check fails. The checks are +[`threadInbox.invariants.test.ts`](../packages/contracts/src/threadInbox.invariants.test.ts) +(properties over generated inboxes, with the rules as a plain-English list at the top) and +[`threadInbox.upgrade.test.ts`](../packages/contracts/src/threadInbox.upgrade.test.ts) (real, +anonymized inbox records from the fixture +[`inboxSnapshot.ts`](../packages/contracts/src/__fixtures__/inboxSnapshot.ts), projected by the +current code and compared with the rule that shipped before). + +## When an inbox or sync test fails + +- First decide which is wrong: the code or the rule. The tests encode founder rules, for example + Kameron: "a new lane i dont mind seeing, but dont want to see the 5 threads it creates." PR #81 + hid every lane from before it because its rule was wrong, not because the code had a bug. If the + rule is wrong, change it only with the founder's word, and record that in the spec list at the top + of the property test file. +- If the upgrade-safety test shows a founder's or machine's count dropping, treat it as a + regression unless the PR states the drop is intended and gives the founder's rule. +- Never lower a number or delete a fixture record to make a test pass. To cover another machine, + append its anonymized records to the fixture under its own `environment` label. + +## When to escalate to a TLA+ model + +- Escalate if the property tests and the upgrade-safety test pass but sync bugs still happen between + machines: threads lost, duplicated, stale, missing on one environment, or alerts delivered twice + or never. Also escalate if the same sync bug comes back after two fixes. +- Model only the concurrent part: cross-environment forwarding, the queue and retry, dedupe, and + settle and route events racing between peers. That is where model checking finds bugs tests miss. +- Keep the pure inbox projection functions under property tests; they don't need TLA+. + +## Not Lean, not Bend + +- Lean would prove a model, not the TypeScript that runs. The two drift apart, and a proof can't + catch a wrong rule. +- Bend is a parallel-execution language, not a verification tool. +- Revisit Lean only if a small, stable pure core is extracted and actually reused as the source of + truth. diff --git a/packages/contracts/src/__fixtures__/inboxSnapshot.ts b/packages/contracts/src/__fixtures__/inboxSnapshot.ts new file mode 100644 index 000000000000..32c627c8e5ee --- /dev/null +++ b/packages/contracts/src/__fixtures__/inboxSnapshot.ts @@ -0,0 +1,490 @@ +// Anonymized inbox records from a real T3 database: routing fields only, no titles, messages or +// ids. One entry per distinct shape with its thread count; captured 2026-11-19 on the ASUS host. +// Add a machine under its own `environment` label; never lower a count to pass a test. +export const INBOX_SNAPSHOT = [ + { + environment: "env-1", + topLevel: false, + settled: false, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 4, + }, + { + environment: "env-1", + topLevel: false, + settled: false, + archived: false, + inbox: { + owner: null, + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 2, + }, + { + environment: "env-1", + topLevel: false, + settled: true, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 65, + }, + { + environment: "env-1", + topLevel: false, + settled: true, + archived: false, + inbox: { + owner: null, + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 90, + }, + { + environment: "env-1", + topLevel: true, + settled: false, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "agent", + id: "agent", + }, + audience: "kameron", + attentionKind: "FYI", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 7, + }, + { + environment: "env-1", + topLevel: true, + settled: false, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "agent", + id: "agent", + }, + audience: "kameron", + attentionKind: "FYI", + reason: "fyi", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 4, + }, + { + environment: "env-1", + topLevel: true, + settled: false, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "human", + id: "kameron", + }, + audience: "kameron", + attentionKind: "FYI", + reason: "fyi", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 3, + }, + { + environment: "env-1", + topLevel: true, + settled: false, + archived: false, + inbox: { + owner: null, + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 1, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 10, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "agent", + id: "agent", + }, + audience: "kameron", + attentionKind: "FYI", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 4, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "human", + id: "kameron", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 6, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "human", + id: "kameron", + }, + audience: "kameron", + attentionKind: "action", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 9, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: "kameron", + assignee: { + kind: "human", + id: "kameron", + }, + audience: "shared", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 1, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: null, + assignee: { + kind: "agent", + id: "agent", + }, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 23, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: null, + assignee: null, + audience: "agent-only", + attentionKind: "background", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 5, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: null, + assignee: null, + audience: "agent-only", + attentionKind: "background", + origin: null, + requestedBy: null, + actor: null, + executorEnvironmentId: null, + }, + count: 1, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: { + owner: null, + assignee: null, + audience: "agent-only", + attentionKind: "FYI", + origin: { + kind: "agent", + id: "agent", + }, + requestedBy: { + kind: "agent", + id: "agent", + }, + actor: { + kind: "agent", + id: "agent", + }, + executorEnvironmentId: "env-1", + }, + count: 1, + }, + { + environment: "env-1", + topLevel: true, + settled: true, + archived: false, + inbox: null, + count: 2, + }, +] as const; diff --git a/packages/contracts/src/threadInbox.invariants.test.ts b/packages/contracts/src/threadInbox.invariants.test.ts new file mode 100644 index 000000000000..9e7224d00b48 --- /dev/null +++ b/packages/contracts/src/threadInbox.invariants.test.ts @@ -0,0 +1,144 @@ +// Founder inbox rules as properties over generated inboxes. SPEC is the plain-English list and +// names each test. Changing a line needs the founder's word and a note here. +// Failing? Read docs/inbox-sync-verification.md first. +import { it } from "@effect/vitest"; +import * as Schema from "effect/Schema"; +import { describe, expect } from "vite-plus/test"; +import { + Founder, + InboxChoice, + founderInboxLane, + matchesInboxFilter, + matchesInboxView, + primaryInbox, + projectThreadInbox, + routeThreadInbox, + type InboxActor, + type ThreadInbox, +} from "./threadInbox.ts"; + +const founders = Founder.literals; +const human = (id: Founder): InboxActor => ({ kind: "human", id }); +const agent: InboxActor = { kind: "agent", id: "agent" }; +const REQUESTED_AT = "2026-01-01T00:00:00.000Z"; + +const shape = { + origin: Schema.Literals(["human", "agent"]), + owner: Schema.NullOr(Founder), + assignee: Schema.Literals(["none", "kameron", "jeff", "agent"]), + audience: Schema.Literals(["kameron", "jeff", "shared", "agent-only"]), + attentionKind: Schema.Literals(["action", "FYI", "background"]), + reason: Schema.Literals(["none", "conversation", "review", "decision", "approval", "fyi"]), + ask: Schema.Literals(["none", "kameron", "jeff"]), + pending: Schema.Boolean, + founder: Founder, +}; +type Shape = { + [K in keyof typeof shape]: Schema.Schema.Type<(typeof shape)[K]>; +}; + +const assigneeOf = (assignee: Shape["assignee"]): InboxActor | null => + assignee === "none" ? null : assignee === "agent" ? agent : human(assignee); + +const inboxOf = (s: Shape, { withAsk = true } = {}): ThreadInbox => ({ + owner: s.owner, + assignee: assigneeOf(s.assignee), + audience: s.audience, + attentionKind: s.attentionKind, + ...(s.reason === "none" ? {} : { reason: s.reason }), + ...(withAsk && s.ask !== "none" + ? { + decisionRequest: { + founder: s.ask, + kind: "decision" as const, + question: "Which one?", + requestedAt: REQUESTED_AT, + }, + } + : {}), + ...(s.pending ? { pendingHumanRequest: true } : {}), + origin: s.origin === "agent" ? agent : human(s.founder), + requestedBy: null, + actor: null, + executorEnvironmentId: null, +}); + +const SPEC = { + 1: "A top-level lane routed to a founder (audience, and owner or human assignee, is that founder, with action or FYI attention) is never hidden from them, with or without a reason. Every lane filed before `reason` existed has none; PR #81 hid them all.", + 2: "An agent-only child with no human assignee is never in a founder lane, except through an open decision request or a pending request on a thread that founder owns.", + 3: "Every classified thread lands in exactly one of a founder lane, Shared, or Agents, never zero.", + 4: "An open decision ask for a founder survives re-projection as that founder's action lane until a person writes after it. Routing itself ends an earlier ask on purpose.", + 5: "Settlement never moves a thread between lanes: the lane takes no settled input. threadInbox.upgrade.test.ts counts settled and unsettled threads alike.", +} as const; + +describe("founder inbox invariants", () => { + it.prop(`1: ${SPEC[1]}`, shape, (s) => { + // Built routed: audience and owner are the founder, a human assignee is the founder, and the + // attention is one a founder sees (background reports in Agents). Origin and reason vary. + const base = inboxOf(s, { withAsk: false }); + const inbox: ThreadInbox = { + ...base, + owner: s.founder, + audience: s.founder, + assignee: s.assignee === "agent" || s.assignee === "none" ? base.assignee : human(s.founder), + attentionKind: s.attentionKind === "background" ? "FYI" : s.attentionKind, + }; + const lane = founderInboxLane(inbox, s.founder); + expect(lane === "action" || lane === "FYI").toBe(true); + expect(matchesInboxView(inbox, s.founder)).toBe(true); + }); + + it.prop(`2: ${SPEC[2]}`, shape, (s) => { + const inbox: ThreadInbox = { + ...inboxOf(s, { withAsk: false }), + audience: "agent-only", + assignee: s.assignee === "agent" ? agent : null, + }; + for (const founder of founders) { + const lane = founderInboxLane(inbox, founder); + if (s.pending && inbox.owner === founder) expect(lane).toBe("action"); + else expect(lane).toBe("hidden"); + } + expect(matchesInboxView(inbox, "agents")).toBe(true); + }); + + it.prop(`3: ${SPEC[3]}`, shape, (s) => { + const inbox = inboxOf(s); + const home = primaryInbox(inbox); + expect(home).not.toBeNull(); + const matching = InboxChoice.literals.filter((choice) => matchesInboxFilter(inbox, [choice])); + expect(matching).toEqual([home]); + }); + + it.prop(`4: ${SPEC[4]}`, shape, (s) => { + const base = inboxOf(s, { withAsk: false }); + const routed = routeThreadInbox(base, { audience: s.audience, attentionKind: s.attentionKind }); + // Routing ends any earlier ask; a new one is not dropped by the projection that follows. + expect(routed.decisionRequest).toBeUndefined(); + if (s.ask === "none") return; + const asked: ThreadInbox = { + ...routed, + decisionRequest: { + founder: s.ask, + kind: "decision", + question: "Which one?", + requestedAt: REQUESTED_AT, + }, + }; + const open = projectThreadInbox(asked, { + pendingHumanRequest: false, + latestHumanMessageAt: null, + }); + expect(founderInboxLane(open, s.ask)).toBe("action"); + const before = projectThreadInbox(asked, { + pendingHumanRequest: false, + latestHumanMessageAt: "2025-12-31T00:00:00.000Z", + }); + expect(founderInboxLane(before, s.ask)).toBe("action"); + const answered = projectThreadInbox(asked, { + pendingHumanRequest: false, + latestHumanMessageAt: "2026-01-02T00:00:00.000Z", + }); + expect(answered.decisionRequest).toBeUndefined(); + }); +}); diff --git a/packages/contracts/src/threadInbox.test.ts b/packages/contracts/src/threadInbox.test.ts index 0722a46e327b..baf118e40bc8 100644 --- a/packages/contracts/src/threadInbox.test.ts +++ b/packages/contracts/src/threadInbox.test.ts @@ -64,13 +64,16 @@ describe("shared fleet organizational inbox", () => { ]); // Agent work filed to another founder or Shared stays out of "Kameron + Agents". const mineAndAgents = ["kameron", "agents"] as const; - // An agent files work to a founder only with a reason; without one it stays in Agents. + // New agent routes to a founder need a reason. Routing without one is how lanes were filed + // before `reason` existed; those show to that founder as FYI rather than vanishing. const filedToJeff = makeThreadInbox({ actor: bot, routing: { ...inboxRoutingFor("jeff"), reason: "decision" }, }); const unreasoned = makeThreadInbox({ actor: bot, routing: inboxRoutingFor("jeff") }); - expect(primaryInbox(unreasoned)).toBe("agents"); + expect(primaryInbox(unreasoned)).toBe("jeff"); + expect(founderInboxLane(unreasoned, "jeff")).toBe("FYI"); + expect(founderInboxLane(unreasoned, "kameron")).toBe("hidden"); const sharedByKameron = makeThreadInbox({ actor: kameron, routing: { audience: "shared" } }); expect(matchesInboxFilter(filedToJeff, mineAndAgents)).toBe(false); expect(matchesInboxFilter(filedToJeff, ["jeff"])).toBe(true); @@ -142,7 +145,7 @@ describe("shared fleet organizational inbox", () => { expect(visibleIn(quieter)).toEqual(["kameron", "agents"]); expect(founderInboxLane(quieter, "kameron")).toBe("FYI"); }); - it("never files reason-less agent work into a founder's lane", () => { + it("shows reason-less agent lanes only to the founder they were routed to, as FYI", () => { const people = [null, kameron, jeff] as const; const patches: ThreadInboxRoutingPatch[] = [{}]; for (const owner of [null, "kameron", "jeff"] as const) @@ -153,9 +156,15 @@ describe("shared fleet organizational inbox", () => { for (const routing of patches) { for (const parent of [undefined, makeThreadInbox({ actor: kameron })]) { const inbox = makeThreadInbox({ actor: bot, routing, ...(parent ? { parent } : {}) }); + // Pre-reason lanes (audience = founder) keep showing; nothing else reason-less does. + const expected = (founder: "kameron" | "jeff") => { + if (inbox.audience === "agent-only" && inbox.assignee?.kind !== "human") return "hidden"; + const assigned = inbox.assignee?.kind === "human" ? inbox.assignee.id : inbox.owner; + return assigned === founder && inbox.audience === founder ? "FYI" : "hidden"; + }; expect([founderInboxLane(inbox, "kameron"), founderInboxLane(inbox, "jeff")]).toEqual([ - "hidden", - "hidden", + expected("kameron"), + expected("jeff"), ]); expect(agentInboxRoutingError(inbox, routing) === null).toBe( inbox.audience === "agent-only" && inbox.assignee?.kind !== "human", @@ -280,6 +289,7 @@ describe("shared fleet organizational inbox", () => { expect(child.requestedBy).toEqual(jeff); expect(child.origin).toEqual(bot); // Child work an agent started reports in Agents, not the requester's inbox. + expect(child.audience).toBe("agent-only"); expect(founderInboxLane(child, "jeff")).toBe("hidden"); expect(child.executorEnvironmentId).toBe("r720"); }); diff --git a/packages/contracts/src/threadInbox.ts b/packages/contracts/src/threadInbox.ts index e67b8f8d13a1..4dd00e7c6819 100644 --- a/packages/contracts/src/threadInbox.ts +++ b/packages/contracts/src/threadInbox.ts @@ -119,7 +119,15 @@ export function makeThreadInbox(input: { routing?.assignee !== undefined ? routing.assignee : (input.parent?.assignee ?? (owner ? { kind: "human" as const, id: owner } : actor)); - const audience = routing?.audience ?? target ?? input.parent?.audience ?? owner ?? "agent-only"; + // An agent's child work reports in Agents, so it never inherits a founder audience from its + // parent: with no reason, that would be indistinguishable from a lane filed before reasons. + const audience = + routing?.audience ?? + target ?? + (actor?.kind === "agent" && input.parent ? "agent-only" : undefined) ?? + input.parent?.audience ?? + owner ?? + "agent-only"; return { owner, assignee, @@ -211,7 +219,8 @@ export function projectThreadInbox( /** * A founder's lane holds only threads waiting on them: an open decision request for them, a * pending runtime request on a thread they own, or a thread they own that a person filed or an - * agent filed with a reason. Other agent work stays in Agents. + * agent filed with a reason, or an agent lane routed to them before reasons existed (FYI). + * Other agent work stays in Agents. */ export function founderInboxLane(inbox: ThreadInbox | null | undefined, founder: Founder) { if (!inbox) return "unknown"; @@ -220,7 +229,10 @@ export function founderInboxLane(inbox: ThreadInbox | null | undefined, founder: const assigned = inbox.assignee?.kind === "human" ? inbox.assignee.id : inbox.owner; if (inbox.audience === "agent-only" && inbox.assignee?.kind !== "human") return "hidden"; if (assigned !== founder) return "hidden"; - if (inbox.origin?.kind === "agent" && inbox.reason === undefined) return "hidden"; + if (inbox.origin?.kind === "agent" && inbox.reason === undefined) + // Lanes filed before `reason` existed carry none. Routed to this founder they stay visible as + // FYI; agent work that merely names them as owner (audience elsewhere) stays in Agents. + return inbox.audience === founder ? "FYI" : "hidden"; return inbox.reason === "fyi" && inbox.attentionKind === "action" ? "FYI" : inbox.attentionKind; } @@ -250,7 +262,8 @@ const isAllInboxes = (filter: ReadonlyArray) => export function primaryInbox(inbox: ThreadInbox | null | undefined): InboxChoice | null { if (matchesInboxView(inbox, "shared")) return "shared"; for (const founder of Founder.literals) if (matchesInboxView(inbox, founder)) return founder; - return matchesInboxView(inbox, "agents") ? "agents" : null; + // Anything else classified, such as background work filed to a founder, reports in Agents. + return inbox ? "agents" : null; } /** `matchesInboxFilter` for a thread already reduced to its `primaryInbox`. */ @@ -279,7 +292,8 @@ export function matchesInboxView(inbox: ThreadInbox | null | undefined, view: In return ( inbox?.origin?.kind === "agent" || inbox?.assignee?.kind === "agent" || - inbox?.audience === "agent-only" + inbox?.audience === "agent-only" || + (inbox != null && primaryInbox(inbox) === "agents") ); if (view === "shared") return inbox?.audience === "shared"; const lane = founderInboxLane(inbox, view); diff --git a/packages/contracts/src/threadInbox.upgrade.test.ts b/packages/contracts/src/threadInbox.upgrade.test.ts new file mode 100644 index 000000000000..cae048bca9d1 --- /dev/null +++ b/packages/contracts/src/threadInbox.upgrade.test.ts @@ -0,0 +1,109 @@ +// Real, anonymized inbox records must not lose founder-visible threads against the rule before +// PR #81, which hid every reason-less lane. A count drop is a regression unless the PR gives the +// founder's rule. Failing? Read docs/inbox-sync-verification.md first. +import * as Schema from "effect/Schema"; +import { describe, expect, it } from "vite-plus/test"; +import { INBOX_SNAPSHOT } from "./__fixtures__/inboxSnapshot.ts"; +import { + Founder, + ThreadInbox, + founderInboxLane, + primaryInbox, + projectThreadInbox, + type InboxActor, +} from "./threadInbox.ts"; + +const GUIDE = "docs/inbox-sync-verification.md"; +const agent: InboxActor = { kind: "agent", id: "agent" }; +const base = { + owner: "kameron", + assignee: agent, + audience: "kameron", + attentionKind: "FYI", + origin: agent, + requestedBy: agent, + actor: agent, + executorEnvironmentId: null, +} as const satisfies ThreadInbox; +const idle = { pendingHumanRequest: false, latestHumanMessageAt: null }; + +const visible = (lane: string) => lane === "action" || lane === "FYI"; + +/** The founder lane as shipped before PR #81 (commit 7ec797a64d^), kept as the baseline. */ +const lanePreReasonRule = (inbox: ThreadInbox, founder: Founder) => { + const assigned = inbox.assignee?.kind === "human" ? inbox.assignee.id : inbox.owner; + if (inbox.audience === "agent-only" && inbox.assignee?.kind !== "human") return "hidden"; + if (assigned !== founder) return "hidden"; + return inbox.attentionKind; +}; + +describe("founder inbox upgrade safety", () => { + it("shows a lane filed before reasons existed, settled or not", () => { + // Agent origin, audience kameron, FYI, no reason: what every lane looked like before #81. + expect(founderInboxLane(base, "kameron")).toBe("FYI"); + expect(founderInboxLane(base, "jeff")).toBe("hidden"); + expect( + founderInboxLane({ ...base, assignee: { kind: "human", id: "kameron" } }, "kameron"), + ).toBe("FYI"); + // Shown as FYI whatever attention it carried: nothing records that it still waits on anyone. + expect(founderInboxLane({ ...base, attentionKind: "action" }, "kameron")).toBe("FYI"); + }); + + it("keeps an agent-only child out of the founder inbox", () => { + const child: ThreadInbox = { ...base, audience: "agent-only", attentionKind: "background" }; + expect([founderInboxLane(child, "kameron"), founderInboxLane(child, "jeff")]).toEqual([ + "hidden", + "hidden", + ]); + }); + + it("still lands a decision request in the asked founder's action lane", () => { + const asked: ThreadInbox = { + ...base, + audience: "agent-only", + attentionKind: "background", + decisionRequest: { + founder: "kameron", + kind: "decision", + question: "Which one?", + requestedAt: "2026-01-01T00:00:00.000Z", + }, + }; + expect(founderInboxLane(projectThreadInbox(asked, idle), "kameron")).toBe("action"); + }); + + it("does not lose visible threads per founder and environment against the previous rule", () => { + const decode = Schema.decodeUnknownSync(Schema.NullOr(ThreadInbox)); + type Key = `${Founder}|${string}|${"settled" | "open"}`; + const before = new Map(); + const after = new Map(); + const add = (counts: Map, key: Key, n: number) => + counts.set(key, (counts.get(key) ?? 0) + n); + let children = 0; + for (const shape of INBOX_SNAPSHOT) { + const inbox = decode(shape.inbox); + if (inbox === null) continue; + expect( + primaryInbox(inbox), + `unclassified thread in the snapshot. See ${GUIDE}`, + ).not.toBeNull(); + for (const founder of Founder.literals) { + const key: Key = `${founder}|${shape.environment}|${shape.settled ? "settled" : "open"}`; + if (visible(lanePreReasonRule(inbox, founder))) add(before, key, shape.count); + const lane = founderInboxLane(projectThreadInbox(inbox, idle), founder); + if (visible(lane)) { + add(after, key, shape.count); + if (!shape.topLevel) children += shape.count; + } + } + } + expect(before.size, "the snapshot must contain founder-visible lanes").toBeGreaterThan(0); + for (const [key, was] of before) { + expect( + after.get(key) ?? 0, + `${key}: ${was} visible threads before, fewer now. A drop is a regression unless the PR gives the founder's rule. See ${GUIDE}`, + ).toBeGreaterThanOrEqual(was); + } + expect(children, `children appeared in a founder inbox. See ${GUIDE}`).toBe(0); + }); +});