@intentic/sandbox-contract 1.234.0 → 1.236.0

package/src/schemas/agents.ts

@@ -701,11 +701,11 @@ export const LandConflictPathSchema = z.object({
         "Why it would not merge, and the three have nothing in common but the symptom. Your own uncommitted edits on that path, where yours is the copy at risk. The shared tree having moved under the conversation since it started, where nothing of yours is at risk. Or a file git cannot merge at all, where no automatic answer exists.",
     ),
 });
-/* land's outcome, per repo of the composition. `paths` is the set that genuinely failed to apply. NOT the
+/* A composed land's refusal, grouped per repo. `paths` is the set that genuinely failed to apply. NOT the
  * whole delta, which is what the first version reported whenever it could not pin the cause down, turning
- * four real conflicts into a wall of fourteen. `clean` counts what would land regardless, so the UI can say
- * how much is being held back by how little, and offer to take it. An empty `paths` with `clean: 0` is the
- * repo-unavailable case: the main checkout is gone, and no path-level account exists. */
+ * four real conflicts into a wall of fourteen. `clean` counts what passed in that repo but stays on the branch
+ * with the rest of the composition. An empty `paths` with `clean: 0` is the repo-unavailable case: the main
+ * checkout is gone, and no path-level account exists. */
 export const LandConflictSchema = z.object({
     repo: z.string().describe("Which repository."),
     paths: z
@@ -716,7 +716,7 @@ export const LandConflictSchema = z.object({
     clean: z
         .number()
         .describe(
-            "How many files would apply regardless, so a screen can say how much is being held back by how little and offer to take it. Zero alongside an empty list means the repository could not be reached at all.",
+            "How many files in this repository passed but remain held with the refused composition. Zero alongside an empty list means the repository could not be reached at all.",
         ),
     // The branch the user's checkout is on, the thing the agent has to rebase onto. Carried because only the
     // daemon can see it: an isolated turn's worktree is mounted over the agent's whole view, so the resolution
@@ -730,13 +730,13 @@ export const LandConflictSchema = z.object({
         ),
 });
 export type LandConflict = z.infer<typeof LandConflictSchema>;
-// land's outcome; landed only when every repo with changes applied cleanly. Conflicted repos keep their
-// worktree state, nothing is lost, and "Land now" stays available. `resolving` is populated only by a
-// `merge` land: the paths written into the workspace carrying conflict markers, which the user finishes by
-// hand in their own editor exactly as they would any merge.
+// Land's outcome for the whole frozen repo composition. The ordinary mode preflights every repo before it
+// writes any main tree: landed means all of them applied, and a conflict means none did. Every worktree keeps
+// its state, nothing is lost, and "Land now" stays available. `resolving` is populated only by a `merge` land:
+// the paths written into the workspace carrying conflict markers, which the user finishes by hand.
 export const LandResultSchema = z.object({
-    landed: z.boolean().describe("Whether anything was applied."),
-    conflicts: z.array(LandConflictSchema).optional().describe("What stopped it, per repository."),
+    landed: z.boolean().describe("Whether the entire composed change was applied."),
+    conflicts: z.array(LandConflictSchema).optional().describe("What stopped the whole composed change, grouped per repository."),
     resolving: z
         .array(
             z.object({
@@ -745,7 +745,7 @@ export const LandResultSchema = z.object({
             }),
         )
         .optional()
-        .describe("Files left half-merged, when you asked for the mode that lands what it can and leaves the rest marked up."),
+        .describe("Files left half-merged when you asked to carry the whole composition with its conflicts marked for resolution."),
     // A `measure` outcome with an outstanding delta: nothing was applied and nothing failed, the work is
     // waiting on the branch for a deliberate Land. `landed: false` alone can't say that (it means refusal).
     held: z
@@ -756,14 +756,13 @@ export const LandResultSchema = z.object({
         ),
 });
 export type LandResult = z.infer<typeof LandResultSchema>;
-/* land's input. `check` is the safe default and the historical behaviour: the delta is applied only if ALL of
- * it applies, so a refusal leaves the workspace byte-identical. `merge` is the escape hatch the conflict
- * report offers, a three-way apply that lands every clean path and leaves the rest with conflict markers to
- * resolve in place. It is opt-in because it WRITES on failure, which is the one thing `check` promises not
- * to do. `measure` is the auto-land-off mode: everything a land does EXCEPT touching the main tree, the
- * provenance commit onto agent/<id>, the cumulative diffstat, and the bookkeeping for work that reached the
- * main line by another road, so a held agent's card stays as current as a landed one's while its delta waits
- * on the branch for a deliberate Land. */
+/* Land's input. `check` is the safe default: every repo is preflighted and the composition is applied only if
+ * ALL of it applies, so a refusal leaves every main tree byte-identical. `merge` is the escape hatch the
+ * conflict report offers, a three-way apply that carries the whole composition and leaves conflicted paths
+ * with markers to resolve in place. It is opt-in because it writes those markers. `measure` is the
+ * auto-land-off mode: everything a land does EXCEPT touching the main trees, the provenance commit onto
+ * agent/<id>, the cumulative diffstat, and the bookkeeping for work that reached main by another road, so a
+ * held agent's card stays current while its composed delta waits for a deliberate Land. */
 export const LandModeSchema = z.enum(["check", "merge", "measure"]);
 export type LandMode = z.infer<typeof LandModeSchema>;
 /* WHICH RUNG OF AN AGENT'S HISTORY A READING, or a land. STARTS AT.
@@ -795,7 +794,7 @@ export type AgentSpan = z.infer<typeof AgentSpanSchema>;
 export const AgentLandSchema = z.object({
     id: z.string().min(1).describe("Which conversation's work to merge."),
     mode: LandModeSchema.optional().describe(
-        "How to apply it. The default applies all of it or none, so a refusal leaves the workspace exactly as it was. The other lands every clean file and leaves the rest with conflict markers to resolve by hand.",
+        "How to apply it. The default applies every repository or none, so a refusal leaves the workspace exactly as it was. The other carries the whole composition and leaves conflicted paths with markers to resolve by hand.",
     ),
     span: AgentSpanSchema.optional().describe("How much of the work to take. Leave it out for everything not yet merged."),
     force: z.boolean().optional().describe("Go ahead despite a check that would otherwise refuse."),

package/src/schemas/computers.ts

@@ -117,6 +117,53 @@ export const MachineFlowLineSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("error"), message: z.string() }),
 ]);
 export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
+/* RUNNING ONE OF THIS PRODUCT'S OWN CLIs ON A CONNECTED COMPUTER, FROM A BUTTON, with no agent in the loop.
+ *
+ * A machine that is connected as a computer can already be told things: the ops above drive its docker, and an
+ * agent with the `host` capability can run whatever it likes through `run_command`. What had no door was the
+ * ordinary case in between — the user wants the thing the CLI on their machine already does, and the sandbox is
+ * where they are looking. Their alternatives were to go and find a terminal, or to ask an agent to do it, which
+ * spends a turn and a model's judgement on a decision that has none in it.
+ *
+ * So: a CLOSED SET OF NAMES, and the argv is built on the daemon from the name alone (hosts/machine-commands.ts).
+ * The browser sends `mirror-off`, never a command line. That is the whole security property, and it is the
+ * reason this is an enum rather than a string: the same socket carries `run_command`, so a route that forwarded
+ * caller-supplied text would hand every browser session a shell on the user's laptop, which is a grant the
+ * capability card never made.
+ *
+ * The machine still enforces its own switches. "Run commands" being off comes back as its own refusal, in its
+ * own words, naming the control to flip — exactly as it does for the sandbox ops. */
+export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on"]);
+export type MachineCommand = z.infer<typeof MachineCommandSchema>;
+/* Which paired sandbox the command acts on: the machine's own id for it, as it appears in that machine's report,
+ * so nothing here has to re-derive the sanitizing the agent applied. Absent means every sandbox that machine
+ * pairs, which is what the CLI does when it is run bare.
+ *
+ * Pattern-bound because it becomes an argv token. It must start with an alphanumeric, not merely consist of id
+ * characters: a value like `--takeover` is made only of legal id characters and is a FLAG by the time the CLI on
+ * the machine parses it. Real ids are `sandbox-<hex>-<zone>`-shaped, so nothing legitimate leads with a dash. */
+export const MachineSandboxIdSchema = z
+    .string()
+    .max(200)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export const MachineCommandInputSchema = z.object({
+    id: z.string().min(1),
+    command: MachineCommandSchema,
+    sandboxId: MachineSandboxIdSchema.optional(),
+});
+export type MachineCommandInput = z.infer<typeof MachineCommandInputSchema>;
+/* What came back. `ok` is the command's own exit status, not this route's: a machine that refused the call, or a
+ * CLI that exited non-zero, is a real answer to show the person who clicked, not an exception to convert into
+ * one. Only an unreachable machine throws, because then there is nothing to report at all.
+ *
+ * `output` is what the command printed, kept because the CLI's own sentences ("Port mirroring OFF for: …") are
+ * better than anything this side would write over them. */
+export const MachineCommandResultSchema = z.object({
+    ok: z.boolean(),
+    message: z.string(),
+    output: z.string().optional(),
+});
+export type MachineCommandResult = z.infer<typeof MachineCommandResultSchema>;
 // One paired sandbox as the local agent holds it. `localDir` is the answer to the question the Desktop sync card
 // has never been able to answer: which folder on that computer this sandbox's /work actually is.
 export const MachinePairingSchema = z.object({
@@ -124,6 +171,19 @@ export const MachinePairingSchema = z.object({
     mode: z.enum(["sync", "mirror"]),
     // Set only for mode "sync", and only for the sandbox being reported to, see the redaction note above.
     localDir: z.string().optional(),
+    /* Whether that computer is putting this sandbox's ports on its own localhost, which is a switch its owner
+     * holds and not a state this sandbox can read off anything else. An empty port list means two opposite
+     * things — nothing is listening in the sandbox, or the machine was told to keep them off — and only the
+     * second is worth a word on screen or a button to undo.
+     *
+     * The MACHINE owns the flag (the agent's `sync mirror off`), because the localhost being written to is
+     * there: a computer told to keep ports off must keep them off while this sandbox is asleep, unreachable, or
+     * arguing. A browser asks for it by running that same command over the machine's `host` capability, so the
+     * button and the CLI are one gesture rather than two mechanisms that can disagree.
+     *
+     * Optional because it is a fact only an agent new enough to have the switch reports; absent is read as "on",
+     * which is what mirroring has always been. */
+    mirroring: z.enum(["on", "off"]).optional(),
     // Mutagen's own word for what the session is doing ("watching", "scanning", "transitioning", "halted-…").
     // Carried verbatim rather than mapped to a traffic light: the halted states name their own cause, and a UI
     // that reduces them to "problem" sends the user back to the terminal this report exists to replace.

package/src/schemas/extension-updates.ts

@@ -299,13 +299,15 @@ export const WorkspaceExtensionCreatedSchema = z.object({
     id: z.string().describe("The id it was given."),
     dir: z.string().describe("Where its files are, so you can open them."),
 });
-/* A batch of calls the host observed against this extension's declared routes, entry → how many since the last
- * report. Counts rather than events, and declared entries rather than concrete paths, because the question the
- * ledger answers is "is this permission earned?": a finer record would be a log of what the owner was doing,
- * indexed by extension, which is not a thing this product should be accumulating to answer it. */
-export const ExtensionUsageInputSchema = z.object({
-    id: z.string().describe("Which extension."),
-    used: z.record(z.string(), z.number().int().positive()).describe("Which of its declared powers it exercised, and how many times."),
+/* Batches of calls the host observed against extensions' declared routes: extension id → declared entry → how
+ * many since the last report. Counts rather than events, and declared entries rather than concrete paths,
+ * because the question the ledger answers is "is this permission earned?": a finer record would be a log of
+ * what the owner was doing, indexed by extension, which is not a thing this product should be accumulating to
+ * answer it. Every extension rides one request so the bookkeeping cannot become its own request burst. */
+export const ExtensionUsageBatchSchema = z.object({
+    reports: z
+        .record(z.string(), z.record(z.string(), z.number().int().positive()))
+        .describe("Each extension that called something, and the counts against the declared powers it exercised."),
 });
 // One declared background process (contributes.processes), status/start/stop, addressed by the capability
 // entry id + the manifest's process name. Undeclared names are NOT_FOUND, the manifest-honesty rule again.

package/src/schemas/workspace-tree.ts

@@ -101,16 +101,25 @@ export const WorkspaceTreeSchema = z.object({
     hidden: z.number().describe("How many entries at the top level were cut for size. Zero means the listing is complete."),
 });
 export type WorkspaceTree = z.infer<typeof WorkspaceTreeSchema>;
-// Lazy-load one directory's children, for a dir the tree walk listed but didn't descend into. Child dirs again
-// carry no `children`, so they lazy-load on their own expand. `hidden` = how many entries the cap cut (0 = all
-// listed).
+// Lazy-load one directory's children, for a dir the tree walk listed but didn't descend into. The ordinary
+// request is one level; a bounded `depth` lets a caller that genuinely needs a small subtree receive its
+// descendants in the same flat `entries` list instead of issuing one request per directory.
 export const WorkspaceChildrenQuerySchema = WorkspaceScopeSchema.extend({
     path: z.string().min(1).describe("The folder to open, as a workspace path."),
+    depth: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe("How many levels to include. Omitted means direct children only; at most five levels can be read in one request."),
 });
 export const WorkspaceChildrenSchema = z.object({
     entries: z
         .array(WorkspaceTreeEntrySchema)
-        .describe("What is directly inside it. Folders in here carry no contents of their own, so they open the same way."),
+        .describe(
+            "What is inside it, as a flat list. With the default depth these are direct children; a deeper request also includes descendants, whose full paths say where they belong. Folders carry no nested contents of their own.",
+        ),
     hidden: z.number().describe("How many entries were cut for size. Zero means the listing is complete."),
 });
 export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;

package/src/tunnel-ids.ts

@@ -6,10 +6,10 @@ import { createHash } from "node:crypto";
 export const sha256Hex = (value: string): string => createHash("sha256").update(value).digest("hex");
 
 // The sandbox's stable 12-hex id, digested from the connect token. Used by:
-//   • the CLI's sandbox-tunnel bootstrap (sandbox-tunnel.ts) to name the tunnel + DNS
-//   • the preview hostname builder beside it (hostnames.ts)
-//   • the sandbox daemon's sync SSH hostname derivation (sync.ts)
-// All three MUST agree on the digest, so it lives in the contract they share.
+//   • the hostname builders beside it (hostnames.ts) — every public name embeds this id
+//   • the platform's reachability grant mint and tunnelId lookup (reachability.ts, ingress-contract.ts)
+//   • the desktop agent's loopback-port derivation for the direct-dial shortcut (daemon-base.ts)
+// All of them MUST agree on the digest, so it lives in the contract they share.
 export const sandboxIdFromToken = (connectToken: string): string | undefined =>
     connectToken === "" ? undefined : sha256Hex(connectToken).slice(0, 12);