@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/events/cards.ts

@@ -0,0 +1,286 @@
+import { z } from "zod";
+import { AgentProviderSchema } from "../schemas/agent.js";
+import { CredentialGateKindSchema, CredentialGateScopeSchema, CredentialLaneSchema } from "../schemas/secrets.js";
+
+// Cards a turn raises to ask the person something mid-turn; each pauses the turn until `POST /agent/reply` answers it.
+// Shapes shared by the daemon that raises them, the browser that draws them, and the transcript that records them
+// (transcript.ts).
+
+// One interactive question the agent asks via the `ask` tool (mirrors AskUserQuestion's input shape).
+export const AskOptionSchema = z.object({
+    label: z.string().describe("The choice, in a few words."),
+    description: z.string().describe("What picking it means."),
+    preview: z.string().optional().describe("Something to look at while deciding: a mock-up, a snippet, a layout."),
+});
+export type AskOption = z.infer<typeof AskOptionSchema>;
+
+export const AskQuestionSchema = z.object({
+    question: z.string().describe("What the agent is asking."),
+    header: z.string().describe("A short label for the question."),
+    multiSelect: z.boolean().describe("Whether more than one answer can be picked."),
+    options: z.array(AskOptionSchema).describe("The choices offered. A free-text answer is always possible as well."),
+});
+export type AskQuestion = z.infer<typeof AskQuestionSchema>;
+
+// The command a card is holding, as data rather than prose. `spans` is carried from the classifier's own match (never
+// re-derived), offset into `text` after truncation.
+export const ProgramAskSchema = z.object({
+    text: z.string().describe("What would run."),
+    language: z.enum(["bash", "javascript"]).describe("Which of the two backends it is written for, named as the grammar that colours it."),
+    truncated: z
+        .boolean()
+        .describe(
+            "Whether this is an excerpt of a longer program, so the card can say so instead of ending mid-word. An excerpt always carries the flagged fragment: the beginning, then a window around the fragment, with any skipped middle written into the text as a bracketed count.",
+        ),
+    spans: z
+        .array(z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }))
+        .describe(
+            "Which fragments of the text the pattern match fired on: every matched class's, or, under the hard rule, only the class the title names. Offsets into text, in order, never overlapping.",
+        ),
+});
+export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
+
+// One per-tool permission prompt (SDK's canUseTool, surfaced as a card); the daemon passes the bridge's own rendered
+// strings through unchanged. `alwaysLabel` is present only when the SDK offered a rule to persist.
+export const PermissionAskSchema = z.object({
+    toolName: z.string().describe("Which tool it wants to use."),
+    // The whole prompt sentence, exactly as the runtime words it, when the bridge rendered one.
+    title: z.string().optional().describe("The whole question, as a sentence, exactly as the runtime words it."),
+    // Short noun phrase for the allow button ("Read file").
+    displayName: z.string().optional().describe("A short phrase for the button, such as read file."),
+    description: z.string().optional().describe("More about what it is asking for."),
+    // Why the prompt fired ('rule' | 'mode' | 'classifier' | …), shown as the card's muted subline.
+    reason: z.string().optional().describe("Why it is asking at all: a rule, the current mode, something that looked risky."),
+    // The file the request is about, when it is about one, workspace-root-relative.
+    path: z.string().optional().describe("Which file it concerns, when it concerns one."),
+    alwaysLabel: z
+        .string()
+        .optional()
+        .describe(
+            "The wording for an always-allow answer. Present only when there is something an always could actually remember; without it the only answers are once and no.",
+        ),
+    program: ProgramAskSchema.optional().describe(
+        "The program this card is holding, when the card is about one. Present on a command gate's card and absent on every other permission ask.",
+    ),
+    // The judge's own sentence, present only when the title can't say it; never written by the agent being gated.
+    explain: z
+        .string()
+        .optional()
+        .describe(
+            "One plain sentence saying what the program does and why it is being asked about, where the title says something else. Written by the judge that read your safety policy, never by the agent being gated.",
+        ),
+});
+export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
+
+// One missing capability asked for; `card`/`name` are resolved by the daemon from the catalog it validates against. The
+// model contributes only `why`, so the card can't misrepresent what's being connected.
+export const CapabilityOfferSchema = z.object({
+    // The catalog card being asked for, and how the catalog itself titles it ("Notion", "GitHub", "Docker").
+    card: z.string().describe("Which connection is being asked for."),
+    name: z.string().describe("What it is called, as the catalogue titles it rather than as the agent named it."),
+    // The agent's one-line case for connecting it, the only prose on the card that is the model's.
+    why: z.string().optional().describe("The agent's case for connecting it, and the only words on this card that are the agent's."),
+});
+export type CapabilityOffer = z.infer<typeof CapabilityOfferSchema>;
+
+// One outbound USDC payment offered; every number is the daemon's own arithmetic over the endpoint's challenge and the
+// wallet's ledger. The model contributes only `why`, so the price can't be misquoted.
+export const PaymentOfferSchema = z.object({
+    // The paid resource, as the endpoint's challenge stated it.
+    url: z.string().describe("What is being paid for."),
+    description: z.string().optional().describe("What the endpoint says it is."),
+    // Where the money goes, verbatim off the challenge: recipient address, CAIP-2 network, token contract.
+    payTo: z.string().describe("Where the money goes, taken verbatim from the endpoint's own demand."),
+    network: z.string().describe("On which network."),
+    asset: z.string().describe("In which token."),
+    // The token's display name ("USDC"), dollar-pegged, so every amount below reads as USD.
+    assetName: z.string().describe("That token's name. It is pegged to the dollar, which is what lets every amount here read as dollars."),
+    // The exact price; the x402 exact scheme has no ranges, so this is the whole spend, not a ceiling.
+    amountUsd: z.string().describe("The exact price. Not a ceiling: this scheme has no ranges, so this is the whole spend."),
+    // The wallet's meter as the daemon's ledger states it, what "spent today / cap" renders from.
+    spentTodayUsd: z.string().describe("What has already gone out today."),
+    dailyCapUsd: z.string().describe("What may go out in a day."),
+    // The agent's one-line case for paying, the only prose on the card that is the model's.
+    why: z.string().optional().describe("The agent's case for paying, and the only words on this card that are the agent's."),
+});
+export type PaymentOffer = z.infer<typeof PaymentOfferSchema>;
+
+// One gated credential asked for; every field but `why` is the daemon's own, off the gate policy and the exit that
+// would spend it. `approvers` are shown since the card addresses a named list, not the owner.
+export const CredentialOfferSchema = z.object({
+    // The gate's subject: a secret's reference name (`DATABASE_URL`) or a capability id (`reddit`).
+    subject: z.string().describe("Which credential is being asked for."),
+    kind: CredentialGateKindSchema,
+    lane: CredentialLaneSchema,
+    // Where it would go, in the reader's terms; reference-form, never a value, so it can be shown safely.
+    detail: z
+        .string()
+        .optional()
+        .describe("Where it would go: the start of the command, the site, or what is being mounted. Never a value: the command still reads as a reference at this point."),
+    // The agent's one-line case, the only prose on the card that is the model's.
+    why: z.string().optional().describe("The agent's case for using it, and the only words on this card that are the agent's."),
+    approvers: z.array(z.string()).describe("Who may release it. A click from anyone else is refused and leaves the card standing."),
+    scope: CredentialGateScopeSchema,
+});
+export type CredentialOffer = z.infer<typeof CredentialOfferSchema>;
+
+// One provider-advertised slash command (ACP's available_commands, or a Claude Code session's supportedCommands).
+// `hint` is the argument placeholder the popover shows after the name.
+export const AgentCommandSchema = z.object({
+    name: z.string().describe("What to type, without the leading slash."),
+    description: z.string().describe("What it does."),
+    hint: z.string().optional().describe("What its argument should look like, shown after the name."),
+});
+export type AgentCommand = z.infer<typeof AgentCommandSchema>;
+
+// GET /agent/commands: which provider's last-published list to read; absent means claude, matching AgentTurn.
+export const AgentCommandsQuerySchema = z.object({
+    agent: AgentProviderSchema.optional().describe("Whose commands to read. Leave it out for Claude."),
+});
+export const AgentCommandsSchema = z.object({
+    commands: z.array(AgentCommandSchema).describe("The shortcut commands, as the provider last published them."),
+});
+
+// One TodoWrite/Task checklist item, surfaced live so the UI shows the agent's plan-of-work.
+export const TodoItemSchema = z.object({
+    content: z.string().describe("The item, as the agent wrote it."),
+    status: z.enum(["pending", "in_progress", "completed"]).describe("Where it is."),
+    activeForm: z
+        .string()
+        .optional()
+        .describe("How to phrase it while it is happening, so a screen can say what the agent is doing rather than what it plans to do."),
+});
+export type TodoItem = z.infer<typeof TodoItemSchema>;
+
+// Context-window fill for a conversation: tokens the latest request sent vs. the model's window, so the UI can warn
+// near auto-compaction. Per-conversation, unlike the account-wide usage.
+export const ContextUsageSchema = z.object({
+    tokens: z.number().describe("How much the latest request sent, all told."),
+    contextWindow: z.number().describe("How much the model can hold. The gap between these two is how close the conversation is to being compacted."),
+});
+export type ContextUsage = z.infer<typeof ContextUsageSchema>;
+
+// ACP-aligned tool taxonomy (Agent Client Protocol's ToolKind, verbatim): what a tool call does, driving the card icon
+// regardless of which backend named the tool.
+export const ToolKindSchema = z.enum(["read", "edit", "delete", "move", "search", "execute", "think", "fetch", "other"]);
+export type ToolKind = z.infer<typeof ToolKindSchema>;
+
+export const ToolCallStatusSchema = z.enum(["pending", "in_progress", "completed", "failed"]);
+export type ToolCallStatus = z.infer<typeof ToolCallStatusSchema>;
+
+// A file a tool call touches. Workspace-root-relative, forward-slash; adapters normalize from the turn's cwd. `line` is
+// 1-based.
+export const ToolCallLocationSchema = z.object({
+    path: z.string().describe("The file, as a workspace path, whatever directory the tool was run from."),
+    line: z.number().optional().describe("Which line, counting from one."),
+});
+export type ToolCallLocation = z.infer<typeof ToolCallLocationSchema>;
+
+// Structured tool output (ACP's ToolCallContent, verbatim); `diff` is hunk-level for edits, whole-file for Write.
+// `image` is a workspace path, not bytes, so it stays openable without bloating the stream.
+export const ToolCallContentSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("text").describe("Plain output."),
+        text: z.string().describe("What the tool said."),
+    }),
+    z.object({
+        type: z.literal("diff").describe("A change to a file."),
+        path: z.string().describe("Which file, as a workspace path."),
+        oldText: z.string().optional().describe("What was there. Absent for a new file, or where the previous contents are not known."),
+        newText: z.string().describe("What is there now."),
+        truncated: z.boolean().optional().describe("One of the two sides was too large to send whole."),
+    }),
+    z.object({
+        type: z.literal("image").describe("A picture the tool produced."),
+        path: z
+            .string()
+            .describe(
+                "Where it is, as a workspace path. A path rather than the bytes, because the workspace already serves it, sending it inline would bloat every stored record, and this way the picture stays openable afterwards.",
+            ),
+    }),
+]);
+export type ToolCallContent = z.infer<typeof ToolCallContentSchema>;
+
+// The document a parked card is asking about, carried by value: the bytes are already in hand, and a restored
+// transcript has no workspace to fetch a path from. `path` rides along for an overflow.
+export const CardDocumentSchema = z.object({
+    path: z.string().describe("Where it lives, as a workspace path."),
+    title: z.string().describe("What it is called: its opening heading, or its file name."),
+    markdown: z.string().describe("The document itself."),
+    truncated: z.boolean().optional().describe("It was clipped at the wire cap; the file on disk has more."),
+    plan: z.boolean().optional().describe("It is one of the CLI's plan files, written to be approved rather than merely read."),
+});
+export type CardDocument = z.infer<typeof CardDocumentSchema>;
+
+// One card's fields, spelled once: the raising frame, the parked-card journal entry, and the transcript row all share
+// this shape rather than declaring it three times.
+const REQUEST_ID = z.string().describe("What to send back when you answer.");
+export const planCard = {
+    requestId: REQUEST_ID,
+    text: z.string().describe("The plan itself."),
+    // Present when the plan prose points at a document; absent when the text already is the whole plan.
+    document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
+};
+export const questionCard = {
+    requestId: REQUEST_ID,
+    questions: z.array(AskQuestionSchema).describe("What it wants to know."),
+    document: CardDocumentSchema.optional().describe("The document this turn wrote and is asking about, so the choice can be read beside it."),
+};
+export const permissionCard = { requestId: REQUEST_ID };
+// The agent's browser is parked on something it can't clear itself (captcha, password, phone check). `session` names it
+// on /browsers; `account` says whose login is stuck.
+export const browserHelpCard = {
+    requestId: z.string(),
+    session: z.string(),
+    account: z.string(),
+    message: z.string(),
+};
+// The agent's terminal is sitting at a prompt it can't answer (OTP, security-key touch, confirm). `session` names it on
+// the terminal panel, same division as the browser card.
+export const terminalHelpCard = {
+    requestId: z.string(),
+    session: z.string(),
+    message: z.string(),
+};
+export const capabilityOfferCard = { requestId: z.string(), offer: CapabilityOfferSchema };
+export const paymentOfferCard = { requestId: z.string(), offer: PaymentOfferSchema };
+export const credentialOfferCard = { requestId: z.string(), offer: CredentialOfferSchema };
+
+// How an accepted capability offer ended, shared by the frame that reports it and the record that keeps it, so a
+// reopened receipt matches the live card.
+export const CapabilityOutcomeSchema = z.object({
+    outcome: z.enum(["connected", "unfinished"]),
+    id: z.string().optional(),
+});
+export type CapabilityOutcome = z.infer<typeof CapabilityOutcomeSchema>;
+export const PaymentReceiptSchema = z.object({
+    outcome: z.enum(["paid", "failed"]),
+    amountUsd: z.string(),
+    transaction: z.string().optional(),
+    network: z.string().optional(),
+});
+export type PaymentReceipt = z.infer<typeof PaymentReceiptSchema>;
+// Who released a gated credential, or that someone refused it. `released` carries the approver's verified identity, not
+// what the click claimed.
+export const CredentialReceiptSchema = z.object({
+    outcome: z.enum(["released", "refused"]),
+    approvedBy: z.string().optional(),
+});
+export type CredentialReceipt = z.infer<typeof CredentialReceiptSchema>;
+
+// The three cards a turn journal can restore verbatim after a daemon restart. `browser_help`/`terminal_help` are
+// excluded: their Chromium/waiting command dies with the container, so those can only be reported, not restored.
+export const PlanCardSchema = z.object({
+    kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
+    ...planCard,
+});
+export const QuestionCardSchema = z.object({
+    kind: z.literal("question").describe("The agent has asked you something and is waiting."),
+    ...questionCard,
+});
+export const PermissionCardSchema = PermissionAskSchema.extend({
+    kind: z.literal("permission").describe("The agent wants to use a tool it needs permission for."),
+    ...permissionCard,
+});
+export const ParkedCardSchema = z.discriminatedUnion("kind", [PlanCardSchema, QuestionCardSchema, PermissionCardSchema]);
+export type ParkedCard = z.infer<typeof ParkedCardSchema>;

