@intentic/sandbox-contract 1.225.0 → 1.226.1

package/src/contracts/inventory.contract.ts

@@ -5,7 +5,31 @@ import { AddInventoryInputSchema, InventoryListSchema, InventoryNameParamSchema
 // commit it (mirroring an agent edit) and return the full updated list so the UI re-renders from one response.
 // Deploy-target hosts self-register out-of-band via the daemon's plain /enroll route (connect-host script).
 export const inventoryContract = {
-    list: oc.route({ method: "GET", path: "/inventory" }).output(InventoryListSchema),
-    add: oc.route({ method: "POST", path: "/inventory" }).input(AddInventoryInputSchema).output(InventoryListSchema),
-    remove: oc.route({ method: "DELETE", path: "/inventory/{name}" }).input(InventoryNameParamSchema).output(InventoryListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/inventory",
+            summary: "Machines and services you have declared",
+            description: "What the deployment configuration says this setup owns and what it wants provisioned.",
+        })
+        .output(InventoryListSchema),
+    add: oc
+        .route({
+            method: "POST",
+            path: "/inventory",
+            summary: "Declare a machine or service",
+            description:
+                "Writes the entry into the configuration file and commits it, exactly as an agent editing that file by hand would. Answers with the whole updated list, so a screen redraws from one response.",
+        })
+        .input(AddInventoryInputSchema)
+        .output(InventoryListSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/inventory/{name}",
+            summary: "Undeclare a machine or service",
+            description: "Takes the entry back out of the configuration and commits that too. Answers with the whole updated list.",
+        })
+        .input(InventoryNameParamSchema)
+        .output(InventoryListSchema),
 };

package/src/contracts/logs.contract.ts

@@ -4,6 +4,22 @@ import { LogReadQuerySchema, LogReadSchema, LogsListSchema } from "../schemas.js
 // Daemon-owned debug logs (historyRoot/logs): terminal pipe-pane captures, intentic CLI run logs, daemon.log.
 // Read-only by design, the files are written by the daemon/tmux only, so the record stays trustworthy.
 export const logsContract = {
-    list: oc.route({ method: "GET", path: "/logs" }).output(LogsListSchema),
-    read: oc.route({ method: "GET", path: "/logs/file" }).input(LogReadQuerySchema).output(LogReadSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/logs",
+            summary: "Logs the sandbox keeps",
+            description:
+                "Every log file the daemon owns: captured terminal output, command runs, and the daemon's own log. Read-only, because only the sandbox writes them.",
+        })
+        .output(LogsListSchema),
+    read: oc
+        .route({
+            method: "GET",
+            path: "/logs/file",
+            summary: "Read part of a log",
+            description: "A window of one log file's text. A window rather than the whole thing, because a busy log outgrows any single answer.",
+        })
+        .input(LogReadQuerySchema)
+        .output(LogReadSchema),
 };

package/src/contracts/loops.contract.ts

