@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/models/provider-specs.ts

@@ -0,0 +1,272 @@
+import type { ProviderBrand } from "@intentic/constants";
+import { type AgentCapabilities, CLAUDE_CODE, CODEX, CURSOR, OPENCODE, OPENCODE_GEMINI } from "./agent-runtimes.js";
+
+// Every fact about a provider more than one surface needs, one row each, replacing lists that drifted out of sync.
+// `access` (cost) and `auth` (connection) stay separate: conflating them mis-describes Z.ai, a prepaid plan spent
+// through a minted key. Adding a provider is one row here plus one registry line; everything else derives.
+
+// What a provider costs to unlock: `free` is a real tier (Google's channel needs only a sign-in), and there is
+// deliberately no `key` rung, since a raw API key against your own gateway is an `endpoint` capability, not a row here.
+export type AccessKind = "free" | "subscription";
+
+export interface ProviderAccess {
+    readonly kind: AccessKind;
+    // What the user connects, named the way its vendor names it: the noun every connect prompt uses.
+    readonly requirement: string;
+    // What connecting it lets them run, for the connect gate's one-line pitch.
+    readonly runs: string;
+}
+
+// Cost order at the margin (free, subscription); not AccessKind's own order, which isn't a runtime fact.
+export const ACCESS_COST: Record<AccessKind, number> = { free: 0, subscription: 1 };
+
+// How a credential for this provider is obtained and held; every surface branches on this instead of the provider's
+// name:
+// - oauth: the daemon runs the sign-in and stores the tokens itself
+// - translator: the bundled CLIProxyAPI holds a subscription OAuth and re-serves it behind an Anthropic endpoint
+// - minted: the daemon mints the vendor's own API key from a sign-in and stores that
+export type ProviderAuth =
+    | { readonly kind: "oauth" }
+    | { readonly kind: "translator"; readonly cliProxy: string }
+    | { readonly kind: "minted"; readonly variants: readonly MintedVariant[] };
+
+// One identity a minted provider signs into: a vendor (Z.ai) can sell one product through separate estates whose hosts
+// and keys are not interchangeable. Bases live per-variant, so a turn dials the host that minted its key.
+export interface MintedVariant {
+    // The stored account's record of where it came from, and what login/start names; never shown.
+    readonly id: string;
+    // What the connect row's estate control calls it, in the vendor's own words.
+    readonly label: string;
+    // How this sign-in ends, deciding only the connect panel's shape:
+    // - device: the daemon polls the vendor to completion, nothing to paste back
+    // - redirect: the vendor sends the browser to a loopback address, and the user brings the URL back
+    readonly flow: "device" | "redirect";
+    // ANTHROPIC_BASE_URL for a turn minted here; no version segment, the harness appends /v1/messages itself.
+    readonly anthropicBase: string;
+    // Where this estate's catalog is read from: an OpenAI-compatible root, with its version segment.
+    readonly catalogBase: string;
+}
+
+export interface ProviderSpec {
+    // The wire id, and a reserved capability id: an installed agent capability may not reuse one.
+    readonly id: string;
+    // What the picker, the rail and the account tabs call it.
+    readonly label: string;
+    // Whose allowance a turn spends, as a sentence subject; a routed turn can spend a quota neither field names.
+    readonly vendor: string;
+    // Where account rows are filed under (tab, picker section, connect chip); differs from vendor only for Grok.
+    readonly accountLabel: string;
+    // Where the sign-in happens, not the provider's product name: what a user leaving the page should recognize.
+    readonly destination: string;
+    readonly brand: ProviderBrand;
+    readonly access: ProviderAccess;
+    readonly auth: ProviderAuth;
+    // Whether a plan-limit reading is obtainable, so a blank meter is told apart from a plan that publishes none.
+    readonly planLimits: boolean;
+    // The two runtimes this provider runs on; equal records here mean the harness is not a real choice for it.
+    readonly runtimes: { readonly native: AgentCapabilities; readonly claudeCode: AgentCapabilities };
+}
+
+// satisfies checks each row's shape; as const keeps ids/auth kinds literal, so NativeProvider stays a union.
+export const PROVIDER_SPECS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        vendor: "Claude",
+        accountLabel: "Claude",
+        destination: "Anthropic",
+        brand: "claude",
+        access: { kind: "subscription", requirement: "Claude subscription", runs: "Claude Code" },
+        auth: { kind: "oauth" },
+        planLimits: true,
+        // Claude has no second runtime: the harness axis is not a choice here.
+        runtimes: { native: CLAUDE_CODE, claudeCode: CLAUDE_CODE },
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        vendor: "ChatGPT",
+        accountLabel: "ChatGPT",
+        destination: "ChatGPT",
+        brand: "codex",
+        access: { kind: "subscription", requirement: "ChatGPT subscription", runs: "Codex" },
+        auth: { kind: "translator", cliProxy: "codex" },
+        planLimits: true,
+        runtimes: { native: CODEX, claudeCode: CLAUDE_CODE },
+    },
+    {
+        id: "grok",
+        label: "Grok",
+        vendor: "xAI",
+        accountLabel: "Grok",
+        destination: "x.ai",
+        brand: "grok",
+        access: { kind: "subscription", requirement: "SuperGrok subscription", runs: "Grok" },
+        // The app says grok, CLIProxyAPI says xai; Grok alone also runs natively, not just through the translator.
+        auth: { kind: "translator", cliProxy: "xai" },
+        planLimits: false,
+        runtimes: { native: OPENCODE, claudeCode: CLAUDE_CODE },
+    },
+    {
+        id: "kimi",
+        label: "Kimi Code",
+        vendor: "Kimi Code",
+        accountLabel: "Kimi Code",
+        destination: "Kimi Code",
+        brand: "kimi",
+        access: { kind: "subscription", requirement: "Kimi Code subscription", runs: "Kimi Code" },
+        auth: { kind: "translator", cliProxy: "kimi" },
+        planLimits: true,
+        // Kimi has no native runtime: it exists only under the Claude Code loop, on both harnesses.
+        runtimes: { native: CLAUDE_CODE, claudeCode: CLAUDE_CODE },
+    },
+    {
+        // Labelled for the account (Google), not the model family: this channel vends Claude and GPT-OSS beside Gemini.
+        id: "gemini",
+        label: "Google",
+        vendor: "Google",
+        accountLabel: "Google",
+        destination: "Google",
+        brand: "gemini",
+        access: { kind: "free", requirement: "Google sign-in", runs: "Gemini, Claude and GPT-OSS under Claude Code" },
+        // antigravity is Google's own agent product, the name CLIProxyAPI files this credential under.
+        auth: { kind: "translator", cliProxy: "antigravity" },
+        planLimits: true,
+        // The only routed provider that ignores harness: Google refuses any request announcing the Claude Code loop.
+        runtimes: { native: OPENCODE_GEMINI, claudeCode: OPENCODE_GEMINI },
+    },
+    {
+        // Cursor's own runtime via Anysphere's SDK; labelled for the account since it vends several vendors' models.
+        id: "cursor",
+        label: "Cursor",
+        vendor: "Cursor",
+        accountLabel: "Cursor",
+        destination: "Cursor",
+        brand: "cursor",
+        // Requirement names the plan, not the account: a free Cursor sign-in works but cannot run a turn here.
+        access: { kind: "subscription", requirement: "Cursor Pro subscription", runs: "Cursor Agent" },
+        auth: { kind: "oauth" },
+        planLimits: false,
+        // Cursor ignores harness too: there is no route to it but its own SDK.
+        runtimes: { native: CURSOR, claudeCode: CURSOR },
+    },
+    // The two minted providers need no new runtime or translator hop: each has its own Anthropic Messages endpoint.
+    {
+        id: "meta",
+        label: "Meta",
+        vendor: "Meta",
+        accountLabel: "Meta",
+        destination: "Meta",
+        brand: "meta",
+        // A subscription like the rest: the device sign-in mints a plan key, and the plan is what a turn spends.
+        access: { kind: "subscription", requirement: "Muse Code subscription", runs: "Muse Spark under Claude Code" },
+        auth: {
+            kind: "minted",
+            // One estate, no choice to offer; the id still exists since a stored account records which variant minted
+            // it.
+            variants: [
+                {
+                    id: "meta",
+                    label: "Meta",
+                    // The textbook device flow (RFC 8628): a code read off the card, and a poll that returns nothing
+                    // here.
+                    flow: "device",
+                    // No version segment here: /v1/messages is appended by the harness, beside the catalog's OpenAI
+                    // surface.
+                    anthropicBase: "https://api.meta.ai",
+                    catalogBase: "https://api.meta.ai/v1",
+                },
+            ],
+        },
+        // No quota surface a minted key can read: the row shows no meter and says so, not an empty one reading as zero.
+        planLimits: false,
+        runtimes: { native: CLAUDE_CODE, claudeCode: CLAUDE_CODE },
+    },
+    {
+        id: "zai",
+        label: "Z.ai",
+        vendor: "Z.ai",
+        accountLabel: "Z.ai",
+        destination: "Z.ai",
+        brand: "zai",
+        // A prepaid GLM Coding Plan with a watched quota; the sign-in mints its own key, so requirement names the plan.
+        access: { kind: "subscription", requirement: "Z.ai GLM Coding Plan", runs: "GLM under Claude Code" },
+        auth: {
+            kind: "minted",
+            // Two estates, each its own base (a key from one is refused by the other); root is the coding-plan path.
+            variants: [
+                {
+                    id: "zai",
+                    // Cased as the vendor cases it, matching how the row itself is titled elsewhere on screen.
+                    label: "Z.ai international",
+                    // zcode.z.ai mediates the callback itself: the daemon polls it, nothing dead-ends in the user's
+                    // browser.
+                    flow: "device",
+                    anthropicBase: "https://api.z.ai/api/anthropic",
+                    catalogBase: "https://api.z.ai/api/coding/paas/v4",
+                },
+                {
+                    id: "bigmodel",
+                    label: "BigModel (中国大陆)",
+                    // BigModel refuses that callback; a loopback redirect dead-ends the page, and the user brings the
+                    // grant back.
+                    flow: "redirect",
+                    anthropicBase: "https://open.bigmodel.cn/api/anthropic",
+                    catalogBase: "https://open.bigmodel.cn/api/coding/paas/v4",
+                },
+            ],
+        },
+        planLimits: false,
+        runtimes: { native: CLAUDE_CODE, claudeCode: CLAUDE_CODE },
+    },
+] as const satisfies readonly ProviderSpec[];
+
+type Spec = (typeof PROVIDER_SPECS)[number];
+
+// The agent runtimes the daemon can serve; a native id is reserved, `endpoint/<id>` or any other value names an
+// installed capability instead. Derived from the table and a union of six names, so the wire vocabulary can't drift.
+export type NativeProvider = Spec["id"];
+export const NATIVE_PROVIDERS: readonly NativeProvider[] = PROVIDER_SPECS.map((spec) => spec.id);
+
+const BY_ID = new Map<string, ProviderSpec>(PROVIDER_SPECS.map((spec) => [spec.id, spec] as const));
+
+// The row for a provider id, or nothing for an ACP agent, an endpoint, or a typo: the one lookup every table and
+// surface goes through.
+export const providerSpec = (provider: string): ProviderSpec | undefined => BY_ID.get(provider);
+
+// Providers whose model runs under Claude Code through the bundled translator (CLIProxyAPI); claude is absent, native
+// Anthropic OAuth serves it directly. Narrowed off the auth kind so tables built on this move with it.
+export type TranslatorProvider = Extract<Spec, { auth: { kind: "translator" } }>["id"];
+export const TRANSLATOR_PROVIDERS: readonly TranslatorProvider[] = PROVIDER_SPECS.filter(
+    (spec): spec is Extract<Spec, { auth: { kind: "translator" } }> => spec.auth.kind === "translator",
+).map((spec) => spec.id);
+
+// Providers whose sign-in mints the vendor's own API key, served straight off that vendor's own Anthropic Messages
+// endpoint.
+export type MintedProvider = Extract<Spec, { auth: { kind: "minted" } }>["id"];
+export const MINTED_PROVIDERS: readonly MintedProvider[] = PROVIDER_SPECS.filter(
+    (spec): spec is Extract<Spec, { auth: { kind: "minted" } }> => spec.auth.kind === "minted",
+).map((spec) => spec.id);
+
+// This provider's CLIProxyAPI id, where it has one; not always ours (grok/xai, gemini/antigravity).
+export const cliProxyIdOf = (provider: string): string | undefined => {
+    const auth = providerSpec(provider)?.auth;
+    return auth?.kind === "translator" ? auth.cliProxy : undefined;
+};
+
+// Every estate a minted provider can sign into, in connect-row order, or nothing if it is not minted. The head is the
+// default a variant-less login/start gets.
+export const mintedVariants = (provider: string): readonly MintedVariant[] | undefined => {
+    const auth = providerSpec(provider)?.auth;
+    return auth?.kind === "minted" ? auth.variants : undefined;
+};
+
+// The whole estate (bases and flow together), so a base is never read without its sibling. An absent id defaults to the
+// head; a name matching no variant is undefined, not the default, so a lost variant surfaces honestly.
+export const mintedVariant = (provider: string, variant?: string): MintedVariant | undefined => {
+    const variants = mintedVariants(provider);
+    if (variants === undefined) {
+        return undefined;
+    }
+    return variant === undefined || variant === "" ? variants[0] : variants.find((entry) => entry.id === variant);
+};

