@intentic/sandbox-contract 1.244.0 → 1.246.1

package/src/batch-runs.test.ts

@@ -0,0 +1,167 @@
+import { STATE_DIR } from "@intentic/constants";
+import { describe, expect, it } from "vitest";
+import {
+    type BatchRunKind,
+    batchConversationId,
+    batchItemDir,
+    batchReportingClause,
+    batchResultPath,
+    batchRunDir,
+    batchRunIdAt,
+    batchRunManifestPath,
+    batchRunPrefix,
+    batchTurnBody,
+    parseBatchFile,
+} from "./batch-runs.js";
+import { ConversationIdSchema } from "./schemas/agent.js";
+
+// The two real layouts this substrate had to fit without moving anything already on disk: one that fans out
+// over items under `records/artifacts`, and one where a run IS the item, under `records/chores`.
+const FANNED: BatchRunKind = { runsDir: `records/artifacts/acceptance`, prefix: `xt`, scanRuns: 10 };
+const SINGLE: BatchRunKind = { runsDir: `records/chores/runs`, prefix: `mt`, scanRuns: 30 };
+
+describe(`batch run ids`, () => {
+    it(`sorts by the moment it was minted`, () => {
+        const earlier = batchRunIdAt(Date.parse(`2026-09-04T00:00:00Z`));
+        const later = batchRunIdAt(Date.parse(`2026-09-05T00:00:00Z`));
+        expect([earlier < later, earlier.startsWith(`r`)]).toEqual([true, true]);
+    });
+
+    /* Sorting has to survive a base-36 digit boundary, which is what an unpadded `toString(36)` gets wrong:
+     * the smaller number is the shorter string, and the shorter string sorts first only by luck. */
+    it(`still sorts when two moments straddle a digit boundary`, () => {
+        const boundary = 36 ** 7;
+        expect(batchRunIdAt(boundary - 1) < batchRunIdAt(boundary)).toBe(true);
+    });
+
+    /* The drift that made this shared. A surface where one run IS one item mints several inside a millisecond
+     * ("run this chore in every repository"), and the copy without a counter handed them all the same id. */
+    it(`does not repeat inside one millisecond`, () => {
+        const minted = new Set(Array.from({ length: 50 }, () => batchRunIdAt(1_700_000_000_000)));
+        expect(minted.size).toBe(50);
+    });
+});
+
+describe(`batch conversation ids`, () => {
+    it(`carries the kind's prefix, so a run joins the fleet by filtering GET /agents`, () => {
+        const id = batchConversationId(FANNED, `r5k2`, `checkout-flow`);
+        expect([id, id.startsWith(batchRunPrefix(FANNED))]).toEqual([`xt-r5k2-checkout-flow`, true]);
+    });
+
+    it(`names a single-item run by its run id alone`, () => {
+        expect(batchConversationId(SINGLE, `r5k2a`)).toBe(`mt-r5k2a`);
+    });
+
+    /* The run id is how a finished card is attributed back to its run, so the ITEM is what gets cut. Measured
+     * against the real schema rather than a copy of its regex: the cap exists because that schema enforces it. */
+    it(`cuts the item, never the run id, and still satisfies ConversationIdSchema`, () => {
+        const runId = batchRunIdAt(1_700_000_000_000);
+        const id = batchConversationId(FANNED, runId, `x`.repeat(200));
+        expect([id.startsWith(`xt-${runId}-`), ConversationIdSchema.safeParse(id).success]).toEqual([true, true]);
+    });
+
+    // A cut that lands on the separator would leave `xt-r5k2-`, which ConversationIdSchema refuses.
+    it(`leaves no trailing separator when the cut lands on one`, () => {
+        const runId = `r${`z`.repeat(58)}`;
+        const id = batchConversationId(FANNED, runId, `story`);
+        expect([id.endsWith(`-`), ConversationIdSchema.safeParse(id).success]).toEqual([false, true]);
+    });
+});
+
+describe(`where a run keeps its files`, () => {
+    it(`puts every run under the state dir, in the kind's own directory`, () => {
+        expect(batchRunManifestPath(FANNED, `r5k2`)).toBe(`${STATE_DIR}/records/artifacts/acceptance/r5k2/run.json`);
+    });
+
+    it(`gives a fanned-out item a directory of its own`, () => {
+        expect(batchResultPath(FANNED, `r5k2`, `checkout-flow`)).toBe(`${STATE_DIR}/records/artifacts/acceptance/r5k2/checkout-flow/result.json`);
+    });
+
+    // A run whose item is the run writes beside its manifest rather than one pointless level down: the layout
+    // maintenance already has on disk.
+    it(`writes a single-item run's result beside its manifest`, () => {
+        expect([batchResultPath(SINGLE, `r5k2a`), batchItemDir(SINGLE, `r5k2a`)]).toEqual([
+            `${STATE_DIR}/records/chores/runs/r5k2a/result.json`,
+            batchRunDir(SINGLE, `r5k2a`),
+        ]);
+    });
+});
+
+describe(`reading a file an agent may still be writing`, () => {
+    const shape = (value: Record<string, unknown>): { outcome: string } | undefined =>
+        typeof value[`outcome`] === `string` ? { outcome: value[`outcome`] } : undefined;
+
+    it(`reads a well-formed file through the caller's shape`, () => {
+        expect(parseBatchFile(`{"outcome":"acted"}`, shape)).toEqual({ outcome: `acted` });
+    });
+
+    /* All three failures are the same answer — undefined — because one bad directory must not blank a whole
+     * history, and a half-written file is ordinary here rather than exceptional. */
+    it(`skips a file that is truncated, is not an object, or does not fit the shape`, () => {
+        expect([parseBatchFile(`{"outcome":`, shape), parseBatchFile(`"acted"`, shape), parseBatchFile(`{"summary":"x"}`, shape)]).toEqual([
+            undefined,
+            undefined,
+            undefined,
+        ]);
+    });
+
+    it(`does not read null as an object`, () => {
+        expect(parseBatchFile(`null`, shape)).toBeUndefined();
+    });
+});
+
+describe(`what the agent is told`, () => {
+    const clause = batchReportingClause({
+        path: batchResultPath(SINGLE, `r5k2a`),
+        fields: `{"outcome": "acted" | "clean", "summary": "<one or two sentences>"}`,
+        outcomes: `Use "clean" when the findings did not hold up.`,
+    });
+
+    it(`names the exact path the surface will read back`, () => {
+        expect(clause).toContain(batchResultPath(SINGLE, `r5k2a`));
+    });
+
+    /* A turn that concludes there was nothing to do and writes no file is indistinguishable from a turn that
+     * died, and the surface has to show the second as an unknown. */
+    it(`asks for the file even when there was nothing to do`, () => {
+        expect(clause).toContain(`even if you conclude there was nothing to do`);
+    });
+
+    it(`leaves the outcome vocabulary out when the kind has none`, () => {
+        expect(batchReportingClause({ path: `p`, fields: `f` })).not.toContain(`clean`);
+    });
+});
+
+describe(`the turn a run starts`, () => {
+    it(`is always isolated and unattended, which is what registers the fleet entry`, () => {
+        const body = batchTurnBody({ prompt: `do it`, title: `t`, conversationId: `mt-r5k2a` });
+        expect([body[`isolated`], body[`unattended`]]).toEqual([true, true]);
+    });
+
+    it(`caps the title at what the fleet row can show`, () => {
+        expect(String(batchTurnBody({ prompt: `p`, title: `t`.repeat(200), conversationId: `c` })[`title`])).toHaveLength(80);
+    });
+
+    it(`carries a pinned model and its tier when the row's caret chose one`, () => {
+        const body = batchTurnBody({
+            prompt: `p`,
+            title: `t`,
+            conversationId: `c`,
+            pick: { provider: `claude`, model: `opus`, effort: `high` },
+        });
+        expect([body[`agent`], body[`model`], body[`effort`]]).toEqual([`claude`, `opus`, `high`]);
+    });
+
+    /* ABSENT rather than undefined: the body is serialized to JSON and the daemon's fill step reads a missing
+     * key as "the owner's agentRunModels decide", which is not what an explicit null would say. */
+    it(`omits the keys a pick did not pin, rather than sending them empty`, () => {
+        const body = batchTurnBody({ prompt: `p`, title: `t`, conversationId: `c`, pick: { provider: `claude` } });
+        expect(Object.keys(body)).not.toContain(`model`);
+        expect(Object.keys(body)).not.toContain(`effort`);
+    });
+
+    it(`sends no model keys at all when nothing was pinned`, () => {
+        const keys = Object.keys(batchTurnBody({ prompt: `p`, title: `t`, conversationId: `c` }));
+        expect(keys.some((key) => [`agent`, `model`, `effort`].includes(key))).toBe(false);
+    });
+});

