@intentic/sandbox-contract 1.230.3 → 1.231.0

package/src/schemas.ts

@@ -3,6 +3,7 @@ import { ExtensionManifestSchema } from "@intentic/extension-manifest";
 import { RegistryEntrySchema } from "@intentic/registry";
 import { z } from "zod";
 import { OutputFieldsSchema } from "./output-fields.js";
+import { AgentPlacementSchema } from "./runner-protocol.js";
 
 // All request/response wire schemas for the sandbox daemon. 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
@@ -253,6 +254,13 @@ export const AgentTurnSchema = z
             .describe(
                 "Work in this conversation's own private copy of the repos rather than the shared tree, so several agents can work at once. Needs a conversation id.",
             ),
+        /* WHERE the conversation executes, decided like `isolated` directly above: the request's choice on the
+         * first turn, the registry entry's on every turn after. `runner` implies isolation (the branch is what
+         * moves between machines) and needs a conversation id for the same reason `isolated` does. Absent =
+         * local. Design: docs/remote-runners-plan.md; refused until runners ship. */
+        placement: AgentPlacementSchema.optional().describe(
+            "Where this conversation runs: this sandbox (leave it out), or a paired runner by id. Decided on the first turn; later turns follow the conversation.",
+        ),
         /* Pin a NEW isolated conversation's worktree composition to these repository commits. Daemon-owned:
          * ordinary chats omit it and keep rebasing onto the current workspace; a workflow supplies the one
          * snapshot all of its candidates must share. Repeated iterations carry it too, which suppresses the
@@ -2778,7 +2786,13 @@ export const SandboxSettingsSchema = z.object({
      * `<provider>.<type>` ("discord.message.send") with `<provider>.*` as the per-provider wildcard; exact key
      * wins. An action with no rule is allowed, the empty default wires no hook at all, so an unconfigured
      * workspace pays nothing. "hold" cannot park a running turn (nobody may be there to answer); it refuses the
-     * live call and points the agent at the drafts outbox, which IS the held form of a send. */
+     * live call and points the agent at the drafts outbox, which IS the held form of a send.
+     *
+     * The CHILD-AGENT surface reads the same book: `agents.spawn` covers starting, steering and answering
+     * child agents on every provider, `agents.spawn.<provider>` singles one out (the specific key wins), and
+     * the daemon's own taint floor holds a spawn from a turn that has taken in outside content unless the
+     * owner wrote an explicit allow (guard/actions.ts childSpawn). "hold" refuses with the owner named, the
+     * same translation a send gets. */
     actionRules: z
         .record(z.string(), AdmissionRuleSchema)
         .default({})
@@ -3812,13 +3826,43 @@ export const SnapshotFileDiffQuerySchema = z.object({
     scope: z.string().min(1).describe("Which part of the workspace the path belongs to."),
     path: z.string().min(1).describe("The file, relative to that scope."),
 });
+/* WHAT A FILE TOO BIG TO SEND WHOLE ANSWERS WITH INSTEAD, and why that is not simply "no".
+ *
+ * Both whole sides of a half-megabyte file are a megabyte of JSON per click, so above the cap they are not
+ * sent, which used to be the end of it: the response said "too large" and every review surface printed one
+ * sentence over an empty pane. That is the wrong trade, because the thing a reader wants out of a big file is
+ * almost never the file: it is the handful of lines that MOVED, and those are small however big the file is.
+ *
+ * So the daemon diffs it and sends the CHANGED REGIONS as a unified patch, at the same three lines of context
+ * a collapsed region keeps elsewhere. A 40 KB patch stands in for a 60 MB pair, and the reader gets the actual
+ * review rather than a refusal. `patch` carries the `@@` sections only, the file headers git prints above them
+ * name rev-specs no one can apply anyway.
+ *
+ * An added or deleted file has no counterpart to diff against, so its patch IS the file, one region of pure
+ * +/− lines. That is still the right answer: cut to the budget, it is the head of the file, which is the peek
+ * the reader came for.
+ *
+ * `patch` is absent only when there was nothing to make one from: a change too large even to render as a
+ * patch, or a git that refused. The sizes are still there, so a surface can at least say how big the thing it
+ * is not showing is. */
+export const PartialFileDiffSchema = z.object({
+    beforeBytes: z.number().int().nonnegative().optional().describe("How big the before side is, in bytes. Absent when the file did not exist yet."),
+    afterBytes: z.number().int().nonnegative().optional().describe("How big the after side is, in bytes. Absent when the file was deleted."),
+    patch: z
+        .string()
+        .optional()
+        .describe("The changed regions as unified-diff hunks (`@@` sections only). Absent when the change was too large to render even as a patch."),
+    more: z.boolean().optional().describe("There were more changed regions than fit; the patch stops at a region boundary."),
+});
+export type PartialFileDiff = z.infer<typeof PartialFileDiffSchema>;
+
 // Both sides of a file diff, a snapshot vs its parent, or a working tree vs HEAD; an absent side means the
