@intentic/sandbox-contract 1.232.0 → 1.233.0

package/src/events.ts

@@ -1,18 +1,12 @@
 import { z } from "zod";
-import {
-    AgentProviderSchema,
-    AgentReplySchema,
-    AgentSummarySchema,
-    FastModeStateSchema,
-    LandConflictSchema,
-    MemberRoleSchema,
-    PermissionModeSchema,
-    RateLimitInfoSchema,
-    ShareDetailSchema,
-    SubagentKindSchema,
-    SubagentStatusSchema,
-    UsageWindowSchema,
-} from "./schemas.js";
+import { AgentProviderSchema, PermissionModeSchema } from "./schemas/agent.js";
+import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
+import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
+import { FastModeStateSchema } from "./schemas/fast-mode.js";
+import { AgentReplySchema, UsageWindowSchema } from "./schemas/plan-limits.js";
+import { ShareDetailSchema } from "./schemas/share.js";
+import { MemberRoleSchema } from "./schemas/shared.js";
+import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "./schemas/terminal.js";
 
 // The wire shapes streamed from the daemon's event-iterator procedures. This is their canonical home: the
 // daemon yields them and the browser client consumes them from the same schema, so the two can't drift (they
@@ -35,6 +29,29 @@ export const AskQuestionSchema = z.object({
 });
 export type AskQuestion = z.infer<typeof AskQuestionSchema>;
 
+/* THE PROGRAM A COMMAND CARD IS HOLDING, as the thing it is rather than as prose about it.
+ *
+ * It used to ride in `description`, the field every other permission ask fills with a sentence, which left the
+ * card with no way to know it was holding four hundred characters of shell: it rendered them as a paragraph,
+ * wrapped mid-flag, and the fragment that caused the hold was somewhere in the middle of it.
+ *
+ * `spans` is the gate's own evidence, computed by the classifier at the moment the rule fired (contract's
+ * command-classes.ts, matchCommand) and carried rather than re-derived: a browser that re-ran the patterns
+ * would be a second classifier, and the day the two disagreed the card would be marking a fragment that is not
+ * the one anybody was held for. Offsets are into `text` AFTER truncation, so they are always paintable.
+ *
+ * `language` is a Shiki grammar id, and the two are the two execution backends the gate reads (command-gate's
+ * EXECUTION_SOURCES): a shell line and a script. */
+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 the head of a longer program, so the card can say so instead of ending mid-word."),
+    spans: z
+        .array(z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }))
+        .describe("Which fragments of the text put it in the class that held it. Offsets into text, in order, never overlapping."),
+});
+export type ProgramAsk = z.infer<typeof ProgramAskSchema>;
+
 // One per-tool permission prompt (the SDK's canUseTool callback, surfaced as a card). The daemon passes the
 // bridge's own rendered strings through rather than re-deriving them, so the prompt reads exactly as Claude
 // Code words it. `alwaysLabel` is present only when the SDK offered rules to persist, without it the card
