@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/contracts/intentic.contract.ts

@@ -1,5 +1,5 @@
 import { eventIterator, oc } from "@orpc/contract";
-import { IntenticLineSchema } from "../events.js";
+import { IntenticLineSchema } from "../events/system-events.js";
 import { IntenticRunSchema } from "../schemas/intentic.js";
 import { OkSchema } from "../schemas/shared.js";
 

package/src/contracts/logs.contract.ts

@@ -7,10 +7,8 @@ import {
     LogsListSchema,
 } from "../schemas/logs.js";
 
-// Daemon-owned debug logs (historyRoot/logs): terminal pipe-pane captures, intentic CLI run logs, daemon.log.
-// Reads are read-only by design, the files are written by the daemon/tmux only, so the record stays
-// trustworthy. `report` is the one write, and the exception that proves the rule: the browser is the only
-// witness to its own crashes, and a record it cannot reach is a record that has nothing to say about them.
+// Daemon-owned debug logs (historyRoot/logs): terminal captures, CLI run logs, daemon.log; read-only, since only the
+// daemon/tmux write them. `report` is the one write, since the browser is the only witness to its own crashes.
 export const logsContract = {
     list: oc
         .route({
@@ -30,15 +28,7 @@ export const logsContract = {
         })
         .input(LogReadQuerySchema)
         .output(LogReadSchema),
-    /* What the browser saw. The counterpart to every other route here: those serve what the daemon wrote down,
-     * this accepts what only the browser could have known.
-     *
-     * A WRITE from the client, which every other log route deliberately is not, and the trust argument is the
-     * inverse of theirs: the reads are trustworthy because only the daemon writes them, and this is trustworthy
-     * only about ITSELF. So it lands in its own file, never daemon.log, and its lines say plainly that a browser
-     * said them. It floors at viewer rather than the maintainer the logs prefix takes, because a viewer whose
-     * page just white-screened is exactly who needs to be able to report it, and cannot raise their own role to
-     * do it. */
+    // The one write route; lands in its own file, never daemon.log, floored at viewer role for a crashed page.
     report: oc
         .route({
             method: "POST",

package/src/contracts/loops.contract.ts

@@ -11,27 +11,11 @@ import {
 } from "../schemas/loops.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* The loop routes, "run this conversation again until the goal is met".
- *
- * TWO HALVES THAT LOOK LIKE ONE FEATURE AND ARE NOT, which is why they share a file and share nothing else.
- *
- * A RUNNING LOOP has no editor. It is started against a conversation, it converges or it gives up, and then it
- * is history: `start`, `stop`, and a `list` of what has run. No upsert, no enabled toggle, no id of its own,
- * the conversation IS the id.
- *
- * A SAVED LOOP is a manifest entry like a workflow, and gets the manifest treatment: list, save, remove. It is
- * the loop's MACHINERY without its goal (LoopDesignSchema says why at length), so it is authored once and
- * pointed at a different job every time. It has no `run` route of its own on purpose, running one is `start`
- * with the design's fields and the composer's sentence, so there is exactly one way a loop begins and exactly
- * one place that can refuse it.
- *
- * `start` acks immediately with the loop as recorded and runs detached, the same contract POST /agent keeps: the
- * first iteration alone can take minutes, and every surface that would render progress is already attached to
- * the conversation. What comes back is the record, not an outcome, the outcome arrives on the fleet card.
- */
+// Two halves: a running loop (start/stop/list, no editor, the conversation is its id) and a saved loop
+// (list/save/remove, the loop's machinery without a goal). A saved loop has no `run` of its own; running one is `start`
+// with the design's fields. `start` acks at once and runs detached; the record comes back, not the outcome.
 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.
+    // Kept after the loop ends: the iteration history is the answer to why it stopped when it did.
     list: oc
         .route({
             method: "GET",
@@ -41,12 +25,7 @@ export const loopsContract = {
                 "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. */
+    // Rejects an already-looping conversation; a fresh conversation id opens it, like a first turn.
     start: oc
         .route({
             method: "POST",
@@ -57,12 +36,7 @@ export const loopsContract = {
         })
         .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. */
+    // Stops future rounds only; the round in flight keeps going. Use /agent/stop to kill it too.
     stop: oc
         .route({
             method: "POST",
@@ -74,8 +48,7 @@ export const loopsContract = {
         .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.
+    // A saved loop is the same loop with its goal left blank, not a separate feature.
     designs: oc
         .route({
             method: "GET",
@@ -85,10 +58,7 @@ export const loopsContract = {
                 "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. */
+    // Names create vs replace explicitly, rather than upserting; refuses a design with nothing to produce or check.
     saveDesign: oc
         .route({
             method: "POST",
@@ -99,8 +69,7 @@ export const loopsContract = {
         })
         .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.
+    // Deleting a design does not stop a loop running from it; it already copied the fields it needed.
     removeDesign: oc
         .route({
             method: "DELETE",

package/src/contracts/personas.contract.ts

@@ -13,23 +13,9 @@ import {
 } from "../schemas/personas.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* The sandbox's named personas (PersonaSchema): which connected accounts each one speaks for, what a session
- * wearing it may do, where it works, and what it is told. The card half is a plain three-verb CRUD with no apply
- * step, because a card provisions NOTHING, unlike a capability, saving one connects nothing, installs nothing
- * and spends nothing. It records a decision about accounts that already exist.
- *
- * The file behind it is committed workspace config (personas/personas-store.ts), so these routes are one of
- * two equally supported ways to edit them: this, and opening the file in the editor like any other project
- * config. Neither is the "real" one, which is why `save` is a whole-card upsert rather than a field patch, so
- * a round trip through the UI leaves a diff a reviewer would recognise.
- *
- * THE KIT ROUTES BELOW EDIT FILES, not the card, and they are here rather than on the skills contract because
- * what they write belongs to one persona: its prompt, and the skills only its turns can reach
- * (personas/persona-kit.ts). The sandbox's `skills` domain answers "what does the agent know" for every chat;
- * this answers "what does this card carry", and the two lists are different questions with different answers.
- *
- * 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. */
+// Named personas (PersonaSchema): accounts each speaks for, what it may do, what it is told. Card CRUD provisions
+// nothing, only a decision about existing accounts. The kit routes below edit its files (prompt, skills only its turns
+// reach) per verb, not one whole-kit PUT, so one skill's edit cannot delete another.
 export const personasContract = {
     list: oc
         .route({
@@ -51,14 +37,8 @@ export const personasContract = {
         })
         .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
-     * them", so the automation goes quiet instead of posting as somebody unintended. */
-    /* Removing a card takes away a persona, never an account: the login it named stays connected and reachable from
-     * 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. */
+    // Never removes the account; an automation pinned to this id resolves as no accounts, and goes quiet.
+    // Also deletes the persona's kit folder (prompt + skills), rather than leaving it orphaned on disk.
     remove: oc
         .route({
             method: "DELETE",
@@ -70,22 +50,19 @@ export const personasContract = {
         .input(PersonaIdParamSchema)
         .output(OkSchema),
 
-    /* WHICH CARD A NEW CHAT BELONGS TO, asked by the composer before the first turn and answered by the
-     * `persona-router` helper role (the sandbox's agent/persona-router.ts). A READ that spends a small model
-     * call, which is why it is a POST: it is not idempotent in cost, only in effect. Nothing is applied here; the
-     * composer applies the answer, or shows it, under the `personaRouting` setting. */
+    // Costs a model call, hence POST though a read; the chat that asked applies the answer, this only reports it.
     route: oc
         .route({
             method: "POST",
             path: "/personas/route",
             summary: "Which persona a new chat belongs to",
             description:
-                "Reads the message a chat is about to open with, and one line per persona, and names the card it belongs to, or none. Costs one small model call on the persona-routing list. Nothing is applied: the composer shows or applies the answer according to the persona routing setting.",
+                "Reads the message a chat has just been sent, and one line per persona, and names the card it belongs to, or none, along with the model that answered. Costs one small model call on the persona-routing list, and says so. Nothing is applied here: the chat that asked puts the card on, and only when the persona routing setting is on.",
         })
         .input(PersonaRouteAskSchema)
         .output(PersonaRouteSchema),
 
-    // ---- the kit: what this card is told, and the skills only it reaches ----
+    // The kit: what this card is told, and the skills only it reaches.
 
     kit: oc
         .route({
@@ -97,8 +74,7 @@ export const personasContract = {
         })
         .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).
+    // An empty prompt deletes the file rather than storing a blank; it then falls back to the sandbox's own prompt.
     savePrompt: oc
         .route({
             method: "POST",
@@ -118,8 +94,7 @@ export const personasContract = {
         })
         .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.
+    // Upsert by name, no enabled list to write: a kit skill is on exactly when its persona is worn.
     saveSkill: oc
         .route({
             method: "POST",

package/src/contracts/providers.contract.ts

@@ -2,24 +2,11 @@ import { oc } from "@orpc/contract";
 import { NativeProviderParamSchema } from "../schemas/agent.js";
 import { ModelsSchema } from "../schemas/provider-oauth.js";
 
-// EVERY NATIVE PROVIDER'S PICKER CATALOG, ON ONE ROUTE.
-//
-// There were five of these: /claude/models, /codex/models, /grok/models, /kimi/models, /gemini/models, one per
-// provider, each a contract entry, a route factory and a service field wired separately. They differed in
-// nothing: same method, same output schema, same "the daemon's catalog for this provider, never empty". Three of
-// the five route files were the same fifteen lines with a name swapped, and the daemon paid for that shape twice
-// more in the branch chains that had to fan back out over the providers to ask them all the same question.
-//
-// So the provider is a PARAMETER, not five routes. Adding one is a row in the daemon's catalog registry, the
-// same discipline the adapter registry already applies to serving a turn, rather than a vertical slice through
-// the contract, the router, the service container and every test double.
-//
-// Endpoints keep their own route (endpoints.contract.ts) and should: they are user-created and unbounded, their
-// id names a capability that may not exist, and a missing one is a NOT_FOUND rather than an empty catalog. That
-// is a different question with a different failure, not a sixth provider.
+// The provider is a parameter, not a route per provider; adding one is a row in the catalog registry. Endpoints keep
+// their own route (endpoints.contract.ts): they are user-created and unbounded, and a missing one is NOT_FOUND, not an
+// empty catalog.
 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.
+    // Never empty: live discovery with a persisted/seed floor; order is the provider's own, not re-ranked.
     models: oc
         .route({
             method: "GET",

package/src/contracts/runner.contract.ts

@@ -1,46 +1,24 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { z } from "zod";
-import { AgentEventSchema } from "../events.js";
-import { RunnerFactsSchema, RunnerSyncLineSchema, RunnerSyncSchema, RunnerTurnSchema } from "../runner-protocol.js";
+import { AgentEventSchema } from "../events/agent-events.js";
+import { RunnerFactsSchema, RunnerSyncLineSchema, RunnerSyncSchema, RunnerTurnSchema } from "../protocol/runner-protocol.js";
 import { EditorContextSchema } from "../schemas/agent.js";
 import { AgentReplySchema } from "../schemas/plan-limits.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* What a RUNNER can be asked, over the socket it opened to its parent sandbox. Phase-1 skeleton: the shape is
- * decided (docs/remote-runners-plan.md §5, workspace root), the implementations land with runner mode.
- *
- * Same inversion as hostContract: the runner dialled, but the runner is the oRPC SERVER and the parent holds
- * the client, because a runner sits behind NAT or inside a Fly private network and can only ever be the side
- * that connects. No `.route()` on these, the link never touches HTTP; the procedure path IS the address.
- *
- * TYPED THROUGHOUT, where hostContract keeps its deliberate `mcp` hole, and the difference is who releases
- * what. A machine's tools must outlive the daemon's release cycle, so their schemas stay on the machine. A
- * runner IS this daemon, the same image the parent runs, released together by construction, so an untyped
- * channel would buy independence nobody has while costing the parent's persistence layer its guarantee that
- * every frame is exactly what a local turn would have produced. */
+// What a runner can be asked, over the socket it opened; same inversion as hostContract, the runner is the oRPC server,
+// the parent the client. No `.route()`: the procedure path is the address. Typed throughout, unlike hostContract's
+// `mcp` hole, since a runner is the same daemon image as the parent, released together.
 export const runnerContract = {
-    // What this runner is, hardware-wise: pulled after the socket authenticates and again whenever the
-    // placement picker wants it fresh. Parity facts (image, overlay hash) ride the hello instead, they change
-    // only with a rebuild, which drops the socket anyway.
+    // Hardware facts, refreshed on demand; parity facts (image, overlay hash) ride the hello, not this call.
     describe: oc.output(RunnerFactsSchema),
-    // Bring the runner's checkout of one conversation's branch up to date (`pull`), or return the result
-    // after a turn (`push`). Streamed: a first sync clones repositories, and a person may be watching.
+    // `pull` updates the checkout, `push` returns a turn's result; streamed since a first sync clones repos.
     syncWorkspace: oc.input(RunnerSyncSchema).output(eventIterator(RunnerSyncLineSchema)),
-    // The dispatch: one turn in, the frames a local turn would have produced out. The parent republishes them
-    // into the same pipeline local frames enter, which is the whole "feels local" mechanism.
+    // One turn in, the frames a local turn would produce out; the parent republishes them into the local pipeline.
     runTurn: oc.input(RunnerTurnSchema).output(eventIterator(AgentEventSchema)),
-    /* THE USER, REACHING THE TURN THEY ARE WATCHING. A remote turn's question, permission prompt and plan
-     * approval are minted in the RUNNER's request registry, and the answer arrives at the PARENT (that is
-     * where the browser is). So it travels back down the same socket and is applied there by the same code a
-     * local answer takes (agent/turn-interactions.ts).
-     *
-     * `applied` rather than a throw: "nothing holds that id any more" is an ordinary race (the card was
-     * answered in another window, or the turn ended while the user was reading), and the parent turns it
-     * into the same NOT_FOUND its local path gives. */
+    // Returns `applied` rather than throwing: a missing id is an ordinary race, same as local NOT_FOUND.
     reply: oc.input(AgentReplySchema).output(z.object({ applied: z.boolean() })),
-    /* Speaking into a running remote turn. The parent sends the user's words, the attachment paths and the
-     * editor context UNCOMPOSED: the note over those paths has to be built against the runner's own
-     * workspace root, since that is the machine whose files the agent will open. */
+    // Attachments/editor context travel uncomposed: the note must build against the runner's own workspace root.
     steer: oc
         .input(
             z.object({
@@ -51,15 +29,10 @@ export const runnerContract = {
             }),
         )
         .output(z.object({ applied: z.boolean(), invalid: z.string().optional() })),
-    /* The parent pushing its declared shape onto this runner: a settings-only definition (sandbox.toml text,
-     * runner-protocol.ts's hello says why settings are all a runner declares). REPLACE semantics, not the
-     * owner-facing apply's merge-beside: a key the definition omits returns to its default, because the parent
-     * is a runner's whole authority and "make this runner match" must also unset what the parent unset. The
-     * answer names the keys now holding non-default values, which is what the parent adopts as the runner's
-     * new declared shape without waiting for a reconnect. */
+    // REPLACE semantics: a key the definition omits returns to its default, unlike the owner apply's merge-beside.
     applyDefinition: oc.input(z.object({ toml: z.string() })).output(z.object({ settings: z.array(z.string()) })),
     // Stop the running turn; the parent's stop button reaching through.
     interrupt: oc.input(RunnerTurnSchema.pick({ conversationId: true })).output(OkSchema),
-    // Liveness, driven by the parent: keepalive and gone-detection in one, the host hub's heartbeat verbatim.
+    // Liveness driven by the parent: keepalive and gone-detection in one.
     ping: oc.output(OkSchema),
 };

package/src/contracts/safety.contract.ts

@@ -1,18 +1,11 @@
 import { oc } from "@orpc/contract";
-import { SafetyLogEntrySchema, SafetyPolicySchema } from "../safety-policy.js";
+import { SafetyLogEntrySchema, SafetyPolicySchema } from "../policy/safety-policy.js";
 import { OkSchema } from "../schemas/shared.js";
 import { z } from "zod";
 
-/* The owner's safety policy (.intentic/config/safety.md) and the log of what it decided.
- *
- * ITS OWN ROUTES RATHER THAN A FIELD ON /settings, and the split is the same one `rule-firings` already draws
- * next door: the policy is a DOCUMENT edited at human speed, and the log is a value that changes on its own
- * several times a turn. Folding either into the settings object would put a self-changing value inside the
- * thing a screen optimistically patches, and would make every judged command a settings write.
- *
- * The policy is also the only config file here whose reader is a model rather than a parser, so it travels as
- * text and is never parsed on the way through: whatever the owner wrote is what the judge reads.
- */
+// Owner's safety policy (.intentic/config/safety.md) and the log of what it decided. Own routes, not a /settings field:
+// the policy is a document edited at human speed, the log changes on its own mid-turn. The policy travels as text,
+// never parsed, since its reader is a model, not a parser.
 export const safetyContract = {
     policy: oc
         .route({
@@ -33,9 +26,7 @@ export const safetyContract = {
         })
         .input(z.object({ text: z.string().describe("The policy, as you want it written.") }))
         .output(OkSchema),
-    // What the policy actually did, newest first. The half of the Safety page that makes the other half
-    // writable: nobody can author a policy for behaviour they cannot see, and a column of verdicts is what
-    // teaches an owner which line to add next.
+    // Verdicts teach the owner which policy line to add next; answers why you weren't asked about something.
     log: oc
         .route({
             method: "GET",

package/src/contracts/secrets.contract.ts

@@ -13,11 +13,9 @@ import {
 } from "../schemas/secrets.js";
 import { OkSchema } from "../schemas/shared.js";
 
-// User-supplied env-var secrets, written to the sandbox's gitignored desired-state/.env (which
-// `apply` reloads each run, no restart). `set` upserts one KEY=value, `remove` deletes it; `list` returns the
-// keys present. `inventory` aggregates every secret store into one view (keys + status + provenance, never
-// 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.
+// User-supplied secrets, in the gitignored desired-state/.env; `apply` reloads them, no restart. `inventory` aggregates
+// every store (never values) and always answers; the rest refuse until desired-state is scaffolded. `reveal` alone
+// returns a value, owner-only, POST so the key avoids the URL.
 export const secretsContract = {
     set: oc
         .route({
@@ -65,23 +63,7 @@ export const secretsContract = {
         })
         .input(SecretKeyParamSchema)
         .output(SecretRevealSchema),
-    /* THE APPROVAL GATES, four routes with three different audiences, which is why they are worth reading as a
-     * group.
-     *
-     * `gates` is READ BY EVERYONE who needs to explain the sandbox to itself: the Secrets view draws a badge
-     * from it, and the AGENT is allowed it too (auth/grants.ts), because a model that cannot see which
-     * credentials are gated cannot tell "not connected" from "needs Bob", and the difference decides whether
-     * its next move is to ask a person or to go looking for another road. It answers names, subjects and
-     * approver addresses; there is nothing else in it to leak.
-     *
-     * `setGate` and `removeGate` are the OWNER's alone, enforced in-route with authorizeOwner rather than by
-     * the /secrets role floor, because the floor is maintainer and a maintainer is exactly who a gate is
-     * sometimes written about. The policy lives off the workspace beside the credential vault for the same
-     * reason the vault does: `.intentic/config/` is tracked and agent-editable, so a gate stored there would
-     * be a lock whose key is in the room with the agent.
-     *
-     * `request` is the AGENT's door, and the only one of the four that can park a turn: it raises the release
-     * card and waits, so a gated account can be asked for rather than merely discovered to be absent. */
+    // Gate policy lives off the workspace, not in agent-editable `.intentic/config/`, so agents can't hold the key.
     gates: oc
         .route({
             method: "GET",

package/src/contracts/sessions.contract.ts

@@ -1,6 +1,6 @@
 import { oc } from "@orpc/contract";
 import { z } from "zod";
-import { SessionTranscriptSchema } from "../events.js";
+import { SessionTranscriptSchema } from "../events/transcript.js";
 import { SessionIdParamSchema, SessionsListSchema } from "../schemas/sessions.js";
 
 // Past conversations in this workspace (the SDK-native session store, keyed on the working dir, which for a

package/src/contracts/settings.contract.ts

@@ -3,13 +3,9 @@ import { BuiltinPromptSchema, BuiltinPromptTextSchema, RuleFiringsSchema, Sandbo
 import { OkSchema } from "../schemas/shared.js";
 import { DayWindowQuerySchema } from "../schemas/usage.js";
 
-// Per-sandbox agent settings (.intentic/config/settings.json). `get` returns the current flags with defaults applied
-// when the file is absent; `set` overwrites them. `savings` reports what each token-reduction mechanism was
-// worth, the cleaners' realized per-command savings over an inclusive
-// UTC day window, the same one the spend ledger takes, so a screen can filter both with one calendar.
-// `builtinPrompt` returns one of the two built-in system prompts as text. Intentic's own, or Claude Code's
-// 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.
+// Per-sandbox agent settings (.intentic/config/settings.json); `get` fills defaults for an absent file, `set`
+// overwrites whole. `savings` measures each token-reduction mechanism's worth over the same UTC day window the spend
+// ledger takes. `builtinPrompt` returns a built-in prompt's actual text to show or fork.
 export const settingsContract = {
     get: oc
         .route({
@@ -48,9 +44,7 @@ export const settingsContract = {
         })
         .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.
+    // Own route, not a settings field: a firing isn't an edit, so it shouldn't cost a settings write.
     firings: oc
         .route({
             method: "GET",

package/src/contracts/share.contract.ts

@@ -2,15 +2,9 @@ import { oc } from "@orpc/contract";
 import { ShareCreateSchema, SharedConversationSchema, ShareListSchema, ShareRemoveSchema, ShareUpdateSchema } from "../schemas/share.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* Conversations published as read-only pages (see schemas/share.ts).
- *
- * Its own group rather than two more routes on `public`, because the two speak different path spaces and mean
- * different things by "publish". The outbox's routes take a path in the workspace and copy the bytes at it; a
- * share takes a CONVERSATION ID and renders something that did not exist as a file until it was asked for.
- * Folding them together would have `publish` accept two unrelated kinds of input distinguished by a flag.
- *
- * There is no route to read a share back. The page is the read, it answers on the unauthenticated
- * `public-<slot>` hostname like every other published file, which is the point of having made one. */
+// Conversations published as read-only pages. Separate from `public`: a share takes a conversation id and renders it,
+// `public` copies bytes at a workspace path. No route reads a share back, the page itself is the read, on the
+// unauthenticated `public-<slot>` hostname.
 export const shareContract = {
     list: oc
         .route({

package/src/contracts/skills.contract.ts

@@ -1,20 +1,12 @@
 import { oc } from "@orpc/contract";
-import { SkillBodySchema, SkillDraftSchema, SkillIdSchema, SkillRemoveSchema, SkillsListSchema } from "../schemas/settings.js";
+import { SkillBodySchema, SkillDraftSchema, SkillIdSchema, SkillRemoveSchema, SkillsListSchema, SkillSwitchSchema } from "../schemas/settings.js";
 import { OkSchema } from "../schemas/shared.js";
 
-/* WHAT THE AGENT KNOWS RIGHT NOW, and which half of it the owner controls.
- *
- * Its own domain rather than three more routes on `settings`, because only one of the four sources it reads is
- * the settings file: the rest are the owner's own skill store, the plugin checkouts a capability cloned, and the
- * skills folders inside installed extensions. `list` is the join of all four (skill-inventory.ts).
- *
- * The ENABLED half still rides the settings object's `skills` array, that array is what the reconciler
- * converges and what the boot path already reads, so a switch on this list is an ordinary settings write and
- * there is exactly one place that decides which skills exist on disk. `save` and `remove` write the text AND
- * that array together, which is why they are here rather than being two calls a screen has to sequence.
- *
- * `read` is a GET with the id in the query rather than in the path: an id can name an owner
- * (`extension:intentic.knowledge:knowledge`), and a path template cannot carry those segments. */
+// What the agent knows and which half the owner controls; `list` joins every source (the owner's own, the settings,
+// connections, plugin checkouts, extension folders, persona kits). A baked tool's switch rides settings' `skills`
+// array; an own skill is on while the agent's copy of it exists, which `switch` moves and `save`/`remove` write
+// together with the text. `read` takes the id in the query, since an id can name an owner and won't fit a path
+// template.
 export const skillsContract = {
     list: oc
         .route({
@@ -22,7 +14,7 @@ export const skillsContract = {
             path: "/skills",
             summary: "What the agent knows how to do",
             description:
-                "Every skill available here and whether it is switched on, joined from all four places they come from: the owner's own, the settings, plugins a connection installed, and folders inside extensions.",
+                "Every skill available here and whether it is switched on, joined from all the places they come from: the owner's own, the settings, plugins a connection installed, folders inside extensions, and persona kits.",
         })
         .output(SkillsListSchema),
     read: oc
@@ -35,25 +27,35 @@ export const skillsContract = {
         })
         .input(SkillIdSchema)
         .output(SkillBodySchema),
-    // Upsert by name: saving over an existing skill rewrites it, which is also how one is renamed (the old name
-    // is a different skill and is deleted on its own). A saved skill is switched ON, you wrote it to use it.
+    // Upsert by name; renaming saves under a new name and deletes the old. A new skill starts on; rewriting keeps its
+    // switch as it was.
     save: oc
         .route({
             method: "POST",
             path: "/skills",
             summary: "Write a skill",
             description:
-                "Creates or rewrites a skill by name, and switches it on, because you wrote it in order to use it. Renaming is saving under the new name and deleting the old.",
+                "Creates or rewrites a skill by name. A new one starts switched on, because you wrote it in order to use it; rewriting one you switched off leaves it off. Renaming is saving under the new name and deleting the old.",
         })
         .input(SkillDraftSchema)
         .output(OkSchema),
+    switch: oc
+        .route({
+            method: "POST",
+            path: "/skills/switch",
+            summary: "Switch one of your own skills on or off",
+            description:
+                "Off takes the agent's copy away and keeps your text; on writes the copy back from it. Built-in tools are switched in the agent settings instead, and nothing else has a switch.",
+        })
+        .input(SkillSwitchSchema)
+        .output(OkSchema),
     remove: oc
         .route({
             method: "POST",
             path: "/skills/remove",
             summary: "Delete a skill",
             description:
-                "Removes the text and takes it off the enabled list in one step, so a screen never has to sequence two calls and never leaves one half done.",
+                "Removes the text and the agent's copy in one step, so a screen never has to sequence two calls and never leaves one half done.",
         })
         .input(SkillRemoveSchema)
         .output(OkSchema),