-// file was added/deleted. Binary or oversized content is flagged instead of shipped.
+// file was added/deleted. Binary content is flagged instead of shipped; oversized content arrives as `partial`.
 export const FileDiffSchema = z.object({
-    before: z.string().optional().describe("The whole file as it was. Absent when it did not exist yet."),
-    after: z.string().optional().describe("The whole file as it is now. Absent when it was deleted."),
+    before: z.string().optional().describe("The whole file as it was. Absent when it did not exist yet, or when `partial` is set."),
+    after: z.string().optional().describe("The whole file as it is now. Absent when it was deleted, or when `partial` is set."),
     binary: z.boolean().optional().describe("The file is not text, so neither side is sent."),
-    truncated: z.boolean().optional().describe("The file was too large to send whole, so what you have is the start of it."),
+    partial: PartialFileDiffSchema.optional().describe("Set when the file was too large to send whole: what is sent instead of the two sides."),
 });
 export type FileDiff = z.infer<typeof FileDiffSchema>;
 
@@ -5617,6 +5661,26 @@ export const CapabilityOtpSchema = z.object({
         .describe("How long it lasts. Its expiring is what makes handing one to an agent safe, since the seed behind it is never revealed."),
 });
 
+/* POST /capabilities/probe response: did these settings actually reach the thing, asked BEFORE they are saved.
+ *
+ * The answer is a sentence rather than a status code because the reader is standing in front of a form: what
+ * they need is either the service's own confirmation ("Reached GitHub, authenticated as ada") or the exact
+ * refusal ("GitHub answered 401: the token is not valid"), in the place where the box they would fix still is.
+ * That is also the whole point of doing it here: every one of these failures is otherwise discovered after the
+ * add, on a card that says "not connected" with nothing about which of six answers was wrong.
+ *
+ * `ok: false` is a REPORTED failure, not a transport error: the probe ran and the service said no. A card whose
+ * settings cannot be checked from here at all answers `checked: false`, which is a different thing from a
+ * failure and must never be drawn as one. */
+export const CapabilityProbeSchema = z.object({
+    checked: z.boolean().describe("Whether this connection can be tested from here at all. False is not a failure: it is 'no test exists'."),
+    ok: z.boolean().describe("Whether the service answered as itself."),
+    message: z
+        .string()
+        .describe("What happened, in the words a person standing in front of the form needs: the service's own answer, or its refusal."),
+});
+export type CapabilityProbe = z.infer<typeof CapabilityProbeSchema>;
+
 // ---- hosts: the user's own connected computers (the `host` capability's live half) ----
 // The manifest says which machines the user INTENDS to have connected; this says which are actually holding a
 // socket right now. Nothing here is remembered across a daemon restart except the enrollment itself: a machine
