@intentic/sandbox-contract 1.249.0 → 1.251.0

package/src/state/arrival.ts

@@ -30,7 +30,7 @@ export const ArrivalGroupSchema = z.enum([
     "capability",
     // The agent settings that differ from their defaults.
     "settings",
-    // A merge into CLAUDE.md / AGENTS.md.
+    // A merge into the workspace's memory file.
     "memory",
     "skill",
     "automation",

package/src/state/fix-attempt-plan.test.ts

@@ -0,0 +1,64 @@
+import { expect, test } from "vitest";
+import { ciFixConversationId, fixAttemptId } from "../ids/conversation-ids.js";
+import type { AgentSummary } from "../schemas/agents.js";
+import { planFixAttempt } from "./fix-attempt-plan.js";
+
+const NO_ATTENTION = { plan: false, question: false, permission: false, capability: false, credential: false, conflict: false };
+const BASE = ciFixConversationId(`web`, 41);
+
+const agent = (id: string, over: Partial<AgentSummary> = {}): AgentSummary => ({
+    id,
+    status: `running`,
+    provider: `claude`,
+    harness: `native`,
+    attention: { ...NO_ATTENTION },
+    updatedAt: 1_000,
+    ...over,
+});
+
+test("with nobody on the failure, a press opens attempt 1 under the failure's own id", () => {
+    expect(planFixAttempt(BASE, [], [])).toEqual({ kind: `new`, conversationId: BASE, attempt: 1 });
+});
+
+// The archive counts: attempt 1 was set aside earlier, and re-minting its id would un-archive it.
+test("an archived attempt is skipped over, not resurrected", () => {
+    expect(planFixAttempt(BASE, [], [BASE])).toEqual({ kind: `new`, conversationId: fixAttemptId(BASE, 2), attempt: 2 });
+});
+
+test("a landed attempt is closed: the same gates red again get a fresh attempt", () => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `landed` })], []);
+    expect(plan).toEqual({ kind: `new`, conversationId: fixAttemptId(BASE, 2), attempt: 2 });
+});
+
+test("an attempt that ended is continued by a plain press, and by an explicit Continue", () => {
+    const roster = [agent(BASE, { status: `error`, failure: `no capacity` })];
+    expect(planFixAttempt(BASE, roster, [])).toEqual({ kind: `continue`, conversationId: BASE, attempt: 1 });
+    expect(planFixAttempt(BASE, roster, [], `continue`)).toEqual({ kind: `continue`, conversationId: BASE, attempt: 1 });
+});
+
+test("start over retires the latest attempt and numbers the next past it", () => {
+    const second = fixAttemptId(BASE, 2);
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `stopped` }), agent(second, { status: `error` })], [], `start-over`);
+    expect(plan).toEqual({ kind: `start-over`, retire: second, stopFirst: false, conversationId: fixAttemptId(BASE, 3), attempt: 3 });
+});
+
+// Only a running turn needs stopping before the archive will take it; a parked one is already still.
+test("starting over on a working attempt stops it first", () => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `running` })], [], `start-over`);
+    expect(plan).toMatchObject({ kind: `start-over`, retire: BASE, stopFirst: true });
+    const parked = planFixAttempt(BASE, [agent(BASE, { status: `awaiting`, attention: { ...NO_ATTENTION, question: true } })], [], `start-over`);
+    expect(parked).toMatchObject({ kind: `start-over`, stopFirst: false });
+});
+
+// A second agent beside a live one is the race the derived id exists to prevent; the press opens the live one instead.
+test.each([`running`, `awaiting`, `ready`] as const)("an attempt still in play (%s) is busy, not a fresh press", (status) => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status })], []);
+    expect(plan).toMatchObject({ kind: `busy`, conversationId: BASE });
+    // Continue is not a way around it either.
+    expect(planFixAttempt(BASE, [agent(BASE, { status })], [], `continue`).kind).toBe(`busy`);
+});
+
+test("a spent allowance is a wait, not an ending: the press does not spend it again", () => {
+    const plan = planFixAttempt(BASE, [agent(BASE, { status: `error`, failureCode: `rate_limit` })], []);
+    expect(plan.kind).toBe(`busy`);
+});

