@intentic/sandbox-contract 1.248.0 → 1.250.0

package/src/schemas/ci.ts

@@ -1,32 +1,19 @@
 // ci: pipeline runs on the workspace repos' github/gitlab remotes
 import { z } from "zod";
 import { AgentRunPickSchema } from "./agent.js";
-// The daemon maps each workspace repo to the CI project behind its remote (a connected github/gitlab
-// capability supplies the token), registers a webhook so completed pipelines dispatch `ci` listener
-// automations instantly, and serves the Pipelines rail view from a webhook-freshened cache backfilled over the
-// same REST clients. `host` names WHICH provider API serves a repo; the listener provider is always `ci`, one
-// automation covers both hosts because the repo, not the vendor, is what a trigger narrows to.
+// The daemon maps each workspace repo to its CI project via a connected github/gitlab capability, registers a webhook
+// to fire `ci` listener automations instantly, and serves the Pipelines rail from a webhook-freshened, poll-backfilled
+// cache. `host` names which provider API serves a repo; the listener provider is always `ci`, since a trigger narrows
+// by repo, not by vendor.
 
 export const CiHostSchema = z.enum(["github", "gitlab"]);
 export type CiHost = z.infer<typeof CiHostSchema>;
-/* Both vendors' vocabularies over one enum: github's status+conclusion pair and gitlab's single status collapse
- * onto these six.
- *
- * QUEUED IS ITS OWN STATE AND NOT A FLAVOUR OF RUNNING, which it used to be, on the reasoning that a view only
- * needs "still moving" vs the three ways it stopped. What that produced is a board that spins over work nothing
- * is doing: a nightly whose six self-hosted jobs are waiting for a runner that is offline reads as six jobs in
- * progress, with a duration ticking up, for as long as the runner stays down. The distinction is not cosmetic,
- * it is the difference between "wait" and "go look at your runners", and it is the only question a reader of a
- * stuck pipeline actually has.
- *
- * The two are still one class for everything that asks "has this said anything yet": neither is a verdict, and
- * the callers that care read them as a pair. */
+// Both vendors' vocabularies collapsed onto six states. `queued` is its own state, not a flavor of `running`: a job
+// waiting on an offline runner must read as "go look at your runners", not as work in progress with a ticking duration.
 export const PipelineStatusSchema = z.enum(["queued", "running", "success", "failed", "canceled", "skipped"]);
 export type PipelineStatus = z.infer<typeof PipelineStatusSchema>;