package/src/policy/approvals-execution.ts

@@ -0,0 +1,58 @@
+// A held item is dated this far out (an ordinary scheduledAt), to catch a mis-click before it's public.
+export const APPROVAL_HOLD_MS = 60_000;
+
+// Platforms reachable by a stored API credential alone; the rest need a turn to drive the logged-in browser.
+export const DIRECT_PUBLISH_PLATFORMS: ReadonlySet<string> = new Set(["discord"]);
+
+// The workspace-relative directory both prompts below name, spelled once.
+const APPROVALS_DIR = ".intentic/config/approvals";
+
+// Status bookkeeping every executing turn is told, identical across kinds so the queue reads one shape back.
+const WRITE_BACK = [
+    `Before you act on one, set its "status" to "running" and "startedAt" to the epoch ms, so a turn that dies`,
+    `here cannot do it twice. When it is done, set "status":"done" plus "finishedAt" (epoch ms) and, where`,
+    `there is one, "result": the post's URL, a confirmation number, whatever a person would want to go and`,
+    `look at. If it failed, set "status":"failed" plus an "error" saying what went wrong in plain words the`,
+    `owner can act on, then move to the next one instead of retrying in a loop.`,
+];
+
+// Names the files directly rather than saying "go look": the daemon already decided what's due, and a re-deriving turn
+// could disagree. Writes the outcome back into the same file, since that's where the queue reads it.
+export const publishTurnPrompt = (posts: readonly { readonly id: string; readonly platform: string }[]): string =>
+    [
+        `Publish these approved posts, which are due now. They live in ${APPROVALS_DIR}/, one JSON file each:`,
+        ``,
+        ...posts.map((post) => `- ${post.id}.json (${post.platform})`),
+        ``,
+        `Take them ONE AT A TIME, and for each:`,
+        `1. Read the file. ${WRITE_BACK[0]}`,
+        `   ${WRITE_BACK[1]}`,
+        `2. Post exactly its "content": with its "title", "target" and "media", using that platform's skill.`,
+        `   A "target" that is a URL means this post is a REPLY to whatever is at it: open that exact URL and`,
+        `   reply where it lands. On reddit a comment permalink (.../comments/<post>/<slug>/<comment>/) has to`,
+        `   nest under that comment rather than becoming a new top-level comment on the thread.`,
+        `3. ${WRITE_BACK[2]} ${WRITE_BACK[3]}`,
+        `   ${WRITE_BACK[4]}`,
+        ``,
+        `Never rewrite the content: the owner approved these exact words. Never touch a file not listed above.`,
+    ].join(`\n`);
+
+// Same discipline as a publish turn, but the work comes from the file, written by the agent that proposed it since this
+// turn has none of that conversation. Approval covers exactly summary/details; anything more is failed, not improvised.
+export const actionTurnPrompt = (actions: readonly { readonly id: string; readonly summary: string }[]): string =>
+    [
+        `Carry out these approved actions, which are due now. They live in ${APPROVALS_DIR}/, one JSON file each:`,
+        ``,
+        ...actions.map((action) => `- ${action.id}.json: ${action.summary}`),
+        ``,
+        `Take them ONE AT A TIME, and for each:`,
+        `1. Read the file. ${WRITE_BACK[0]}`,
+        `   ${WRITE_BACK[1]}`,
+        `2. Do exactly what its "instructions" say. The owner approved what "summary" and "details" describe and`,
+        `   nothing more: if carrying it out would need something they do not say, stop and fail it with that`,
+        `   reason rather than improvising.`,
+        `3. ${WRITE_BACK[2]} ${WRITE_BACK[3]}`,
+        `   ${WRITE_BACK[4]}`,
+        ``,
+        `Never touch a file not listed above.`,
+    ].join(`\n`);