@@ -7625,6 +7689,9 @@ export const PanelSummarySchema = z.object({
     servers: z
         .array(
             z.object({
+                // The port itself, not just the URL it appears in: forwarding one is how a repo answering on
+                // several ports becomes previewable at all, and that call takes a number.
+                port: z.number().describe("The port it is listening on, which is what forwarding it takes."),
                 url: z.string().describe("Where it answers, with the right scheme: a server on its own certificate is served over https."),
                 dir: z
                     .string()
@@ -7641,8 +7708,15 @@ export const PanelSummarySchema = z.object({
             }),
         )
         .describe("Every server this repository is really serving, found by looking at what is listening. Empty when nothing answers."),
-    // https://preview-<repo>-<sandboxId>.<zone>; absent when the sandbox has no zone or connect token (loopback/tests).
-    previewUrl: z.string().optional().describe("Where to open it from outside. Absent on a sandbox with no outside address."),
+    /* https://preview-<repo>-<sandboxId>.<zone>, and ONLY where that address actually serves this repo: absent
+     * on a sandbox with no zone or connect token (loopback/tests), and absent whenever the preview proxy has
+     * nothing to route it to — nothing running, still starting, or (the ordinary monorepo) several dev servers
+     * on ports of their own, none of which one hostname can stand for. Present ⇒ safe to open or frame, which
+     * is what stops a surface from showing a 502 as if it were the app. */
+    previewUrl: z
+        .string()
+        .optional()
+        .describe("Where to open it from outside, present only while that address really serves it. Absent on a sandbox with no outside address."),
     // The workspace role this repo dir occupies (the three fixed dirs); absent for extra clones.
     role: z
         .enum(["intent", "desired-state", "app"])
@@ -8323,28 +8397,28 @@ export const BrowserNameParamSchema = z.object({ name: z.string().describe("Whic
  * (another agent, working, that you did not start):
  *   • `subagent`, the SDK's Agent/Task tool. The daemon learns of it from the SubagentStart/SubagentStop hooks
  *     and the task_* stream messages, joined on `toolUseId`.
- *   • `codex` / `grok`, a CLI the agent drove from its own Bash (agent/delegation.ts). Detected in the Bash
- *     PreToolUse hook, bound to its thread/session id from the command's output.
- *
- * `id` IS THE SPAWNING TOOL CALL'S id, the Agent card's, or the Bash card's for a delegation. It is the one key
- * every source already carries (the SDK's subagent meta, its task_* messages, and the `parentToolUseId` the
- * client nests inner frames under), so nothing has to be correlated: a card links to its subagent with the id it
- * already has, and the subagent points back at the card the same way. The ids the transcripts are actually READ
- * with, the SDK's agent id, a Codex thread, an OpenCode session, stay daemon-side, because no surface asks a
- * question they answer.
- *
- * WHAT A KIND CHANGES, and it is only ever the live view: a subagent has no process of its own to look at, so
- * watching it means reading its transcript. A delegation runs in a tmux window, so it has both, `terminal`
- * names it, and the card keeps its existing "Watch in terminal" beside the transcript door. */
-export const SubagentKindSchema = z.enum(["subagent", "codex", "grok"]);
+ *   • `spawned`, a full agent the turn started through the daemon's own spawn door (children/children.ts), on
+ *     ANY connected provider, Cursor's Composer, Codex, Gemini, another Claude. The daemon runs the child
+ *     itself, so its whole life is reported by direct calls rather than reconstructed from hooks or stdout.
+ *
+ * `id` IS THE SPAWNING TOOL CALL'S id for an SDK child (the one key its meta file, its task messages and the
+ * client's `parentToolUseId` nesting all carry), and the child's own conversation id for a `spawned` one (the
+ * spawn door returns it, so both sides hold it). A card links to its subagent with the id it has, and the
+ * subagent points back at the card the same way. The ids the transcripts are actually READ with, the SDK's
+ * agent id, stay daemon-side, because no surface asks a question they answer.
+ *
+ * WHAT A KIND CHANGES, and it is only ever the live view: an SDK subagent has no process of its own to look
+ * at, so watching it means reading its transcript; a spawned child is a conversation of its own, so its live
+ * view is that conversation's stream. */
+export const SubagentKindSchema = z.enum(["subagent", "spawned"]);
 export type SubagentKind = z.infer<typeof SubagentKindSchema>;
 
 // running/pending/blocked are live; the rest are terminal. Deliberately the SDK's own task vocabulary
 // (SDKTaskUpdatedMessage.patch.status) rather than AgentStatus: this is not a fleet card's lifecycle (no
 // draft/landed/conflict), and mapping the two would invent states neither side reports. `blocked` is the one
-// addition the SDK never says: it comes from a delegated CLI's own signals (a Codex PermissionRequest hook, an
-// OpenCode permission ask, agent/delegation-signals.ts), and it exists because "the child needs an answer" is
-// the one live state a parent or an operator acts on differently from "the child is working".
+// addition the SDK never says: a spawned child's own question/permission/plan card raises it
+// (children/children.ts), and it exists because "the child needs an answer" is the one live state a parent or
+// an operator acts on differently from "the child is working".
 export const SubagentStatusSchema = z.enum(["pending", "running", "blocked", "completed", "failed", "killed", "paused"]);
 export type SubagentStatus = z.infer<typeof SubagentStatusSchema>;
 
@@ -8352,20 +8426,23 @@ export const SubagentSessionSchema = z.object({
     id: z
         .string()
         .describe(
-            "The id of the tool call that started it, which every side already holds, so a card links to its helper with the id it has and the helper points back the same way.",
+            "The id of the tool call that started it (an SDK child) or the child's own conversation id (a spawned one); either way both sides already hold it, so a card links to its helper with the id it has and the helper points back the same way.",
         ),
     kind: SubagentKindSchema.describe(
-        "What sort of helper: one the runtime spawned, or a separate tool the agent drove from a shell. It changes only how you watch it.",
+        "What sort of helper: one the runtime's own Task tool spawned in-process, or a full agent the daemon started for the turn. It changes only how you watch it.",
     ),
     // The conversation whose turn spawned this, what the area groups its rows by, and the way back to the chat
     // the card lives in.
     conversationId: z.string().describe("The conversation whose turn started it, and the way back to the chat it belongs to."),
-    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or the delegated
-    // provider's model, and the caller's one-line description. The area's row and the card's title read as
-    // `Explore · Locate claimIndexer definition`.
+    // What it is and what it was asked to do: the subagent type (`Explore`, `general-purpose`) or a spawned
+    // child's provider label, and the caller's one-line description. The area's row and the card's title read
+    // as `Explore · Locate claimIndexer definition`.
     agentType: z.string().optional().describe("What kind of helper it is."),
     description: z.string().optional().describe("What it was asked to do, in one line."),
     model: z.string().optional().describe("Which model it runs on."),
+    // Which provider serves a `spawned` child (its AgentProvider id), so the row can wear the right logo. An
+    // SDK subagent implies its own: it runs on its parent's provider.
+    provider: z.string().optional().describe("Which provider serves it, for a helper spawned across providers."),
     // How deep in the spawn tree (1 = spawned by the turn itself). From the SDK's meta.json; a subagent may
     // itself delegate, and a flat list that cannot say so reads as though the turn started all of them.
     spawnDepth: z
@@ -8403,14 +8480,6 @@ export const SubagentSessionSchema = z.object({
         .optional()
         .describe("Its report: what it concluded, without opening its record. The question a finished helper gets read for."),
     error: z.string().optional().describe("Why it failed, when it did."),
-    // A delegation's live view: the tmux session its command runs in. Absent for an SDK subagent, which has no
-    // process of its own to attach to.
-    terminal: z
-        .string()
-        .optional()
-        .describe(
-            "The terminal its command runs in, when there is one. Absent for a helper with no process of its own, which is watched by reading its record instead.",
-        ),
 });
 export type SubagentSession = z.infer<typeof SubagentSessionSchema>;
 export const SubagentsListSchema = z.object({