@intentic/sandbox-contract 1.240.0 → 1.243.0

package/src/schemas/agent.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { KEY_PROVIDERS, NATIVE_PROVIDERS } from "../provider-specs.js";
 import { AgentPlacementSchema } from "../runner-protocol.js";
 import { entryId } from "./internal.js";
 // The agent runtimes the daemon can serve, the vocabulary every surface that picks an agent shares (chat
@@ -8,16 +9,23 @@ import { entryId } from "./internal.js";
 // ACP (Agent Client Protocol).
 // Kept as a bare string on the wire (not an enum) so an unknown id is a clean error frame from the agent
 // route, the same bet RepoParamSchema makes, and adding an ACP agent needs no contract change.
-export const NATIVE_PROVIDERS = ["claude", "codex", "grok", "kimi", "gemini", "cursor"] as const;
-export type NativeProvider = (typeof NATIVE_PROVIDERS)[number];
+//
+// NATIVE_PROVIDERS itself is DERIVED from the one row-per-provider table (provider-specs.ts) and imported
+// here rather than written out again, so the wire vocabulary cannot name a provider the product does not
+// describe, or miss one it does.
 export const AgentProviderSchema = z.string().min(1);
 export type AgentProvider = z.infer<typeof AgentProviderSchema>;
 // The provider naming a catalog in the one route every native provider shares (providers.contract.ts). An ENUM
 // rather than the bare-string schema above, and deliberately so: the open vocabulary exists because an ACP agent
 // or an endpoint can be added without a contract change, but neither has a daemon-held catalog, this route's
-// subjects are exactly the five the daemon keeps one for. Closing it here is what makes an unknown id a 400 from
+// subjects are exactly the ones the daemon keeps one for. Closing it here is what makes an unknown id a 400 from
 // the contract instead of a registry lookup that reads back `undefined` and serves an empty list.
 export const NativeProviderParamSchema = z.object({ provider: z.enum(NATIVE_PROVIDERS) });
+// The provider naming an account on the routes that connect one by pasting a key (keys.contract.ts). Closed the
+// same way and for the same reason as the catalog param above, narrowed to the providers whose credential this
+// daemon actually stores as a key: pasting one at a provider that authenticates some other way is a 400 from
+// the contract rather than a handler discovering there is no store to write to.
+export const KeyProviderParamSchema = z.object({ provider: z.enum(KEY_PROVIDERS) });
 // The harness (agentic loop) a turn runs on, orthogonal to the provider. See AgentTurnSchema.harness.
 export const AgentHarnessSchema = z.enum(["native", "claude-code"]);
 export type AgentHarness = z.infer<typeof AgentHarnessSchema>;
@@ -275,7 +283,7 @@ export const AgentTurnSchema = z
          * opposite defaults, the chat wants the provider's own catalog default, an unattended run wants the
          * tier its owner chose for work that spends money while they are not watching.
          *
-         * The daemon fills `agent`/`model`/`effort` from agentRunModels/agentRunEffort for any turn that says
+         * The daemon fills `agent`/`model` and the pinned entry's own knobs from agentRunModels for any turn that says
          * this and names none of them (startConversationTurn), walking that list until one can actually be
          * started. Naming one still wins: every surface-started run now carries a caret that overrides the list
          * for that run alone, and Acceptance picks per run because it fans a session out per story. Either way
@@ -384,7 +392,14 @@ export type AgentTurn = z.infer<typeof AgentTurnSchema>;
  *
  * Both halves or neither, because a model id is only meaningful to the provider that vends it: half a pick
  * would send a Codex model id to Claude. Routes that accept this pass it through verbatim; a model this build
- * has never heard of is a supported pick, since the picker offers a custom-id escape hatch. */
+ * has never heard of is a supported pick, since the picker offers a custom-id escape hatch.
+ *
+ * AND THE TIER IT RUNS AT, because naming a model is only half of what the standing setting says. A pinned
+ * entry carries its own effort (AgentRunPinSchema), and the daemon applies the pin's knobs ONLY to a turn that
+ * named no model (turn-resume.ts): so a caret that could re-point the model but not the tier moved every
+ * override onto the provider's own default effort, and the one moment somebody reaches for the caret is the
+ * failure that just beat the standing order. Optional, and absent means absent, the turn goes out without an
+ * effort and the model's own answers. */
 export const AgentRunPickSchema = z
     .object({
         agent: z.string().min(1).describe("Which provider."),
@@ -392,31 +407,61 @@ export const AgentRunPickSchema = z
             .string()
             .min(1)
             .describe("Which of its models. Both or neither, because a model name only means anything to the provider that serves it."),
+        effort: z
+            .string()
+            .optional()
+            .describe("How hard that model should think, where it offers a choice. Leave it out to take the model's own default."),
     })
     .optional();
 export type AgentRunPick = z.infer<typeof AgentRunPickSchema>;
