@intentic/sandbox-contract 1.232.0 → 1.234.0

package/src/schemas/extension-updates.ts

@@ -0,0 +1,324 @@
+// extensions: installed extension-kind capabilities resolved to their manifests
+// extension updates: what the registry check found, and what the owner decided to do about such findings
+import { z } from "zod";
+import { ExtensionManifestSchema } from "@intentic/extension-manifest";
+// What the web extension host boots from: each row is an extension capability whose checkout still parses,
+// the approved manifest (contribution declarations), and the checked-out commit (the code identity; the bundle
+// route's ETag). A rotted checkout is skipped here; its capability row still shows status.
+// The routing handle: a git-installed extension uses its capability entry id; an image-baked one has no
+// capability entry and is addressed by the manifest-derived publisher.name, hence the dot in the pattern.
+const extensionId = z
+    .string()
+    .min(1)
+    .max(121)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/);
+// The owner's per-extension update posture. `updates` is the ladder: `notify` (badge and wait, the default),
+// `agent` (the discovery also prepares an agent diff-read of the new sha), `auto` (apply unattended, but only
+// a verified listing whose powers didn't grow, health-watched with auto-revert, anything less falls back to
+// notify). `advisories` is separate because its safe direction is the opposite: disabling runs no new code, so
+// `auto-disable` is the default and `notify` is the opt-out.
+export const ExtensionUpdatePolicySchema = z.object({
+    updates: z.enum(["notify", "agent", "auto"]),
+    advisories: z.enum(["auto-disable", "notify"]),
+});
+export type ExtensionUpdatePolicy = z.infer<typeof ExtensionUpdatePolicySchema>;
+// A newer sha the registry lists for an installed extension, the "update available" badge's substance. The
+// pointer (url/path) rides along because updating follows the ROW as it stands now, not the install as it was.
+export const ExtensionUpdateSchema = z.object({
+    ref: z.string().describe("The commit being offered."),
+    version: z.string().optional().describe("What it calls itself."),
+    url: z.string().describe("Where it comes from."),
+    path: z.string().optional().describe("Where inside that repository it lives."),
+    trust: z.enum(["verified", "listed"]).describe("Whether anybody vouched for it, or it is merely listed."),
+    // The listing says this release fixes a security problem in earlier ones, the badge goes loud, because
+    // here the OLD version is the dangerous one.
+    securityFix: z
+        .boolean()
+        .optional()
+        .describe("This release fixes a security problem in earlier ones, so here the old version is the dangerous one."),
+    registry: z.string().describe("Which registry said so."),
+    at: z.string().describe("When it was published."),
+    // Why the auto rung refused this one and fell back to notify ("powers grew", "not verified"), the card
+    // leads with it so the owner knows the click is theirs for a reason.
+    needsReview: z
+        .string()
+        .optional()
+        .describe(
+            "Why this one was not taken automatically and is asking for a person instead: it wants more than it used to, or nobody has vouched for it.",
+        ),
+    // The agent-prepared rung's work: the conversation where the owner's agent already read the diff between
+    // the installed sha and this one. The card links it instead of offering to start it.
+    review: z
+        .object({
+            conversationId: z.string().describe("Where to read what it found."),
+            at: z.string().describe("When it looked."),
+        })
+        .optional()
+        .describe(
+            "An agent has already read the difference between what is installed and this, so the card can link to what it found rather than offer to start looking.",
+        ),
+});
+export type ExtensionUpdate = z.infer<typeof ExtensionUpdateSchema>;
+// The registry blocked this installed extension's listing. Delisting protects people browsing; this record is
+// for the person already running it, the reason verbatim, and whether the daemon already pulled the switch.
+export const ExtensionAdvisorySchema = z.object({
+    reason: z
+        .string()
+        .describe(
+            "Why the registry pulled the listing, in its own words. Delisting protects people browsing; this record is for the person already running it.",
+        ),
+    registry: z.string().describe("Which registry said so."),
+    at: z.string().describe("When."),
+    autoDisabled: z.boolean().describe("Whether the sandbox has already switched it off."),
+});
+export type ExtensionAdvisory = z.infer<typeof ExtensionAdvisorySchema>;
+// The post-update watch: validation catches broken, not wrong, so for a minute after a swap the daemon checks
+// that what the new version declared actually came up (autoStart processes running, backend activated).
+// `fromRef` is the sha the kept-previous checkout holds, what a revert returns to.
+export const ExtensionHealthSchema = z.object({
+    state: z
+        .enum(["watching", "healthy", "unhealthy"])
+        .describe("How it has behaved since the last update. Checks catch broken, not wrong, so for a while after a swap it is simply watched."),
+    detail: z.string().optional().describe("What is going wrong, when something is."),
+    fromRef: z.string().optional().describe("Which version it was updated from, which is what going back would return to."),
+    at: z.string().describe("When the watching started."),
+    // The auto rung's failure path already ran: the update was rolled back unattended, and the record stays to
+    // say so rather than pretending the attempt never happened.
+    autoReverted: z
+        .boolean()
+        .optional()
+        .describe("The update was already rolled back without anybody asking. The record stays rather than pretending the attempt never happened."),
+});
+export type ExtensionHealth = z.infer<typeof ExtensionHealthSchema>;
+// The mechanical comparison of two manifests' declared reach (extension-manifest's diffPowers), plain
+// sentences, so the update dialog renders exactly what approval is being asked to cover.
+export const PowersDiffSchema = z.object({
+    added: z.array(z.string()).describe("What the new version asks for that the running one does not. The whole point of the comparison."),
+    removed: z.array(z.string()).describe("What it no longer asks for."),
+    unchanged: z.array(z.string()).describe("What stays the same."),
+});
+export type PowersDiff = z.infer<typeof PowersDiffSchema>;
+// What an owner reads before clicking Update: the offered sha's manifest folded to the version story, the
+// engines verdict, and the powers diff against the installed manifest. `ref` optional on the way in, absent
+// means "the update the check recorded", which is the only caller most of the time.
+export const ExtensionUpdateActionSchema = z.object({
+    id: extensionId.describe("Which extension."),
+    ref: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/)
+        .optional()
+        .describe("Which commit, in full. Leave it out for whatever the last check found, which is what most callers mean."),
+});
+export const ExtensionUpdatePreviewSchema = z.object({
+    ref: z.string().describe("The commit this would install."),
+    version: z.string().describe("What that version calls itself."),
+    installedVersion: z.string().describe("What is running now."),
+    engines: z.string().describe("Which sandbox versions the new one says it needs."),
+    compatible: z.boolean().describe("Whether this sandbox is one of them."),
+    powers: PowersDiffSchema.describe(
+        "Exactly what the new code asks for that the running one does not. This is what approving an update is approving.",
+    ),
+});
+// `rebuildNeeded` (update only): the new version's environment fragment changed the composed overlay, so the
+// card must say a one-time image rebuild is pending rather than let the update read as wholly landed.
+export const ExtensionUpdateAppliedSchema = z.object({
+    ok: z.literal(true).describe("It went through."),
+    ref: z.string().describe("Which commit is now running."),
+    rebuildNeeded: z
+        .boolean()
+        .optional()
+        .describe(
+            "The new version changes what the sandbox image contains, so a one-time rebuild is still pending and the update is not wholly landed yet.",
+        ),
+});
+export const ExtensionUpdatePolicyInputSchema = z.object({
+    id: extensionId.describe("Which extension."),
+    updates: z
+        .enum(["notify", "agent", "auto"])
+        .optional()
+        .describe("What to do about a newer version: tell you, have an agent read the difference first, or just take it."),
+    advisories: z.enum(["auto-disable", "notify"]).optional().describe("What to do about a security warning: switch it off at once, or tell you."),
+});
+export const ExtensionUpdatesCheckedSchema = z.object({
+    ok: z.literal(true).describe("The check ran."),
+    checkedAt: z.string().describe("When, so a screen can date the answer."),
+});
+export const ExtensionSummarySchema = z.object({
+    id: extensionId.describe("The extension's id."),
+    manifest: ExtensionManifestSchema.describe("What it declares about itself: what it contributes, what it needs, and what it may reach."),
+    commit: z.string().describe("Exactly which commit is installed."),
+    /* Where the code comes from, which is also what the web varies per row: `builtin` (image-baked, no git
+     * checkout, not removable) hides the uninstall affordance, `installed` (a git capability) shows the pinned
+     * commit, `workspace` (a directory under .intentic/config/workspace-extensions/, created and edited in place,
+     * typically by an agent) is "uninstalled" by deleting its directory. */
+    source: z
+        .enum(["builtin", "installed", "workspace"])
+        .describe(
+            "Where the code comes from: baked into the sandbox image and not removable, installed from a repository at a pinned commit, or written in this workspace and edited in place.",
+        ),
+    // The owner's switch (.intentic/config/extension-enablement.json). A disabled extension is still listed, that's
+    // what makes it switchable back on, but the daemon wires none of its contributions up and the web host
+    // doesn't activate it.
+    enabled: z
+        .boolean()
+        .describe(
+            "The owner's switch. A switched-off extension is still listed, which is what makes it switchable back on, but nothing it contributes is wired up.",
+        ),
+    /* THE SWITCH IS FIXED ON, this extension is the only control surface for an engine the daemon runs
+     * regardless. The automations scheduler fires turns on a clock whether or not anything draws them, and
+     * hiding the one page that can see, stop or approve those fires would not stop the spend, it would only
+     * remove the owner's ability to notice it. So the daemon refuses the flip, and the tab draws the switch as
+     * fixed with this fact as the reason.
+     *
+     * Declared by the CORE about its own engines' surfaces, never by a manifest: a field an extension could set
+     * on itself would be a pack making itself un-removable, which is a self-granted privilege the approval flow
+     * exists to prevent. */
+    essential: z
+        .boolean()
+        .optional()
+        .describe(
+            "Its switch is fixed on, because it is the only way to see or stop an engine the sandbox runs regardless. Hiding that page would not stop the spending, only your ability to notice it. Declared by the core about its own surfaces, never by an extension about itself, which would be a pack making itself un-removable.",
+        ),
+    /* How much of the reach this extension asked for it has actually used, keyed by the DECLARED entry so a row
+     * joins straight onto `permissions.sandbox`. Absent for an extension that has never been observed calling
+     * anything, which is a different claim from "uses none of them" and has to stay tellable: a freshly installed
+     * extension has an empty ledger and an unexercised one does too, and reading either as "these permissions are
+     * unnecessary" would turn this from evidence into a guess with a number on it. */
+    usage: z
+        .record(
+            z.string(),
+            z.object({ calls: z.number().int().nonnegative().describe("How many times."), last: z.string().describe("When, most recently.") }),
+        )
+        .optional()
+        .describe(
+            "How much of the reach it asked for it has actually used, keyed by what it declared. Absent means never observed doing anything, which is a different claim from uses none of them, and the two have to stay tellable apart: reading either as these permissions are unnecessary turns evidence into a guess with a number on it.",
+        ),
+    /* The BACKEND half's state, present only for an extension whose manifest ships a `server` bundle: what the
+     * daemon's backend host reports for it (running / an activation error with its message), or what only the
+     * daemon can know (absent, the code is not in this image; incompatible, its engines exclude this daemon;
+     * starting/stopped, the host itself is between states). The tab renders it beside the row so a backend
+     * that failed to activate is a sentence, not a namespace that 404s. */
+    backend: z
+        .object({
+            state: z
+                .enum(["running", "error", "absent", "incompatible", "starting", "stopped"])
+                .describe(
+                    "How its server half is doing. Absent means the code is not in this image at all; incompatible means it needs a different sandbox version.",
+                ),
+            detail: z
+                .string()
+                .optional()
+                .describe("What went wrong, so a backend that failed to start is a sentence rather than an address that answers nothing."),
+        })
+        .optional()
+        .describe("Present only for an extension that ships a server half."),
+    /* The update lifecycle, present only where it can exist, a git-installed extension. `update` is the badge,
+     * `advisory` the alarm, `health` the after-the-click watch, `previous` the way back (the kept one-back
+     * checkout's sha), `updatePolicy` the owner's standing answer. A builtin updates with the image and a
+     * workspace one is live-edited, so all five stay absent for them. */
+    update: ExtensionUpdateSchema.optional().describe(
+        "A newer version waiting. All five of these exist only for one installed from a repository: a built-in updates with the image and one written here is edited live.",
+    ),
+    advisory: ExtensionAdvisorySchema.optional().describe("A security warning about the installed version."),
+    health: ExtensionHealthSchema.optional().describe("How it has behaved since the last update, which is what decides whether that update sticks."),
+    previous: z
+        .object({
+            ref: z.string().describe("The commit that was running before."),
+            version: z.string().optional().describe("What it called itself."),
+        })
+        .optional()
+        .describe("The version kept one step back, which is what going back means."),
+    updatePolicy: ExtensionUpdatePolicySchema.optional().describe(
+        "The owner's standing answer for this one: tell me, have an agent look, or just do it.",
+    ),
+});
+export type ExtensionSummary = z.infer<typeof ExtensionSummarySchema>;
+// A workspace-extension directory that failed to enumerate, and why. Its only feedback channel: there is no
+// install moment to reject a bad manifest, so the parse failure (or id collision) rides the list instead of
+// silently dropping the row, the Extensions tab renders it, and an authoring agent reads it off GET /extensions.
+export const InvalidWorkspaceExtensionSchema = z.object({
+    dir: z.string().describe("Which folder."),
+    error: z.string().describe("Why it could not be read."),
+});
+export type InvalidWorkspaceExtension = z.infer<typeof InvalidWorkspaceExtensionSchema>;
+export const ExtensionsListSchema = z.object({
+    extensions: z.array(ExtensionSummarySchema).describe("What is installed."),
+    invalid: z
+        .array(InvalidWorkspaceExtensionSchema)
+        .describe(
+            "Extensions written here that could not be read at all. Listed rather than dropped, because there is no install moment at which to reject a broken one, so this is its only way of saying anything.",
+        ),
+    // When the registry comparison last ran, absent until the first check completes. Serving it on the list is
+    // what lets the tab say "checked an hour ago" instead of presenting staleness as certainty.
+    updatesCheckedAt: z
+        .string()
+        .optional()
+        .describe(
+            "When updates were last looked for. Absent until the first check has run. Sent so a screen can say checked an hour ago rather than presenting staleness as certainty.",
+        ),
+});
+// The extension's contributes.settings values, persisted daemon-side (.intentic/config/extension-settings.json) keyed
+// by the manifest-derived extension id, the checkout stays pristine, so a re-clone update never loses them.
+// Secret-marked values are stripped from `settings`; `secretsSet` lists the secret keys that DO hold a value,
+// so the UI renders "•••• (set)" without ever receiving the secret back.
+export const ExtensionSettingsSchema = z.object({
+    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("The values, minus anything marked secret."),
+    secretsSet: z
+        .array(z.string())
+        .describe("Which of its secret settings actually hold a value. Names only: the values themselves never come back."),
+});
+export type ExtensionSettings = z.infer<typeof ExtensionSettingsSchema>;
+export const ExtensionSettingsInputSchema = z.object({
+    id: z.string().describe("Which extension."),
+    settings: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .describe("The values to write. A key the extension never declared is refused rather than quietly stored."),
+});
+// Flip one extension on or off. Persisted by publisher.name (like settings), so the choice outlives the
+// checkout; the daemon's immediate half of the flip, declared processes, converges in the same handler.
+export const ExtensionEnabledInputSchema = z.object({
+    id: z.string().describe("Which extension."),
+    enabled: z.boolean().describe("On or off."),
+});
+/* Create a workspace extension: the identity, and deliberately nothing else. What gets written is the daemon's
+ * decision, not a form the author fills in, the point of the action is that a running extension exists a second
+ * after it is asked for, and shaping it happens by editing the files it wrote (or by asking an agent to). The two
+ * slugs are the same shape the manifest schema demands, checked again here because `name` becomes a directory. */
+export const WorkspaceExtensionCreateSchema = z.object({
+    publisher: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/)
+        .describe("Who it is by, which together with the name makes its id."),
+    name: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/)
+        .describe("What it is called."),
+});
+// Where it landed. `dir` is workspace-root-relative so the caller can name the files it should open next.
+export const WorkspaceExtensionCreatedSchema = z.object({
+    id: z.string().describe("The id it was given."),
+    dir: z.string().describe("Where its files are, so you can open them."),
+});
+/* A batch of calls the host observed against this extension's declared routes, entry → how many since the last
+ * report. Counts rather than events, and declared entries rather than concrete paths, because the question the
+ * ledger answers is "is this permission earned?": a finer record would be a log of what the owner was doing,
+ * indexed by extension, which is not a thing this product should be accumulating to answer it. */
+export const ExtensionUsageInputSchema = z.object({
+    id: z.string().describe("Which extension."),
+    used: z.record(z.string(), z.number().int().positive()).describe("Which of its declared powers it exercised, and how many times."),
+});
+// One declared background process (contributes.processes), status/start/stop, addressed by the capability
+// entry id + the manifest's process name. Undeclared names are NOT_FOUND, the manifest-honesty rule again.
+export const ExtensionProcessParamSchema = z.object({
+    id: z.string().describe("Which extension."),
+    name: z.string().describe("Which of its declared processes."),
+});
+export const ExtensionProcessStatusSchema = z.object({
+    name: z.string().describe("Which process."),
+    running: z.boolean().describe("Whether it is up. False with a port means it crashed and the supervisor is waiting to retry it."),
+    port: z.number().optional().describe("The port it was given."),
+    restarts: z.number().optional().describe("How many times it died and was brought back since it was started. A growing number is a service in trouble."),
+    lastExitCode: z.number().optional().describe("How it last exited, when it has crashed at least once."),
+    previewUrl: z.string().optional().describe("Where to open it, when it has an address."),
+});
+export type ExtensionProcessStatus = z.infer<typeof ExtensionProcessStatusSchema>;