@@ -56,6 +73,15 @@ export const PermissionAskSchema = z.object({
         .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.",
+    ),
+    explain: z
+        .string()
+        .optional()
+        .describe(
+            "One plain sentence saying what the program does and why the agent wants it. Written by the quick model, never by the agent being gated, and only when the owner switched the setting on.",
+        ),
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
 
@@ -360,8 +386,9 @@ export const RestoredMessageSchema = z.object({
     thinking: z.string().optional().describe("What the agent was reasoning about."),
     tools: z.array(RestoredToolCallSchema).optional().describe("The tool calls this part of the turn made."),
     /* What the daemon added to this turn's message (user rows only), the same notes the live `preamble` frame
-     * carries, recovered from the stored prompt when the transcript is read back. The reader that strips them out
-     * of the user's words is the one that hands them over here instead of dropping them on the floor.
+     * carries. A daemon-recorded turn takes them straight off that frame in its own log, typed end to end
+     * (sessions/turn-transcript.ts); only a conversation adopted from a provider's session store recovers them
+     * by parsing the composed prompt kept there, the one store the daemon never wrote typed.
      *
      * On the message rather than as a row of its own, and that matters twice: they ARE part of what was
      * sent, and a record row per turn preamble would break the one-row-per-bubble correspondence a branch counts
@@ -489,8 +516,9 @@ export type ParkedCard = z.infer<typeof ParkedCardSchema>;
 // ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
 // (delta/thinking/tool_call/tool_call_update/todos/usage/rate_limit_info/account_usage/context_usage/init/compact); any SDK message
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
-// `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
-// permission posture as the agent changes it.
+// `POST /agent/reply` side channel, and `resolved` releases the one it names; `permission_note` adds a sentence
+// to a permission card already on screen without settling it; `mode` reports the live permission posture as the
+// agent changes it.
 // `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
 // subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
@@ -554,12 +582,14 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * way to find out what those instructions said. This frame is the fix: the note text verbatim, one entry per
      * note, rendered collapsed so it costs a click rather than a scroll.
      *
-     * `title` is the note's own opening header, which is what the stripper already anchors on, so the two
-     * cannot drift, and a note nobody thought to title cannot reach the wire unlabelled.
+     * Emitted from the TYPED notes the wire prompt is serialized from at the same point (turn-preamble.ts,
+     * composeWirePrompt), so the disclosure and what the model receives cannot drift: a note is in both or in
+     * neither, and a note nobody thought to title cannot reach the wire unlabelled.
      *
      * ONE MOMENT, always: the notes went in front of the user's own message before the turn started, so they hang
-     * off that message and are stored on it, which is how a reopened tab still has them. Nothing is injected into
-     * a RUNNING turn, the rebase taken while a card sat waiting was the only thing that ever was, and it no
+     * off that message and are stored on it, the transcript fold reads this very frame out of the turn's own
+     * frame log (sessions/turn-transcript.ts), which is how a reopened tab still has them. Nothing is injected
+     * into a RUNNING turn, the rebase taken while a card sat waiting was the only thing that ever was, and it no
      * longer says anything to the model at all (agent/turn-preamble.ts). */
     z.object({ kind: z.literal("preamble"), notes: z.array(TurnNoteSchema) }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
@@ -666,6 +696,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         lastTool: z.string().optional(),
         summary: z.string().optional(),
         error: z.string().optional(),
+        // Whether anything checked the work the report describes (SubagentVerificationSchema). Rides the frame
+        // that ENDS the child, beside the report itself, so the card carries both at once.
+        verification: SubagentVerificationSchema.optional(),
     }),
     z.object({ kind: z.literal("todos"), items: z.array(TodoItemSchema) }),
     // The provider's own slash commands (ACP available_commands_update), replaced whole each time, the
@@ -875,6 +908,19 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // already moved on. It rides verbatim, exactly as the client POSTed it; absent, nobody answered (the turn
     // was stopped, or died under the card), which is not a decision and must not replay as one.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
+    /* A LATE SENTENCE FOR A CARD ALREADY ON SCREEN: the quick model's plain-language reading of a held command,
+     * landing on the permission card named by `requestId` (see PermissionAsk.explain).
+     *
+     * A frame of its own rather than a field on the card, because the card MUST NOT WAIT FOR IT. This is a
+     * safety prompt and the turn is parked on it; a quick-model rung can take tens of seconds before the chain
+     * steps down (agent/quick-model.ts measured one at 58), and holding the card back for that reads exactly
+     * like the agent freezing, which is the failure the explanation was meant to prevent rather than cause. So
+     * the card goes out complete and unexplained, and this arrives if and when it does. Same shape and the same
+     * reason as `service_event`, which streams a running service's status onto an offer already rendered.
+     *
+     * Never arrives at all when the setting is off, when nothing is connected to answer, or when the user
+     * settles the card first, and none of those change what the card says. */
+    z.object({ kind: z.literal("permission_note"), requestId: z.string(), explain: z.string() }),
     // The turn's permission mode, whenever it changes, the user's pick at turn start, then every move the
     // AGENT makes on its own (EnterPlanMode on a request that needs thinking through, ExitPlanMode once the
     // user approves). The composer's mode selector follows this, so the UI never lies about the live posture.
@@ -955,6 +1001,22 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                  * context-window-too-small does: they never reached a provider, and losing them to a
                  * capacity fact the user did not cause would be ours to answer for. */
                 "sandbox-memory-low",
+                /* THE LOOP RAN OUT OF ITERATIONS, not out of work: the runtime hit its own turn ceiling and
+                 * stopped. Nothing failed, nothing is disconnected and nothing is spent, which is exactly why
+                 * it needs a code of its own rather than a sentence: it is the one ending that LOOKS like a
+                 * finished turn from the outside, and a ledger that filed it as an ordinary error told a
+                 * reader nothing they could act on.
+                 *
+                 * The recovery is the user's, not the daemon's: whatever the turn was doing is half done, and
+                 * re-running it blind would either redo the finished half or resume work nobody looked at. */
+                "turn-cap",
+                /* THE HARNESS ENDED THE TURN WITHOUT SUCCEEDING and did not say why in terms anything here
+                 * models: an internal execution error, or a result subtype a later vendor build invented. The
+                 * sentence carries the subtype verbatim, because that word is the only thing separating two of
+                 * these, and a code that meant "one of several unrelated things" would be worse than none. It
+                 * is a real classification all the same: it says the failure came from the LOOP rather than
+                 * from the provider, the credential or the request, which rules out every recovery next door. */
+                "harness-incomplete",
             ])
             .optional(),
         // rate_limit only: when the exhausted window reopens (epoch seconds, from the stream's own

