@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/schemas/share.ts

@@ -1,62 +1,44 @@
 // share: a conversation published as a page
 import { z } from "zod";
-/* The outbox holds FILES; a conversation is not one, so sharing it means RENDERING it into one. The result is
- * an ordinary published page under the same `public-<slot>` hostname, with the same guards in front of it,
- * which is the whole reason this rides the outbox rather than inventing a second public surface with its own
- * auth story to get wrong.
- *
- * A share is a SNAPSHOT, not a window. The page holds the conversation as it read at the moment of sharing and
- * does not move again until the owner re-takes it, because the alternative, a link that keeps publishing
- * whatever is said next, makes every later turn a disclosure the user did not consciously make. `sharedAt`
- * is therefore relied on by the row: it dates what the recipient can actually see. */
+// A share renders the conversation into an ordinary published page under the same `public-<slot>` hostname as the
+// outbox, with the same guards. It is a snapshot: the page holds the conversation as it read at `sharedAt` until
+// re-shared.
 
-/* HOW MUCH OF A CONVERSATION TRAVELS, decided per share rather than by a setting, because the two answers suit
- * genuinely different acts. `messages` is the two speakers' words and nothing else, what you send a friend to
- * show what the thing said. `everything` adds the agent's work (its tool cards, the diffs of what it edited,
- * the pictures it took) and its thinking, what you send a colleague to show HOW it got there, and which
- * necessarily publishes the code and command output that appear in those cards.
- *
- * Two levels, not a set of switches: every extra toggle is another thing to get wrong about a link that cannot
- * be recalled once sent, and the honest distinction here is between "the conversation" and "the record". */
+// messages carries only the two speakers' words. everything adds the agent's tool cards, diffs and thinking, publishing
+// any code or command output they contain.
 export const ShareDetailSchema = z.enum(["messages", "everything"]);
 export type ShareDetail = z.infer<typeof ShareDetailSchema>;
 // One shared conversation, as the Public view lists it.
 export const SharedConversationSchema = z.object({
-    /* The share's own id, and the name its page is filed under in the outbox. NOT the conversation's id: that
-     * one is a memorable pair (`swift-otter-k9m2`, see conversation-ids.ts) chosen to be guessable BY A HUMAN
-     * at a glance, which is the opposite of what should name a page whose only protection is that its address
-     * is not enumerable. Minted per share, so re-sharing the same conversation twice yields two links. */
+    // The share's own id, minted per share, not the conversation's id; re-sharing the same conversation yields two
+    // links.
     id: z
         .string()
         .describe(
             "The share's own id, minted fresh each time, so sharing one conversation twice gives two links. Deliberately not the conversation's id, which is memorable by design and would make a page's address guessable.",
         ),
-    // Which conversation the snapshot was taken from, what Update re-reads, and what the chat matches against
-    // to know it already has a share.
+    // Which conversation this was taken from; what Update re-reads and matching uses to find an existing share.
     conversationId: z.string().describe("Which conversation it was taken from."),
     title: z.string().describe("The title on the page, which is the sharer's choice rather than the conversation's own."),
     detail: ShareDetailSchema.describe(
         "How much travels: the two speakers' words alone, or the whole record including the agent's work and thinking, which necessarily publishes the code and command output in it.",
     ),
-    // When the snapshot was taken (epoch ms). A share is frozen, so this dates what a recipient can see,
-    // not when the conversation happened.
+    // Epoch ms of the snapshot; a share is frozen, so this dates what the recipient sees, not the conversation.
     sharedAt: z
         .number()
         .describe(
             "When the snapshot was taken, in milliseconds. A share is frozen, so this dates what a recipient can see rather than when the conversation happened.",
         ),
-    // How many messages the snapshot holds, so a row can say how much is behind the link without opening it.
+    // How many messages the snapshot holds.
     messages: z.number().describe("How many messages are behind the link."),
-    // The page's public URL. Absent on a sandbox with no tunnel, which has nowhere to publish to, the same
-    // rule (and the same cause) as PublicFile.url.
+    // The page's URL; absent when the sandbox has no tunnel to publish to.
     url: z.string().optional().describe("The page's address. Absent on a sandbox with nowhere to publish to."),
 });
 export type SharedConversation = z.infer<typeof SharedConversationSchema>;
 export const ShareListSchema = z.object({ shares: z.array(SharedConversationSchema).describe("Every conversation currently published as a page.") });
 export type ShareList = z.infer<typeof ShareListSchema>;
