@intentic/sandbox-contract 1.174.0 → 1.175.1

package/src/schemas.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { CapabilitiesListSchema, SandboxSettingsSchema } from "./schemas.js";
+import { CapabilitiesListSchema, DeployOverviewResponseSchema, SandboxSettingsSchema } from "./schemas.js";
 
 /* The settings shape spans a version seam that really moves: the browser ships with the platform, the daemon
  * ships inside the user's sandbox image, so a web build routinely parses a payload from an OLDER daemon. These
@@ -18,69 +18,23 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         outputCleaners: "-cap",
         outputHoldout: 0.1,
     };
-    expect(SandboxSettingsSchema.parse(older)).toEqual({
-        ...older,
-        terseHoldout: 0,
-        iqContext: false,
-        iqContextHoldout: 0,
-        filterBackend: "native",
-        systemPromptMode: "intentic",
-        systemPrompt: "",
-        quickModel: "",
-        agentRetentionDays: 3,
-        autoLand: true,
-        resumeAfterOutage: true,
-        autoResumeOnRestart: true,
-        prepushCommand: "",
-        prepushTimeoutMs: 900_000,
-        prepushFixModel: "",
-        prepushFixEffort: "",
-    });
+    // The defaults come from the schema, not from a copy of it written here. Transcribing them made every
+    // setting the product gained land as a failure in this file — a diff that only ever said "the list moved",
+    // never "tolerance broke", and whose fix was always to paste the new default in. What this test is about
+    // is the seam: what the old build sent survives verbatim, and what it never heard of arrives at default.
+    expect(SandboxSettingsSchema.parse(older)).toEqual({ ...SandboxSettingsSchema.parse({}), ...older });
 });
 
-test("an empty object is the full default settings object", () => {
-    expect(SandboxSettingsSchema.parse({})).toEqual({
-        stableSystemPrompt: false,
-        skills: [],
-        hashlineEdits: false,
-        terseOutput: false,
-        // Off: the steer's turn-level control spends the tokens it measures, so measuring is opt-in.
-        terseHoldout: 0,
-        iqSearch: false,
-        // Off, and its holdout with it: pre-injection spends input tokens on every eligible turn, and the
-        // control that would tell you whether they paid for themselves costs the turns it measures.
-        iqContext: false,
-        iqContextHoldout: 0,
-        outputCleaners: "off",
-        outputHoldout: 0,
-        filterBackend: "native",
-        // The default base is Intentic's own prompt; the text field is only read under "custom".
-        systemPromptMode: "intentic",
-        systemPrompt: "",
-        // Empty is not "no quick model" — it is Auto, resolved from the connected accounts on every read
-        // (quick-model.ts). Storing a resolved id as the default would name a provider a fresh sandbox has no
-        // credential for, and would go stale the moment one is connected.
-        quickModel: "",
-        // The one default that isn't "off": the fleet board's Finished lane has no exit of its own, and each
-        // card it holds is a worktree checkout. Opting INTO cleanup would mean shipping a leak by default.
-        agentRetentionDays: 3,
-        // On because it is the historical behaviour — defaulting off would silently hold every existing
-        // sandbox's finished work on branches nobody is watching.
-        autoLand: true,
-        // On, where a spent usage limit re-runs nothing: an outage resume spends nothing the dead turn hadn't
-        // already committed, and the turns it saves are the unattended ones nobody is watching to restart by hand.
-        resumeAfterOutage: true,
-        // On: a daemon restart is usually intentic's own doing (an image update, an approved environment
-        // change), not the user's decision, so the turn it interrupted resumes rather than staying stuck.
-        autoResumeOnRestart: true,
-        // Empty disables the pre-push check until the owner supplies this workspace's verification command.
-        prepushCommand: "",
-        prepushTimeoutMs: 900_000,
-        // Empty ⇒ the suggested fix session opens on whatever the chat composer would have started with, which
-        // is the model the user already chose to work with.
-        prepushFixModel: "",
-        prepushFixEffort: "",
-    });
+/* The invariant a fresh sandbox depends on: NO field is required. A settings object is written for the first
+ * time only when the user changes something, so until then the daemon parses `{}` — one field without a
+ * `.default()` turns that into a throw at boot, and the version tolerance above is built on the same property.
+ *
+ * Asserted by shape rather than by value: what each default IS belongs next to the field in schemas.ts, where
+ * the reason it holds is written down. A second copy here proved nothing the schema didn't already say and
+ * failed on every field the product added. */
+test("no field is required — a workspace that has never written settings parses", () => {
+    const defaults = SandboxSettingsSchema.parse({});
+    expect(Object.keys(defaults).sort()).toEqual(Object.keys(SandboxSettingsSchema.shape).sort());
 });
 
 test("a key of the wrong type is still a parse failure — tolerance is for absence, not for garbage", () => {
@@ -98,3 +52,35 @@ test("a capability list from a daemon that predates recommendations parses, with
     const older = { capabilities: [{ id: "github", kind: "cli", status: { state: "active" }, config: { provider: "github" } }] };
     expect(CapabilitiesListSchema.parse(older).recommendations).toEqual([]);
 });
+
+/* The deployments board crosses the same seam and learned it the hard way. `repos` (workspace repo → Komodo
+ * stack links) shipped REQUIRED, and the first sandbox whose daemon predated it rendered
+ * `Invalid input: expected array, received undefined at repos` instead of the board — a dead page, on the one
+ * surface whose job is to say whether production is up, to hide a band of suggestions.
+ *
+ * `viewer` is the deliberate contrast: also added later, also absent from an older daemon, but OPTIONAL rather
+ * than defaulted, because its absence is information. The empty state tells "the key can see nothing" apart
+ * from "we could not tell", and defaulting it would have collapsed the two. */
+
+test("an overview from a daemon that predates repo links parses, with no links rather than no board", () => {
+    const older = { komodoUrl: "https://komodo.example.com", reachable: true, resources: [], servers: [], alerts: [] };
+    const parsed = DeployOverviewResponseSchema.parse(older);
+    expect(parsed.repos).toEqual([]);
+    // Absent, NOT defaulted: the empty state reads this to avoid claiming an empty Komodo it cannot vouch for.
+    expect(parsed.viewer).toBeUndefined();
+});
+
+test("a board that did carry links keeps them, and garbage in them is still a failure", () => {
+    const current = {
+        komodoUrl: "https://komodo.example.com",
+        reachable: true,
+        viewer: { username: "intentic", admin: false },
+        repos: [{ repo: "app", projectName: "app", composePath: "app/compose.yaml", suggestions: ["app-prod"] }],
+        resources: [],
+        servers: [],
+        alerts: [],
+    };
+    expect(DeployOverviewResponseSchema.parse(current).repos[0]?.suggestions).toEqual(["app-prod"]);
+    // Tolerance is for absence, not for the wrong shape — a `repos` that is present and wrong is real drift.
+    expect(DeployOverviewResponseSchema.safeParse({ ...current, repos: "none" }).success).toBe(false);
+});

package/src/schemas.ts

@@ -1,4 +1,5 @@
 import { ExtensionManifestSchema } from "@intentic/extension-api";
+import { RegistryEntrySchema } from "@intentic/registry";
 import { z } from "zod";
 
 // All request/response wire schemas for the sandbox daemon. Inputs that carry a `{param}` in their route path
@@ -962,17 +963,21 @@ export const IntenticRunSchema = z.object({ args: z.array(z.string()) });
 
 // ---- git ----
 
-// What a commit records — two shapes, each a real git spelling:
-//   all: true   ⇒ stage every change in the repo, then commit (`commit -a`; VSCode's "stage all and commit")
+// What a commit records — three shapes, each a real git spelling. The last two are for the case where nothing
+// is staged yet and the caller has said what to stage; they are alternatives, and a caller sends at most one:
 //   absent      ⇒ commit whatever is staged (plain `git commit`)
+//   all: true   ⇒ stage every change in the repo, then commit (`commit -a`; VSCode's "stage all and commit")
+//   paths       ⇒ `git add` those repo-relative paths, then commit the index
 //
-// There is deliberately no `paths`. The index IS git's mechanism for choosing what a commit contains, so a
-// second path-selection channel alongside it can only disagree with it: a `commit --only` over a partially
-// staged file records the WORKTREE content while the row the user picked showed the INDEX content. Staging is
-// the selection; this endpoint only ever records it.
+// `paths` is emphatically NOT `commit --only`. The index IS git's mechanism for choosing what a commit
+// contains, so a second path-selection channel alongside it could only disagree with it: a partial commit over
+// a half-staged file records the WORKTREE content while the row the user picked showed the INDEX content. This
+// stages and then records the whole index, which is why it is safe — and why it also survives a merge, where
+// git refuses a partial commit outright (and refuses it only AFTER moving the index).
 export const CommitSchema = RepoParamSchema.extend({
     message: z.string().min(1),
     all: z.boolean().optional(),
+    paths: z.array(z.string().min(1)).max(500).optional(),
 });
 export const DiscardSchema = RepoParamSchema.extend({
     // Repo-relative paths to discard; absent ⇒ discard every uncommitted change in the repo.
@@ -1001,13 +1006,21 @@ export const GitFilesSchema = z.object({ files: z.array(z.string()) });
 export const GitFileSchema = z.object({ path: z.string(), content: z.string() });
 export const CommitResultSchema = z.object({ committed: z.boolean() });
 
+// One repo's slice of a workspace-wide git action: the whole repo, or only the repo-relative paths named. The
+// same pair the per-repo routes take as {repo} + `paths`, in the one shape a caller that spans repos can send.
+export const RepoPathsSchema = z.object({ repo: z.string().min(1), paths: z.array(z.string().min(1)).max(500).optional() });
+export type RepoPaths = z.infer<typeof RepoPathsSchema>;
+
 /* AI-drafted commit message. Workspace-wide, not per repo, because the commit box's target IS a set of repos
  * sharing one message — so the draft has to see every one of their diffs to describe what the commit actually
- * records. `repos` and `all` mirror the panel's own commit target exactly: `all` reads the WORKTREE (what
- * "Commit all" would sweep), absent reads the INDEX (what a bare commit records). Getting that wrong would
- * describe changes the commit isn't going to contain. */
+ * records. The input mirrors CommitSchema field for field, which is the whole point: whatever the commit is
+ * about to do is what gets described, and the two cannot drift.
+ *   repos[].paths ⇒ the subset that commit will stage — read the WORKTREE, narrowed to those paths
+ *   all: true     ⇒ the whole worktree, untracked included (what "Commit all" sweeps)
+ *   neither       ⇒ the INDEX (what a bare commit records)
+ * Getting that wrong would describe changes the commit isn't going to contain. */
 export const CommitMessageDraftSchema = z.object({
-    repos: z.array(z.string().min(1)).min(1).max(50),
+    repos: z.array(RepoPathsSchema).min(1).max(50),
     all: z.boolean().optional(),
 });
 // The draft plus WHICH model wrote it, so the surface can name it rather than claiming an anonymous "AI" —
@@ -1316,6 +1329,11 @@ export const WorkspaceChildrenSchema = z.object({
 });
 export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;
 export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1) });
