@intentic/sandbox-contract 1.226.0 → 1.226.1

package/src/contracts/chores.contract.ts

@@ -13,11 +13,37 @@ import { ChoreLedgerWriteSchema, ChoreProbeRequestSchema, ChoresReportSchema, Ok
 export const choresContract = {
     // Every repo's standing evidence in one read: cached probe results (with their age and state), the cheap
     // resident signals, the ledger, and the daemon's node version. The rail badge polls this; so does the panel.
-    list: oc.route({ method: "GET", path: "/chores" }).output(ChoresReportSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/chores",
+            summary: "What maintenance the repos are asking for",
+            description:
+                "Every repo's standing evidence in one read: what the last measurement found and how old it is, the cheap signals that are always current, and what has already been decided about each.",
+        })
+        .output(ChoresReportSchema),
     // Re-run one repo's probe now, ignoring its TTL, the panel's per-probe refresh. An ack: the runner works in
     // the background and the result arrives on the next `list`, because a jscpd sweep outlives any sane request.
-    probe: oc.route({ method: "POST", path: "/chores/probe" }).input(ChoreProbeRequestSchema).output(OkSchema),
+    probe: oc
+        .route({
+            method: "POST",
+            path: "/chores/probe",
+            summary: "Measure one repo again now",
+            description:
+                "Re-runs a single check without waiting for it to go stale. Answers immediately: the work happens in the background and the result turns up in the next read, because some of these sweeps outlive any sane request.",
+        })
+        .input(ChoreProbeRequestSchema)
+        .output(OkSchema),
     // Record what a chore turn concluded, or snooze one. Upsert by repo+chore: a chore has one current verdict,
     // and a growing history of "we looked at this and it was fine" is not something any reader wants paged.
-    record: oc.route({ method: "POST", path: "/chores/ledger" }).input(ChoreLedgerWriteSchema).output(OkSchema),
+    record: oc
+        .route({
+            method: "POST",
+            path: "/chores/ledger",
+            summary: "Record a verdict, or snooze one",
+            description:
+                "Writes what somebody concluded about one repo's chore, replacing the previous verdict. A chore has one current answer, not a growing pile of times it was fine.",
+        })
+        .input(ChoreLedgerWriteSchema)
+        .output(OkSchema),
 };

package/src/contracts/ci.contract.ts