package/src/{events.test.ts → events/resume.test.ts}

@@ -1,54 +1,40 @@
 import { expect, test } from "vitest";
-import { RESUME_NOTES, resumeDisclosure, withResumeNote, withoutResumeNote } from "./events.js";
+import { RESUME_NOTES, resumeDisclosure, withResumeNote, withoutResumeNote } from "./resume.js";
 
-/* The resume note is a round trip across the wire: the daemon wraps a prompt to tell the model what interrupted
- * it, and the client unwraps the SAME prompt off an attach head to tell whether it already has that bubble. A
- * mismatch between the two halves fails silently and cosmetically: a paragraph of machine prose rendered as
- * something the user typed, which is exactly the kind of drift that stays broken. */
+// Wrapping then unwrapping a resume note must return the exact original prompt; a mismatch leaks machine narration into
+// the user's own words on screen.
 test("a resume note round-trips back to the user's own words", () => {
     for (const note of Object.values(RESUME_NOTES)) {
         expect(withoutResumeNote(withResumeNote("ship the parser", note))).toBe("ship the parser");
     }
 });
 
-// A prompt with blank lines of its own: only the note's own separator comes off, never the user's paragraphs.
+// The prompt itself contains blank lines, to prove only the note's own separator is stripped.
 test("stripping takes the note and nothing of the prompt", () => {
     const prompt = "step one\n\nstep two\n\nstep three";
     expect(withoutResumeNote(withResumeNote(prompt, RESUME_NOTES.outage))).toBe(prompt);
 });
 