@@ -32,31 +32,83 @@ import {
 export const loopsContract = {
     // Every loop this workspace has run, newest first, the record is kept after the loop ends, because "why did
     // it stop at iteration 4" is the question a loop is read for, and the answer is its iteration history.
-    list: oc.route({ method: "GET", path: "/loops" }).output(LoopsListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/loops",
+            summary: "Every loop that has run",
+            description:
+                "The loops this workspace has run, newest first, kept after they end. Why it stopped on the fourth round is the question a loop gets read for, and the round-by-round history is the answer.",
+        })
+        .output(LoopsListSchema),
     /* Start looping a conversation. Rejects when that conversation is already looping, a second loop on one
      * agent would have two pumps racing the same worktree and the same turn mutex, and the loser would spend a
      * turn to discover it.
      *
      * The conversation need not exist yet: a loop against a fresh id opens it, exactly as a first chat turn
      * does, which is what lets "run this until it's green" be the FIRST thing said to a new agent. */
-    start: oc.route({ method: "POST", path: "/loops" }).input(LoopSchema).output(LoopRecordSchema),
+    start: oc
+        .route({
+            method: "POST",
+            path: "/loops",
+            summary: "Run a conversation until it is done",
+            description:
+                "Starts repeating a conversation towards a goal and answers straight away with the loop as recorded; the work carries on without you. The conversation need not exist yet, so run this until it passes can be the first thing you ever say to a new agent. A conversation already looping is refused.",
+        })
+        .input(LoopSchema)
+        .output(LoopRecordSchema),
     /* Stop the loop, leaving the turn in flight alone.
      *
      * The split is deliberate and it is the one thing about this route that has to be right: stopping a LOOP
      * means "do not start another iteration", not "kill what is running". A user watching iteration 6 do good
      * work should be able to say "this is the last one" without throwing that work away. Killing the turn is
      * what /agent/stop is for, and pressing both is the ordinary way to abandon a loop outright. */
-    stop: oc.route({ method: "POST", path: "/loops/{conversationId}/stop" }).input(LoopIdParamSchema).output(OkSchema),
+    stop: oc
+        .route({
+            method: "POST",
+            path: "/loops/{conversationId}/stop",
+            summary: "Make this round the last",
+            description:
+                "Means do not start another round, not stop what is running. Somebody watching the sixth round do good work can say this is the last one without throwing that work away. To cut the current round off as well, stop the conversation too.",
+        })
+        .input(LoopIdParamSchema)
+        .output(OkSchema),
 
     // Every saved loop. A literal path segment under /loops rather than a surface of its own, because a saved
     // loop is not a different feature, it is the same loop with its goal left blank until somebody types one.
-    designs: oc.route({ method: "GET", path: "/loops/designs" }).output(LoopDesignsListSchema),
+    designs: oc
+        .route({
+            method: "GET",
+            path: "/loops/designs",
+            summary: "Saved loop designs",
+            description:
+                "Loops somebody authored once and can point at a different job each time. A saved loop is the same loop with its goal left blank until you type one, not a different feature.",
+        })
+        .output(LoopDesignsListSchema),
     /* Create or replace a saved loop, with the operation explicit so a name collision cannot turn a create into
      * a replacement. Refuses a design that could never finish, nothing to produce and nothing to check, with
      * the same sentence `start` refuses an ad-hoc loop for, because it is the same mistake made earlier and
      * catching it at save time is the whole advantage of saving. */
-    saveDesign: oc.route({ method: "POST", path: "/loops/designs" }).input(LoopDesignSaveSchema).output(LoopDesignSchema),
+    saveDesign: oc
+        .route({
+            method: "POST",
+            path: "/loops/designs",
+            summary: "Create or replace a saved loop",
+            description:
+                "Say which of the two you mean, so a name that happens to collide cannot silently overwrite somebody's work. A design that could never finish, with nothing to produce and nothing to check, is refused in the same words an ad-hoc loop would be: catching that at save time is the whole advantage of saving.",
+        })
+        .input(LoopDesignSaveSchema)
+        .output(LoopDesignSchema),
     // Deleting a saved loop does NOT stop a loop running from it: a running loop copied the fields it needed
     // when it started, so it converges or gives up on its own terms, and its record stays readable.
-    removeDesign: oc.route({ method: "DELETE", path: "/loops/designs/{id}" }).input(LoopDesignIdParamSchema).output(OkSchema),
+    removeDesign: oc
+        .route({
+            method: "DELETE",
+            path: "/loops/designs/{id}",
+            summary: "Delete a saved loop",
+            description:
+                "Removes the design. A loop already running from it keeps going on its own terms, because it took a copy of what it needed when it started.",
+        })
+        .input(LoopDesignIdParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/panels.contract.ts

@@ -6,7 +6,30 @@ import { OkSchema, PanelRepoParamSchema, PanelsListSchema } from "../schemas.js"
 // on the global GET /system/terminals (the web app's one terminal panel); the interactive I/O is the
 // /system/terminal WebSocket.
 export const panelsContract = {
-    list: oc.route({ method: "GET", path: "/panels" }).output(PanelsListSchema),
-    start: oc.route({ method: "POST", path: "/panels/{repo}/start" }).input(PanelRepoParamSchema).output(OkSchema),
-    stop: oc.route({ method: "POST", path: "/panels/{repo}/stop" }).input(PanelRepoParamSchema).output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/panels",
+            summary: "Repos you can run and preview",
+            description: "Every repo with whether its dev server is up and what the sandbox worked out about its contents.",
+        })
+        .output(PanelsListSchema),
+    start: oc
+        .route({
+            method: "POST",
+            path: "/panels/{repo}/start",
+            summary: "Start a repo's dev server",
+            description: "Brings the repo's own runnable app up in a terminal you can attach to, so its preview address starts answering.",
+        })
+        .input(PanelRepoParamSchema)
+        .output(OkSchema),
+    stop: oc
+        .route({
+            method: "POST",
+            path: "/panels/{repo}/stop",
+            summary: "Stop a repo's dev server",
+            description: "Shuts it down and frees the port.",
+        })
+        .input(PanelRepoParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/personas.contract.ts

@@ -29,9 +29,26 @@ import {
  * Per-verb routes rather than one whole-kit PUT: a kit is a directory of files somebody edits one at a time, and
  * a save that shipped the whole folder would make an edit to one skill capable of deleting another. */
 export const personasContract = {
-    list: oc.route({ method: "GET", path: "/personas" }).output(PersonasListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/personas",
+            summary: "The characters an agent can wear",
+            description:
+                "Each persona with the connected accounts it speaks for, what a conversation wearing it is allowed to do, and where it works.",
+        })
+        .output(PersonasListSchema),
     // Upsert by id, re-saving the same id edits that card.
-    save: oc.route({ method: "POST", path: "/personas" }).input(PersonaSchema).output(OkSchema),
+    save: oc
+        .route({
+            method: "POST",
+            path: "/personas",
+            summary: "Create or edit a persona",
+            description:
+                "Writes the whole card; sending an id that exists edits it. Nothing is connected, installed or spent by saving one, because a persona only records a decision about accounts that already exist. It is stored as a file you can equally well edit by hand, which is why this writes the card whole rather than patching a field: a round trip through a screen should leave a change a reviewer recognises.",
+        })
+        .input(PersonaSchema)
+        .output(OkSchema),
     /* Removing a card takes away a persona, never an account: the login it named stays connected and reachable from
      * every other surface. What it CAN do is orphan a reference, an automation pinned to this id now names a
      * card that no longer exists, and the resolver reads that as "no accounts at all" rather than "all of
@@ -40,17 +57,69 @@ export const personasContract = {
      * every other surface. It DOES take the card's kit with it, a folder no card can reach is a folder no list
      * shows, and leaving the owner's prompt and skills orphaned on disk is worse than deleting what they just
      * asked to delete. */
-    remove: oc.route({ method: "DELETE", path: "/personas/{id}" }).input(PersonaIdParamSchema).output(OkSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/personas/{id}",
+            summary: "Delete a persona",
+            description:
+                "Takes away the character, never the accounts: every login it named stays connected. Its own prompt and skills go with it, since a folder nothing can reach is worse than deleting what somebody just asked to delete. Anything still pointed at it goes quiet rather than falling back to speaking as everyone.",
+        })
+        .input(PersonaIdParamSchema)
+        .output(OkSchema),
 
     // ---- the kit: what this card is told, and the skills only it reaches ----
 
-    kit: oc.route({ method: "GET", path: "/personas/{id}/kit" }).input(PersonaIdParamSchema).output(PersonaKitSchema),
+    kit: oc
+        .route({
+            method: "GET",
+            path: "/personas/{id}/kit",
+            summary: "What one persona carries",
+            description:
+                "The instructions this persona is given and the skills only its conversations can reach. A different question from what the agent knows generally, with a different answer.",
+        })
+        .input(PersonaIdParamSchema)
+        .output(PersonaKitSchema),
     // An empty prompt DELETES the file rather than storing a blank one, so "custom with nothing written" is one
     // state instead of two, the resolver falls back to the sandbox's prompt for it (personas.ts personaPrompt).
-    savePrompt: oc.route({ method: "POST", path: "/personas/{id}/prompt" }).input(PersonaPromptSchema).output(OkSchema),
-    readSkill: oc.route({ method: "GET", path: "/personas/{id}/skills/read" }).input(PersonaSkillNameSchema).output(PersonaSkillBodySchema),
+    savePrompt: oc
+        .route({
+            method: "POST",
+            path: "/personas/{id}/prompt",
+            summary: "Write a persona's instructions",
+            description:
+                "Sets what this persona is told. Saving an empty one removes it entirely rather than storing a blank, so the persona simply falls back to the sandbox's own instructions.",
+        })
+        .input(PersonaPromptSchema)
+        .output(OkSchema),
+    readSkill: oc
+        .route({
+            method: "GET",
+            path: "/personas/{id}/skills/read",
+            summary: "Read one of a persona's skills",
+            description: "The full text of a single skill belonging to this persona.",
+        })
+        .input(PersonaSkillNameSchema)
+        .output(PersonaSkillBodySchema),
     // Upsert by name, like the sandbox's own skills, and with no enabled list to write, because a kit skill is
     // on exactly when its persona is worn. That is what "specific to that persona" has to mean.
-    saveSkill: oc.route({ method: "POST", path: "/personas/{id}/skills" }).input(PersonaSkillSchema).output(OkSchema),
-    removeSkill: oc.route({ method: "POST", path: "/personas/{id}/skills/remove" }).input(PersonaSkillNameSchema).output(OkSchema),
+    saveSkill: oc
+        .route({
+            method: "POST",
+            path: "/personas/{id}/skills",
+            summary: "Write one of a persona's skills",
+            description:
+                "Creates or replaces a skill by name. There is nothing to switch on: a persona's skill is available exactly when that persona is worn, which is what belonging to it has to mean.",
+        })
+        .input(PersonaSkillSchema)
+        .output(OkSchema),
+    removeSkill: oc
+        .route({
+            method: "POST",
+            path: "/personas/{id}/skills/remove",
+            summary: "Delete one of a persona's skills",
+            description: "Removes a single skill from this persona and leaves the rest of its kit alone.",
+        })
+        .input(PersonaSkillNameSchema)
+        .output(OkSchema),
 };

package/src/contracts/ports.contract.ts

@@ -5,7 +5,31 @@ import { OkSchema, PortForwardResultSchema, PortParamSchema, PortsListSchema } f
 // schemas.ts). `forward` is idempotent, re-forwarding a port returns its existing slot's URL; `unforward`
 // frees the slot immediately (the hostname keeps resolving, the proxy just stops mapping it).
 export const portsContract = {
-    list: oc.route({ method: "GET", path: "/ports" }).output(PortsListSchema),
-    forward: oc.route({ method: "POST", path: "/ports/forward" }).input(PortParamSchema).output(PortForwardResultSchema),
-    unforward: oc.route({ method: "POST", path: "/ports/unforward" }).input(PortParamSchema).output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/ports",
+            summary: "What is listening inside the sandbox",
+            description: "Every port something is answering on, and whether each one is reachable from outside.",
+        })
+        .output(PortsListSchema),
+    forward: oc
+        .route({
+            method: "POST",
+            path: "/ports/forward",
+            summary: "Make a port reachable",
+            description:
+                "Gives one port an address on the outside. Asking twice is harmless: the second call hands back the address the first one made.",
+        })
+        .input(PortParamSchema)
+        .output(PortForwardResultSchema),
+    unforward: oc
+        .route({
+            method: "POST",
+            path: "/ports/unforward",
+            summary: "Stop exposing a port",
+            description: "Frees the slot at once. The address keeps resolving; it simply stops leading anywhere.",
+        })
+        .input(PortParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/prepush.contract.ts

@@ -11,7 +11,30 @@ import { OkSchema, PrepushRunSchema } from "../schemas.js";
 // tmux window, so watching it is the terminal's job. `cancel` kills that window; the run settles as `cancelled`
 // and the push it was gating does not go.
 export const prepushContract = {
-    state: oc.route({ method: "GET", path: "/prepush/state" }).output(PrepushRunSchema),
-    run: oc.route({ method: "POST", path: "/prepush/run" }).output(OkSchema),
-    cancel: oc.route({ method: "POST", path: "/prepush/cancel" }).output(OkSchema),
+    state: oc
+        .route({
+            method: "GET",
+            path: "/prepush/state",
+            summary: "How the pre-push check is going",
+            description:
+                "The verdict, or the progress so far. Nothing is addressed by id here, because there is one working tree and so exactly one check.",
+        })
+        .output(PrepushRunSchema),
+    run: oc
+        .route({
+            method: "POST",
+            path: "/prepush/run",
+            summary: "Run the checks before pushing",
+            description:
+                "Starts the suite the workspace runs before anything leaves the machine, and answers immediately. A suite takes minutes, and a request held open that long dies at the first proxy. It runs in a real terminal, so watch it there and poll for the verdict.",
+        })
+        .output(OkSchema),
+    cancel: oc
+        .route({
+            method: "POST",
+            path: "/prepush/cancel",
+            summary: "Stop the pre-push check",
+            description: "Kills the run. It settles as cancelled and the push it was gating does not go.",
+        })
+        .output(OkSchema),
 };

package/src/contracts/providers.contract.ts

@@ -19,5 +19,14 @@ import { ModelsSchema, NativeProviderParamSchema } from "../schemas.js";
 export const providersContract = {
     // One provider's models (+ its default id), never empty, live discovery with a persisted/seed floor behind
     // it. Order is the provider's own preference order and is not re-ranked here; see ModelsSchema.
-    models: oc.route({ method: "GET", path: "/providers/{provider}/models" }).input(NativeProviderParamSchema).output(ModelsSchema),
+    models: oc
+        .route({
+            method: "GET",
+            path: "/providers/{provider}/models",
+            summary: "Models one provider offers",
+            description:
+                "Every model this provider serves and which one it defaults to. Never empty: it is discovered live with a stored list behind it. The order is the provider's own preference and is not rearranged here.",
+        })
+        .input(NativeProviderParamSchema)
+        .output(ModelsSchema),
 };

package/src/contracts/public.contract.ts

@@ -8,7 +8,33 @@ import { OkSchema, PublicListSchema, PublishResultSchema, PublishSchema, Unpubli
 // unauthenticated `public-<slot>` hostname, and a second, authenticated way in would just be the workspace file
 // API with extra steps.
 export const publicContract = {
-    list: oc.route({ method: "GET", path: "/public" }).output(PublicListSchema),
-    publish: oc.route({ method: "POST", path: "/public/publish" }).input(PublishSchema).output(PublishResultSchema),
-    unpublish: oc.route({ method: "POST", path: "/public/unpublish" }).input(UnpublishSchema).output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/public",
+            summary: "What is published to the internet",
+            description:
+                "Everything currently in the outbox and the address it answers on. There is no call to read a published file back: it is served openly to anyone with the link, which is the entire point of having put it there.",
+        })
+        .output(PublicListSchema),
+    publish: oc
+        .route({
+            method: "POST",
+            path: "/public/publish",
+            summary: "Put a file on the internet",
+            description:
+                "Copies a workspace file or folder into the outbox, where it is served to anyone with the link and no sign-in. Answers with the address.",
+        })
+        .input(PublishSchema)
+        .output(PublishResultSchema),
+    unpublish: oc
+        .route({
+            method: "POST",
+            path: "/public/unpublish",
+            summary: "Take something off the internet",
+            description:
+                "Withdraws one published entry. When the last one goes, the outbox goes with it, so its existing at all always means something is published.",
+        })
+        .input(UnpublishSchema)
+        .output(OkSchema),
 };