package/src/schemas/fast-mode.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+// What speed a turn is actually being served at. `cooldown` is its own state rather than a flavour of `off`
+// because it is the only one that lifts by itself: fast mode draws on a rate-limit pool separate from the
+// model's, and a turn that exhausts it drops to standard speed and stays there until the pool reopens. The
+// distinction is what lets the client say "not right now" instead of "not available", which are different
+// answers to "why am I not getting what I asked for". Mirrors the harness's own vocabulary (SDK: FastModeState).
+export const FastModeStateSchema = z.enum(["off", "cooldown", "on"]);
+export type FastModeState = z.infer<typeof FastModeStateSchema>;

package/src/schemas/git-history.ts

@@ -0,0 +1,265 @@
+// git history graph (the "Git Graph" view over a repo's real commits)
+import { z } from "zod";
+import { GitChangeSchema } from "./git.js";
+import { RefNameSchema } from "./internal.js";
+import { RepoParamSchema } from "./shared.js";
+// A hex sha (full or git-abbreviated): the only shape the graph ever sends back, so the per-commit routes
+// constrain to it rather than accepting an arbitrary git revision expression.
+const ShaSchema = z.string().regex(/^[0-9a-f]{4,64}$/);
+// One commit in the graph. `parents` (0 = root, 1 = normal, 2+ = merge) drive the lane layout, computed
+// client-side. `refs` are the branch/tag decorations at this commit (tags keep their `tag: ` prefix; the bare
+// "HEAD" marker is lifted into `head` instead). `at` is author time in ms since epoch; `short` is git's
+// abbreviated sha; `body` is the message minus its subject line.
+export const GitCommitSchema = z.object({
+    sha: z.string().describe("The commit, in full."),
+    short: z.string().describe("The abbreviated form, for showing."),
+    parents: z
+        .array(z.string())
+        .describe(
+            "What it came from. None means the first commit, one is ordinary, two or more is a merge, which is what a graph draws its lanes from.",
+        ),
+    subject: z.string().describe("Its first line."),
+    body: z.string().describe("Everything after that."),
+    author: z.string().describe("Who wrote it."),
+    email: z.string().describe("Their address."),
+    at: z.number().describe("When they wrote it, in milliseconds."),
+    refs: z.array(z.string()).describe("Branches and tags sitting on it."),
+    head: z.boolean().describe("Whether this is where the repository currently stands."),
+});
+export type GitCommit = z.infer<typeof GitCommitSchema>;
+// One repo's log: commits newest-first across ALL refs (branch topology is the point of a graph), plus the
+// checked-out branch (absent on a detached HEAD or an unborn repo).
+export const GitLogSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    branch: z.string().optional().describe("Which branch these are from."),
+    commits: z.array(GitCommitSchema).describe("The commits, newest first."),
+    // Whether a further page exists behind this one. The daemon learns it by asking git for one commit more than
+    // it returns, see commitLog. It is also what stops the oldest row of a page from being drawn as a ROOT
+    // commit, which is how a truncated history used to claim it began where the page happened to stop.
+    hasMore: z
+        .boolean()
+        .describe(
+            "There are older ones behind this page. It is also what stops the last row being drawn as the beginning of history, which is how a truncated log used to claim it started where the page happened to stop.",
+        ),
+});
+export type GitLog = z.infer<typeof GitLogSchema>;
+export const GitLogQuerySchema = RepoParamSchema.extend({
+    limit: z.coerce.number().int().positive().max(2000).optional().describe("How many commits to return."),
+    // How many newer commits to step over, the page cursor. Paged rather than one big read because a large
+    // repository's log is tens of thousands of rows, and every one of them costs a zod validation, a wire
+    // payload and a lane computation before anything is drawn.
+    skip: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .max(1_000_000)
+        .optional()
+        .describe(
+            "How many newer commits to step over, which is how you page further back. Paged rather than read whole, because a large repository's history is tens of thousands of rows.",
+        ),
+});
+// Every real git repo under /work as root-relative dir ids ("root" is implicit, the /work repo itself).
+export const GitReposSchema = z.object({
+    repos: z.array(z.string()).describe('Every repository\'s id. The workspace itself is always present as "root".'),
+});
+export type GitRepos = z.infer<typeof GitReposSchema>;
+/* WHERE EACH WORKSPACE REPO LIVES ONLINE, one entry per repo that has a parseable remote, as the host and the
+ * `owner/name` project it names. Separate from `repos` above rather than folded into it because that route is
+ * on the file tree's hot path and this costs a `git remote -v` per repo; a caller that wants to recognise a
+ * workspace repo in somebody else's list (the publisher claim does exactly that) asks for it deliberately.
+ *
+ * A repo with no remote, or one naming a local path, is absent rather than present-and-empty: "this repo is
+ * nowhere online" and "this repo is at X" are different answers and only one of them can be matched against. */
+export const GitRemoteRepoSchema = z.object({
+    repo: z.string().describe("The workspace repository."),
+    host: z.string().describe("Which forge its remote points at."),
+    project: z.string().describe("Which project there, as owner and name."),
+});
+export type GitRemoteRepo = z.infer<typeof GitRemoteRepoSchema>;
+export const GitRemoteReposSchema = z.object({
+    repos: z.array(GitRemoteRepoSchema).describe("Each repository matched to the project its remote points at."),
+});
+export type GitRemoteRepos = z.infer<typeof GitRemoteReposSchema>;
+/* PUT ONE FILE ON THE DEFAULT BRANCH AND PUBLISH IT, write, commit that path alone, push, in one call.
+ *
+ * One route rather than three because the interesting states are the ones BETWEEN the steps: a file written but
+ * not committed, or committed but not pushed, is a repo the user now has to clean up by hand, and a browser
+ * making three requests owns that mess without being able to describe it. Here the caller gets one answer that
+ * says how far it got.
+ *
+ * `message` is the caller's because the commit shows up in the user's own history and a generic subject there
+ * is litter. */
+export const GitPublishFileSchema = RepoParamSchema.extend({
+    path: z.string().min(1).describe("Which file, relative to the repository."),
+    content: z.string().describe("Its whole new contents."),
+    message: z.string().min(1).describe("The commit message."),
+});
+/* HOW FAR THE PUBLISH GOT, in the terms the screen has to explain it in. `ok` is "the file is on the default
+ * branch of the remote" and nothing less, the only state that makes a public read of it succeed.
+ *
+ * The three steps are reported SEPARATELY because every boundary between them is a state a user can be left
+ * in and would otherwise have to discover: a file written but not committed, a commit that exists locally but
+ * was refused by the remote for credentials. Each of those needs a different sentence and a different next
+ * move, and one `ok: false` cannot carry either. It is also what tells the daemon whether the worktree moved
+ * at all, which decides whether this counts as a user write on the timeline.
+ *
+ * `branch` and `defaultBranch` ride along so a refusal can name both sides of the mismatch rather than saying
+ * "wrong branch" at someone who cannot see which one they are on. */
+export const GitPublishFileResultSchema = z.object({
+    ok: z.boolean().describe("Whether the whole thing went through."),
+    wrote: z.boolean().describe("The file was written."),
+    committed: z.boolean().describe("The commit was recorded."),
+    pushed: z.boolean().describe("It reached the remote."),
+    branch: z.string().optional().describe("Which branch it happened on."),
+    defaultBranch: z.string().optional().describe("Which branch the repository considers its main one, so a caller can see it was on a side branch."),
+    reason: z
+        .string()
+        .optional()
+        .describe(
+            "Why it stopped where it did. Being on a side branch, having no remote and having no credentials are all reported here rather than raised.",
+        ),
+});
+export type GitPublishFileResult = z.infer<typeof GitPublishFileResultSchema>;
+export const GitCommitDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSchema.describe("Which commit.") });
+// A commit's changed files (vs its first parent; a root commit vs the empty tree), the graph's detail tree
+// renders these (line stats included) and reuses the diff UI on click. Just GitChanges: the line stats live on
+// GitChange now, so working-tree and commit files share one shape.
+export const GitCommitDiffSchema = z.object({
+    files: z
+        .array(GitChangeSchema)
+        .describe(
+            "Which files it touched, with counts but not contents. Fetch any one file's contents separately, so a commit with a thousand files stays one cheap answer.",
+        ),
+});
+export type GitCommitDiff = z.infer<typeof GitCommitDiffSchema>;
+export const GitCommitFileDiffQuerySchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit."),
+    path: z.string().min(1).describe("Which file in it."),
+});
+// Git write actions from the graph's commit context menu (VSCode "Git Graph" parity). Non-destructive: branch
+// and tag just add a ref (HEAD + worktree untouched, no checkpoint). Sequence ops (revert / cherry-pick /
+// merge / rebase / drop) add or replay commits and are auto-checkpointed daemon-side; a conflict aborts and
+// reports `ok:false` (an expected outcome, not a throw). Checkout and reset move HEAD (reset --hard discards
+// the worktree), also auto-checkpointed. A `{repo, sha}` names the target commit for every commit-scoped
+// action; a ref name (branch/tag) is validated structurally, git enforces the rest of ref-name legality
+// (RefNameSchema is declared above, with the branch schemas that first use it).
+export const GitBranchCreateSchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit to start it at."),
+    name: RefNameSchema.describe("The new branch's name."),
+});
+export const GitTagCreateSchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit to tag."),
+    name: RefNameSchema.describe("The tag's name."),
+});
+export const GitCheckoutSchema = RepoParamSchema.extend({ ref: RefNameSchema.describe("Where to switch to: a branch, a tag, or a commit.") });
+// Deleting a tag locally, and, when a remote is named, on that remote too. The remote half is best-effort: a
+// tag that was never pushed must not make deleting the local one report a failure.
+export const GitTagDeleteSchema = RepoParamSchema.extend({
+    name: RefNameSchema.describe("Which tag."),
+    remote: RefNameSchema.optional().describe("Also delete it there. Leave it out to remove it locally only."),
+});
+// Publishing ONE tag, named explicitly so it never drags every other unpushed tag along with it.
+export const GitTagPushSchema = RepoParamSchema.extend({
+    name: RefNameSchema.describe("Which tag."),
+    remote: RefNameSchema.describe("Which remote to send it to."),
+});
+export const GitResetSchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit to move the branch to."),
+    mode: z
+        .enum(["soft", "mixed", "hard"])
+        .describe(
+            "How much to take with it: move the branch alone, also unstage, or also throw away what is on disk. The last one takes a checkpoint first.",
+        ),
+});
+export const GitCommitActionSchema = RepoParamSchema.extend({ sha: ShaSchema.describe("Which commit to act on.") });
+export const GitActionResultSchema = z.object({
+    ok: z.boolean().describe("Whether it worked."),
+    reason: z
+        .string()
+        .optional()
+        .describe(
+            "Why not, in git's own words. A conflict, a missing remote and missing credentials are all reported here rather than raised, because they are things a screen has to render rather than breakages.",
+        ),
+});
+export type GitActionResult = z.infer<typeof GitActionResultSchema>;
+/* THE STASH, work set aside without committing it, and the one part of a repository's real state the workspace
+ * used to be blind to entirely. A `git stash` in a terminal made the agent's (or the user's) work vanish from
+ * every surface here.
+ *
+ * An entry IS a commit: it has a sha, a time, a diff, and parents (HEAD when it was taken, the index, and the
+ * untracked tree when `-u` was used). What it does not have is a place in any branch's ancestry, so the graph
+ * hangs it off the commit it was taken on rather than flowing it down a lane.
+ *
+ * `ref` (`stash@{0}`) is the handle every verb takes, and it is POSITIONAL, dropping one renumbers the rest, so
+ * a caller must re-read the list after any mutation rather than holding an index across it. */
+export const StashEntrySchema = z.object({
+    ref: z.string().describe("How to address it, which applying and dropping take."),
+    sha: z.string().describe("The commit behind it, because a stash entry is a commit."),
+    short: z.string().describe("The abbreviated form, for showing."),
+    // git's own `WIP on <branch>: …` scaffolding stripped, leaving what a reader would call the message.
+    subject: z.string().describe("What it was set aside as, with git's own scaffolding stripped off."),
+    branch: z.string().optional().describe("Which branch it was set aside from."),
+    at: z.number().describe("When, in milliseconds."),
+    parents: z.array(z.string()).describe("What it sits on, so a graph can draw it like any other commit."),
+});
+export type StashEntry = z.infer<typeof StashEntrySchema>;
+export const StashListSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    stashes: z.array(StashEntrySchema).describe("What is set aside, newest first."),
+});
+// A stash ref as git numbers them. Constrained rather than free text because it reaches a shell argument.
+const StashRefSchema = z.string().regex(/^stash@\{\d{1,4}\}$/);
+export const StashPushSchema = RepoParamSchema.extend({
+    message: z.string().max(500).optional().describe("What to call it, so you know what it was later."),
+    includeUntracked: z.boolean().optional().describe("Also set aside files git is not yet tracking, which are otherwise left where they are."),
+});
+// `pop` drops the entry on a clean apply; `apply` keeps it. Git's own distinction, and both are things people
+// mean: pop is "resume this", apply is "try this here too".
+export const StashApplySchema = RepoParamSchema.extend({
+    ref: StashRefSchema.describe("Which entry."),
+    pop: z.boolean().optional().describe("Remove it from the stash once it has been applied cleanly."),
+});
+export const StashRefParamSchema = RepoParamSchema.extend({ ref: StashRefSchema.describe("Which entry.") });
+export const StashDiffQuerySchema = RepoParamSchema.extend({ ref: StashRefSchema.describe("Which entry.") });
+/* THE LAST THING THAT MOVED THIS BRANCH, and whether it can be walked back.
+ *
+ * Complements the Checkpoints timeline rather than duplicating it: a checkpoint restores the WORKING TREE, this
+ * moves the BRANCH. After a bad rebase the files are often already right and only the ref is wrong, and
+ * restoring a whole worktree snapshot to fix that would drag every unrelated edit since back with it.
+ *
+ * `description` is git's own reflog subject, so the button can name what it will undo in git's words rather than
+ * a guess. `previousSha` is where the branch returns to, and it doubles as the CONCURRENCY TOKEN: the undo is
+ * refused when the repository has moved since this was read, so an undo prepared against a stale view cannot
+ * land somewhere the user never looked at. Absent = nothing to undo (a fresh branch, a detached HEAD, or a
+ * halted operation, which ends by aborting rather than by moving the branch). */
+export const UndoKindSchema = z.enum(["commit", "amend", "merge", "rebase", "cherry-pick", "revert", "reset", "pull", "other"]);
+export type UndoKind = z.infer<typeof UndoKindSchema>;
+export const UndoableActionSchema = z.object({
+    kind: UndoKindSchema.describe("What the last action was."),
+    description: z.string().describe("What undoing it would do, in words."),
+    branch: z.string().describe("Which branch would move."),
+    sha: z.string().describe("Where it stands now."),
+    previousSha: z
+        .string()
+        .describe(
+            "Where it would go back to. Send this with the undo as proof you looked, so one prepared against a view that has since moved is refused rather than landing somewhere unexamined.",
+        ),
+    // The action rewrote FILES as well as the ref, so undoing it faithfully needs a hard reset. The UI uses this
+    // to decide whether it has to warn about losing work.
+    changesWorkingTree: z
+        .boolean()
+        .describe("Undoing would rewrite files as well as moving the branch, so anything offering it should warn about losing work."),
+});
+export type UndoableAction = z.infer<typeof UndoableActionSchema>;
+export const GitUndoStateSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    action: UndoableActionSchema.optional().describe("What undoing would reverse. Absent means there is nothing to go back from."),
+});
+export type GitUndoState = z.infer<typeof GitUndoStateSchema>;
+// `previousSha` is the position the caller was shown; `discardChanges` picks a hard reset over a soft one.
+export const GitUndoSchema = RepoParamSchema.extend({
+    previousSha: ShaSchema.describe(
+        "Where to go back to, from the matching read. It is also proof you looked: one prepared against a stale view is refused.",
+    ),
+    discardChanges: z.boolean().optional().describe("Also rewrite the files, rather than only moving the branch."),
+});