package/src/fast-tier.ts

@@ -1,6 +1,6 @@
 import { compareCheapestFirst, isCheaperRung } from "./model-order.js";
 import { parsePinned } from "./quick-model.js";
-import type { AgentProvider } from "./schemas.js";
+import type { AgentProvider } from "./schemas/agent.js";
 
 /* WHICH MODEL A DOWNGRADED TURN ACTUALLY RUNS ON, the second half of automatic tier selection.
  * prompt-complexity.ts decides a turn COULD be cheaper; this decides whether there is anything cheaper to put

package/src/history-state.ts

@@ -128,6 +128,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
     { path: "sync-pair-consumed.json", portability: "identity" },
     { path: "host-enrollments.json", portability: "identity" },
+    /* A connected BROWSER's enrollment (webext/webext-store.ts). Identity for the hosts file's reason and one
+     * more of its own: the token admits a socket into somebody's signed-in browser, and that browser was paired
+     * with THIS sandbox — carried into another one it would either be dead weight or, worse, a second sandbox
+     * holding a live key to a browser its owner never connected it to. Re-pairing is a code and one click. */
+    { path: "webext-enrollments.json", portability: "identity", note: "Pair your browser again from its card: the extension is still installed." },
     // The burn list for setup-time computer pairings. Identity, like sync's beside it, and for a sharper reason:
     // carrying it into another sandbox would mark that sandbox's own fresh pairing as already spent.
     { path: "host-pair-consumed.json", portability: "identity" },

package/src/host-protocol.ts