package/src/contracts/push.contract.ts

@@ -11,8 +11,41 @@ import { OkSchema, PushChannelIdSchema, PushChannelSchema, PushConfigQuerySchema
 // (device permission, service-worker or shell registration, the daemon's key, the push service itself), a
 // button that proves the whole chain end-to-end is worth more than any amount of status rendering.
 export const pushContract = {
-    config: oc.route({ method: "GET", path: "/push/config" }).input(PushConfigQuerySchema).output(PushConfigSchema),
-    subscribe: oc.route({ method: "POST", path: "/push/subscribe" }).input(PushChannelSchema).output(OkSchema),
-    unsubscribe: oc.route({ method: "POST", path: "/push/unsubscribe" }).input(PushChannelIdSchema).output(OkSchema),
-    test: oc.route({ method: "POST", path: "/push/test" }).output(PushTestSchema),
+    config: oc
+        .route({
+            method: "GET",
+            path: "/push/config",
+            summary: "What a device needs to subscribe",
+            description: "The public key and settings a browser or app needs before it can register for notifications from this sandbox.",
+        })
+        .input(PushConfigQuerySchema)
+        .output(PushConfigSchema),
+    subscribe: oc
+        .route({
+            method: "POST",
+            path: "/push/subscribe",
+            summary: "Send notifications to this device",
+            description:
+                "Registers one device. The sandbox only interrupts you on the three moments where attention is genuinely wanted: a turn has finished, the agent is stuck on a question, and something is waiting for approval.",
+        })
+        .input(PushChannelSchema)
+        .output(OkSchema),
+    unsubscribe: oc
+        .route({
+            method: "POST",
+            path: "/push/unsubscribe",
+            summary: "Stop notifying a device",
+            description: "Removes one registered device. Others keep receiving.",
+        })
+        .input(PushChannelIdSchema)
+        .output(OkSchema),
+    test: oc
+        .route({
+            method: "POST",
+            path: "/push/test",
+            summary: "Send a test notification",
+            description:
+                "Proves the whole chain end to end. Worth having, because there are four separate places a notification can be lost that nobody can inspect from the outside: the device's permission, its registration, the sandbox's key, and the delivery service.",
+        })
+        .output(PushTestSchema),
 };

package/src/contracts/secrets.contract.ts

@@ -7,9 +7,50 @@ import { OkSchema, SecretInventorySchema, SecretKeyParamSchema, SecretKeysSchema
 // values). `reveal` is the single value-returning route, owner-only, POST so the key never sits in a URL.
 // set/remove/list/reveal refuse until DevOps has scaffolded the desired-state repo; inventory always answers.
 export const secretsContract = {
-    set: oc.route({ method: "POST", path: "/secrets" }).input(SecretSetSchema).output(OkSchema),
-    list: oc.route({ method: "GET", path: "/secrets" }).output(SecretKeysSchema),
-    remove: oc.route({ method: "DELETE", path: "/secrets/{key}" }).input(SecretKeyParamSchema).output(OkSchema),
-    inventory: oc.route({ method: "GET", path: "/secrets/inventory" }).output(SecretInventorySchema),
-    reveal: oc.route({ method: "POST", path: "/secrets/reveal" }).input(SecretKeyParamSchema).output(SecretRevealSchema),
+    set: oc
+        .route({
+            method: "POST",
+            path: "/secrets",
+            summary: "Store a secret",
+            description:
+                "Writes one name and value into the sandbox's own store, where running processes pick it up without a restart. Refused until the sandbox has somewhere to keep them.",
+        })
+        .input(SecretSetSchema)
+        .output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/secrets",
+            summary: "Names of the stored secrets",
+            description: "Which secrets exist here. Names only, never values.",
+        })
+        .output(SecretKeysSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/secrets/{key}",
+            summary: "Delete a secret",
+            description: "Removes one by name.",
+        })
+        .input(SecretKeyParamSchema)
+        .output(OkSchema),
+    inventory: oc
+        .route({
+            method: "GET",
+            path: "/secrets/inventory",
+            summary: "Every secret this sandbox holds, from everywhere",
+            description:
+                "One view across all the places secrets live here: what exists, where it came from and whether it is working. Never any values. This one always answers, even before there is a store to write to.",
+        })
+        .output(SecretInventorySchema),
+    reveal: oc
+        .route({
+            method: "POST",
+            path: "/secrets/reveal",
+            summary: "Show one secret's value",
+            description:
+                "The only call that hands a value back, and it is for the owner alone. Sent as a body rather than in the address, so the name never ends up in a log or a browser's history.",
+        })
+        .input(SecretKeyParamSchema)
+        .output(SecretRevealSchema),
 };