@@ -15,13 +15,62 @@ import {
 // (/ci/webhook/:host) is a plain Hono route, vendors can't do Google ID tokens, so it lives outside this
 // contract, like /automations/{id}/fire.
 export const ciContract = {
-    runs: oc.route({ method: "GET", path: "/ci/runs" }).output(CiRunsResponseSchema),
-    rerun: oc.route({ method: "POST", path: "/ci/runs/rerun" }).input(CiRunParamSchema).output(OkSchema),
-    cancel: oc.route({ method: "POST", path: "/ci/runs/cancel" }).input(CiRunParamSchema).output(OkSchema),
-    jobs: oc.route({ method: "POST", path: "/ci/runs/jobs" }).input(CiRunParamSchema).output(CiJobsResponseSchema),
-    fix: oc.route({ method: "POST", path: "/ci/fix" }).input(CiFixParamSchema).output(CiFixResponseSchema),
+    runs: oc
+        .route({
+            method: "GET",
+            path: "/ci/runs",
+            summary: "Pipeline runs across the repos",
+            description:
+                "What the forges are reporting for every workspace repo that has a remote, served from a cache and filled in on demand. Repos whose notifications are not wired up say so.",
+        })
+        .output(CiRunsResponseSchema),
+    rerun: oc
+        .route({
+            method: "POST",
+            path: "/ci/runs/rerun",
+            summary: "Run a pipeline again",
+            description: "Asks the forge to re-run one pipeline. The daemon only passes the request along.",
+        })
+        .input(CiRunParamSchema)
+        .output(OkSchema),
+    cancel: oc
+        .route({
+            method: "POST",
+            path: "/ci/runs/cancel",
+            summary: "Cancel a pipeline run",
+            description: "Asks the forge to stop a run in progress.",
+        })
+        .input(CiRunParamSchema)
+        .output(OkSchema),
+    jobs: oc
+        .route({
+            method: "POST",
+            path: "/ci/runs/jobs",
+            summary: "The steps inside one pipeline run",
+            description: "Each job in a run with its outcome, which is where you look to find out what actually broke.",
+        })
+        .input(CiRunParamSchema)
+        .output(CiJobsResponseSchema),
+    fix: oc
+        .route({
+            method: "POST",
+            path: "/ci/fix",
+            summary: "Put an agent on a broken pipeline",
+            description:
+                "Opens a fresh isolated conversation already holding the failure: which job, which repo, what it said. The answer names the conversation so you can open it.",
+        })
+        .input(CiFixParamSchema)
+        .output(CiFixResponseSchema),
     // "I have looked at the pipelines", what silences the rail badge for breakages already read. No input:
     // the surface is read as a whole, and the daemon stamps its own clock so a skewed browser can't mark
     // future failures as already seen.
-    seen: oc.route({ method: "POST", path: "/ci/seen" }).output(CiSeenResponseSchema),
+    seen: oc
+        .route({
+            method: "POST",
+            path: "/ci/seen",
+            summary: "Mark the pipelines as read",
+            description:
+                "Silences the badge for breakages already looked at. Takes nothing, because the view is read as a whole, and the daemon stamps its own clock so a browser with the wrong time cannot mark future failures as already seen.",
+        })
+        .output(CiSeenResponseSchema),
 };

package/src/contracts/claude.contract.ts

@@ -19,11 +19,53 @@ import {
 // shared /providers/{provider}/models route (providers.contract.ts). What is left is what is genuinely Claude's
 //, an account handshake no other provider has.
 export const claudeContract = {
-    start: oc.route({ method: "POST", path: "/claude/oauth/start" }).output(AuthorizeChallengeSchema),
-    exchange: oc.route({ method: "POST", path: "/claude/oauth/exchange" }).input(OauthExchangeSchema).output(OauthAccountSchema),
+    start: oc
+        .route({
+            method: "POST",
+            path: "/claude/oauth/start",
+            summary: "Begin connecting a Claude account",
+            description:
+                "Hands back the address to send somebody to, and the proof this sandbox will need to finish the exchange. The sandbox holds the credential afterwards, not the browser.",
+        })
+        .output(AuthorizeChallengeSchema),
+    exchange: oc
+        .route({
+            method: "POST",
+            path: "/claude/oauth/exchange",
+            summary: "Finish connecting a Claude account",
+            description:
+                "Trades the code from the sign-in for stored tokens and answers with the account it just connected. A sandbox can hold several Claude accounts side by side.",
+        })
+        .input(OauthExchangeSchema)
+        .output(OauthAccountSchema),
     // Each account carries its plan-limit reading. `force` re-measures before answering, see
     // AccountListQuerySchema, and USAGE_WAIT_MS in claude.routes.ts for what an ordinary read waits.
-    accounts: oc.route({ method: "GET", path: "/claude/accounts" }).input(AccountListQuerySchema).output(OauthAccountListSchema),
-    rename: oc.route({ method: "POST", path: "/claude/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
-    disconnect: oc.route({ method: "POST", path: "/claude/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
+    accounts: oc
+        .route({
+            method: "GET",
+            path: "/claude/accounts",
+            summary: "Connected Claude accounts",
+            description:
+                "Each connected account with how full its plan limits were when last measured. Ask for a fresh measurement and it takes one before answering, which is slower.",
+        })
+        .input(AccountListQuerySchema)
+        .output(OauthAccountListSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/claude/account/rename",
+            summary: "Rename a Claude account",
+            description: "Changes the label one account shows under, so several are tellable apart.",
+        })
+        .input(AccountRenameSchema)
+        .output(OauthAccountSchema),
+    disconnect: oc
+        .route({
+            method: "POST",
+            path: "/claude/account/disconnect",
+            summary: "Disconnect a Claude account",
+            description: "Clears the stored tokens for one account. The others stay connected.",
+        })
+        .input(AccountIdSchema)
+        .output(OkSchema),
 };

package/src/contracts/drafts.contract.ts

@@ -5,7 +5,30 @@ import { DraftIdParamSchema, DraftsListSchema, DraftSummarySchema, OkSchema } fr
 // directly, these routes are the OWNER's side: `list` is the approval inbox, `upsert` covers approve / edit /
 // retry (all a plain re-post with a field changed, like the automations enabled toggle), `remove` is reject.
 export const draftsContract = {
-    list: oc.route({ method: "GET", path: "/drafts" }).output(DraftsListSchema),
-    upsert: oc.route({ method: "POST", path: "/drafts" }).input(DraftSummarySchema).output(OkSchema),
-    remove: oc.route({ method: "DELETE", path: "/drafts/{id}" }).input(DraftIdParamSchema).output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/drafts",
+            summary: "Posts waiting for your approval",
+            description: "The queue of things an agent has written and would like to publish. Nothing here has gone anywhere yet.",
+        })
+        .output(DraftsListSchema),
+    upsert: oc
+        .route({
+            method: "POST",
+            path: "/drafts",
+            summary: "Approve, edit or retry a draft",
+            description: "All three are the same act with a different field changed, so they share one call. Send the draft back as you want it.",
+        })
+        .input(DraftSummarySchema)
+        .output(OkSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/drafts/{id}",
+            summary: "Reject a draft",
+            description: "Throws one away unposted.",
+        })
+        .input(DraftIdParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/endpoints.contract.ts

@@ -44,6 +44,23 @@ export const TrialStatusSchema = z.object({
 export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;
 
 export const endpointsContract = {
-    models: oc.route({ method: "GET", path: "/endpoints/{id}/models" }).input(CapabilityIdParamSchema).output(ModelsSchema),
-    trial: oc.route({ method: "GET", path: "/endpoints/trial/status" }).output(TrialStatusSchema),
+    models: oc
+        .route({
+            method: "GET",
+            path: "/endpoints/{id}/models",
+            summary: "Models a connected server offers",
+            description:
+                "Asks one configured model server what it serves. There is no built-in list and no fallback: what a server offers is knowable only by asking it, so an empty answer is the honest report that we could not.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(ModelsSchema),
+    trial: oc
+        .route({
+            method: "GET",
+            path: "/endpoints/trial/status",
+            summary: "What is left of the free trial",
+            description:
+                "The allowance, what has been used, when it resets, and which model actually answered the last message. Not being available is the ordinary answer rather than a failure: most sandboxes run against a platform that offers no trial at all.",
+        })
+        .output(TrialStatusSchema),
 };

package/src/contracts/exit.contract.ts

@@ -18,25 +18,87 @@ export const exitContract = {
     // Every configured exit with its live state, where it was asked to come out and where it actually does.
     // Drives the Status card, the browser account picker and `geo list` (the CLI is `geo`: `exit` is a shell
     // builtin, so a binary of that name is unreachable from a command line).
-    list: oc.route({ method: "GET", path: "/exit" }).output(ExitListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/exit",
+            summary: "Ways to come out somewhere else",
+            description:
+                "Every configured exit with its live state, the country it was asked to appear in, and the country it actually appears in. Those last two disagreeing is the whole reason this reports both.",
+        })
+        .output(ExitListSchema),
     // What this exit can reach, ranked by how much capacity is actually there. Live from the provider when it
     // answers (Tor's directory, VPN Gate's CSV, the pasted confs), from the baked fallback when it does not,
     // and `live` says which. This is what auto-fills the country picker instead of a user hunting hostnames.
-    countries: oc.route({ method: "GET", path: "/exit/{id}/countries" }).input(ExitIdParamSchema).output(ExitCountriesSchema),
+    countries: oc
+        .route({
+            method: "GET",
+            path: "/exit/{id}/countries",
+            summary: "Countries one exit can reach",
+            description:
+                "Where this exit can put you, ranked by how much capacity is really there. Asked of the provider when it answers and taken from a built-in list when it does not, and the answer says which of those you got.",
+        })
+        .input(ExitIdParamSchema)
+        .output(ExitCountriesSchema),
     // Bring the exit up at its stored country. Streams, because a first start pulls a catalog, brings up a
     // tunnel and then verifies the address, which is tens of seconds on the free providers and can fail at
     // each step with something the user has to read. Idempotent: starting an up exit reports it and stops.
-    start: oc.route({ method: "POST", path: "/exit/{id}/start" }).input(ExitIdParamSchema).output(eventIterator(IntenticLineSchema)),
+    start: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/start",
+            summary: "Bring an exit up",
+            description:
+                "Starts the exit in the country it was configured for. Streamed, because a first start fetches a catalogue, raises a tunnel and then checks the address, which takes tens of seconds on the free providers and can fail at each step with something worth reading. Starting one that is already up simply says so.",
+        })
+        .input(ExitIdParamSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // Move to another country, starting the exit first if it was down. Streams for the same reason as start,
     // and THROWS when the observed country does not end up matching: a switch that silently left traffic where
     // it was is the one failure mode this whole feature exists to make impossible.
-    use: oc.route({ method: "POST", path: "/exit/{id}/use" }).input(ExitUseInputSchema).output(eventIterator(IntenticLineSchema)),
+    use: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/use",
+            summary: "Move to another country",
+            description:
+                "Switches the exit's country, starting it first if it was down. It ends by checking where the world actually sees you and fails if that does not match what you asked for. A switch that quietly left your traffic where it was is the exact failure this whole feature exists to rule out.",
+        })
+        .input(ExitUseInputSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // A different address in the SAME country. Cheap on tor (a control-port signal), a re-dial to another
     // server on the rest. Fails when the address does not actually change, which on a small pool it can't.
-    rotate: oc.route({ method: "POST", path: "/exit/{id}/rotate" }).input(ExitIdParamSchema).output(eventIterator(IntenticLineSchema)),
+    rotate: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/rotate",
+            summary: "Take a different address, same country",
+            description:
+                "Swaps to another address in the country you are already in. Fails if the address does not actually change, which on a small pool it sometimes cannot.",
+        })
+        .input(ExitIdParamSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // What the world sees through this exit right now. Cheap, unstreamed, and the honest answer to "am I
     // actually in Germany", which is the question every other route here is judged against.
-    check: oc.route({ method: "POST", path: "/exit/{id}/check" }).input(ExitIdParamSchema).output(ExitObservationSchema),
+    check: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/check",
+            summary: "Where the world sees you right now",
+            description:
+                "Looks up the address and country as seen through this exit. Cheap, and the honest answer to whether you are really where you meant to be, which is what every other call here is judged against.",
+        })
+        .input(ExitIdParamSchema)
+        .output(ExitObservationSchema),
     // Take it down. Tolerates an already-down exit: "make it not be up" is the contract, not "it was up".
-    stop: oc.route({ method: "POST", path: "/exit/{id}/stop" }).input(ExitIdParamSchema).output(OkSchema),
+    stop: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/stop",
+            summary: "Take an exit down",
+            description:
+                "Shuts the exit off. One that was already down is fine: the promise is that it is not up afterwards, not that it was up before.",
+        })
+        .input(ExitIdParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/extensions.contract.ts

@@ -24,25 +24,86 @@ import {
 // `settings`/`setSettings` carry the extension's own contributes.settings values; keys the manifest never
 // declared are refused, the same honesty rule the host applies to runtime view/command registrations.
 export const extensionsContract = {
-    list: oc.route({ method: "GET", path: "/extensions" }).output(ExtensionsListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/extensions",
+            summary: "Installed extensions",
+            description:
+                "Every extension installed here, resolved to the manifest the owner approved, which is what the app boots its extension host from. The code itself is served separately, because raw script bytes are not a JSON answer.",
+        })
+        .output(ExtensionsListSchema),
     // Author a new extension in place: writes a running one into .intentic/config/workspace-extensions/<name>/. The only
     // creating route here, and it exists because that directory is otherwise reachable exclusively through an
     // agent's file tools, which is a fine way to CHANGE an extension and a poor way to meet the idea of one.
-    create: oc.route({ method: "POST", path: "/extensions/workspace" }).input(WorkspaceExtensionCreateSchema).output(WorkspaceExtensionCreatedSchema),
-    settings: oc.route({ method: "GET", path: "/extensions/{id}/settings" }).input(CapabilityIdParamSchema).output(ExtensionSettingsSchema),
-    setSettings: oc.route({ method: "POST", path: "/extensions/{id}/settings" }).input(ExtensionSettingsInputSchema).output(OkSchema),
+    create: oc
+        .route({
+            method: "POST",
+            path: "/extensions/workspace",
+            summary: "Write a new extension in place",
+            description:
+                "Scaffolds a working extension into this workspace and installs it. The only call here that creates one, and it exists because that folder is otherwise reachable only through an agent's file tools, which is a fine way to change an extension and a poor way to meet the idea of one.",
+        })
+        .input(WorkspaceExtensionCreateSchema)
+        .output(WorkspaceExtensionCreatedSchema),
+    settings: oc
+        .route({
+            method: "GET",
+            path: "/extensions/{id}/settings",
+            summary: "An extension's settings",
+            description: "The current values for the settings this extension declared it has.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(ExtensionSettingsSchema),
+    setSettings: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/settings",
+            summary: "Change an extension's settings",
+            description:
+                "Writes new values. A key the extension never declared is refused rather than quietly stored, the same honesty rule that governs everything else an extension claims.",
+        })
+        .input(ExtensionSettingsInputSchema)
+        .output(OkSchema),
     // The owner's on/off switch. Disabling stops the extension's declared processes here and now; its agent
     // plugin dir and PATH entry are rebuilt per turn, and an `environment` fragment only at the next image
     // rebuild, the Extensions tab states which of those an extension actually has.
-    setEnabled: oc.route({ method: "POST", path: "/extensions/{id}/enabled" }).input(ExtensionEnabledInputSchema).output(OkSchema),
+    setEnabled: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/enabled",
+            summary: "Turn an extension on or off",
+            description:
+                "The owner's switch. Turning one off stops its background processes at once. What it contributes to an agent's tools is rebuilt at the start of the next turn, and anything it adds to the sandbox image only at the next rebuild.",
+        })
+        .input(ExtensionEnabledInputSchema)
+        .output(OkSchema),
     // The host reporting which declared routes it just let through. Written by the browser because that is where
     // the permission gate runs (apiImpl.ts), the daemon sees an extension's traffic as ordinary authenticated
     // requests and cannot tell which extension, or which declared entry, any of it belongs to.
-    recordUsage: oc.route({ method: "POST", path: "/extensions/{id}/usage" }).input(ExtensionUsageInputSchema).output(OkSchema),
+    recordUsage: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/usage",
+            summary: "Record what an extension just used",
+            description:
+                "Written by the app rather than measured by the daemon, because the permission gate runs in the browser: from the sandbox's side an extension's traffic is indistinguishable from anyone else's. This is how the record of which powers an extension actually exercises gets kept.",
+        })
+        .input(ExtensionUsageInputSchema)
+        .output(OkSchema),
     /* Whether this extension is fit for somebody else to run, the checks answerable from its files alone. Read
      * on demand rather than carried on the list: it reads the bundle off disk per extension, and it is looked at
      * when an author is about to publish, not every time the tab renders. */