package/src/state/fix-attempt-plan.ts

@@ -0,0 +1,54 @@
+import { fixAttemptOf, latestFixAttempt, nextFixAttemptId } from "../ids/conversation-ids.js";
+import type { AgentSummary } from "../schemas/agents.js";
+import { type FixStance, fixStance } from "./fix-stance.js";
+
+/* WHAT A PRESS ON A FAILURE'S FIX CONTROL DOES, decided once for every surface that has one — the push question in
+ * the shell, the pipelines board's rows, the daemon's own /ci/fix route — so the browser and the daemon cannot
+ * disagree about whether a press continues an attempt, opens the next one, or has to wait. Pure: the roster in, a
+ * plan out. Carrying the plan out (stopping, archiving, starting) is the caller's, since each side does that
+ * through its own doors.
+ *
+ * THE RULE, in the order it is read: nothing live (or the last answer landed) opens the NEXT attempt; "start over"
+ * sets the latest aside and opens the next; an attempt that ENDED is continued; anything else is still in play and
+ * the reader is sent to it rather than allowed to race a second agent beside it. */
+
+// How the reader ended the picker, when they did; absent is the plain press on the button.
+export type FixResume = "continue" | "start-over";
+
+export type FixAttemptPlan =
+    // Nothing live answers this failure, or the last answer landed: open the next attempt with the full prompt.
+    | { readonly kind: "new"; readonly conversationId: string; readonly attempt: number }
+    // The latest attempt ended without a fix: carry on in it, with a nudge rather than the whole opening prompt.
+    | { readonly kind: "continue"; readonly conversationId: string; readonly attempt: number }
+    // Set the latest attempt aside (stopped first if still running) and open the next one on a clean worktree.
+    | {
+          readonly kind: "start-over";
+          readonly retire: string;
+          readonly stopFirst: boolean;
+          readonly conversationId: string;
+          readonly attempt: number;
+      }
+    // The latest attempt is still in play: working, parked on the reader, or holding a fix to review. Open it instead.
+    | { readonly kind: "busy"; readonly conversationId: string; readonly stance: FixStance };
+
+// `roster` is the live fleet; `knownIds` is every conversation id that exists, archived ones included, since the next
+// attempt's number must clear the archive too (conversation-ids.ts, nextFixAttemptId).
+export const planFixAttempt = (base: string, roster: readonly AgentSummary[], knownIds: Iterable<string>, resume?: FixResume): FixAttemptPlan => {
+    const latest = latestFixAttempt(base, roster);
+    const stance = latest === undefined ? undefined : fixStance(latest.agent);
+    const known = [...knownIds, ...(latest === undefined ? [] : [latest.agent.id])];
+    const next = (): { conversationId: string; attempt: number } => {
+        const conversationId = nextFixAttemptId(base, known);
+        return { conversationId, attempt: fixAttemptOf(base, conversationId) ?? 1 };
+    };
+    if (latest === undefined || stance === undefined || stance.kind === "landed") {
+        return { kind: "new", ...next() };
+    }
+    if (resume === "start-over") {
+        return { kind: "start-over", retire: latest.agent.id, stopFirst: stance.kind === "working", ...next() };
+    }
+    if (stance.retry) {
+        return { kind: "continue", conversationId: latest.agent.id, attempt: latest.attempt };
+    }
+    return { kind: "busy", conversationId: latest.agent.id, stance };
+};