@@ -24,7 +24,7 @@ export const HostHelloSchema = z.object({
      * onto one-shot tickets, auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
      * arrives the socket is anonymous and short-lived: the daemon closes it in seconds if it never does. */
     token: z.string(),
-    // The @intentic/host build the machine is running, surfaced per machine so an old binary is visible rather
+    // The @intentic/machine build the machine is running, surfaced per machine so an old binary is visible rather
     // than mysteriously missing a tool. What the machine IS (`describe`) is not here: it is pulled over the
     // typed link a moment later, so there is one definition of those facts rather than two.
     version: z.string(),

package/src/hostnames.test.ts

@@ -25,8 +25,8 @@ test("preview and port hostnames round-trip through their Host-header parsers",
 });
 
 test("the two schemes never bleed into each other, and stray/wrong-id hosts parse to nothing", () => {
-    expect(portSlotFromHost("preview-app-" + ID + ".example.com", ID)).toBeUndefined();
-    expect(panelFromHost("port-a-" + ID + ".example.com", ID)).toBeUndefined();
+    expect(portSlotFromHost(`preview-app-${ID}.example.com`, ID)).toBeUndefined();
+    expect(panelFromHost(`port-a-${ID}.example.com`, ID)).toBeUndefined();
     expect(panelFromHost("app.example.com", ID)).toBeUndefined();
     expect(panelFromHost(`preview-app-000000000000.example.com`, ID)).toBeUndefined();
     expect(portSlotFromHost(`port-a-000000000000.example.com`, ID)).toBeUndefined();

package/src/index.ts

@@ -59,6 +59,9 @@ export { historyContract } from "./contracts/history.contract.js";
 /* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
  * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
+// The same inversion again, one layer in: spoken over the socket a BROWSER EXTENSION opened, with the
+// extension implementing it (contracts/webext.contract.ts).
+export { webextContract } from "./contracts/webext.contract.js";
 // Same inversion, other direction of trust: spoken over a RUNNER's WebSocket, with the runner implementing it.
 export { runnerContract } from "./contracts/runner.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
@@ -104,11 +107,14 @@ export * from "./history-state.js";
 export * from "./agent-catalog.js";
 export * from "./agent-run-model.js";
 export * from "./capability-env.js";
+export * from "./command-classes.js";
 export * from "./capability-secrets.js";
 export * from "./conversation-ids.js";
 export * from "./documents.js";
 export * from "./fast-tier.js";
 export * from "./host-protocol.js";
+export * from "./webext-protocol.js";
+export * from "./webext-links.js";
 export * from "./runner-protocol.js";
 export * from "./listener-protocol.js";
 export * from "./hostnames.js";
@@ -118,7 +124,60 @@ export * from "./prompt-complexity.js";
 export * from "./quick-model.js";
 export * from "./output-fields.js";
 export * from "./publish-drafts.js";
-export * from "./schemas.js";
+/* The wire shapes, one module per subject area, mirroring `contracts/` above: every request and response the
+ * daemon speaks is declared in exactly one of them. Inputs that carry a `{param}` in their route path (repo /
+ * id / name) merge the path param into the same flat object, oRPC fills the path placeholder from the matching
+ * key and routes the rest to the body (POST/PUT) or query (GET).
+ *
+ * `schemas/internal.ts` is deliberately absent: it holds the id and ref primitives these modules are written
+ * in, which are vocabulary rather than shapes either side of the wire sends. */
+export * from "./schemas/activity.js";
+export * from "./schemas/agent.js";
+export * from "./schemas/agents.js";
+export * from "./schemas/automations.js";
+export * from "./schemas/capabilities.js";
+export * from "./schemas/ci.js";
+export * from "./schemas/claude-gate.js";
+export * from "./schemas/codebase-health.js";
+export * from "./schemas/computers.js";
+export * from "./schemas/drafts.js";
+export * from "./schemas/environment.js";
+export * from "./schemas/exit.js";
+export * from "./schemas/extension-updates.js";
+export * from "./schemas/fast-mode.js";
+export * from "./schemas/git.js";
+export * from "./schemas/git-history.js";
+export * from "./schemas/history.js";
+export * from "./schemas/hosts.js";
+export * from "./schemas/intentic.js";
+export * from "./schemas/inventory.js";
+export * from "./schemas/logs.js";
+export * from "./schemas/loops.js";
+export * from "./schemas/maintenance.js";
+export * from "./schemas/marketplace.js";
+export * from "./schemas/panels.js";
+export * from "./schemas/personas.js";
+export * from "./schemas/plan-limits.js";
+export * from "./schemas/ports.js";
+export * from "./schemas/provider-oauth.js";
+export * from "./schemas/provider-subscriptions.js";
+export * from "./schemas/public.js";
+export * from "./schemas/push.js";
+export * from "./schemas/secrets.js";
+export * from "./schemas/sessions.js";
+export * from "./schemas/settings.js";
+export * from "./schemas/share.js";
+export * from "./schemas/shared.js";
+export * from "./schemas/system.js";
+export * from "./schemas/terminal.js";
+export * from "./schemas/usage.js";
+export * from "./schemas/vpn.js";
+export * from "./schemas/webext.js";
+export * from "./schemas/workflows.js";
+export * from "./schemas/workspace-repos.js";
+export * from "./schemas/workspace-search.js";
+export * from "./schemas/workspace-setup.js";
+export * from "./schemas/workspace-tree.js";
 export * from "./definition.js";
 export * from "./search-globs.js";
 export * from "./starter.js";

package/src/listener-protocol.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ActivityStatusSchema } from "./schemas.js";
+import { ActivityStatusSchema } from "./schemas/activity.js";
 
 /* The wire between the daemon and an extension's realtime-listener GATEWAY process (ext-discord, ext-slack,
  * ext-telegram, ext-whatsapp, ext-imap): the four provider-scoped routes app.ts mounts under

package/src/quick-model.ts

@@ -1,6 +1,6 @@
 import { ACCESS_COST, accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js";
 import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
-import type { AgentProvider } from "./schemas.js";
+import type { AgentProvider } from "./schemas/agent.js";
 
 /* THE QUICK MODEL, the cheap, fast model a small automatic job spends instead of the frontier model the chat
  * runs on. Today that is the commit message written when an agent's work lands; anything else of that shape (a

package/src/runner-protocol.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { DefinitionActionSchema } from "./definition-action.js";
 
 /* THE RUNNER LINK'S EDGES: the handshake on /system/runners/connect, the env a runner boots with, and the
  * placement value a turn request carries. The procedures spoken over the link once it exists live in
@@ -30,6 +31,13 @@ export const RunnerHelloSchema = z.object({
     image: z.string(),
     channel: z.string().optional(),
     overlayHash: z.string().optional(),
+    /* The runner's DECLARED SHAPE, as the definition format spells it (definition.ts): a sandbox.toml whose
+     * only populated section is settings, because that is all a runner declares — capabilities and secrets
+     * never travel to one, and its repos are a mirror of the parent's git rather than clones with remotes.
+     * The parent diffs this against its own settings to itemize drift (a stale toolchain is a rebuild; a
+     * drifted setting is one applyDefinition call over this same socket), so parity stops being a bare
+     * "outdated" and becomes lines naming what differs. Absent on an image too old to derive one. */
+    definitionToml: z.string().optional(),
 });
 export type RunnerHello = z.infer<typeof RunnerHelloSchema>;
 