-    readiness: oc.route({ method: "GET", path: "/extensions/{id}/readiness" }).input(CapabilityIdParamSchema).output(ExtensionReadinessSchema),
+    readiness: oc
+        .route({
+            method: "GET",
+            path: "/extensions/{id}/readiness",
+            summary: "Whether an extension is fit to share",
+            description:
+                "The checks that can be answered from an extension's own files, for an author about to publish. Read on demand rather than carried on the list, because it reads the code off disk each time.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(ExtensionReadinessSchema),
     /* The update lifecycle for a GIT-INSTALLED extension. The list carries what the periodic registry check
      * found (update/advisory/health per row); these are the verbs around it. `checkUpdates` runs the comparison
      * now (the tab's "check now"). `updatePreview` stages the offered sha and answers with the version story +
@@ -51,25 +112,83 @@ export const extensionsContract = {
      * checkout one back), restart, health-watch, on the EXISTING capability config, so a private-source token
      * survives what a bare re-add would lose. `revert` swaps the kept-previous checkout back. Update and revert
      * change the code that runs, so like install they are owner-only. */
-    checkUpdates: oc.route({ method: "POST", path: "/extensions/updates/check" }).output(ExtensionUpdatesCheckedSchema),
+    checkUpdates: oc
+        .route({
+            method: "POST",
+            path: "/extensions/updates/check",
+            summary: "Look for extension updates now",
+            description:
+                "Compares every installed extension against its source and reports what is newer, what carries an advisory and what looks unhealthy. This also happens on a schedule; call it to check on demand.",
+        })
+        .output(ExtensionUpdatesCheckedSchema),
     updatePreview: oc
-        .route({ method: "POST", path: "/extensions/{id}/update/preview" })
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/update/preview",
+            summary: "What an update would change",
+            description:
+                "The read before the click: which versions are involved and exactly which powers the new code asks for that the running one does not. Costs one throwaway copy of the source, the same as browsing a registry entry.",
+        })
         .input(ExtensionUpdateActionSchema)
         .output(ExtensionUpdatePreviewSchema),
     applyUpdate: oc