package/src/state/fix-stance.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from "vitest";
+import { fixStance } from "./fix-stance.js";
+import type { AgentSummary } from "../schemas/agents.js";
+
+const NO_ATTENTION = { plan: false, question: false, permission: false, capability: false, credential: false, conflict: false };
+
+const agent = (over: Partial<AgentSummary> = {}): AgentSummary => ({
+    id: `ci-fix-web-42`,
+    status: `running`,
+    provider: `claude`,
+    harness: `native`,
+    attention: { ...NO_ATTENTION },
+    updatedAt: 1_000,
+    ...over,
+});
+
+test("a live turn reads as work in progress, and asks nothing of the reader", () => {
+    const stance = fixStance(agent({ status: `running` }));
+    expect(stance.kind).toBe(`working`);
+    expect(stance.ongoing).toBe(true);
+    expect(stance.retry).toBe(false);
+});
+
+test.each([`resuming`, `stopping`, `dismissing`] as const)("%s still reads as working", (status) => {
+    expect(fixStance(agent({ status })).kind).toBe(`working`);
+});
+
+test("a parked turn is read off the attention flag, not the status", () => {
+    const stance = fixStance(agent({ status: `idle`, attention: { ...NO_ATTENTION, question: true } }));
+    expect(stance.kind).toBe(`needs-you`);
+    expect(stance.label).toBe(`Question for you`);
+    expect(stance.ongoing).toBe(true);
+});
+
+test("a setup that is not connected yet outranks a question raised beside it", () => {
+    const stance = fixStance(agent({ status: `awaiting`, attention: { ...NO_ATTENTION, question: true, capability: true } }));
+    expect(stance.label).toBe(`Setup needed`);
+});
+
+test("a turn parked with no flag yet still says it is waiting on you", () => {
+    expect(fixStance(agent({ status: `awaiting` })).kind).toBe(`needs-you`);
+});
+
+test("held work reads as a fix to review, whether the fleet called it ready or left it idle", () => {
+    expect(fixStance(agent({ status: `ready` })).kind).toBe(`ready`);
+    expect(fixStance(agent({ status: `idle`, diff: { files: 4, insertions: 120, deletions: 8 } })).kind).toBe(`ready`);
+});
+
+// Diff present doesn't change a failed status to ready; it only earns a mention in the hint.
+test("an agent that failed after writing files still reads as failed", () => {
+    const stance = fixStance(agent({ status: `error`, diff: { files: 2, insertions: 34, deletions: 6 } }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.retry).toBe(true);
+    expect(stance.hint).toContain(`2 changed files on its branch`);
+});
+
+test("a finished turn that changed nothing offers to try again", () => {
+    const stance = fixStance(agent({ status: `idle` }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.label).toBe(`Nothing changed`);
+    expect(stance.retry).toBe(true);
+    expect(stance.ongoing).toBe(false);
+});
+
+test("a landed fix is over, and stops holding the branch's other rows back", () => {
+    const stance = fixStance(agent({ status: `landed`, diff: { files: 2, insertions: 10, deletions: 1 } }));
+    expect(stance.kind).toBe(`landed`);
+    expect(stance.ongoing).toBe(false);
+    expect(stance.retry).toBe(false);
+});
+
+test("a failed turn carries the provider's own sentence into the hint", () => {
+    const stance = fixStance(agent({ status: `error`, failure: `the model endpoint refused the request` }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.retry).toBe(true);
+    expect(stance.hint).toContain(`the model endpoint refused the request`);
+});
+
+// Retry is false because retrying would spend the same already-refused allowance.
+test("a spent allowance reads as a wait rather than an error", () => {
+    const stance = fixStance(agent({ status: `error`, failureCode: `rate_limit`, failure: `usage limit reached` }));
+    expect(stance.kind).toBe(`waiting`);
+    expect(stance.retry).toBe(false);
+    expect(stance.ongoing).toBe(true);
+});
+
+test("a stopped turn says so, and offers the press again", () => {
+    const stance = fixStance(agent({ status: `stopped` }));
+    expect(stance.label).toBe(`Stopped`);
+    expect(stance.retry).toBe(true);
+});
+
+// An unknown status can arrive from a newer daemon; the stance must still read rather than crash on a missing ending.
+test("an unknown ending still produces a stance", () => {
+    const stance = fixStance(agent({ status: `teleported` as AgentSummary["status"] }));
+    expect(stance.kind).toBe(`ended`);
+    expect(stance.label).toBe(`Agent stopped`);
+    expect(stance.retry).toBe(true);
+});

package/src/state/fix-stance.ts

@@ -0,0 +1,140 @@
+import type { AgentSummary } from "../schemas/agents.js";
+
+/* WHAT BECAME OF THE AGENT A SURFACE SENT AFTER A FAILURE — a red pipeline row, a refused push — read off the fleet
+ * summary that surface joined by conversation id (ids/conversation-ids.ts). Reads both status and attention, since
+ * a parked turn is `idle` with a flag rather than finished. Mirrors the fleet board's own labels except for naming
+ * the subject (`Fix ready`), because on these surfaces the failure is what's read. Pure: no host, no clock.
+ *
+ * IN THE CONTRACT, NOT IN ONE SURFACE, because the words must not differ between the pipelines board (an
+ * extension) and the push question (the shell): the same agent, one click apart, described two ways is a bug a
+ * reader notices before a test does. Only the reading lives here; how each kind is DRAWN (icon, colour) is the UI
+ * kit's `fixStanceLook`, which an extension cannot load in a test and this package must not know about. */
+
+export type FixStanceKind =
+    // A turn is in flight. Nothing is owed by the reader.
+    | "working"
+    // Parked on the user: a question, a plan, a permission, a setup, a conflict.
+    | "needs-you"
+    // The fix is written and held on the agent's branch, waiting to be reviewed and landed.
+    | "ready"
+    // It is in the workspace. What is left is proving it: re-run the check.
+    | "landed"
+    // Stopped on a spent allowance, which is a wait rather than a failure and must not be drawn as one.
+    | "waiting"
+    // Over, with nothing held: it failed, it was interrupted, it was stopped, or it changed nothing.
+    | "ended";
+
+export interface FixStance {
+    readonly kind: FixStanceKind;
+    // True while this agent is still the failure's live answer; false once ended or landed.
+    readonly ongoing: boolean;
+    // True only for an ended fix: the one state where continuing it is a press rather than a chip.
+    readonly retry: boolean;
+    readonly label: string;
+    // Why the chip says what it says, and what pressing it does; no time-relative words.
+    readonly hint: string;
+}
+
+const needsYou = (label: string, hint: string): FixStance => ({ kind: "needs-you", ongoing: true, retry: false, label, hint });
+
+// Ranks parked flags like the fleet does: setup outranks a plain question since it blocks the agent outright.
+const ATTENTION: readonly { readonly flag: keyof AgentSummary["attention"]; readonly label: string; readonly why: string }[] = [
+    { flag: "plan", label: "Approval needed", why: "it has proposed a plan and is waiting for a yes" },
+    { flag: "capability", label: "Setup needed", why: "it needs something connected that is not connected yet" },
+    { flag: "question", label: "Question for you", why: "it has asked you something" },
+    { flag: "permission", label: "Permission needed", why: "it wants to use a tool it needs permission for" },
+    { flag: "conflict", label: "Land conflict", why: "its work cannot be merged until somebody resolves a clash" },
+];
+
+// Live turn: running, unwinding a Stop, or waiting on a daemon repair; `awaiting` is handled above.
+const IN_FLIGHT: ReadonlySet<AgentSummary["status"]> = new Set(["running", "resuming", "stopping", "dismissing"]);
+
+const WORKING: FixStance = {
+    kind: "working",
+    ongoing: true,
+    retry: false,
+    label: "Agent working",
+    hint: "An agent is already working on this failure. Open the conversation to watch it.",
+};
+
+const READY: FixStance = {
+    kind: "ready",
+    ongoing: true,
+    retry: false,
+    label: "Fix ready",
+    hint: "The fix is written and held on the agent's branch. Open it to review the diff and land it.",
+};
+
+const LANDED: FixStance = {
+    kind: "landed",
+    ongoing: false,
+    retry: false,
+    label: "Fix landed",
+    hint: "The fix is in your workspace. Running the check again is what proves it.",
+};
+
+const WAITING: FixStance = {
+    kind: "waiting",
+    ongoing: true,
+    retry: false,
+    label: "Waiting",
+    hint: "The fix agent's allowance is spent. Nothing is owed: the turn goes again when the provider's window reopens.",
+};
+
+// True only for a clean finish (`ready`, or `idle` with a diff); a crashed turn with files also has a diff, but that
+// belongs in the ending's hint, not here.
+const holdingWork = (agent: AgentSummary): boolean =>
+    agent.status === "ready" || (agent.status === "idle" && agent.diff !== undefined && agent.diff.files > 0);
+
+// Each ending's label states the reader's next move, not just what happened; `idle` counts too, since finishing with no
+// changed files fixed nothing.
+const ENDINGS: Partial<Record<AgentSummary["status"], { readonly label: string; readonly why: string }>> = {
+    error: { label: "Agent failed", why: "The fix agent's turn failed" },
+    interrupted: { label: "Interrupted", why: "The fix agent's turn was cut off when the sandbox went away" },
+    stopped: { label: "Stopped", why: "The fix agent was stopped before it finished" },
+    idle: { label: "Nothing changed", why: "The fix agent finished without changing any files" },
+};
+
+const ended = (agent: AgentSummary): FixStance => {
+    const ending = ENDINGS[agent.status] ?? { label: "Agent stopped", why: "The fix agent's turn ended" };
+    // File count left behind by a turn that died mid-edit; not a fix, but worth surfacing.
+    const files = agent.diff?.files ?? 0;
+    const partial = files === 0 ? "" : ` It left ${files} changed file${files === 1 ? "" : "s"} on its branch.`;
+    return {
+        kind: "ended",
+        ongoing: false,
+        retry: true,
+        label: ending.label,
+        // Includes the provider's own failure sentence when present; often the only record of an unwatched run.
+        hint: `${ending.why}${agent.failure === undefined ? "" : `: ${agent.failure}`}.${partial} Continuing carries on in the same conversation; starting over opens a fresh one.`,
+    };
+};
+
+// List order is priority, so a new status is inserted at its rank rather than appended as a trailing if. A spent
+// allowance is checked first, ahead of `error`, since it is not a failure and must not offer a retry that spends the
+// same allowance again.
+const RULES: readonly ((agent: AgentSummary) => FixStance | undefined)[] = [
+    (agent) => (agent.status === "error" && agent.failureCode === "rate_limit" ? WAITING : undefined),
+    (agent) => {
+        const parked = ATTENTION.find((entry) => agent.attention[entry.flag]);
+        return parked === undefined ? undefined : needsYou(parked.label, `The fix agent is waiting on you: ${parked.why}.`);
+    },
+    // Bare `awaiting`/`conflict` with no flag raised: parked, with nothing more specific to say.
+    (agent) =>
+        agent.status === "awaiting" || agent.status === "conflict"
+            ? needsYou("Needs you", "The fix agent has stopped and is waiting on you.")
+            : undefined,
+    (agent) => (IN_FLIGHT.has(agent.status) ? WORKING : undefined),
+    (agent) => (holdingWork(agent) ? READY : undefined),
+    (agent) => (agent.status === "landed" ? LANDED : undefined),
+];
+
+export const fixStance = (agent: AgentSummary): FixStance => {
+    for (const rule of RULES) {
+        const stance = rule(agent);
+        if (stance !== undefined) {
+            return stance;
+        }
+    }
+    return ended(agent);
+};

package/src/state/runtime-state.ts

@@ -31,7 +31,8 @@ const RUNTIME_DOMAINS = [
     { domain: "subagents", invalidates: [["subagents"]] },
 
     // Machines on the other end of a socket (devices, browsers, runners); "online" is the socket itself, never sampled.
-    // hosts/webext land on capabilities since a pairing card's state is literally the hub's online answer.
+    // hosts/webext land on capabilities since a pairing card's state is literally the hub's online answer. `hosts` also
+    // carries a device reading that landed too late for the reader waiting on it (hosts/device-reports.ts).
     { domain: "hosts", invalidates: [["capabilities"], ["devices"]] },
     { domain: "webext", invalidates: [["capabilities"]] },
     { domain: "runners", invalidates: [["runners"]] },