-// The title is the sharer's, not the conversation's: the chat's own name is only the default the dialog opens
-// with. Bounded at the registry's title budget (title.ts MAX_LENGTH) so one surface can't store what the others
-// truncate away.
+// Title is the sharer's, not the conversation's default name. Capped at 80, matching the registry's MAX_LENGTH in
+// title.ts.
 export const ShareCreateSchema = z.object({
     conversationId: z.string().min(1).describe("Which conversation to publish."),
     title: z.string().min(1).max(80).describe("The title for the page. The conversation's own name is only what a dialog would open with."),
@@ -64,7 +46,7 @@ export const ShareCreateSchema = z.object({
         "How much to publish. Two levels rather than a set of switches, because every extra toggle is another thing to get wrong about a link that cannot be recalled.",
     ),
 });
-// Re-take an existing share's snapshot, keeping its id, and therefore its link, which has already been sent.
+// Re-takes an existing share's snapshot; the id, and its already-sent link, stays the same.
 export const ShareUpdateSchema = z.object({
     id: z.string().min(1).describe("Which share to re-take. Its link stays the same, which matters because it has already been sent."),
 });

package/src/schemas/shared.ts

@@ -1,28 +1,29 @@
 import { z } from "zod";
-// Success ack for routes that only report completion (push / disconnect / self-host register). A turn paused on
-// a plan/question that no longer exists, or a missing repo/path, is an ORPCError thrown by the handler instead.
+// Success ack for routes that only report completion (push, disconnect, self-host register). A paused turn or missing
+// repo/path throws an ORPCError instead.
 export const OkSchema = z.object({
     ok: z
         .literal(true)
         .describe("Always true. A route that answers this either did the thing or refused with a status; there is no third outcome to report."),
 });
-// The trust tiers of everyone who can open this sandbox, ordered. `owner` is the one bound identity
-// (auth/auth.ts); the other three are granted per email on the daemon's /members list. viewer watches,
-// collaborator drives agents (outward actions become requests), maintainer has the owner's operating authority
-// while remaining revokable. Ownership itself is not a grant and controls the access roster.
+// Trust tiers, ordered low to high: viewer watches, collaborator's outward actions become requests, maintainer holds
+// the owner's authority but is revocable, owner is the one bound identity and not a grant.
 export const MemberRoleSchema = z.enum(["viewer", "collaborator", "maintainer", "owner"]);
 export type MemberRole = z.infer<typeof MemberRoleSchema>;
-// The roles an invite can grant, everything but `owner`, which is bound at first sign-in, never granted.
+// Roles an invite can grant: everything but owner, which binds at first sign-in and is never granted.
 export const GrantedRoleSchema = z.enum(["viewer", "collaborator", "maintainer"]);
 export type GrantedRole = z.infer<typeof GrantedRoleSchema>;
-// Shared by every surface that gates on a role (daemon route floors, web affordances) so the order lives in
-// exactly one place.
+// Single source for role order; every surface that gates on a role reads this ranking.
 const MEMBER_ROLE_RANK: Record<MemberRole, number> = { viewer: 0, collaborator: 1, maintainer: 2, owner: 3 };
 export const roleAtLeast = (role: MemberRole, floor: MemberRole): boolean => MEMBER_ROLE_RANK[role] >= MEMBER_ROLE_RANK[floor];
-// Which repo a git route targets: "root" (the /work workspace repo) or a repo id, the repo's root-relative
-// dir, which may be nested ("clients/foo"; URL-encoded in the path param). Kept as a bare string on the wire
-// (not an enum) so an unknown repo is a handler-thrown NOT_FOUND, matching the daemon's prior 404, rather
-// than an input-validation rejection.
+// Rotating a door credential (event webhook, release gate, bug intake): the old value stops working immediately; the
+// new one is shown once to be saved.
+export const DoorTokenSchema = z.object({
+    token: z.string().min(1).describe("The freshly minted credential. The previous one stopped working the moment this answered."),
+});
+export type DoorToken = z.infer<typeof DoorTokenSchema>;
+// "root" is the workspace repo; otherwise a repo id, its root-relative dir, URL-encoded, may be nested. Kept as a
+// string so an unknown repo is a handler NOT_FOUND, not a validation error.
 export const RepoParamSchema = z.object({
     repo: z
         .string()

package/src/schemas/system.ts

@@ -1,46 +1,31 @@
 import { z } from "zod";
-// version: what this daemon runs (baked). latest/updateAvailable: the daemon compares its version to the
-// latest published `stable` release so the web can offer a non-blocking update (see system/version-check.ts).
-/* Whether an agent runtime can serve a turn right now, probed off the turn path (see the sandbox's
- * agent/adapter-health.ts). "unknown" is a real answer, a probe that could not run must not read as
- * "unavailable" and grey out a provider the user can in fact use, so surfaces treat it as
- * available-but-unverified rather than as a soft no. */
+// version is this build's baked-in version; latest/updateAvailable come from comparing it to the published stable
+// release.
+// Whether a runtime can serve a turn, probed off the turn path. "unknown" reads as available-but-unverified, never as
+// unavailable.
 export const AdapterHealthSchema = z.object({
     state: z
         .enum(["ready", "unavailable", "unknown"])
         .describe(
             "Whether this runtime can serve a turn. Unknown is a real answer rather than a soft no: a check that could not run must not grey out a provider you can in fact use.",
         ),
-    // Why it cannot serve, in the user's terms and naming what to do about it. Absent when ready.
+    // Why it cannot serve and what to do about it; absent when ready.
     detail: z.string().optional().describe("Why it cannot, and what to do about it. Absent when it can."),
     checkedAt: z.number().describe("When it was last checked, in milliseconds."),
 });
 export type AdapterHealthReport = z.infer<typeof AdapterHealthSchema>;
-/* AN UPDATE ALREADY DOWNLOADED AND BUILT, waiting for the restart that applies it.
- *
- * An update is one blocking operation but it was never one kind of work: pulling the new image and re-applying
- * the environment recipe take the overwhelming majority of the wall clock, and the sandbox is up and serving
- * through both of them. Only the cutover is downtime, and it is seconds.
- *
- * The daemon cannot know any of this by itself, it holds no host Docker socket, so `ic sandbox prepare`
- * tells it, on the machine that runs the container. That is the whole reason this exists: without it, the
- * update card had to quote the download as if it were an outage, and "a few minutes, this page loses the
- * sandbox" is a completely different decision from "about half a minute".
- *
- * Advisory only, in the strict sense: it decides what a card SAYS and never what gets installed. The swap
- * re-derives every one of these facts from the host-side record and refuses the fast path if any has drifted. */
+// An update already downloaded and built, waiting for the restart that applies it. Advisory only: the swap re-derives
+// these facts and refuses the fast path if they drifted.
 export const StagedUpdateSchema = z.object({
-    // The version the staged image reports about itself. Absent when the image would not say (an older build,
-    // a probe that failed), which reads as "ready, version unknown", never as nothing being ready.
+    // What the staged build reports about itself; absent means ready but unnamed, not that nothing is ready.
     version: z.string().optional().describe("What the downloaded build says it is. Absent means ready but unnamed, never that nothing is ready."),
-    // The release channel it was staged FROM, which is not necessarily the one this sandbox follows: preparing
-    // a beta build is not moving onto beta.
+    // Channel it was staged from; not necessarily the one this sandbox follows.
     channel: z
         .string()
         .describe(
             "Which channel it was taken from. Not necessarily the one this sandbox follows: downloading a beta build is not the same as moving onto beta.",
         ),
-    // When it finished downloading, epoch ms, what answers "is this still the update I am being offered?"
+    // Epoch ms the download finished; used to check this is still the update being offered.
     at: z.number().describe("When the download finished, in milliseconds, which answers whether this is still the update being offered."),
 });
 export type StagedUpdate = z.infer<typeof StagedUpdateSchema>;
@@ -50,81 +35,51 @@ export const InfoSchema = z.object({
     version: z.string().optional().describe("The version of that image."),
     latest: z.string().optional().describe("The newest published version on its channel."),
     updateAvailable: z.boolean().optional().describe("Whether those two differ."),
-    // Keyed by AgentCapabilities.runtime. Absent until the first background sweep lands, which reads the same
-    // as every entry being "unknown", one of the two cannot go stale, so the daemon sends the absence.
+    // Keyed by AgentCapabilities.runtime; absent until the first sweep, reading as every entry unknown.
     runtimes: z
         .record(z.string(), AdapterHealthSchema)
         .optional()
         .describe(
             "Which agent runtimes can serve a turn right now, keyed by runtime. Absent until the first check has run, which reads the same as every entry being unknown.",
         ),
-    /* Which release channel this sandbox follows (`stable` unless it was moved), and the base image the last
-     * swap replaced, both set on the container by the host script that performed the swap, since neither is
-     * knowable from inside afterwards. `previousImage` is what a rollback returns to; absent means there is
-     * nothing to go back to and no rollback is offered. */
+    // Channel and previousImage are set by the host swap script; previousImage absent means no rollback.
     channel: z.string().optional().describe("Which release channel this sandbox follows."),
     previousImage: z
         .string()
         .optional()
         .describe("The image the last update replaced, which is what a rollback would return to. Absent means there is nothing to go back to."),
-    /* WHAT IS IN THE UPDATE, in the words of the people it is for, the user-facing lines from every release
-     * between `version` and `latest`, newest first (platform/release-notes.ts reads them off the published
-     * GitHub Releases).
-     *
-     * The update card's other half. It could always say an update exists and what taking it costs, recreating
-     * the container interrupts every agent mid-turn, and never what the update was worth, which left the
-     * decision it asks for with nothing on one side of it.
-     *
-     * Absent, or empty, whenever there is nothing to say: the notes cache is cold, GitHub is unreachable, or
-     * every release in the gap changed only things nobody outside the project would notice. All three read the
-     * same way on the card, which shows the offer without them, exactly as it did before. */
+    // User-facing release notes from version to latest, newest first; absent or empty means nothing to say.
     updateNotes: z
         .array(z.string())
         .optional()
         .describe(
             "What is in the update, in the words of the people it is for, newest first. Absent or empty whenever there is nothing worth saying, which reads on screen exactly as it did before there were notes at all.",
         ),
-    // How many further notes the gap holds beyond the ones sent, for a sandbox that has been left alone a long
-    // time. Absent or 0 ⇒ `updateNotes` is the whole of it.
+    // How many further notes exist beyond the ones sent; absent or zero means updateNotes has them all.
     moreUpdateNotes: z
         .number()
         .optional()
         .describe(
             "How many further notes there are beyond the ones sent, for a sandbox left alone a long time. Absent or zero means you have all of them.",
         ),
-    /* WHAT THE UPDATE TAKES AWAY, the "Breaking changes" lines from every release in the same gap, uncapped
-     * (a warning that fell off a truncated list is a breaking update taken unwarned). Their presence is what
-     * turns the update card from an offer into a warning that asks to be read before it hands over the
-     * command. Absent for the overwhelming majority of updates, which break nothing. */
+    // Breaking-change lines from every release in the gap, uncapped; absent for updates that break nothing.
     breakingNotes: z
         .array(z.string())
         .optional()
         .describe(
             "What the update takes away, uncapped, because a warning that fell off a shortened list is a breaking update taken unwarned. Absent for the overwhelming majority, which break nothing.",
         ),
-    /* AN UPDATE THAT HAS ALREADY BEEN DOWNLOADED AND BUILT on the machine that runs this container, and is
-     * waiting for the restart that applies it. Absent for the ordinary case where nothing is staged. */
+    // Update already downloaded and built, waiting for the restart that applies it; absent when nothing is staged.
     staged: StagedUpdateSchema.optional().describe(
         "An update already downloaded and built on the machine running this container, waiting only for the restart that applies it. That restart is seconds, where an unprepared update is minutes, which is a different decision entirely. Absent when nothing is waiting.",
     ),
 });
 export type Info = z.infer<typeof InfoSchema>;
-/* WHAT THE DAEMON COULD NOT READ IN ITS OWN STATE FILES.
- *
- * Every manifest under `.intentic/` is read through a schema and falls back when that schema says no, which
- * keeps the daemon up and, until this route, ended there. A settings file with one bad character read as
- * every setting at its default, a misspelled flag was stripped in silence, and a skipped capability said so
- * only in the daemon log. All three look identical from a browser: the feature is simply off.
- *
- * `kind` is what to do about it, which is why it is not just a message:
- *   unreadable  , the whole file is being ignored. Everything in it is at its default.
- *   unknownKey  , one key this build does not know. Only that key is ignored, and `suggestion` carries the
- *                  name it was probably meant to be, when one is close enough to guess honestly.
- *   invalidEntry, one entry of a list was skipped. The rest of the file is unaffected.
- *
- * Reported per file rather than as one flat list because the file is the unit a person fixes, and only for the
- * files a person CAN fix (REPORTED_MANIFEST_PATHS in workspace-state.ts). A daemon-written ledger that stops
- * matching a tightened schema is not a repair job to hand the owner; it recovers on its own next write. */
+// What the daemon could not read in its own `.intentic/` state files. Reported per file, only for files listed in
+// REPORTED_MANIFEST_PATHS (workspace-state.ts). `kind`:
+// unreadable: whole file ignored, everything in it at default.
+// unknownKey: only that key ignored; `suggestion` may name what it should be.
+// invalidEntry: one list entry skipped, rest of the file stands.
 export const ManifestProblemSchema = z.object({
     kind: z
         .enum(["unreadable", "unknownKey", "invalidEntry"])
@@ -133,21 +88,15 @@ export const ManifestProblemSchema = z.object({
         ),
     detail: z.string().describe("What exactly was wrong, as one sentence and nothing else. Never the remedy: that is `fix`."),
     suggestion: z.string().optional().describe("The name it was probably meant to be, when one is close enough to guess honestly."),
-    /* THE REMEDY, ONLY WHEN THE DAEMON KNOWS ONE THE READER CANNOT GUESS. For nearly every problem here the fix
-     * is "open the file and correct the line", which the browser can say without being told; carrying that
-     * sentence over the wire per problem would be the daemon dictating copy it has no more information about
-     * than the reader. The exception is the version skew (store/manifest-problems.ts): there the file is
-     * probably RIGHT and editing it is the wrong move, which nothing on the reading side could work out on its
-     * own. Kept apart from `detail` so a renderer can put cause and action on separate lines instead of
-     * concatenating them into a paragraph, which is what it used to be. */
+    // Set only when the fix isn't "open the file and correct it", e.g. a version skew where editing would be wrong.
     fix: z
         .string()
         .optional()
         .describe("What to do about it, when that is something other than 'correct the file'. Absent whenever the file itself is the thing to edit."),
 });
 export type ManifestProblem = z.infer<typeof ManifestProblemSchema>;
-// Workspace-relative path (`.intentic/config/settings.json`) and everything currently wrong with that file. A file
-// with nothing wrong is absent from the list rather than present and empty.
+// Workspace-relative path and everything currently wrong with that file; a clean file is absent from the list, not
+// present and empty.
 export const ManifestProblemReportSchema = z.object({
     path: z.string().describe("The file, as a workspace path. The file is the unit somebody fixes, which is why problems are grouped by it."),
     problems: z
@@ -156,9 +105,28 @@ export const ManifestProblemReportSchema = z.object({
 });
 export type ManifestProblemReport = z.infer<typeof ManifestProblemReportSchema>;
 export const ManifestProblemsSchema = z.array(ManifestProblemReportSchema);
-// A daemon-minted session (system.session): the steady-state browser credential, exchanged for a verified
-// Google ID token so Google UI is a sign-in moment instead of an hourly renewal. `expiresAt` is epoch ms,
-// the browser renews ahead of it without parsing the token; `email` is who the daemon verified.
+
+// The one repair a button may perform: drop a stray top-level key, or rename it to what `suggestion` named. The other
+// two problem kinds are refused:
+// unreadable: nothing to act on but bytes; the file may already be correct (version skew).
+// invalidEntry: dropping it would remove real configuration, not an inert key.
+export const ManifestRepairSchema = z.object({
+    path: z
+        .string()
+        .describe(
+            "The file to repair, as the workspace path the problem was reported under. Only the handful of manifests a person hand-edits can be named; anything else is refused.",
+        ),
+    key: z.string().describe("The stray top-level key, exactly as it was reported. Absent from the file already means there is nothing to do."),
+    to: z
+        .string()
+        .optional()
+        .describe(
+            "Rename the key to this instead of removing it, carrying its value across. Absent means remove it. Naming a key that is already in the file is refused rather than silently overwriting what is there.",
+        ),
+});
+export type ManifestRepair = z.infer<typeof ManifestRepairSchema>;
+// Steady-state browser credential (system.session), exchanged for a verified Google ID token so Google UI appears only
+// at sign-in. expiresAt is epoch ms; renew ahead of it without parsing the token.
 export const DaemonSessionSchema = z.object({
     token: z.string().describe("The credential every other call carries. Present it as a bearer token."),
     expiresAt: z.number().describe("When it stops working, in milliseconds, so a caller can renew ahead of it without reading the token."),