-        .route({ method: "POST", path: "/extensions/{id}/update" })
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/update",
+            summary: "Update an extension",
+            description:
+                "The whole swap as one transaction: fetch, check, quiet the running one, replace it while keeping the outgoing copy one step back, restart and watch it come up. The existing configuration is kept, so a token for a private source survives what removing and re-adding would lose. Owner only, because it changes what code runs.",
+        })
         .input(ExtensionUpdateActionSchema)
         .output(ExtensionUpdateAppliedSchema),
-    revert: oc.route({ method: "POST", path: "/extensions/{id}/revert" }).input(CapabilityIdParamSchema).output(ExtensionUpdateAppliedSchema),
+    revert: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/revert",
+            summary: "Go back to the previous version",
+            description: "Swaps the copy kept from before the last update back into place. Owner only, for the same reason updating is.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(ExtensionUpdateAppliedSchema),
     // The owner's standing answer per extension (notify / agent / auto, and the advisory opt-out), see
     // ExtensionUpdatePolicySchema for what each rung means.
-    setUpdatePolicy: oc.route({ method: "POST", path: "/extensions/{id}/update-policy" }).input(ExtensionUpdatePolicyInputSchema).output(OkSchema),
+    setUpdatePolicy: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/update-policy",
+            summary: "How an extension should handle its own updates",
+            description:
+                "The owner's standing answer for one extension: tell me, have an agent look at it, or just do it. Security advisories can be opted out of separately.",
+        })
+        .input(ExtensionUpdatePolicyInputSchema)
+        .output(OkSchema),
     // Declared background processes (contributes.processes): tmux-managed through the panel machinery
     // (session `panel-ext-<id>-<name>`, PORT-assigned, optional tunneled preview route).
     processStatus: oc