package/src/batch-runs.ts

@@ -0,0 +1,181 @@
+import { STATE_DIR } from "@intentic/constants";
+
+/* ONE BATCH RUN ENGINE, for every surface that fans an ISOLATED AGENT TURN out over a set of items and reads
+ * the answers back off disk.
+ *
+ * Three packs had written this separately — acceptance (a run per story), maintenance (a run per chore, per
+ * repository) and documentation (a run per package) — and the three copies agreed on every decision that
+ * matters and drifted on every detail that does not: `SCAN_RUNS` was 10 in one and 30 in another, one minted
+ * run ids with a per-process counter and one without (the one without could collide, and did, the moment a
+ * surface started several runs inside a millisecond), and each spelled the reporting clause its own way, so an
+ * agent's instructions for where to leave its answer depended on which screen started it.
+ *
+ * WHY THE CORE OWNS IT rather than one of them exporting it. A substrate is what other packs fire into, and a
+ * pack can be switched off: a run engine that stops existing because somebody hid a screen is not an engine.
+ * The reverse — a substrate living in one pack — is what produced the three copies, because reaching into
+ * `acceptance` for a run id is a dependency no other pack wants and reinventing it is one afternoon.
+ * `_extensions/README.md` states the rule; this is the second of the four substrates named there.
+ *
+ * WHAT A RUN IS, and the part that is load-bearing rather than incidental:
+ *
+ *  • IT IS BACKED BY FILES, never by a store a pack owns. `run.json` is written before the first turn starts
+ *    and each agent writes its own result beside it. So a run survives archiving the fleet agents, discarding
+ *    them, closing the browser and rebuilding the image, and a browser that was shut when a turn finished picks
+ *    the answer up the next time it opens.
+ *  • ITS CONVERSATION IDS ARE DERIVED, so joining a run to the fleet is a filter over `GET /agents` rather than
+ *    bookkeeping that can drift. This is why none of these surfaces owns session machinery: the worktree, the
+ *    live status, the cost, the transcript and the `/agents/<id>` page all already exist.
+ *  • IT LIVES UNDER `.intentic`, which is outside every repo (the root repo excludes it) and is bound back in
+ *    SHARED for isolated turns, so an agent writing its result from inside its own worktree writes into the
+ *    same tree the browser reads: nothing to land, no git noise.
+ *
+ * The manifest and result SHAPES stay with the packs. A chore's outcome vocabulary and a story's criteria have
+ * nothing to say to each other, and a substrate that tried to own both would be a union that grows a field per
+ * screen. What is here is what all three do identically: where the files go, how the ids are made, how a
+ * half-written file is survived, and what the agent is told about where to leave its answer. */
+
+/* WHERE ONE KIND OF RUN KEEPS ITS DIRECTORIES. Taken as the tail rather than composed from a pack id, because
+ * the three existing layouts are not uniform and rewriting them would orphan every run already on disk:
+ * acceptance keeps runs under `records/artifacts/acceptance`, maintenance under `records/chores/runs`. A path
+ * is a fact about a tree that exists, not a naming opportunity. */
+export interface BatchRunKind {
+    /* The directory holding this kind's run directories, workspace-relative, under the state dir. */
+    readonly runsDir: string;
+    /* The conversation-id prefix, two or three characters. Every conversation this kind starts carries it, so a
+     * prefix filter over `GET /agents` is the join key and not merely a naming convention. */
+    readonly prefix: string;
+    /* How many runs deep anything that READS RESULTS goes. A bound on the walk, not on what can be run: only
+     * recent runs carry news, and a workspace with hundreds of run directories must not spend a request per
+     * item to render a list or light a badge. One number per kind, shared by every reader of that kind, so a
+     * badge's idea of "recent" and a list's can never disagree. */
+    readonly scanRuns: number;
+}
+
+/* The conversation id's own regex is `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$` — it lands in branch names and in
+ * paths — so this is a hard ceiling rather than a style choice. */
+const CONVERSATION_ID_MAX = 64;
+
+/* `r` + a base-36 millisecond, zero-padded, + a per-process counter: sortable, ~10 characters, and readable
+ * enough to match a directory to a moment. The clock is taken from the caller so this stays pure and testable.
+ *
+ * THE PADDING IS WHAT MAKES "SORTABLE" TRUE. Both copies this replaces claimed it and neither had it: a base-36
+ * number is shorter when it is smaller, so a plain `toString(36)` sorts `r1a` after `rzz` the moment two ids
+ * straddle a digit boundary. Today's milliseconds are all eight digits so nothing has gone wrong yet, and
+ * nothing will until 2059 — which is exactly the kind of latent boundary that is cheap to remove now and
+ * expensive to find later. Padded to the same width, the ids on disk are the length they already were.
+ *
+ * THE COUNTER IS NOT OPTIONAL, the other drift worth naming. A surface that fans out over items can get away
+ * without one, because its ids differ by item; a surface where one run IS one item cannot, and "run this chore
+ * in every repository" starts several inside the same millisecond. Both kinds share this function, so the
+ * safe answer is the only answer, and it costs the id one character. */
+const TIME_DIGITS = 8;
+let sequence = 0;
+export const batchRunIdAt = (epochMs: number): string => `r${epochMs.toString(36).padStart(TIME_DIGITS, `0`)}${(sequence++).toString(36)}`;
+
+/* The fleet conversation id for one item of one run, or for a run that is a single item (omit `item`).
+ *
+ * THE RUN ID SURVIVES TRUNCATION and the item is what gets cut, because the run id is how a card is attributed
+ * back to its run: lose that and a finished turn belongs to nothing. Callers that fan out must already have
+ * made their item slugs unique by suffixing, and the suffix sits at the end — exactly where the cut lands — so
+ * uniqueness holds only while the cut leaves it. In practice nothing is close: slugs are capped at 40 and run
+ * ids are ~10, well inside 64. A trailing separator left by the cut is trimmed, because `xt-r5k2-` is a
+ * conversation id the regex above would refuse. */
+export const batchConversationId = (kind: BatchRunKind, runId: string, item?: string): string =>
+    `${kind.prefix}-${runId}${item === undefined ? `` : `-${item}`}`.slice(0, CONVERSATION_ID_MAX).replace(/[-_]+$/u, ``);
+
+// Every conversation one kind starts, for the prefix filter over `GET /agents` that joins a run to the fleet.
+export const batchRunPrefix = (kind: BatchRunKind): string => `${kind.prefix}-`;
+
+// The directory holding one kind's run directories, workspace-relative. What a listing is asked for.
+export const batchRunsDir = (kind: BatchRunKind): string => `${STATE_DIR}/${kind.runsDir}`;
+export const batchRunDir = (kind: BatchRunKind, runId: string): string => `${batchRunsDir(kind)}/${runId}`;
+export const batchRunManifestPath = (kind: BatchRunKind, runId: string): string => `${batchRunDir(kind, runId)}/run.json`;
+
+/* Where one item of a run leaves its files. A run whose items are the run itself (`item` omitted) writes
+ * straight into the run directory, which is what maintenance already does and what keeps its `result.json`
+ * beside its `run.json` rather than one pointless level down. */
+export const batchItemDir = (kind: BatchRunKind, runId: string, item?: string): string =>
+    item === undefined ? batchRunDir(kind, runId) : `${batchRunDir(kind, runId)}/${item}`;
+export const batchResultPath = (kind: BatchRunKind, runId: string, item?: string): string => `${batchItemDir(kind, runId, item)}/result.json`;
+
+/* A FILE THAT IS HALF-WRITTEN, or written by a build whose shape has since changed, IS SKIPPED rather than
+ * thrown on. One bad directory must not blank a whole history, and a run directory is written by an agent
+ * mid-turn, so reading one that is not finished being written is ordinary rather than exceptional.
+ *
+ * The caller supplies the shape check, because the shape is the pack's. This owns only the two failure modes
+ * every reader shares: text that is not JSON, and JSON that is not an object. */
+export const parseBatchFile = <T>(text: string, shape: (value: Record<string, unknown>) => T | undefined): T | undefined => {
+    try {
+        const parsed: unknown = JSON.parse(text);
+        return typeof parsed !== `object` || parsed === null ? undefined : shape(parsed as Record<string, unknown>);
+    } catch {
+        return undefined;
+    }
+};
+
+/* WHAT THE AGENT IS TOLD ABOUT WHERE TO LEAVE ITS ANSWER, appended to whatever prompt the pack composed.
+ *
+ * WHY THE AGENT WRITES A FILE AND NOT A ROUTE. A ledger is a daemon route, and reaching it from a turn would
+ * mean handing the agent a token and a client it needs for nothing else. Writing one small JSON file is
+ * something every agent can already do, and the surface promotes finished runs when it next sees them. The
+ * promotion is idempotent and re-runs on every poll, so nothing is lost by not being watched.
+ *
+ * `outcomes` is the pack's vocabulary and is spelled out in full, because a closed set is what lets a surface
+ * debounce without hiding anything: an agent that verified some findings and concluded they were false
+ * positives has to be able to SAY so, or the next poll starts the same turn again forever. Pass the
+ * explanations with the words — a model that reads an outcome as an admission of having done nothing useful
+ * will avoid it and report something else, and the surface never goes quiet.
+ *
+ * The closing line is not decoration. A turn that concludes there was nothing to do and writes no file is
+ * indistinguishable from a turn that died, and the surface has to show the second as an unknown. */
+export const batchReportingClause = (params: {
+    readonly path: string;
+    readonly fields: string;
+    readonly outcomes?: string | undefined;
+}): string =>
+    [
+        `When you are finished, write your conclusion to ${params.path} as JSON:`,
+        params.fields,
+        ...(params.outcomes === undefined ? [] : [params.outcomes]),
+        `Write that file even if you conclude there was nothing to do.`,
+    ].join(`\n\n`);
+
+/* THE BODY OF THE `POST /agent` THAT STARTS ONE ITEM, so the flag combination that makes a run a run is decided
+ * once. `isolated: true` with a conversationId is the shape (and the only shape) that registers a fleet entry,
+ * which is why none of these packs owns session machinery; `unattended: true` is what the turn IS — started by
+ * a row rather than by a person at a composer — and it is what makes the daemon answer with the owner's
+ * `agentRunModels` unless the caller pinned a model on the row's caret, in which case the pick rides along and
+ * the daemon's fill step leaves it alone.
+ *
+ * PERMISSIONS AND ISOLATION ARE THE CALLER'S, deliberately. They are the two decisions that differ by kind and
+ * both are about safety rather than plumbing: an acceptance test that parks on a permission card is a test that
+ * never finishes, so that surface trades the prompt away; a maintenance chore is different in kind — nobody is
+ * waiting on it, it may take until tomorrow, and a sweep that can answer its own permission prompts is exactly
+ * the thing an owner would want to have been asked about. A default here would decide that for both. */
+export interface BatchTurnPick {
+    readonly provider: string;
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
+
+export const batchTurnBody = (params: {
+    readonly prompt: string;
+    readonly title: string;
+    readonly conversationId: string;
+    readonly pick?: BatchTurnPick | undefined;
+    readonly extra?: Readonly<Record<string, unknown>> | undefined;
+}): Record<string, unknown> => ({
+    prompt: params.prompt,
+    title: params.title.slice(0, 80),
+    conversationId: params.conversationId,
+    isolated: true,
+    unattended: true,
+    ...(params.pick === undefined
+        ? {}
+        : {
+              agent: params.pick.provider,
+              ...(params.pick.model === undefined ? {} : { model: params.pick.model }),
+              ...(params.pick.effort === undefined ? {} : { effort: params.pick.effort }),
+          }),
+    ...params.extra,
+});