+/* The credential a <video>/<audio> element carries to GET /workspace/media, which is the one workspace route a
+ * browser cannot put a header on. Minted here, over the ordinary bearer-authenticated contract, and scoped to
+ * the single path it was asked for — see auth/media-tickets.ts for why scope rather than single-use is what
+ * bounds it. `expiresAt` is epoch ms so a player can tell a dead ticket from a dead file. */
+export const WorkspaceMediaTicketSchema = z.object({ ticket: z.string(), expiresAt: z.number() });
 /* A text read is a read of a WINDOW: `offset` is the byte to start at (negative reads that many bytes from the
  * END, which is what following a growing log means — the tail's offset isn't knowable until the size is), and
  * `limit` how many bytes to serve. The daemon clamps `limit` to its own cap, so an omitted or oversized one is
@@ -2022,23 +2040,13 @@ export const ForticlientConnectionSchema = z.object({
 export type ForticlientConnection = z.infer<typeof ForticlientConnectionSchema>;
 export const ForticlientImportSchema = z.object({ connections: z.array(ForticlientConnectionSchema) });
 
-// Browse a Claude Code plugin marketplace (a git repo with .claude-plugin/marketplace.json). POST so the
-// optional token for a private marketplace never rides a URL or an access log.
+// Browse an extension/plugin registry (a git repo with .claude-plugin/marketplace.json — see
+// @intentic/registry for the format). POST so the optional token for a private registry never rides a URL or
+// an access log.
 export const MarketplaceRequestSchema = z.object({ url: z.string().url(), token: z.string().min(1).optional() });
-// One marketplace entry; `install` is the entry's source resolved onto PluginConfig shape (url/ref/path), so
-// picking an entry just pre-fills the plugin form. Absent = a source the daemon can't clone (e.g. npm).
-export const MarketplacePluginSchema = z.object({
-    name: z.string(),
-    description: z.string().optional(),
-    version: z.string().optional(),
-    // "extension" marks an intentic-extension entry (installs as the `extension` capability, sha-pinned);
-    // absent/"plugin" = a Claude Code plugin. Claude Code ignores unknown marketplace fields, so one
-    // marketplace repo serves both consumers.
-    kind: z.enum(["plugin", "extension"]).optional(),
-    install: z.object({ url: z.string(), ref: z.string().optional(), path: z.string().optional() }).optional(),
-});
-export type MarketplacePlugin = z.infer<typeof MarketplacePluginSchema>;
-export const MarketplaceSchema = z.object({ name: z.string(), plugins: z.array(MarketplacePluginSchema) });
+// The rows are RegistryEntry — the curated decision joined to the resolved pointer and the scanner's upstream
+// facts, exactly as the site's gallery renders them, so browsing in the app and browsing the web show one list.
+export const MarketplaceSchema = z.object({ name: z.string(), plugins: z.array(RegistryEntrySchema) });
 export type Marketplace = z.infer<typeof MarketplaceSchema>;
 
 // ---- extensions: installed extension-kind capabilities resolved to their manifests ----
@@ -2194,10 +2202,18 @@ export const WebchatConfigSchema = z.object({
     // The site's OWN Google OAuth web client id. It cannot be intentic's: Google Identity Services only issues
     // a token to an authorized JavaScript origin, and intentic's client can't list every customer domain.
     googleClientId: z.string().optional(),
-    // Widget chrome. `accent` is any CSS colour the host page can render; `position` picks the launcher corner.
+    /* Widget chrome. `position` picks the launcher corner.
+     *
+     * `accent` is a HEX colour, not any CSS colour, because the widget derives values from its channels rather
+     * than just painting it: a glyph step for the scheme, a 14% wash for the send button, a bubble edge, a focus
+     * ring, and the label that goes on top (see webchat-widget's styles.ts). A colour we cannot read is a widget
+     * with half its accent silently missing, so the unreadable case is rejected here instead. */
     title: z.string().max(80).optional(),
     greeting: z.string().max(500).optional(),