-/* Whether a run or a job has yet to say anything, the pair against the three ways one stops. Here rather than
- * in either consumer because both ends split on it and must split the same way: the daemon, to know that the
- * span between two timestamps is not yet a duration, and the board, to count what is in flight, to keep a
- * Cancel button on offer, and to leave a run out of a verdict walk. */
+// Whether a run has said anything yet, against the three ways it can stop; shared here since the daemon (for duration
+// math) and the board (in-flight count, Cancel button, verdict walk) must split the same way.
 export const isPipelineInFlight = (status: PipelineStatus): boolean => status === "queued" || status === "running";
 export const PipelineRunSchema = z.object({
     // The workspace repo dir (the panels `repo` convention), the join key back to the tree and to triggers.
@@ -36,20 +23,16 @@ export const PipelineRunSchema = z.object({
     project: z.string().describe("The project there, as that forge names it."),
     // The vendor's numeric run/pipeline id, what rerun/cancel address.
     runId: z.number().describe("The forge's own id for the run, which is what re-running and cancelling take."),
-    // The run's headline: github's display_title (the commit subject, or the PR title when a PR triggered it),
-    // gitlab's pipeline name or the head commit's subject. Absent ⇒ the view falls back to ref@sha.
+    // github's display_title (commit subject, or PR title); gitlab's pipeline name or head commit subject.
     title: z
         .string()
         .optional()
         .describe("The run's headline, usually the commit subject or the pull request's title. Absent means falling back to the branch and commit."),
-    // Who the vendor credits for the run, the actor who set it off, matching what both vendors' own UIs
-    // show. The avatar is a vendor-hosted URL; absent ⇒ the view draws the author's initials instead.
+    // The actor the vendor credits, matching what its own UI shows; the avatar is vendor-hosted.
     authorName: z.string().optional().describe("Who the forge credits for setting it off."),
     authorAvatarUrl: z.string().optional().describe("Their picture, hosted by the forge. Absent means drawing their initials instead."),
-    // What set the run off, in the vendor's own vocabulary: gitlab's pipeline `source` (push, schedule,
-    // merge_request_event, web, api, trigger…) or github's `event` (push, pull_request, schedule,
-    // workflow_dispatch…). Left raw rather than flattened into a shared enum, the vendor's word is the
-    // precise one, and the view only calls it out when it isn't the everyday push.
+    // What set it off, in the vendor's own word (gitlab's `source`, github's `event`), left raw rather than flattened
+    // into a shared enum.
     trigger: z
         .string()
         .optional()
@@ -74,27 +57,16 @@ export const PipelineRunSchema = z.object({
         ),
 });
 export type PipelineRun = z.infer<typeof PipelineRunSchema>;
-/* One job inside a pipeline run. The view fetches these lazily (one extra call per visible run) so the list
- * endpoint stays cheap. Both GitHub Actions jobs and GitLab CI jobs normalize onto these fields.
- *
- * HOW THE VIEW LEARNS THE RUN'S SHAPE, in descending order of truth:
- *   1. `needs`, the dependencies the pipeline itself declares. The real graph, and the only one that can say
- *      a job waited on THIS one rather than on everything before it. Neither vendor's jobs API returns it, so
- *      it is read out of the pipeline definition (github: workflowGraph.ts) and is absent whenever that could
- *      not be resolved, a private workflow file, a deleted one, a name no declared job matches.
- *   2. `stage`. GitLab's native sequential grouping, returned by its jobs API and used verbatim.
- *   3. The timestamps, the last resort, and GitHub's before `needs` existed: overlapping runtimes ⇒ the jobs
- *      ran in parallel. Honest about when things happened, silent about what actually gated what.
- * Both timestamps are epoch ms, and a `queued` job carries NEITHER. That is an invariant the normalizers hold
- * up rather than something a vendor gives: GitHub reports a `started_at` on a job that has never started, set
- * to the moment the run was queued, so a job waiting an hour for a runner arrives claiming an hour of work.
- * Everything downstream reads a present `startedAt` as "this began", so the lie has to be dropped at the edge. */
+// Jobs fetched lazily per visible run so the list endpoint stays cheap; both vendors normalize onto these fields. Run
+// shape is read in descending order of truth: `needs` (the real declared graph), then `stage` (gitlab's own grouping),
+// then overlapping timestamps as a last resort. A `queued` job carries neither timestamp, an invariant the normalizers
+// enforce since github reports a fake `started_at` on a job that hasn't started.
 export const PipelineJobSchema = z.object({
     name: z.string().describe("The job's name."),
     status: PipelineStatusSchema.describe("How it went."),
     stage: z.string().optional().describe("Which stage it belongs to, where the pipeline groups its jobs that way."),
-    // Names of jobs IN THIS RUN that this one declared it waits on. Absent ⇒ nothing was resolved and the view
-    // must fall back; an empty array is the different, meaningful claim that this job is a root.
+    // Absent means nothing could be resolved (fall back); an empty array is the different claim that this job is a
+    // root.
     needs: z
         .array(z.string())
         .optional()
@@ -112,9 +84,9 @@ export const CiJobsResponseSchema = z.object({
     jobs: z.array(PipelineJobSchema).describe("The steps inside one run. Fetched separately from the run list, so that list stays cheap."),
 });
 export type CiJobsResponse = z.infer<typeof CiJobsResponseSchema>;
-// One mapped repo's CI wiring state. `hookWarning` is the manual-setup story when webhook registration was
-// refused (token scope, role) or impossible (no public URL): what happened plus the target URL + secret to
-// paste into the repo's webhook settings, the git-access sshRegistrationWarning pattern.
+// One mapped repo's CI wiring: `hookWarning` explains why webhook registration was refused or impossible, visible to
+// everyone. `hookRecipe` is the URL and secret to paste manually, shown to a maintainer or owner only, since the secret
+// signs every delivery this sandbox trusts.
 export const CiRepoSchema = z.object({
     repo: z.string().describe("Which workspace repository."),
     host: CiHostSchema.describe("Which forge it lives on."),
@@ -125,17 +97,16 @@ export const CiRepoSchema = z.object({
         .string()
         .optional()
         .describe(
-            "Present when the sandbox could not register for instant notifications, with what happened and what to paste in by hand. Without them the sandbox polls instead, so this costs a couple of minutes' delay rather than the feature.",
+            "Present when the sandbox could not register for instant notifications, with what happened. Without them the sandbox polls instead, so this costs a couple of minutes' delay rather than the feature.",
         ),
+    hookRecipe: z
+        .string()
+        .optional()
+        .describe("What to paste into the repository's webhook settings by hand, secret included. Shown to a maintainer or the owner only."),
 });
 export type CiRepo = z.infer<typeof CiRepoSchema>;
-/* How often the daemon polls a repo whose webhook could NOT be registered (ci/poller.ts), the fallback that
- * keeps a `ci` automation firing on a sandbox with no public URL or a token without hook scope.
- *
- * Here rather than beside the poller because both ends need the number: the daemon to run on it, and the
- * automation editor to tell the owner what a `hookWarning` actually costs them. "Webhooks are off" is a fact
- * about infrastructure; "this fires within two minutes instead of instantly" is the answer to the question
- * they were really asking. */
+// Fallback poll interval when a repo's webhook couldn't register; lives here since both the poller and the automation
+// editor need it to tell the owner what a `hookWarning` actually costs (minutes' delay, not the feature).
 export const CI_POLL_INTERVAL_MS = 2 * 60_000;
 export const CiRunsResponseSchema = z.object({
     repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
@@ -143,8 +114,7 @@ export const CiRunsResponseSchema = z.object({
     runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
 });
 export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
-// rerun/cancel/fix address a run by repo + vendor id; the daemon re-resolves repo → project + token per call,
-// so a stale card can't act on a project the workspace no longer maps to.
+// Re-resolves repo → project + token on every call, so a stale card can't act on a mapping the workspace no longer has.
 export const CiRunParamSchema = z.object({
     repo: z
         .string()
@@ -154,12 +124,18 @@ export const CiRunParamSchema = z.object({
     runId: z.number().describe("Which run, by the forge's own id."),
 });
 export type CiRunParam = z.infer<typeof CiRunParamSchema>;
-// Fixing takes one thing the vendor proxies do not: which model to open the session on, when the user reached
-// for the caret beside the button rather than pressing it (AgentRunPickSchema). Absent is the ordinary path.
+// Which model to open the session on, when the user reached for the caret instead of pressing the button; absent is
+// ordinary.
 export const CiFixParamSchema = CiRunParamSchema.extend({
     pick: AgentRunPickSchema.describe(
         "Which model to open the conversation on, when somebody chose one. Leave it out for the sandbox's own choice, which is the ordinary path.",
     ),
+    force: z
+        .boolean()
+        .optional()
+        .describe(
+            "Open the conversation even when every failed job died in its runner's own setup, which is the fleet's fault and nothing an agent on the code can repair. Left out, such a run is refused with that sentence.",
+        ),
 });
 export type CiFixParam = z.infer<typeof CiFixParamSchema>;
 // The fix route opens an isolated conversation (fleet card + chat tab) seeded with the failure context.
@@ -167,49 +143,28 @@ export const CiFixResponseSchema = z.object({
     conversationId: z.string().describe("The conversation that was opened, already holding the failure. Open it to watch, or attach to its turn."),
 });
 export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
-/* ---- the pre-push check: the workspace's own answer to "would this push go red" ----
- *
- * WHERE THIS SITS. A fleet of 5-20 agents lands work into the main tree, the user reviews and commits it by
- * parts, pushes, and CI answers minutes later. The check front-runs that answer at the push itself, the last
- * moment before the work leaves the machine, and the first moment at which what will be pushed is finally
- * settled.
- *
- * WHY THE PUSH AND NOT THE LAND, which is where this used to run. A post-land verdict is about a tree that
- * keeps moving: the user commits by parts, another agent lands, an edit arrives, so the verdict spent its life
- * either stale or being recomputed, and needed a content fingerprint, a staleness rule and a badge to say which.
- * All of that machinery existed to answer a question the push asks for free, because at the push there is
- * exactly one artifact and the user is standing in front of it waiting.
- *
- * SO THERE IS NO STORED VERDICT AND NOTHING IS POLLED AT REST. A run exists while it runs, reports to the
- * dialog that started it, and is gone. Nothing survives a daemon restart because nothing needs to: the next
- * push asks again. */
+// The workspace's own answer to "would this push go red": front-runs CI at the push itself, the last moment before work
+// leaves the machine and the first at which what's pushed is finally settled. Runs at the push rather than the land,
+// where the tree keeps moving and a verdict would need staleness tracking to answer a question the push gets for free.
+// No stored verdict, nothing polled at rest: a run exists while it runs and is gone after, since the next push asks
+// again.
 
-/* A COMMAND RUN ON A CLICK, in a visible terminal, with a verdict and a quotable tail: the ONE shape for
- * everything the daemon runs because the owner pressed a button and then has to be told how it went. The
- * pre-push check is one (above); the push itself is another (PushRunSchema, schemas/git.ts), because a push
- * runs the repository's own pre-push hook, which is a suite in disguise. One shape rather than one per
- * moment, so a field the browser learns to read for the check (the terminal to open, the tail to quote, the
- * kill to distinguish from the timeout) is read for the push by the same code, and cannot drift.
- *
- * Where a run is.
- *
- *   idle     , nothing has run in this daemon's life, or the last run was cleared.
- *   running  , the command is live. Its output is the terminal's (`session`), not this object's.
- *   passed   , exited 0. The push goes (or went).
- *   failed   , exited non-zero, or was killed by its ceiling (`timedOut`). The state a fix answers.
- *   error    , the command could not run at all: it was not spawnable. NOT a fix-able failure, because there
- *               is nothing wrong with the code, the command is misconfigured, and saying "tests failed" would
- *               send an agent hunting a bug that isn't there.
- *   cancelled, the user stopped the run.
- */
+// One shape for any command the daemon runs on a click with a verdict and a quotable tail (the pre-push check, and the
+// push itself via PushRunSchema in schemas/git.ts), so the fields the browser reads (terminal, tail, kill vs timeout)
+// can't drift between them.
+// idle: nothing has run yet, or the last run was cleared
+// running: live; its output is the terminal's, not this object's
+// passed: exited 0
+// failed: exited non-zero, or killed by its ceiling (`timedOut`)
+// error: not spawnable at all; not fixable, since nothing is wrong with the code
+// cancelled: the user stopped it
 export const CommandRunStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
 export type CommandRunStatus = z.infer<typeof CommandRunStatusSchema>;
 export const CommandRunSchema = z.object({
     status: CommandRunStatusSchema.describe(
         "Where the run is. Failed and error are deliberately different: failed means the code is wrong, error means the command could not be run at all, and calling the second one a test failure would send an agent hunting a bug that is not there.",
     ),
-    // The command this run executed, echoed rather than read back from settings: a result read after the
-    // setting changed still has to say what produced it.
+    // Echoed rather than read from settings, so a result seen after the setting changed still says what produced it.
     command: z
         .string()
         .describe(
@@ -219,23 +174,16 @@ export const CommandRunSchema = z.object({
     finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
     exitCode: z.number().optional().describe("How the command exited."),
     timedOut: z.boolean().optional().describe("It was killed for taking too long rather than finishing."),
-    /* The tmux session the suite runs in, for the browser to open the terminals panel on, the check is a
-     * visible terminal like every other shell command the daemon runs on a click (terminal/terminal-run.ts), so
-     * WATCHING it is not this object's job and never was. Absent where the sandbox has no tmux wrapper (local
-     * dev): the runner falls back to an invisible shell, and a name nothing can attach to would send the browser
-     * after a tab that is never going to be listed. */
+    // The tmux session to open, since watching a run is the terminal panel's job, not this object's; absent where the
+    // sandbox has no tmux wrapper.
     session: z
         .string()
         .optional()
         .describe(
             "The terminal it runs in, which is where to watch it. Absent where the sandbox has no terminals, in which case there is nothing to attach to.",
         ),
-    /* What the fix proposal quotes, and its only reader, tail-capped (PREPUSH_OUTPUT_BYTES) so a prompt seeded
-     * from a red run stays about fixing rather than scrolling. The TAIL, not the head: a suite's verdict and its
-     * failure summary are at the end. PLAIN TEXT, not what the terminal received: the suite's colour codes and
-     * redrawn progress lines are resolved away (terminal/plain-text.ts) before the cap, so a quoted tail reads
-     * as a failure instead of as litter. Empty while the run is going, and for a run that was killed: the pane
-     * (and its log) is where the whole of it lives. */
+    // Tail-capped plain text, colour codes and redrawn progress lines stripped, so a fix prompt quotes a verdict, not
+    // terminal litter; empty while running or for a killed run.
     output: z
         .string()
         .describe(

package/src/schemas/codebase-health.ts

@@ -1,15 +1,11 @@
 // codebase health: one repository's structure and risk, in numbers
 import { z } from "zod";
 import { WorkspaceSearchFreshnessSchema } from "./workspace-search.js";
-// The repo-level companion to the management panel and the git-history graph: what the same resident engine's
-// `hotspots` (churn × complexity) and `map` (PageRank over the import graph) verbs rank, as figures a panel can
-// plot instead of lines a terminal prints.
-//
-// Every field is a COUNT that can be recounted in the files themselves, commits, branch points, exported
-// symbols. Deliberately no composite "maintainability grade": those aren't comparable across projects and can't
-// be checked, and a repo-health surface that launders counts into a letter is worse than none.
-// How many hotspot files and key modules a report carries when the caller names no limit. A leaderboard, not an
-// inventory: past a screenful the ranking stops being the point, and the reader should be reading the files.
+// Repo-level companion to the management panel and git-history graph: the resident engine's `hotspots` (churn ×
+// complexity) and `map` (PageRank over imports) verbs, as figures a panel can plot. Every field is a recountable count;
+// no composite maintainability grade, since those aren't comparable across projects or checkable. HEALTH_LIMIT is how
+// many hotspot files and key modules a report carries by default: a leaderboard, not an inventory, since past a
+// screenful the reader should be reading the files instead.
 export const HEALTH_LIMIT = 20;
 export const WorkspaceHealthQuerySchema = z.object({
     // "root" (the /work repo) or a nested repo's root-relative dir, the same {repo} ids the git routes take.
@@ -28,8 +24,8 @@ export const WorkspaceHealthQuerySchema = z.object({
         .optional()
         .describe("How many files and modules to rank. A leaderboard rather than an inventory: past a screenful the ranking stops being the point."),
 });
-// One file that is BOTH churning and tangled. `score` is the product the ranking sorts by, carried explicitly
-// so the panel plots the number it ranks by rather than recomputing it.
+// A file both churning and tangled; `score` is the ranking product, carried explicitly so the panel plots what it ranks
+// by rather than recomputing it.
 export const WorkspaceHotspotSchema = z.object({
     path: z.string(),
     commits: z.number(),