-        .route({ method: "GET", path: "/extensions/{id}/processes/{name}" })
+        .route({
+            method: "GET",
+            path: "/extensions/{id}/processes/{name}",
+            summary: "Whether an extension's background process is up",
+            description: "The state of one process an extension declared, with the port it was given and its preview address if it has one.",
+        })
         .input(ExtensionProcessParamSchema)
         .output(ExtensionProcessStatusSchema),
-    processStart: oc.route({ method: "POST", path: "/extensions/{id}/processes/{name}/start" }).input(ExtensionProcessParamSchema).output(OkSchema),
-    processStop: oc.route({ method: "POST", path: "/extensions/{id}/processes/{name}/stop" }).input(ExtensionProcessParamSchema).output(OkSchema),
+    processStart: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/processes/{name}/start",
+            summary: "Start an extension's background process",
+            description: "Brings one of an extension's declared processes up in an attachable terminal.",
+        })
+        .input(ExtensionProcessParamSchema)
+        .output(OkSchema),
+    processStop: oc
+        .route({
+            method: "POST",
+            path: "/extensions/{id}/processes/{name}/stop",
+            summary: "Stop an extension's background process",
+            description: "Shuts one of an extension's declared processes down and frees its port.",
+        })
+        .input(ExtensionProcessParamSchema)
+        .output(OkSchema),
 };