package/src/{batch-runs.test.ts → policy/batch-runs.test.ts}

@@ -1,8 +1,7 @@
 import { STATE_DIR } from "@intentic/constants";
 import { describe, expect, it } from "vitest";
 
-// The job a batch pack starts, which decides whose model list pays for it. Maintenance stands in for all of
-// them: what `batchTurnBody` owes is that the role it is handed reaches the turn, not which one it was.
+// Stands in for any role: what's tested is that the role reaches the turn, not which one it is.
 const ROLE = `maintenance-chore` as const;
 import {
     type BatchRunKind,
@@ -17,10 +16,9 @@ import {
     batchTurnBody,
     parseBatchFile,
 } from "./batch-runs.js";
-import { ConversationIdSchema } from "./schemas/agent.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`.
+// The two real layouts this fits: one fans out over items, one where a run is the item.
 const FANNED: BatchRunKind = { runsDir: `records/artifacts/acceptance`, prefix: `xt`, scanRuns: 10 };
 const SINGLE: BatchRunKind = { runsDir: `records/chores/runs`, prefix: `mt`, scanRuns: 30 };
 
@@ -31,15 +29,12 @@ describe(`batch run ids`, () => {
         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. */
+    // Must survive a digit boundary: unpadded toString(36) sorts the shorter string first, not the smaller number.
     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);
@@ -56,15 +51,12 @@ describe(`batch conversation ids`, () => {
         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`);
@@ -81,8 +73,6 @@ describe(`where a run keeps its files`, () => {
         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`,
@@ -99,8 +89,6 @@ describe(`reading a file an agent may still be writing`, () => {
         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,
@@ -125,8 +113,6 @@ describe(`what the agent is told`, () => {
         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`);
     });
@@ -157,8 +143,6 @@ describe(`the turn a run starts`, () => {
         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 list for this job decides", 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`, role: ROLE, pick: { provider: `claude` } });
         expect(Object.keys(body)).not.toContain(`model`);

package/src/policy/batch-runs.ts

@@ -0,0 +1,137 @@
+import { STATE_DIR } from "@intentic/constants";
+import type { ModelRole } from "../models/model-roles.js";
+
+// One batch run engine for every surface that fans an isolated agent turn out over items and reads results off disk.
+// Backed by files, not a pack's own store, with derived conversation ids that join the fleet via a GET /agents filter,
+// under .intentic. Manifest and result shapes stay with the packs; this owns only what all three need alike.
+
+// Where one kind of run keeps its directories: the tail, not composed from a pack id, since the existing on-disk
+// layouts (acceptance vs maintenance) are not uniform and rewriting them would orphan runs.
+export interface BatchRunKind {
+    /* The directory holding this kind's run directories, workspace-relative, under the state dir. */
+    readonly runsDir: string;
+    // The conversation-id prefix (2-3 chars); every conversation this kind starts carries it as the join key.
+    readonly prefix: string;
+    // How many runs deep a results reader goes; one shared number so a badge and a list never disagree on "recent".
+    readonly scanRuns: number;
+}
+
+// Hard ceiling from the conversation id's own regex (it lands in branch names and paths), not a style choice.
+const CONVERSATION_ID_MAX = 64;
+
+// `r` + a zero-padded base-36 millisecond + a per-process counter: padding keeps it sortable across a digit boundary,
+// and the counter is needed since a single-item-per-run surface can mint several within one millisecond.
+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 a run (or a single-item run, omitting item). The run id survives
+// truncation, since that's what attributes a card back to its run; a trailing separator left by the cut is trimmed.
+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; an item-less run (item omitted) writes straight into the run directory,
+// keeping result.json beside run.json rather than one 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 half-written file, or one from before the shape changed, is skipped rather than thrown on: reading a run mid-write
+// is ordinary here. The caller supplies the shape check; this owns only invalid or non-object JSON.
+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 `runRole` is which of those rows, so the daemon answers
+ * with the owner's list FOR THAT JOB (model-roles.ts) 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. */
+/* WHAT THE CARET ON THE RUN BUTTON CHOSE, in the shell's own vocabulary (`provider`; the turn calls it `agent`).
+ * Every field but the provider is optional and absent means absent: the turn goes out without it and the model's
+ * own default answers. All of them travel, because all of them are things the picker can now set and each is a
+ * different price — a run re-pointed at a frontier model but not at the tier, the loop or the account it was
+ * pinned under is not the run the reader configured. */
+export interface BatchTurnPick {
+    readonly provider: string;
+    readonly model?: string | undefined;
+    readonly account?: string | undefined;
+    readonly harness?: string | undefined;
+    readonly effort?: string | undefined;
+    readonly thinking?: boolean | undefined;
+    readonly fast?: boolean | undefined;
+}
+
+// The same fields under the names a turn uses. Its own function so the body builder below stays one readable
+// object literal rather than seven nested conditionals.
+const runPickFields = (pick: BatchTurnPick): Record<string, unknown> => ({
+    agent: pick.provider,
+    ...(pick.model === undefined ? {} : { model: pick.model }),
+    ...(pick.account === undefined ? {} : { account: pick.account }),
+    ...(pick.harness === undefined ? {} : { harness: pick.harness }),
+    ...(pick.effort === undefined ? {} : { effort: pick.effort }),
+    ...(pick.thinking === undefined ? {} : { thinking: pick.thinking }),
+    ...(pick.fast === undefined ? {} : { fast: pick.fast }),
+});
+
+export const batchTurnBody = (params: {
+    readonly prompt: string;
+    readonly title: string;
+    readonly conversationId: string;
+    // Which job this is, and so which model list pays; required, so a pack can't silently inherit another's budget.
+    readonly role: ModelRole;
+    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,
+    runRole: params.role,
+    ...(params.pick === undefined ? {} : runPickFields(params.pick)),
+    ...params.extra,
+});

package/src/policy/capability-secrets.ts

@@ -0,0 +1,5 @@
+// Marker for "leave the stored value alone"; distinct from empty or missing so a bypassed read fails loudly.
+export const VAULTED = "__intentic_vaulted__";
+
+/** Whether a value is the marker rather than a real credential. */
+export const isVaulted = (value: unknown): boolean => value === VAULTED;

package/src/{card-status.ts → policy/card-status.ts}

@@ -1,19 +1,14 @@
-import type { CardField, TranscriptCards, TranscriptRow } from "./events.js";
-import type { AgentReply } from "./schemas/plan-limits.js";
+import type { CardField, TranscriptCards, TranscriptRow } from "../events/transcript.js";
+import type { AgentReply } from "../schemas/plan-limits.js";
 
-/* HOW A REPLY SETTLES THE CARD IT ANSWERS, the one derivation, used by the fold when the `resolved` frame lands
- * (transcript-fold.ts) and by a chat freezing its own card the instant its answer is accepted, before that
- * frame comes back. Two callers, one rule, which is what keeps "answered" looking the same on the window that
- * clicked and on every window that only watched.
- *
- * No reply is nobody answering: the turn was stopped, or died under the card, which is not a decision, so every
- * card reads `cancelled`. A reply of the wrong kind cannot reach a card of another, the requestId is what
- * matched it, and reads as unanswered rather than inventing a decision. */
+// How a reply settles the card it answers: one rule used both by the fold and by a chat freezing its own card
+// optimistically before the frame returns. No reply (turn stopped or died) reads as cancelled for every card; a reply
+// of the wrong kind cannot settle a card of another, since requestId is what matches them.
 type Cards = { -readonly [K in CardField]?: TranscriptRow[K] };
 
 export const settledCards = (cards: TranscriptCards, reply: AgentReply | undefined): TranscriptCards => {
     const out: Cards = {};
-    const { plan, question, permission, browserHelp, terminalHelp, serviceOffer, capabilityOffer, paymentOffer, credentialOffer } = cards;
+    const { plan, question, permission, browserHelp, terminalHelp, capabilityOffer, paymentOffer, credentialOffer } = cards;
     if (plan !== undefined) {
         out.plan = { ...plan, status: reply?.kind !== "plan" ? "cancelled" : reply.approve ? "approved" : "rejected" };
     }
@@ -44,26 +39,18 @@ export const settledCards = (cards: TranscriptCards, reply: AgentReply | undefin
     if (terminalHelp !== undefined) {
         out.terminalHelp = { ...terminalHelp, status: reply?.kind !== "terminal_help" ? "cancelled" : reply.helped ? "helped" : "declined" };
     }
-    if (serviceOffer !== undefined) {
-        out.serviceOffer = { ...serviceOffer, status: reply?.kind !== "service_offer" ? "cancelled" : reply.approve ? "approved" : "skipped" };
-    }
-    // A yes settles the DECISION, not the ask: the owner is now setting the capability up, so the card moves to
-    // `connecting` and stays there until the capability_outcome frame says how the setup ended.
+    // A yes settles the decision, not the ask: the card moves to connecting until capability_outcome resolves it.
     if (capabilityOffer !== undefined) {
         out.capabilityOffer = {
             ...capabilityOffer,
             status: reply?.kind !== "capability_offer" ? "cancelled" : reply.connect ? "connecting" : "skipped",
         };
     }
-    // A yes settles the decision; whether the money actually moved is the payment_receipt frame's to say.
+    // A yes settles the decision; whether the money moved is the payment_receipt frame's to say.
     if (paymentOffer !== undefined) {
         out.paymentOffer = { ...paymentOffer, status: reply?.kind !== "payment_offer" ? "cancelled" : reply.approve ? "approved" : "skipped" };
     }
-    /* A yes settles the decision; WHO decided is the credential_receipt frame's to say, because only the
-     * daemon knows it — the reply carries no name, the identity was verified off the request that delivered
-     * it. A reply that reaches this derivation at all is one the daemon already accepted from an approver: a
-     * click from anybody else is refused before the card is settled, so it never gets here and the card stays
-     * pending. */
+    // A yes settles the decision; who decided is the credential_receipt frame's, since only the daemon knows.
     if (credentialOffer !== undefined) {
         out.credentialOffer = {
             ...credentialOffer,
@@ -73,9 +60,8 @@ export const settledCards = (cards: TranscriptCards, reply: AgentReply | undefin
     return out;
 };
 
-/* The same cards with every one still `pending` frozen as `cancelled`: the turn ended out from under the ask
- * (a Stop, a death, a failure) and nobody decided anything. Returns the SAME object when nothing was pending,
- * so a caller can tell a row that changed from one that did not. */
+// Freezes every still-pending card as cancelled: the turn ended (stopped, died, failed) before anyone decided. Returns
+// the same object when nothing was pending, so a caller can tell a changed row from an unchanged one.
 export const cancelledCards = (cards: TranscriptCards): TranscriptCards => {
     const out: Cards = {};
     let changed = false;
@@ -85,7 +71,6 @@ export const cancelledCards = (cards: TranscriptCards): TranscriptCards => {
         "permission",
         "browserHelp",
         "terminalHelp",
-        "serviceOffer",
         "capabilityOffer",
         "paymentOffer",
         "credentialOffer",