-    accent: z.string().max(40).optional(),
+    accent: z
+        .string()
+        .regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, "accent must be a hex colour, e.g. #e47100")
+        .optional(),
     position: z.enum(["top-right", "top-left", "bottom-right", "bottom-left"]).optional(),
     /* Two ceilings on top of the route's fixed per-minute window, because a public endpoint's real exposure is
      * cost, not request rate: `dailyMessageMax` caps the whole automation per UTC day, `conversationMessageMax`
@@ -2551,6 +2567,57 @@ export const DeployAlertSchema = z.object({
 });
 export type DeployAlert = z.infer<typeof DeployAlertSchema>;
 
+/* Who the API key acts as. Komodo filters EVERY list by the caller's permissions, so a key minted on a service
+ * user with no grants returns 200 and an empty array — byte-identical to a Komodo with nothing deployed. That
+ * ambiguity shipped once and cost a user an afternoon: their Komodo had four stacks and the board said "no
+ * stacks or deployments yet". Carrying the viewer lets the empty state name the actual reason. */
+export const DeployViewerSchema = z.object({
+    username: z.string(),
+    // Either of Komodo's admin flags — an admin key sees everything, so its empty board really is empty.
+    admin: z.boolean(),
+});
+export type DeployViewer = z.infer<typeof DeployViewerSchema>;
+
+/* A workspace repo that ships a compose file, and the Komodo stack it belongs to.
+ *
+ * Komodo names a stack whatever its creator typed; a repo names its compose project in the file. The two
+ * usually agree, or nearly — `intentic` in the repo against `intentic-platform` in Komodo — so the daemon
+ * SUGGESTS and the owner decides. The link is explicit and persisted because a guess that silently becomes a
+ * fact is worse than no guess: the owner is the one who knows that `atlas` is this repo's staging stack. */
+export const DeployRepoLinkSchema = z.object({
+    // The workspace repo dir — the same `repo` key the rest of the app joins on.
+    repo: z.string(),
+    // The compose project name: the file's own `name:` when it has one, else the repo dir. This is what
+    // `docker compose up` would call the project, so it is the best guess at the stack's name.
+    projectName: z.string(),
+    // Workspace-relative path of the compose file the name came from, so the UI can say where it looked.
+    composePath: z.string(),
+    // The stack the owner linked, once they have. Absent ⇒ unlinked, and `suggestions` is the offer.
+    linkedStack: z.string().optional(),
+    // Stack names that look like this repo, best first. Empty when nothing resembles it — in which case the
+    // UI offers the full list rather than pretending it has an opinion.
+    suggestions: z.array(z.string()),
+});
+export type DeployRepoLink = z.infer<typeof DeployRepoLinkSchema>;
+
+// Link a repo to a stack, or clear the link with an empty `stack`. Explicit rather than a toggle: the owner
+// may be replacing one stack with another, and a toggle cannot express that in one call.
+export const DeployLinkParamSchema = z.object({
+    capability: z.string(),
+    repo: z.string(),
+    stack: z.string(),
+});
+export type DeployLinkParam = z.infer<typeof DeployLinkParamSchema>;
+
+/* EVERY FIELD ADDED AFTER THIS ROUTE FIRST SHIPPED IS OPTIONAL OR DEFAULTED, and that is a rule rather than a
+ * style. The browser validates this response with `.parse()`, and the daemon it is talking to is not
+ * necessarily built from the same commit — a sandbox image is rebuilt on the owner's schedule, the web bundle
+ * on ours. `repos` shipped REQUIRED and the first daemon that predated it took the whole view down with
+ * `Invalid input: expected array, received undefined at repos`: not a missing band, a dead page, on the
+ * surface whose entire job is to tell you whether production is up.
+ *
+ * So: a new field is `.default(...)` when the view can render without it, and `.optional()` when its absence
+ * is itself meaningful. Neither is ever `required`. A newer browser must degrade against an older daemon. */
 export const DeployOverviewResponseSchema = z.object({
     komodoUrl: z.string(),
     // FALSE means Komodo did not answer — the view says so loudly and the badge must not read `danger`.
@@ -2559,6 +2626,13 @@ export const DeployOverviewResponseSchema = z.object({
     reachable: z.boolean(),
     // Why it did not answer, in Komodo's own words — the view shows it instead of a bare "unavailable".
     unreachableReason: z.string().optional(),
+    // Absent when Komodo did not answer — or when the daemon predates the field, which the empty state has to
+    // tell apart from "the key sees nothing", since only one of those is the owner's to fix.
+    viewer: DeployViewerSchema.optional(),
+    // Every workspace repo with a compose file, with its suggested or linked stack. Independent of whether
+    // Komodo returned anything: a repo the owner could link is worth showing even on an empty board, since
+    // that is exactly the moment they need to know what this view is for.
+    repos: z.array(DeployRepoLinkSchema).default([]),
     resources: z.array(DeployResourceSchema),
     servers: z.array(DeployServerSchema),
     // Newest first. Unresolved and resolved both: the view shows recent history, the badge reads only the

package/src/workspace-state.ts

@@ -83,9 +83,9 @@ export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
         why: "Which origins have loaded a Doorbell's widget, written on a 30s flush timer while a customer's site serves page views. The install panel that renders it fetches on open and polls itself while it is on screen, which is the whole window in which the answer changes for anyone. Pushing instead would bill every connected browser a refetch per flush, for a panel almost nobody has open.",
     },
     {
-        path: ".intentic/webchat-sessions.json",
+        path: ".intentic/thread-sessions.json",
         invalidates: [],
-        why: "Doorbell thread bookkeeping (visitor thread → sandbox conversation + provider session), written on EVERY visitor message. Nothing in the browser reads it: what a visitor's chat produces is a conversation, and the fleet board already learns about that from the agent registry's own push. Naming a key here would bill every connected browser a refetch per inbound message — the request storm this table's own note warns about — to refresh nothing it can see.",
+        why: "Thread bookkeeping (an inbound thread — a Doorbell visitor, a Discord or Slack channel — → sandbox conversation + provider session), written on EVERY inbound message. Nothing in the browser reads it: what a thread produces is a conversation, and the fleet board already learns about that from the agent registry's own push. Naming a key here would bill every connected browser a refetch per inbound message — the request storm this table's own note warns about — to refresh nothing it can see.",
     },
     {
         path: ".intentic/extension-settings.json",