package/src/contracts/sessions.contract.ts

@@ -13,8 +13,22 @@ import { SessionIdParamSchema, SessionsListSchema } from "../schemas.js";
 // a switch either of them ignored would show as one field returning two different match sets.
 export const sessionsContract = {
     list: oc
-        .route({ method: "GET", path: "/sessions" })
+        .route({
+            method: "GET",
+            path: "/sessions",
+            summary: "Past conversations in this workspace",
+            description:
+                "Summaries for a history menu, filtered when you pass a search. Covers conversations that worked in their own private copies too, so nothing is hidden just because it happened on a branch.",
+        })
         .input(z.object({ query: z.string().optional(), caseSensitive: z.stringbool().optional() }))
         .output(SessionsListSchema),
-    get: oc.route({ method: "GET", path: "/sessions/{id}" }).input(SessionIdParamSchema).output(SessionTranscriptSchema),
+    get: oc
+        .route({
+            method: "GET",
+            path: "/sessions/{id}",
+            summary: "Read one past conversation",
+            description: "The full record of a single conversation, restored for display.",
+        })
+        .input(SessionIdParamSchema)
+        .output(SessionTranscriptSchema),
 };

package/src/contracts/settings.contract.ts

@@ -17,12 +17,53 @@ import {
 // read out of the installed CLI, so the settings page can SHOW the prompt behind a mode instead of asking the
 // user to trust a description of it, and can fork either into a custom one.
 export const settingsContract = {
-    get: oc.route({ method: "GET", path: "/settings" }).output(SandboxSettingsSchema),
-    set: oc.route({ method: "POST", path: "/settings" }).input(SandboxSettingsSchema).output(OkSchema),
-    savings: oc.route({ method: "GET", path: "/settings/savings" }).input(DayWindowQuerySchema).output(SavingsReportSchema),
-    builtinPrompt: oc.route({ method: "GET", path: "/settings/system-prompt/{base}" }).input(BuiltinPromptSchema).output(BuiltinPromptTextSchema),
+    get: oc
+        .route({
+            method: "GET",
+            path: "/settings",
+            summary: "How this sandbox is configured",
+            description: "Every setting that governs how agents behave here, with the defaults filled in for anything nobody has chosen.",
+        })
+        .output(SandboxSettingsSchema),
+    set: oc
+        .route({
+            method: "POST",
+            path: "/settings",
+            summary: "Change the sandbox settings",
+            description: "Writes the settings whole, so send the complete object rather than the fields you changed.",
+        })
+        .input(SandboxSettingsSchema)
+        .output(OkSchema),
+    savings: oc
+        .route({
+            method: "GET",
+            path: "/settings/savings",
+            summary: "What the token-saving measures were worth",
+            description:
+                "Measured rather than estimated: what each mechanism actually saved over a range of days. The same day range the spending ledger takes, so one calendar filters both.",
+        })
+        .input(DayWindowQuerySchema)
+        .output(SavingsReportSchema),
+    builtinPrompt: oc
+        .route({
+            method: "GET",
+            path: "/settings/system-prompt/{base}",
+            summary: "Read a built-in system prompt",
+            description:
+                "The actual text behind one of the built-in modes, so a settings screen can show the prompt instead of asking anyone to trust a description of it, and so either can be forked into a custom one.",
+        })
+        .input(BuiltinPromptSchema)
+        .output(BuiltinPromptTextSchema),
     // When each rule last did something, keyed by rule id. Its own route rather than a field on the settings
     // object because a firing is not an edit: folding it in would make every push a settings write, and would
     // put a value that changes on its own inside the object the screen optimistically patches.
-    firings: oc.route({ method: "GET", path: "/settings/rule-firings" }).output(RuleFiringsSchema),
+    firings: oc
+        .route({
+            method: "GET",
+            path: "/settings/rule-firings",
+            summary: "When each rule last did something",
+            description:
+                "A separate read rather than a field on the settings, because a rule firing is not somebody editing anything: folding it in would turn every firing into a settings write and put a self-changing value inside the object a screen edits.",
+        })
+        .output(RuleFiringsSchema),
 };