@@ -44,7 +52,8 @@ export const runnerEnrollUrl = (parentUrl: string): string => `${parentUrl.repla
  * parent serves from its real git dirs (<historyRoot>/gits/<encoded id>), authenticated by the runner's own
  * token as a bearer. One builder because three parties spell it: the parent's route, the runner's sync, and
  * anyone debugging with a hand-typed clone. */
-export const runnerGitUrl = (parentUrl: string, repo: string): string => `${parentUrl.replace(/\/$/, "")}/system/runners/git/${encodeURIComponent(repo)}`;
+export const runnerGitUrl = (parentUrl: string, repo: string): string =>
+    `${parentUrl.replace(/\/$/, "")}/system/runners/git/${encodeURIComponent(repo)}`;
 
 /* Where a runner's push LANDS in the parent's git dirs. Never refs/heads/agent/<id> directly: that branch is
  * checked out in the parent's mirror worktree, and git itself refuses updating a checked-out ref, which is a
@@ -52,6 +61,12 @@ export const runnerGitUrl = (parentUrl: string, repo: string): string => `${pare
  * the mirror worktree to this ref, which advances the checked-out branch through the door git sanctions. */
 export const runnerIncomingRef = (conversationId: string): string => `refs/runner-incoming/${conversationId}`;
 
+/* THE CONTAINER A RUNNER'S NAME MEANS on the machine holding it, which is how the update and rebuild flows
+ * address it. The prefix is `ic`'s own (runner.rs SLUG_PREFIX) and the two must stay identical: a mismatch
+ * does not fail loudly, it sends an update at a container that does not exist and reports "no such sandbox"
+ * about a runner sitting right there in the list. */
+export const runnerSlug = (name: string): string => `runner-${name}`;
+
 /* THE CREDENTIAL DOORS: a runner's turns spend the ORIGIN sandbox's model providers, never accounts of their
  * own. The shape is a service, not a sync: the parent resolves each turn's credential with the same code its
  * local turns use and answers with the least that travels — an access token minted for the turn, or a route.
@@ -128,10 +143,20 @@ export const RunnerFactsSchema = z.object({
 });
 export type RunnerFacts = z.infer<typeof RunnerFactsSchema>;
 
+/* WHETHER IT IS RUNNING WHAT THIS SANDBOX IS RUNNING (§7 of the design): `current` matches on image, channel
+ * and approved overlay; `outdated` differs on one of them and gets the update button; `unknown` is a runner
+ * that has never connected, or a parent that cannot name its own image (a dev daemon), where a warning would
+ * be one nobody can act on. Reported, never enforced: an outdated runner still runs turns. */
+export const RunnerParitySchema = z.enum(["current", "outdated", "unknown"]);
+export type RunnerParity = z.infer<typeof RunnerParitySchema>;
+
 // One runner as the owner's views list it: enrolled state plus whatever the hub knows right now, the
 // HostSummary shape retold for a runner (no platform/scopes, parity instead).
 export const RunnerSummarySchema = z.object({
     id: z.string(),
+    // The connected computer holding it, when this sandbox is what asked for it (the Computers view's create
+    // flow). Absent for one started by hand on a machine, which this sandbox can dispatch to but not manage.
+    host: z.string().optional(),
     online: z.boolean(),
     version: z.string().optional(),
     image: z.string().optional(),
@@ -139,6 +164,14 @@ export const RunnerSummarySchema = z.object({
     overlayHash: z.string().optional(),
     facts: RunnerFactsSchema.optional(),
     lastSeen: z.number().optional(),
+    // Computed by the daemon (runners/runner-parity.ts) rather than by each surface, so the badge on a row and
+    // the note in the placement picker cannot disagree about the same runner.
+    parity: RunnerParitySchema,
+    /* Where the runner's environment stands against this sandbox's, one line per difference (the definition
+     * surface's drift unit, computed parent-side from the hello's definitionToml plus the overlay hashes).
+     * Absent when the runner never said, empty when they agree. Lines whose subject is a Setting are fixable
+     * over the live link (the sync door); an overlay line takes a rebuild. */
+    drift: z.array(DefinitionActionSchema).optional(),
 });
 export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
 
@@ -202,8 +235,5 @@ export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
  * client sends them. `runner` implies isolation, a remote conversation is always branch-anchored, because its
  * branch is the unit that moves between machines. Absent means local, which is why this is optional
  * everywhere: the default costs nothing to anyone who never uses it. */
-export const AgentPlacementSchema = z.union([
-    z.object({ kind: z.literal("local") }),
-    z.object({ kind: z.literal("runner"), id: z.string().min(1) }),
-]);
+export const AgentPlacementSchema = z.union([z.object({ kind: z.literal("local") }), z.object({ kind: z.literal("runner"), id: z.string().min(1) })]);
 export type AgentPlacement = z.infer<typeof AgentPlacementSchema>;

package/src/schemas/activity.ts

@@ -0,0 +1,123 @@
+// activity: the activity audit log (historyRoot/activity.jsonl)
+import { z } from "zod";
+import { AgentOriginSchema } from "./agent.js";
+// One provider-agnostic event per agent↔provider interaction, appended by the daemon only (never the agent,
+// the log lives under historyRoot, outside /work, so the agent can't read or rewrite its own trail). Discord
+// is the first source; other cli providers reuse the same shape.
+
+export const ActivityEventSchema = z.object({
+    id: z.string().describe("The entry's own id."),
+    // Epoch ms; also the paging cursor.
+    at: z.number().describe("When it happened, in milliseconds. Also what you page by."),
+    // "discord", …; absent on provider-less system events (a cron automation.run).
+    provider: z.string().optional().describe("Which outside service, when one was involved. Absent for the sandbox's own events."),
+    // Which provider account handled the turn, the attribution key for per-account usage totals. Absent on
+    // provider-less events and turns that ran on the provider's default account.
+    account: z
+        .string()
+        .optional()
+        .describe("Which account handled it. Absent for the sandbox's own events and for work run on a provider's default."),
+    direction: z.enum(["in", "out", "system"]).describe("Whether something arrived, something went out, or the sandbox did it to itself."),
+    // in: message.received | voice_utterance.received | voice_transcript.received
+    // out: message.send | reaction.add | messages.read | api.call (unclassified provider endpoint)
+    // system: gateway.login_failed | dispatch.failed | voice.session_started | voice.session_ended | automation.run
+    //         | turn.started | turn.plan | turn.error | turn.completed (agent turn lifecycle; provider = claude/codex)
+    //         | rule.blocked_push | rule.held_work | rule.continued_turn (a rule DID something, see RuleSchema.
+    //           Only the three outcomes a person would otherwise have no explanation for: a push that did not
+    //           go, work that did not arrive, a turn that did not end. A rule that ran and passed says nothing,
+    //           because a feed that logs every green check is one the eye learns to skip.)
+    type: z
+        .string()
+        .describe(
+            "Exactly what happened: a message received or sent, a reaction, a turn starting or ending, a rule doing something. A rule that ran and passed says nothing here, because a feed of green ticks is one the eye learns to skip.",
+        ),
+    channelId: z.string().optional().describe("Which channel or thread it happened in."),
+    // Inbound author display name.
+    author: z.string().optional().describe("Who sent it, for something that arrived."),
+    // Full message text (inbound) or sent payload content (outbound).
+    content: z.string().optional().describe("The message, in full, whichever direction it went."),
+    // Outbound HTTP method + endpoint path (tokens ride headers, never URLs).
+    method: z.string().optional().describe("The verb of an outgoing call."),
+    endpoint: z.string().optional().describe("The address of an outgoing call. Credentials travel in headers, so they are never here."),
+    // The agent turn that made/handled it, the join key between an inbound wake and its outbound calls.
+    sessionId: z.string().optional().describe("The provider session behind it."),
+    /* ONE TURN'S EVENTS, TIED TOGETHER. A turn writes four lifecycle events plus one per outbound provider call,
+     * and read as five rows they say one thing five times, so the feed groups on this instead. It cannot be
+     * sessionId: the runtime does not mint one until the stream's first frame, which is AFTER turn.started, so
+     * the very event carrying the prompt is the one that could never be joined. Minted by the turn itself. */
+    turnId: z
+        .string()
+        .optional()
+        .describe(
+            "Ties one turn's entries together. A turn writes several, and read as separate rows they say one thing several times, so a feed groups on this.",
+        ),
+    // The stable conversation the turn belongs to. Outlives sessionId, which a provider/account/harness switch
+    // retires mid-conversation, so this, not sessionId, is what "the same agent" means across a feed.
+    conversationId: z
+        .string()
+        .optional()
+        .describe(
+            "Which conversation. This, rather than the provider session, is what the same agent means across a feed, because a session is retired whenever the model changes.",
+        ),
+    // The conversation's display title as it stood when the event was written. Denormalised on purpose: the
+    // registry entry it came from is prunable and renameable, and an audit row must still read as words years
+    // later. Absent on the first event of a fresh conversation, the auto-namer has not run yet.
+    title: z
+        .string()
+        .optional()
+        .describe(
+            "What that conversation was called at the time. Copied in rather than looked up, because an audit entry must still read as words years later, after the conversation has been renamed or pruned.",
+        ),
+    // What woke the conversation from outside, when something did (see AgentOriginSchema), the feed's "who
+    // called me" attribution, and how a turn is filed under Discord rather than under the runtime that served it.
+    origin: AgentOriginSchema.optional().describe(
+        "What woke the conversation from outside, when something did. It is how a turn gets filed under the chat service that caused it rather than under the model that served it.",
+    ),
+    automationIds: z.array(z.string()).optional().describe("Which automations were involved."),
+    outcome: z.enum(["ok", "error"]).optional().describe("How it ended."),
+    error: z.string().optional().describe("What went wrong, when something did."),
+    // Source-specific detail: guildId, attachments, transcript path, participants…
+    extra: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Whatever else the source had to say: attachments, participants, a recording's path. Shape varies by source."),
+});
+export type ActivityEvent = z.infer<typeof ActivityEventSchema>;
+export const ActivityQuerySchema = z.object({
+    provider: z.string().optional().describe("Narrow it to one outside service."),
+    limit: z.coerce.number().min(1).max(500).default(100).describe("How many entries to return."),
+    // `at` cursor, exclusive, newest-first paging.
+    before: z.coerce.number().optional().describe("Only entries older than this timestamp, so paging walks backwards through the feed."),
+});
+export type ActivityQuery = z.infer<typeof ActivityQuerySchema>;
+export const ActivityListSchema = z.object({ events: z.array(ActivityEventSchema).describe("The audit entries, newest first.") });
+// Live connection health, probed per provider capability (not stored): gateway state from the client pool
+// (idle = the gateway is up but has no enabled listener automation to connect for, distinct from a
+// connection that should be up but isn't; pairing = the socket is up but the credential is a ceremony nobody
+// has finished, which no amount of waiting fixes), lastError from the newest system-error event in the log.
+export const ActivityConnectionSchema = z.object({
+    capabilityId: z.string().describe("Which connection."),
+    provider: z.string().describe("Which service it is."),
+    gateway: z
+        .enum(["ready", "connecting", "pairing", "disconnected", "idle"])
+        .describe(
+            "Idle means it is up but has nothing to listen for, which is different from a connection that should be up and is not. Pairing means somebody started a sign-in and never finished it, which no amount of waiting will fix.",
+        ),
+    lastError: z.string().optional().describe("The most recent thing that went wrong on it."),
+});
+export const ActivityStatusSchema = z.object({
+    connections: z
+        .array(ActivityConnectionSchema)
+        .describe("Each source feeding the record, and whether it is working. Probed now rather than remembered."),
+    // The daemon's live voice session, when one is up.
+    voice: z
+        .object({
+            channelId: z.string().describe("Which channel."),
+            channelName: z.string().describe("What it is called."),
+            startedAt: z.number().describe("When it joined, in milliseconds."),
+            participants: z.array(z.string()).describe("Who else is in it."),
+        })
+        .optional()
+        .describe("A voice call the sandbox is currently in, when it is in one."),
+});
+export type ActivityStatus = z.infer<typeof ActivityStatusSchema>;