+/* A MODEL PINNED FOR EVERY SURFACE-STARTED RUN, one entry of settings.agentRunModels: the standing version of
+ * the pick above, and not merely which model but HOW it is to be run.
+ *
+ * THE KNOBS RIDE THE ENTRY RATHER THAN THE LIST, which is the whole reason this is an object where the setting
+ * used to hold a `${provider}:${model}` string. The reasoning effort was a single field beside the list, so one
+ * tier answered for every model in it — and the entries of that list are deliberately NOT interchangeable: it
+ * is a frontier pin with the cheap account underneath that catches it when the first is spent. A tier scale is
+ * a property of the MODEL as well ('max' is off Kimi's scale entirely, and off Claude's own the moment thinking
+ * is switched off), so a shared effort was either off-scale for half the list or the lowest common rung for all
+ * of it. Each entry now carries what the composer's picker configures for the turn in front of you.
+ *
+ * EVERY FIELD BUT THE PAIR IS OPTIONAL, AND ABSENT MEANS ABSENT: the turn goes out without the field and the
+ * provider's own default answers, exactly as an unconfigured pin always did. Nothing here invents a "low".
+ *
+ * NO TIER HOLD, and its absence is the rule rather than an omission: automatic tier selection gates on
+ * `unattended` (prompt-complexity.ts), so a surface-started run is never downgraded in the first place and a
+ * veto over it would be a control whose state can make no difference to anything.
+ *
+ * The pair is BOTH HALVES for the reason the pick above is: a model id is only meaningful to the provider that
+ * vends it, so half a pin would send a Codex id to Claude. Taken verbatim, never validated against a catalog:
+ * the picker offers a custom-id escape hatch, so a model this build has never heard of is a supported pin. */
+export const AgentRunPinSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves the run."),
+    model: z.string().min(1).describe("Which of its models. Both halves, because a model name only means anything to the provider that serves it."),
+    effort: z
+        .string()
+        .optional()
+        .describe("How hard this model should think, where it offers a choice. Leave it out to take the model's own default."),
+    thinking: z.boolean().optional().describe("Whether this model reasons before it answers, where that is a choice it offers."),
+    fast: z.boolean().optional().describe("Ask for this model's work at a higher rate for a higher price. A request rather than a promise."),
+    harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it. Leave it out to use the provider's own."),
+});
+export type AgentRunPin = z.infer<typeof AgentRunPinSchema>;
 // POST /agent's ack: the daemon-minted id of the detached turn run it started. The turn executes daemon-side
 // regardless of any client connection; every window, the initiator included, renders it via /agent/attach.
 export const StartedTurnSchema = z.object({
     run: z.string().describe("The id of the run that just started. Hand it back when you attach, so the stream resumes rather than replaying."),
 });
 export type StartedTurn = z.infer<typeof StartedTurnSchema>;
-// Attach to a conversation's turn run (live, or finished within the retention window). `run`+`after` is the
-// resume cursor of a client whose stream dropped: frames after `after` replay when `run` still names the
-// current run; a mismatch (a newer turn started meanwhile) replays that run from its first frame instead.
+// Attach to a conversation's turn run (live, or finished within the retention window). The head carries the
+// run's rows whole, so there is no cursor to resume from: a client that reconnects takes the rows again and
+// applies what follows. `run` names the run the client was watching, so the head's own id tells it whether a
+// newer turn has started meanwhile.
 export const AttachTurnSchema = z.object({
     conversationId: ConversationIdSchema.describe("Which conversation to watch."),
     run: z
         .string()
         .optional()
-        .describe("The run you were watching. If a newer turn has started since, the stream replays that one from its beginning instead."),
-    after: z
-        .number()
-        .int()
-        .min(0)
-        .optional()
-        .describe(
-            "The last frame you already have. Everything after it replays, then the stream goes live. Leave it out to start from the beginning.",
-        ),
+        .describe("The run you were watching. If a newer turn has started since, the head names that one instead, and its rows are that turn's."),
 });
 export type AttachTurn = z.infer<typeof AttachTurnSchema>;