-// An ordinary prompt passes through untouched, so every attach head can be handed through it.
 test("a prompt that is not a resume is left alone", () => {
     expect(withoutResumeNote("just a question")).toBe("just a question");
     expect(withoutResumeNote("")).toBe("");
 });
 
-// Wrapping is idempotent: a resume that dies the same way again is re-recorded from its own input, and a second
-// note stacked on the first would grow the prompt on every attempt.
 test("wrapping an already-wrapped prompt adds nothing", () => {
     const once = withResumeNote("retry me", RESUME_NOTES.restart);
     expect(withResumeNote(once, RESUME_NOTES.restart)).toBe(once);
     expect(withResumeNote(once, RESUME_NOTES.auth)).toBe(once);
 });
 
-/* THE OTHER HALF OF THE ROUND TRIP: taking the note off is what keeps it out of the user's words, and this is
- * what puts it back on screen as something that happened instead. Every reader of a stored prompt asks the same
- * question here, so a note nobody could disclose is a note that silently reads as the user's own sentence. */
 test("a re-run discloses as a notice, and the answered case as a note on the message", () => {
     for (const reason of ["auth", "outage", "restart"] as const) {
         const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES[reason]));
         expect(disclosure?.kind).toBe("notice");
     }
-    // The answer is new words the user really did type, so nothing is dropped: the interruption rides them.
     const answered = resumeDisclosure(withResumeNote("option two", RESUME_NOTES.answered));
     expect(answered).toEqual({ kind: "note", note: { title: expect.any(String), text: RESUME_NOTES.answered } });
 });
 