package/src/schemas/agents.ts

@@ -204,6 +204,52 @@ export const AgentSummarySchema = z.object({
         .describe(
             "Why the last turn failed, in the words it died on. Absent unless it did, and cleared the moment it runs again. Carried here because the word error on its own is not an answer, least of all for a run nobody was watching.",
         ),
+    /* WHICH KIND OF FAILURE IT WAS, the error frame's own code (AgentEvent's `error`), beside the sentence it
+     * came with. The sentence says what happened to a person; this says it to the board, which has to DRAW the
+     * difference and could not.
+     *
+     * The chat has always had it, and the gap between the two surfaces is the whole reason this exists. A chat
+     * reads `rate_limit` and renders a muted notice with a countdown and a press; the board read `status:
+     * "error"` and rendered a red crash line with "View error" on it, because the code never reached the
+     * summary. So one spent allowance looked exactly like a harness that died mid-run, on the surface where
+     * most people meet it, and the state the product knows most about (it knows when it ends) was the one
+     * drawn with the least. */
+    failureCode: z
+        .string()
+        .optional()
+        .describe(
+            "Which kind of failure it was, as the turn's own error frame coded it. Absent for a failure nothing could classify, which reads as the plain red line it is.",
+        ),
+    /* WHEN THE SPENT WINDOW REOPENS (epoch SECONDS), for a card whose last turn a usage limit refused. The one
+     * fact this failure has and no other failure here does, and the reason it is not a failure at all so much
+     * as a wait: nothing is broken, nobody has anything to fix, and the thing that changes the outcome is a
+     * clock. A card that cannot say the hour has to spend its line saying "Error" instead, which is how an
+     * 18-hour-old refusal went on reporting a wall that had reopened before breakfast.
+     *
+     * Absent means the instant is genuinely unknown, which for Grok (no published quota) and Cursor (not routed
+     * through the translator) is the honest answer and stays one. Never invent one: a countdown to a guess is
+     * worse than no countdown, because the reader plans around it. */
+    limitResetsAt: z.number().optional().describe("When the spent allowance reopens, in epoch seconds. Absent when the provider publishes no instant."),
+    /* THE DAEMON IS STILL HOLDING THAT EXACT TURN, so the way on is one press that RE-RUNS it rather than a new
+     * message saying "carry on" (turn-resume.ts's pendingLimit has the whole argument, and the transcript full
+     * of the word "Continue" that made it). On the summary because the board is where somebody with four
+     * stranded agents is standing, and until now the press existed only inside each chat. */
+    limitHeld: z.boolean().optional().describe("Whether the refused turn is held whole, so sending again re-runs it instead of appending to it."),
+    /* A FIRE IS ALREADY BOOKED FOR THIS ONE: the conversation is armed (`resumeAfterLimit`), the reset instant
+     * is known, and the daemon's pass will send the held turn again when the window opens without anybody
+     * pressing anything.
+     *
+     * IT IS THE ONE THING THAT MOVES A STRANDED CARD OUT OF THE ATTENTION LANE, and the only reason it needs to
+     * be on the wire at all. "Does this session need me?" is the question that lane answers, and for a spent
+     * allowance the honest answer is yes: the window reopening does not send the turn, a person does. Unless
+     * this is set, in which case a machine does, and demanding a press for work already booked is the same
+     * false alarm as demanding one for a turn that is running.
+     *
+     * A BOOLEAN THE DAEMON ALREADY DECIDED rather than a posture the client re-folds. The effective posture is
+     * two levels deep (this conversation's override, else the sandbox setting), and the lane machine is a leaf
+     * with no store to ask: threading a settings read through every caller of `laneOf` would put the answer in
+     * five places and let them disagree. The daemon resolves it once, where the failure happened. */
+    limitScheduled: z.boolean().optional().describe("Whether the held turn is already booked to go again at the reset, so nobody has to press anything."),
     provider: AgentProviderSchema.describe("Which model provider it runs on."),
     harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
     // Which machine its turns execute on: a paired runner's id, absent for this sandbox (runners/). Latched
@@ -265,6 +311,19 @@ export const AgentSummarySchema = z.object({
      * never expressed an opinion follows the sandbox wherever it is pointed next. Written by
      * `agents.resumeAfterOutage`; every surface shows the EFFECTIVE value (this ?? the setting). */
     resumeAfterOutage: z.boolean().optional(),
+    /* The same two-level shape again, for the blocker that is not a failure: "when a usage limit refused my
+     * turn, send it again the moment the allowance comes back".
+     *
+     * IT IS THE ONE RESUME WITH A KNOWN HOUR, which is what makes it worth automating and what makes it
+     * different from its neighbour. An outage resume guesses (a backoff, a bounded number of attempts, no idea
+     * when the provider returns); this one waits for an instant the provider published and fires once, at it.
+     *
+     * OFF unless somebody says otherwise, and that default is load-bearing rather than cautious. Every other
+     * blocker here clears at no cost to the user, while this one clears into a window they may have been
+     * saving: spending it the second it reopens is not a decision to make on anybody's behalf. What arming it
+     * buys is the case nothing else can reach, a turn that hit the wall at 2am on a board nobody is watching,
+     * where the alternative is a card that waited eight hours for a press that was always going to come. */
+    resumeAfterLimit: z.boolean().optional(),
     // A collaborator asked for this agent's work to be landed (agents.requestLand), collaborators may drive
     // agents but not merge into the main tree, so the ask rides the summary where every maintainer's board
     // sees it. Cleared by the land or discard that answers it. Absent ⇒ nobody is waiting.
@@ -681,6 +740,18 @@ export const AgentResumeAfterOutageSchema = z.object({
         .nullable()
         .describe("Whether it retries by itself when the model provider was what failed. Null clears the override back to the sandbox-wide setting."),
 });
+// resumeAfterLimit's input, the same override in the same three states as the outage one above, for the
+// blocker that comes back on a clock. Written by the card's own offer at the moment a limit strands a turn,
+// which is where somebody looking at a stranded card actually is; the settings toggle writes the default.
+export const AgentResumeAfterLimitSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    resumeAfterLimit: z
+        .boolean()
+        .nullable()
+        .describe(
+            "Whether the turn a spent allowance refused is sent again by itself once the window reopens. Null clears the override back to the sandbox-wide setting.",
+        ),
+});
 export const AgentFileDiffQuerySchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
     repo: z.string().min(1).describe("Which repository."),

package/src/schemas/approvals.ts

@@ -0,0 +1,174 @@
+// approvals: things the agent prepared and may not do until the owner says yes (.intentic/config/approvals/<id>.json)
+import { z } from "zod";
+import { entryId } from "./internal.js";
+
+/* ONE QUEUE FOR EVERYTHING THAT WAITS ON A YES, and the test for what belongs in it: the agent prepared an exact
+ * thing, the owner's click releases it, a machine then carries out precisely that thing, and the outcome is
+ * written back. A post is the first such thing and was the whole of this file (it was `drafts`); a hotel
+ * booking, a payment, a message sent under the owner's name are the same shape with a different payload, and
+ * each of them arriving as its own inbox is how a product grows five tiles that all say "approve".
+ *
+ * So the record is an ENVELOPE plus a KIND. The envelope is what every approval shares and what the queue, the
+ * badge and the daemon act on: who it acts as, when it is due, where it stands, what happened. The kind is what
+ * the row draws and the daemon dispatches on, a discriminated union so a new kind is one variant here, one
+ * body component in the extension and one executor in the daemon, and nothing else moves.
+ *
+ * What does NOT belong here, and why the line is drawn where it is: an inbox of FACTS (the issues queue, where
+ * a crash arrived and the owner's verbs are resolve / ignore / investigate) has no prepared thing to release,
+ * and a hold a RUNNING turn is blocked on (a permission card, a spend offer) lives in the conversation, because
+ * a queue is the wrong latency for a click somebody is spinning on.
+ *
+ * One JSON file per approval. The AGENT creates them with its normal file tools, it can't call daemon routes,
+ * the same split as the environment proposal, while the daemon edits/deletes them on the owner's behalf, so
+ * the two writers never share a file. The id IS the filename (entryId charset ⇒ path-safe); the body never
+ * carries it. */
+
+export const ApprovalKindSchema = z.enum(["post", "action"]);
+export type ApprovalKind = z.infer<typeof ApprovalKindSchema>;
+
+/* proposed (agent) → approved (owner) → running (executor, set BEFORE acting so a dead turn can't do it twice)
+ * → done | failed. Reject = delete the file; retry = re-approve a failed one. The names are deliberately not a
+ * post's ("posting", "posted"): they are read by every kind, and a booking is not "posted". */
+export const ApprovalStatusSchema = z.enum(["proposed", "approved", "running", "done", "failed"]);
+export type ApprovalStatus = z.infer<typeof ApprovalStatusSchema>;
+
+/* THE ENVELOPE, spread into every variant below (zod's discriminated union wants flat objects, not an extended
+ * base), which is also why a variant's own fields sit beside these rather than under a `payload` key: the file
+ * an agent writes stays one level deep, and "which fields are mine" is answered by the variant's schema. */
+const envelope = {
+    /* WHOSE NAME THIS ACTS UNDER, a PersonaSchema id, handed to the executing turn as AgentTurnSchema.actsAs.
+     * Required in practice for every post outside DIRECT_PUBLISH_PLATFORMS, and the reason is the whole shape
+     * of turnPersona: acting through a browser needs a logged-in account, and an UNATTENDED turn that names no
+     * persona is denied every account there is. Without this field the executor could only wake such a turn,
+     * one structurally unable to reach the login the post needs, which read from inside the turn as "this
+     * account is not connected" and cost two approved posts before anyone traced it back here.
+     *
+     * A PERSONA RATHER THAN AN ACCOUNT ID, because that is the vocabulary the rest of the system already speaks:
+     * `actsAs` is the only pin turnPersona honours, and a card carries the workspace scope the turn also needs to
+     * write this file's own status back. Naming the account directly would invent a second way to say the same
+     * thing, and the two would disagree the first time a card's accounts changed.
+     *
+     * The daemon never guesses it. One site can be connected several times over, five Reddit logins here, and
+     * picking for the owner means picking wrong in public, with no undo. A post that needs a turn and names
+     * nobody is failed with that sentence instead of sent. An ACTION that names nobody runs with no accounts,
+     * which is a legitimate choice for work that needs none. */
+    actsAs: entryId
+        .optional()
+        .describe(
+            "Whose name it acts under. Needed for anything that requires being logged in, because an unwatched turn naming nobody is allowed no account at all. Never guessed: one site can be connected five times over, and picking for you means picking wrong in public with no undo.",
+        ),
+    // Suggested time (epoch ms, the at/nextRun convention). Optional, the agent may propose without a date and
+    // the owner sets one at approval; an approved item with no date is dated one hold ahead by the daemon.
+    scheduledAt: z
+        .number()
+        .optional()
+        .describe(
+            "When it should happen, in milliseconds. An agent may propose without one and you set it when approving; an approved item with no time goes after a short countdown you can still stop.",
+        ),
+    // Agent-written files only need the kind's own fields; status defaults, the rest are optional, so a
+    // well-formed proposal never lands in `invalid` just for omitting bookkeeping fields.
+    status: ApprovalStatusSchema.default("proposed").describe(
+        "Where it is: proposed by the agent, approved by you, being carried out, done, or failed. Rejecting is deleting it; retrying is approving a failed one again.",
+    ),
+    createdAt: z.number().optional().describe("When it was written, in milliseconds."),
+    // When execution STARTED, stamped with status "running". The executor needs it to tell a run that is under
+    // way from one whose turn died mid-flight, and those two are indistinguishable from the due time: a post
+    // scheduled for last week is not a post that has been sending since last week.
+    startedAt: z
+        .number()
+        .optional()
+        .describe(
+            "When it started being carried out, in milliseconds. Needed to tell a run that is under way from one whose turn died mid-flight, which the scheduled time cannot.",
+        ),
+    finishedAt: z.number().optional().describe("When it was done, in milliseconds."),
+    // What came back, when something did: a post's own address, a booking's confirmation. The one thing a done
+    // row can offer that reading the proposal cannot: the result itself, to go and look at. A URL is drawn as
+    // a link; anything else as the sentence it is.
+    result: z
+        .string()
+        .optional()
+        .describe(
+            "What came back, when something did: the post's own address, a confirmation number. The one thing a finished item can offer that reading it cannot.",
+        ),
+    // Why it failed; set with status "failed". Written for the owner to read in the queue, so it is a sentence
+    // rather than a code.
+    error: z.string().optional().describe("Why it failed, written as a sentence for a person to read rather than as a code."),
+};
+
+/* A POST, the first kind: words that go out in public under the owner's name and cannot be recalled. */
+export const PostApprovalSchema = z.object({
+    kind: z.literal("post").describe("A post to publish somewhere."),
+    // Which skill posts it: "x" | "reddit" | "youtube" | "discord" | …, a bare string so new platforms need
+    // no contract change; an unknown platform simply fails at posting time.
+    platform: z
+        .string()
+        .min(1)
+        .describe("Where it should go. A plain name, so a new site needs no change here; an unknown one simply fails when it tries to post."),
+    content: z.string().min(1).describe("The post itself."),
+    // Reddit posts / YouTube uploads need one.
+    title: z.string().optional().describe("A title, where the site wants one."),
+    /* Where on the platform: subreddit / Discord channel id / community. OR the URL of the thing this post
+     * replies to. A URL target means the post is a reply, and on reddit the difference between a thread's
+     * address and one comment's permalink is the difference between talking to the room and answering the
+     * person: the publisher opens exactly this and replies where it lands. */
+    target: z
+        .string()
+        .optional()
+        .describe(
+            "Where on the site: a community, a channel. Or the address of the thing this replies to, in which case it is a reply, and on some sites the difference between a thread's address and one comment's is the difference between talking to the room and answering the person.",
+        ),
+    // Workspace-relative attachment paths, e.g. ".intentic/config/approvals/media/chart.png".
+    media: z.array(z.string()).optional().describe("Anything to attach, as workspace paths."),
+    ...envelope,
+});
+export type PostApproval = z.infer<typeof PostApprovalSchema>;
+
+/* AN ACTION, the general kind: anything else the agent is about to do that it should not do unasked. A
+ * booking, a purchase, a message to a person, a deletion that cannot be undone. The agent writes what it will
+ * do in words the owner reads (`summary`, `details`), and what it will tell ITSELF to do once released
+ * (`instructions`), because the turn that carries it out is a fresh one, hours later, with none of the
+ * conversation that led here. Executed by an agent turn, always: there is no typed door for "whatever it is". */
+export const ActionApprovalSchema = z.object({
+    kind: z.literal("action").describe("Something the agent will do once you say so."),
+    summary: z.string().min(1).max(200).describe("What will happen, in one line: the row's headline and the confirm dialog's item."),
+    // Markdown. The specifics a yes is being asked for: the hotel and the dates, the amount and the account,
+    // the exact message and its recipient. Everything the owner has to see to be able to say no.
+    details: z.string().optional().describe("The specifics, as Markdown: everything you would want to see before saying yes."),
+    // What the executing turn is told. Written by the agent for its later self, so it names files, ids and
+    // steps rather than saying "do what we discussed".
+    instructions: z
+        .string()
+        .min(1)
+        .describe(
+            "What to do once approved, written for the fresh turn that will do it: names, ids and steps, since it has none of this conversation.",
+        ),
+    ...envelope,
+});
+export type ActionApproval = z.infer<typeof ActionApprovalSchema>;
+
+// The on-disk file body, whichever kind it is.
+export const ApprovalSchema = z.discriminatedUnion("kind", [PostApprovalSchema, ActionApprovalSchema]);
+export type Approval = z.infer<typeof ApprovalSchema>;
+
+// The list row / upsert input: the file body plus its filename id.
+const withId = { id: entryId.describe("The approval's id.") };
+export const PostApprovalSummarySchema = PostApprovalSchema.extend(withId);
+export type PostApprovalSummary = z.infer<typeof PostApprovalSummarySchema>;
+export const ActionApprovalSummarySchema = ActionApprovalSchema.extend(withId);
+export type ActionApprovalSummary = z.infer<typeof ActionApprovalSummarySchema>;
+export const ApprovalSummarySchema = z.discriminatedUnion("kind", [PostApprovalSummarySchema, ActionApprovalSummarySchema]);
+export type ApprovalSummary = z.infer<typeof ApprovalSummarySchema>;
+
+// `invalid` = filenames that failed to parse. Agent-written files are a trust boundary, without this a typo'd
+// approval (or one of a kind this daemon does not know) would silently never run.
+export const ApprovalsListSchema = z.object({
+    approvals: z.array(ApprovalSummarySchema).describe("The queue."),
+    invalid: z
+        .array(z.string())
+        .describe(
+            "Files that could not be read at all, or name a kind this daemon does not know. Listed rather than skipped, because an agent writes these files directly and a malformed one would otherwise never run and never say why.",
+        ),
+});
+export type ApprovalsList = z.infer<typeof ApprovalsListSchema>;
+// entryId, not a bare string: the id becomes a filename under .intentic/config/approvals/.
+export const ApprovalIdParamSchema = z.object({ id: entryId.describe("Which approval.") });

package/src/schemas/ci.ts

@@ -124,22 +124,8 @@ export const CiRunsResponseSchema = z.object({
     repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
     // Newest first, across all mapped repos.
     runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
-    // When the owner last opened the pipelines view. Rides the runs response so the rail can decide what is
-    // NEW without a second call, a breakage older than this has already been seen and must not badge again.
-    // Absent ⇒ never opened, so everything counts as unseen.
-    seenAt: z
-        .number()
-        .optional()
-        .describe(
-            "When this was last looked at, in milliseconds, so a badge can tell new breakages from ones already read without a second call. Absent means never, so everything counts as new.",
-        ),
 });
 export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
-// Stamping the view as read hands back the timestamp it wrote, so the client updates without a refetch.
-export const CiSeenResponseSchema = z.object({
-    seenAt: z.number().describe("The timestamp that was written, handed back so a caller can update without asking again."),
-});
-export type CiSeenResponse = z.infer<typeof CiSeenResponseSchema>;
 // rerun/cancel/fix address a run by repo + vendor id; the daemon re-resolves repo → project + token per call,
 // so a stale card can't act on a project the workspace no longer maps to.
 export const CiRunParamSchema = z.object({
@@ -181,21 +167,28 @@ export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
  * dialog that started it, and is gone. Nothing survives a daemon restart because nothing needs to: the next
  * push asks again. */
 
-/* Where a run is.
+/* A COMMAND RUN ON A CLICK, in a visible terminal, with a verdict and a quotable tail: the ONE shape for
+ * everything the daemon runs because the owner pressed a button and then has to be told how it went. The
+ * pre-push check is one (above); the push itself is another (PushRunSchema, schemas/git.ts), because a push
+ * runs the repository's own pre-push hook, which is a suite in disguise. One shape rather than one per
+ * moment, so a field the browser learns to read for the check (the terminal to open, the tail to quote, the
+ * kill to distinguish from the timeout) is read for the push by the same code, and cannot drift.
+ *
+ * Where a run is.
  *
  *   idle     , nothing has run in this daemon's life, or the last run was cleared.
- *   running  , the check is live. Its output is the terminal's (`session`), not this object's.
- *   passed   , exited 0. The push goes.
- *   failed   , exited non-zero, or was killed by prepushTimeoutMs (`timedOut`). The state a fix answers.
- *   error    , the check could not run at all: the command was not spawnable. NOT a fix-able failure, because
- *               there is nothing wrong with the code, the command is misconfigured, and saying "tests failed"
- *               would send an agent hunting a bug that isn't there.
+ *   running  , the command is live. Its output is the terminal's (`session`), not this object's.
+ *   passed   , exited 0. The push goes (or went).
+ *   failed   , exited non-zero, or was killed by its ceiling (`timedOut`). The state a fix answers.
+ *   error    , the command could not run at all: it was not spawnable. NOT a fix-able failure, because there
+ *               is nothing wrong with the code, the command is misconfigured, and saying "tests failed" would
+ *               send an agent hunting a bug that isn't there.
  *   cancelled, the user stopped the run.
  */
-export const PrepushStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
-export type PrepushStatus = z.infer<typeof PrepushStatusSchema>;
-export const PrepushRunSchema = z.object({
-    status: PrepushStatusSchema.describe(
+export const CommandRunStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
+export type CommandRunStatus = z.infer<typeof CommandRunStatusSchema>;
+export const CommandRunSchema = z.object({
+    status: CommandRunStatusSchema.describe(
         "Where the run is. Failed and error are deliberately different: failed means the code is wrong, error means the command could not be run at all, and calling the second one a test failure would send an agent hunting a bug that is not there.",
     ),
     // The command this run executed, echoed rather than read back from settings: a result read after the
@@ -232,4 +225,4 @@ export const PrepushRunSchema = z.object({
             "The end of what it printed, as plain text with the colour codes and redrawn progress lines resolved away. The end rather than the beginning, because a suite's verdict is at the end. Empty while it runs, and for one that was killed.",
         ),
 });
-export type PrepushRun = z.infer<typeof PrepushRunSchema>;
+export type CommandRun = z.infer<typeof CommandRunSchema>;