-/* THE THREE SPENT-ALLOWANCE NOTES OPEN ON THE SAME SENTENCE, and both readers of a note resolve it by PREFIX
- * (withoutResumeNote, resumeDisclosure). So one of them growing into a prefix of another is a silent swap rather
- * than a failure: a press that moved the turn onto an account with headroom would report itself as an ordinary
- * re-run, and the reader would be told nothing about the one fact that explains why this press worked where the
- * last one bounced. Each resolves to its own line, or this is broken. */
 test("the spent-allowance notes do not disclose as each other", () => {
     const lines = (["limit", "switched", "refused"] as const).map((reason) => {
         const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES[reason]));
@@ -58,7 +44,6 @@ test("the spent-allowance notes do not disclose as each other", () => {
     expect(new Set(lines).size).toBe(3);
 });
 
-// Same guarantee withoutResumeNote gives: an ordinary prompt is not a resume of anything.
 test("a prompt that is not a resume discloses nothing", () => {
     expect(resumeDisclosure("just a question")).toBeUndefined();
     expect(resumeDisclosure("")).toBeUndefined();

package/src/events/resume.ts

@@ -0,0 +1,60 @@
+import type { TurnNote } from "./transcript.js";
+
+// What a resumed turn's prompt says happened; lives on the wire since the client must recognise it too.
+
+// The shared prefix lets a joining window reuse the existing bubble, not render the note as a new message.
+// What follows the note is the original request repeated; `answered` carries the user's actual answer instead.
+const REPEATED =
+    "The interrupted request is repeated below, where part of it was already completed in this session, continue from that point instead of starting over.";
+export const RESUME_NOTES = {
+    auth: `The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically. ${REPEATED}`,
+    outage: `The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically. ${REPEATED}`,
+    restart: `The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back. ${REPEATED}`,
+    // Three notes, one allowance failure: `limit` continues, `switched` opens fresh, `refused` says the opposite.
+    limit: `The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again. ${REPEATED}`,
+    switched:
+        "The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again on a different account, which starts a fresh session. The conversation so far has been carried across above, including the part of the request that was already completed, and the sandbox has measured where the work actually stands (the files changed on this branch, what was verified, what the checklist still holds) in the note headed 'Where the work stands': trust that note over anything recalled, then continue from that point instead of starting over.",
+    // `carried` switches account but keeps the session, so REPEATED stays true here, unlike `switched`.
+    carried: `The model provider's usage allowance ran out while this turn was running, which stopped it, and it has been sent again on a different account of the same provider, in this same session: everything you knew is still here. ${REPEATED}`,
+    refused:
+        "The model provider refused the previous attempt at this request outright, because its usage allowance was spent: no part of the request below was read or acted on, and nothing has been done towards it. It has been sent again, and starts from the beginning. Where the sandbox has measured earlier work on this branch, it is in the note headed 'Where the work stands'.",
+    // A turn parked on the user when the daemon died; what follows the note is their actual answer, not a repeat.
+    answered:
+        "The sandbox restarted while this conversation was waiting for the user to respond; it is back, and their response follows below: continue from where the session left off.",
+} as const;
+
+// The prompt a resume actually sends: the note (each carries its own account of what follows), then the original words.
+export const withResumeNote = (prompt: string, note: string): string =>
+    Object.values(RESUME_NOTES).some((known) => prompt.startsWith(known)) ? prompt : `${note}\n\n${prompt}`;
+
+// The user's own words inside a resumed prompt, note and explanation stripped. Returns the prompt unchanged when it
+// isn't a resume, so any attach head can pass through it.
+export const withoutResumeNote = (prompt: string): string => {
+    const note = Object.values(RESUME_NOTES).find((known) => prompt.startsWith(known));
+    return note === undefined ? prompt : prompt.slice(prompt.indexOf("\n\n") + 2);
+};
+
+export type ResumeReason = keyof typeof RESUME_NOTES;
+
+// How a resumed turn's interruption reads to a person: `notice` for the whole-turn re-runs, a muted line with the
+// repeat dropped; `note` for the answered case, the user's real answer disclosed normally.
+export type ResumeDisclosure = { readonly kind: "notice"; readonly text: string } | { readonly kind: "note"; readonly note: TurnNote };
+
+const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
+    auth: { kind: "notice", text: "Claude sign-in renewed, this turn picked up where it left off." },
+    outage: { kind: "notice", text: "The model provider came back, this turn picked up where it left off." },
+    restart: { kind: "notice", text: "The sandbox came back, this turn picked up where it left off." },
+    // None of these four auto-resumed, a person pressed Continue; `switched`/`carried` name the differing account.
+    limit: { kind: "notice", text: "Sent again after the allowance ran out mid-turn, picking up where it left off." },
+    switched: { kind: "notice", text: "Sent again on the switched account after the allowance ran out mid-turn, in a fresh session." },
+    carried: { kind: "notice", text: "Sent again on the switched account after the allowance ran out mid-turn, carrying the session with it." },
+    refused: { kind: "notice", text: "Sent again after the allowance refused it: nothing had run." },
+    answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
+};
+
+// What a stored prompt's resume note should be shown as; undefined when the prompt isn't a resume, so any reader can
+// ask without checking first.
+export const resumeDisclosure = (prompt: string): ResumeDisclosure | undefined => {
+    const reason = (Object.keys(RESUME_NOTES) as ResumeReason[]).find((key) => prompt.startsWith(RESUME_NOTES[key]));
+    return reason === undefined ? undefined : RESUME_DISCLOSURES[reason];
+};

package/src/events/system-events.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { AgentSummarySchema } from "../schemas/agents.js";
+import { AccountUsageSchema, ProviderRefusalSchema } from "../schemas/plan-limits.js";
+import { MemberRoleSchema } from "../schemas/shared.js";
+
+// Frames about the sandbox rather than a turn: liveness, boot progress, what moved (repos, refs, running processes,
+// presence, the fleet), and account headroom. One stream carries them all.
+
+// One parsed line from `intentic … --output ndjson`; open-ended, so any string `kind` plus extra fields pass through.
+// The apply-events tail also mints `start`/`exit`/`heartbeat` sentinel kinds alongside the engine's own.
+export const IntenticLineSchema = z.looseObject({ kind: z.string() });
+export type IntenticLine = z.infer<typeof IntenticLineSchema>;
+
+// Liveness heartbeat; the browser's watchdog trips if frames stop. `rev` is the fleet revision as of an empty send
+// queue: a mismatch proves a dropped roster snapshot, and the browser re-fetches via GET /agents.
+export const HeartbeatSchema = z.object({ kind: z.literal("heartbeat"), rev: z.number() });
+export type Heartbeat = z.infer<typeof HeartbeatSchema>;
+
+// One step of the daemon's boot chain; `key` is its stable id, `label` the words shown. A failed step still counts as
+// finished: the boot chain logs and continues rather than holding the gate closed.
+export const BootStepSchema = z.object({
+    key: z.string(),
+    label: z.string(),
+    state: z.enum(["pending", "running", "done", "failed"]),
+    // Elapsed ms, once the step has finished.
+    ms: z.number().optional(),
+});
+export type BootStep = z.infer<typeof BootStepSchema>;
+
+// Where the daemon stands in its boot; listeners come up before state converges, so it can be reachable yet unable to
+// answer for a few seconds. The step list is sent whole, pending steps included, so the UI can name what's slow.
+export const BootProgressSchema = z.object({
+    // False only while the chain is still converging; the browser holds every daemon read until this is true.
+    ready: z.boolean(),
+    // Epoch ms the daemon started converging, so the browser can show elapsed time across a reconnect.
+    startedAt: z.number(),
+    steps: z.array(BootStepSchema),
+});
+export type BootProgress = z.infer<typeof BootProgressSchema>;
+
+// Pushed on every step transition and once more when the gate opens; rides /events, which answers before the gate so
+// this can be delivered while everything else waits.
+export const BootSchema = z.object({ kind: z.literal("boot"), ...BootProgressSchema.shape });
+export type Boot = z.infer<typeof BootSchema>;
+
+// The stream's first frame: `workspaceId` and `build` key the browser's persisted cache, so a wiped workspace or new
+// image doesn't hydrate stale data. `routes`/`shapes` turn a version-skewed 404 or missing field into a named gap.
+export const HelloSchema = z.object({
+    kind: z.literal("hello"),
+    workspaceId: z.string(),
+    routes: z.array(z.string()).optional(),
+    shapes: z.record(z.string(), z.string()).optional(),
+    build: z.string().optional(),
+    boot: BootProgressSchema.optional(),
+});
+export type Hello = z.infer<typeof HelloSchema>;
+
+// The full discovered repo set (sorted, root-relative ids), pushed on any change. The watcher ignores `.git`, so the
+// daemon diffs its own discovery instead of detecting a new repo from a path. Snapshot, not diff.
+export const ReposChangedSchema = z.object({ kind: z.literal("reposChanged"), repos: z.array(z.string()) });
+export type ReposChanged = z.infer<typeof ReposChangedSchema>;
+
+// A batch of workspace paths that changed on disk, root-relative forward-slash; the agent edits out-of-band so there's
+// no HTTP mutation to hang an invalidation on. An empty array means refetch the whole tree.
+export const WorkspaceChangedSchema = z.object({ kind: z.literal("workspaceChanged"), paths: z.array(z.string()) });
+export type WorkspaceChanged = z.infer<typeof WorkspaceChangedSchema>;
+
+// Repos whose refs moved (commit, checkout, branch, rebase); a repo's git dir lives outside /work and the watcher
+// ignores `.git`, so no workspace path can say this. Diff, not snapshot: an absent repo didn't move, it didn't vanish.
+export const RefsChangedSchema = z.object({ kind: z.literal("refsChanged"), repos: z.array(z.string()) });
+export type RefsChanged = z.infer<typeof RefsChangedSchema>;
+
+// Which running-thing domain just moved (a session, a port, a browser, a subagent); none of it lives on disk, so
+// `workspaceChanged` can't name it. Carries only the domain, never the roster, so an uninvolved tab pays no request.
+export const RuntimeChangedSchema = z.object({ kind: z.literal("runtimeChanged"), domains: z.array(z.string()) });
+export type RuntimeChanged = z.infer<typeof RuntimeChangedSchema>;
+
+// One connected browser tab of a sandbox member; identity from the verified Google ID token, activity from the tab's
+// own /system/presence reports. No timestamps: an entry lives exactly as long as its /events connection.
+export const PresenceUserSchema = z.object({
+    // Per-connection id, minted by the browser for each /events attempt, never reused across reconnects.
+    clientId: z.string(),
+    email: z.string(),
+    name: z.string().optional(),
+    picture: z.string().optional(),
+    // The caller's trust tier, resolved at connection time; on the roster so a tab can also read its own role.
+    role: MemberRoleSchema,
+    idle: z.boolean(),
+    // Route/view name the tab is on ("workspace", "automations", "ext:<id>/<key>", …).
+    view: z.string().optional(),
+    // The chat conversation the tab has active.
+    sessionId: z.string().optional(),
+    // The workspace file the tab has open (root-relative, forward-slash).
+    path: z.string().optional(),
+});
+export type PresenceUser = z.infer<typeof PresenceUserSchema>;
+
+// The full roster of connected members, broadcast on every change; snapshot not diff, so a reconnecting browser is
+// consistent from its first frame.
+export const PresenceSchema = z.object({ kind: z.literal("presence"), users: z.array(PresenceUserSchema) });
+export type Presence = z.infer<typeof PresenceSchema>;
+
+// The full fleet roster, snapshot per change; unlike presence, not last-frame-wins: the browser applies a frame only if
+// `rev` is newer, since GET /agents and optimistic writes can race it out of order.
+export const AgentsSchema = z.object({ kind: z.literal("agents"), agents: z.array(AgentSummarySchema), rev: z.number() });
+export type Agents = z.infer<typeof AgentsSchema>;
+
+// An account's headroom just moved, keyed as the daemon's store keys it. Snapshot per account, last frame wins; `usage`
+// absent means the account was disconnected.
+export const AccountUsageChangedSchema = z.object({
+    kind: z.literal("accountUsage"),
+    // The provider whose row this account is; the key alone doesn't say it (a native id is bare).
+    provider: z.string(),
+    account: z.string(),
+    usage: AccountUsageSchema.optional(),
+});
+export type AccountUsageChanged = z.infer<typeof AccountUsageChangedSchema>;
+
+// A provider's last refusal was recorded or settled, the observed half of "can I run on this". `refusal` absent means
+// settled, nothing stands.
+export const ProviderRefusalChangedSchema = z.object({ kind: z.literal("providerRefusal"), provider: z.string(), refusal: ProviderRefusalSchema.optional() });
+export type ProviderRefusalChanged = z.infer<typeof ProviderRefusalChangedSchema>;
+
+// The /events stream union: hello, heartbeats, boot progress, workspace/repo/ref/runtime changes, presence and fleet
+// rosters, account headroom and refusal changes. oRPC validates every frame against this.
+export const SystemEventSchema = z.discriminatedUnion("kind", [
+    HelloSchema,
+    HeartbeatSchema,
+    BootSchema,
+    WorkspaceChangedSchema,
+    ReposChangedSchema,
+    RefsChangedSchema,
+    RuntimeChangedSchema,
+    PresenceSchema,
+    AgentsSchema,
+    AccountUsageChangedSchema,
+    ProviderRefusalChangedSchema,
+]);
+export type SystemEvent = z.infer<typeof SystemEventSchema>;