@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/model-pins.ts

@@ -1,183 +0,0 @@
-import { accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js";
-import { ACCESS_COST } from "./provider-specs.js";
-import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
-import { type ModelRole, modelRole } from "./model-roles.js";
-import type { AgentProvider, ModelPin } from "./schemas/agent.js";
-
-/* WHICH MODELS A ROLE MAY RUN, IN THE ORDER TO TRY THEM. One resolver over every list in
- * settings.modelRoles, and the browser and the daemon both read it.
- *
- * IT IS AN ORDER, NOT A MODEL, and that is the shape of every list this file answers for. A single pick is a
- * single point of failure: the account it names spends its allowance on the chat all morning, and the role
- * fails on a limit for the rest of the day while three other connected providers sit idle. So a setting is a
- * LIST read top to bottom, this hands back the whole ladder, and the caller walks it until one answers. Nothing
- * here decides WHICH failures are worth stepping over — only the runner has made the call and seen it fail —
- * this side says what the running order is.
- *
- * THE RULE LIVES IN THE CONTRACT because both sides need the same answer for different jobs: the daemon runs
- * the model, and the browser has to NAME it, in the settings row's "Auto: …" line, before anything has run. Two
- * implementations would drift precisely where it matters most, since a row promising Haiku while the daemon
- * bills Opus is worse than no row at all.
- *
- * WHAT AN EMPTY LIST MEANS IS THE ROLE'S OWN ANSWER (model-roles.ts): a `helper` role derives the Auto ladder
- * from whatever is connected, a `run` role resolves to nothing and lets the caller's floor answer. That fork
- * used to be two near-identical files; it is one line here because it was always one difference. */
-
-/* One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
- *
- * ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
- * own model, so there is no rung to point it at. `endpoint/<id>` providers ARE, and have to be: their models
- * appear in the same picker the settings rows build their options from, so a pin naming one has to hold rather
- * than fall silently back to Auto and spend an account the user was deliberately steering away from. */
-export interface ModelSource {
-    // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union. Auto's
-    // ranking degrades gracefully for one, costOf falls to the metered rung and an id with no tier word is
-    // UNRANKED, which is genuine last place, so an endpoint effectively only wins Auto when nothing else is
-    // connected, while a PIN on one holds. Both are the right answers: what a turn on someone's own model server
-    // costs is not a fact this repo can know, so it is not one Auto should be asserting.
-    readonly provider: AgentProvider;
-    // The same connection predicate every other surface gates on (access.ts web-side, the daemon's own account
-    // stores daemon-side). A catalog is never empty by construction, so "has rows" says nothing about "can send".
-    readonly ready: boolean;
-    readonly models: readonly string[];
-}
-
-export interface ModelChoice {
-    readonly provider: AgentProvider;
-    readonly model: string;
-}
-
-// A (provider, model) pair on the wire: `${provider}:${modelId}`, the same key shape the model picker mints for
-// its entries (PickerEntry.key). Every role list stores PINS rather than these keys — an entry says how it runs
-// as well as which model it is — but the key is still how two entries are compared, how a role list dedupes,
-// and how `autoFastModels` (which pins no knobs, see its own note in settings.ts) is stored.
-export const modelPinKey = (choice: ModelChoice): string => `${choice.provider}:${choice.model}`;
-
-/* Split on the FIRST colon only: a provider id never contains one and a model id might. Exported because
- * `autoFastModels` stores these keys, and because a session composed from a pin travels as one
- * (composeSession). */
-export const parsePinned = (pinned: string): ModelChoice | undefined => {
-    const separator = pinned.indexOf(`:`);
-    if (separator <= 0 || separator === pinned.length - 1) {
-        return undefined;
-    }
-    return { provider: pinned.slice(0, separator), model: pinned.slice(separator + 1) };
-};
-
-/* A pin as a person reads it: the catalog's own label for the id, or the id itself for one the static catalog
- * has not caught up with (the picker offers a custom-id escape hatch, so this is a real case rather than a
- * defensive branch). Beside parsePinned because the two are always wanted together, by any surface that has to
- * name what a click is about to spend BEFORE it spends it, and the two loudest of those are extensions that
- * share no other code with each other. */
-export const pinnedModelLabel = (choice: ModelChoice): string =>
-    modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
-
-// The cheapest row a provider publishes, its whole catalog read from the cheap end. Undefined for a catalog
-// that hasn't loaded yet, which is a real state: every provider serves a floor, but only once something has
-// asked it.
-const cheapestOf = (source: ModelSource): string | undefined => source.models.toSorted(compareCheapestFirst)[0];
-
-// Where a provider's cheapest row sits on the shared tier scale, and therefore how well it answers the question
-// Auto asks. UNRANKED (-1) is a genuine last place: it means the id carries no tier word we know, so the row is
-// the provider's base line rather than its budget one.
-const tierOf = (model: string): number => tierRankOf(familyOf(model));
-
-// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read, the property
-// compareUnrankedModelIds exists to guarantee, and the one a default actually needs. An endpoint is in no fixed
-// list, so it reads -1 and leads the tiebreak; unreachable in practice, since it can never tie on cost.
-const providerOrder = (provider: AgentProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
-
-/* WHAT AN ENDPOINT COSTS, one rung past every provider's, and the reason it is a number here rather than a
- * member of AccessKind. That axis describes the providers this repo ships, and every one of them is unlocked by
- * signing in to something the user already holds, so none of them is metered per call. An endpoint is the
- * opposite: whatever gateway somebody pointed us at, whose bill this repo cannot see. Reading it as dearer than
- * anything on the table is the conservative answer, and it is what keeps Auto from reaching for a paid gateway
- * on its own initiative. */
-const METERED_COST = Math.max(...Object.values(ACCESS_COST)) + 1;
-
-// How much a call on this provider costs at the margin. Every native provider declares an access kind; an
-// endpoint declares none, and takes the metered rung above.
-const costOf = (provider: AgentProvider): number => {
-    const access = accessFor(provider);
-    return access === undefined ? METERED_COST : ACCESS_COST[access.kind];
-};
-
-/* AUTO, every connected provider's cheapest row, best-first, as a ladder rather than a winner. The floor under
- * every `helper` role, and under nothing else.
- *
- * Ranked on TIER FIRST, then cost. That order is the point: a helper's Auto exists to not be the frontier
- * model, so a free flagship is still the wrong tool, while a free Haiku-class row and a subscription
- * Haiku-class row differ only in whose quota they spend. Cost then breaks that tie towards the channel the user
- * is not paying per token for, and against the one they are.
- *
- * NOTE WHAT AUTO IS AND IS NOT AN ARGUMENT FOR. It is the answer for an owner who has said nothing, not a claim
- * that cheap is right: an owner who pins Opus to commit messages is not being talked out of it, which is the
- * whole reason these lists are per role. Auto is what a row says while it is empty.
- *
- * The whole ladder, not just its head, because the same ranking that picks the best answer also states the best
- * SECOND answer, and a sandbox with three accounts connected should not lose its commit messages for six hours
- * because one of them is spent. */
-export const autoLadder = (sources: readonly ModelSource[]): readonly ModelPin[] =>
-    sources
-        .filter((source) => source.ready)
-        .flatMap((source) => {
-            const model = cheapestOf(source);
-            return model === undefined ? [] : [{ provider: source.provider, model }];
-        })
-        .toSorted(
-            (left, right) =>
-                tierOf(right.model) - tierOf(left.model) ||
-                costOf(left.provider) - costOf(right.provider) ||
-                providerOrder(left.provider) - providerOrder(right.provider),
-        );
-
-/* WHICH MODELS THIS ROLE MAY RUN, IN THE ORDER TO TRY THEM, given what this sandbox has connected.
- * `pinned` is the stored setting: settings.modelRoles[role], an ordered list of pins, empty for the role's own
- * floor.
- *
- * A pin only holds while its provider is READY: an account the user disconnected would otherwise sit at the
- * head of the chain failing on a credential error, when the sandbox can plainly still answer. Dropping it is
- * the same move the composer already makes when a live catalog stops offering the selected model. It stays on
- * SCREEN, greyed — the settings row renders the stored list, not this one — because a setting that vanished
- * from view would look like the app had eaten it.
- *
- * THE PINNED LIST IS THE WHOLE ANSWER whenever any of it survives that filter. The floor is NOT appended
- * underneath, and that is deliberate: a user who writes down three models has said which accounts this job may
- * spend, and quietly reaching for a fourth when all three are out is exactly the "spend an account they were
- * steering away from" failure a pin exists to prevent. When NONE of the pins is connected any more the list has
- * stopped saying anything about this sandbox, so the floor takes over rather than leaving a dead button.
- *
- * THE WHOLE PIN SURVIVES, not the pair inside it: an entry's effort, thinking, speed and harness are what the
- * work is composed from, so a resolver handing back a bare (provider, model) would silently run the head of the
- * list at the provider's defaults. Nothing here reads or judges those fields, which is the point of carrying
- * them whole.
- *
- * Empty out means the role has nothing it can reach. For a `helper` that is a sandbox with nothing connected at
- * all, and the caller renders a control that says so rather than a live button that fails on click; for a `run`
- * it is the ordinary state of an unpinned role, and the caller's own floor answers. */
-export const resolveRoleModels = (sources: readonly ModelSource[], pinned: readonly ModelPin[], role: ModelRole): readonly ModelPin[] => {
-    const ready = new Set(sources.filter((source) => source.ready).map((source) => source.provider));
-    // Taken verbatim, unvalidated against the catalog on purpose: the picker offers a custom-id escape hatch for
-    // a model a catalog hasn't caught up with, and second-guessing the user's own id here would silently run a
-    // different model than the settings row names.
-    const requested = pinned.filter((pin) => ready.has(pin.provider));
-    /* The same model twice would spend two attempts proving one account is out — a real state, since the list is
-     * hand-edited and Auto's ladder can rank a provider the user has also pinned.
-     *
-     * THE FIRST OF A PAIR WINS, WHOLE. Two entries can name one model and differ in their knobs (the same Sonnet
-     * at Max and again at Low, written while reordering the list), and the one the user reads first is the one
-     * they meant; keeping the earlier position with the later entry's effort would run a tier that appears
-     * nowhere the pin does. */
-    const chain: ModelPin[] = [];
-    for (const pin of requested) {
-        if (!chain.some((held) => modelPinKey(held) === modelPinKey(pin))) {
-            chain.push(pin);
-        }
-    }
-    if (chain.length > 0) {
-        return chain;
-    }
-    // The floor, which the role declares. An id outside the table has no floor to fall to, and answering with
-    // the cheapest connected model for it would be this file inventing a job.
-    return modelRole(role)?.kind === `helper` ? autoLadder(sources) : [];
-};

package/src/model-roles.ts

@@ -1,224 +0,0 @@
-import { z } from "zod";
-
-/* EVERY JOB IN THIS SANDBOX THAT PICKS A MODEL, LISTED BY THE JOB IT IS, one row per answer the owner is
- * entitled to give differently.
- *
- * WHAT THIS REPLACED, and why it had to go. Model settings used to be grouped by how HARD the work was assumed
- * to be: a "quick model" for the small automatic jobs, an "agent runs" tier for the big ones. Both names
- * described an intensity rather than a job, and an intensity is a guess somebody else made about work the owner
- * knows better. A commit message written by a frontier model is not a mistake, it is a preference, and the
- * grouping made it unsayable: pinning Opus to get better commit subjects also pinned it to session titles, to
- * every loop verdict, and to the safety judge. One bundled row could not say the thing anyone actually wanted
- * to say.
- *
- * SO THE UNIT IS THE ROLE. Each entry here is one place a model gets chosen, and each gets its own ordered list
- * in settings.modelRoles. Seventeen rows is more than four, and that is the point rather than a cost being
- * absorbed: the configuration and the UI both already existed per use-case, and collapsing them was the only
- * thing standing between the owner and a choice the machinery could already honour. A simpler face over this
- * (presets: "cheap everywhere", "frontier everywhere") is a thing that can be built ON TOP of a true model, and
- * cannot be unpicked from a lossy one.
- *
- * EVERY LIST IS AN ORDERED LADDER, whatever the role, and for one reason: the interesting failure of a pinned
- * model is not that it is wrong, it is that it is CONNECTED AND WILL NOT ANSWER TODAY. The account's allowance
- * went on the chat this morning, and one spent provider takes the role down for hours while three others sit
- * idle. Written in order, the next entry catches it.
- *
- * TWO KINDS, and the only thing that separates them is what an EMPTY list means. That is a real fork rather
- * than a leftover of the old grouping, and it is declared per role because it is a property of the job:
- *
- *   helper — a one-shot. One prompt, no tools, one string back, and it is over. An empty list resolves to the
- *            AUTO LADDER: every connected provider's cheapest row, best-first (model-pins.ts). Deriving is the
- *            right default here because the job is small and repeatable, so the cost of a wrong guess is one
- *            cheap call, and because a derived answer improves by itself when an account is connected tomorrow.
- *
- *   run    — a whole session with tools and a worktree, started by a surface rather than by a person at a
- *            composer. An empty list resolves to NOTHING, and the caller's own floor answers: the model the
- *            owner picked for their chat. Nothing here can judge whether a job is worth the frontier tier, and
- *            a wrong guess is billed in whole sessions rather than in tokens, so the honest fallback is a
- *            choice they made rather than one this table invented.
- *
- * EVERY ENTRY IS A FULL PIN (ModelPinSchema): which model, and how it runs — effort, thinking, speed, harness.
- * The helper roles carry them too, which they did not use to: a one-shot ran with reasoning forcibly off, so
- * pinning a reasoning model to commit messages bought the price of one and the behaviour of neither. The knobs
- * now ride through the one-shot path (the daemon's role-model.ts), so an entry means what it says wherever it
- * is written.
- *
- * ADDING A ROLE IS ONE ROW HERE. The settings key, the resolver's floor, the daemon's lookup and the settings
- * page's row all read this table, so a job that starts picking a model tomorrow becomes configurable by saying
- * what it is. That is the property the old grouping cost: a new surface inherited "agent runs" by being
- * unattended, which is how a documentation sweep and a production incident came to share one tier. */
-
-export const ModelRoleKindSchema = z.enum(["helper", "run"]);
-export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
-
-/* The shape of a row. `id` is a bare string HERE and narrowed on the exported type below, because the id union
- * is derived from this very table: a self-referential `satisfies` would be a type that has to know its own
- * answer before it can check it. */
-interface ModelRoleRow {
-    readonly id: string;
-    // What the settings row is called. A JOB, in the owner's words, never a tier.
-    readonly label: string;
-    // The row's one line: what this model is asked to do. Read beside the label, so it says what the label
-    // cannot rather than restating it.
-    readonly blurb: string;
-    readonly kind: ModelRoleKind;
-    // The row's glyph, from the shared icon set. Here rather than in a web-side map because the whole value of
-    // this table is that a role is declared ONCE; a second table keyed by the same ids is the drift this
-    // replaced, moved one layer up.
-    readonly icon: string;
-}
-
-/* THE TABLE. Ordered as the settings page draws it, and the order is an argument about reach: the one-shots
- * first, because nobody chose a model for them and they run constantly; then the runs somebody's click starts;
- * then the runs that start themselves, which are the ones an owner is least likely to be watching and most
- * likely to want held to a budget.
- *
- * The ids are the wire vocabulary: a turn carries one (AgentTurn.runRole), so they are kebab-case and stable,
- * and renaming one is a breaking change to the setting rather than a cosmetic edit. */
-export const MODEL_ROLES = [
-    {
-        id: "commit-message",
-        label: "Commit messages",
-        blurb: "The subject written when an agent's work lands, and the release note under it.",
-        kind: "helper",
-        icon: "file-edit",
-    },
-    {
-        id: "session-title",
-        label: "Session titles",
-        blurb: "The name a conversation wears on the board, written a second into its first turn.",
-        kind: "helper",
-        icon: "pencil",
-    },
-    {
-        /* THE ONE HELPER WHOSE INPUT IS ADVERSARIAL, and the reason the old bundling was worst here. Its prompt
-         * contains a command the agent is about to run, which may have arrived from a stranger's web page, and a
-         * small model can be talked round by it. Being wrong is expensive in both directions: a needless card
-         * teaches the owner to click through the next one. */
-        id: "safety-judge",
-        label: "Safety judge",
-        blurb: "Which model reads your safety policy before a flagged command runs.",
-        kind: "helper",
-        icon: "shield",
-    },
-    {
-        id: "loop-verdict",
-        label: "Loop verdicts",
-        blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
-        kind: "helper",
-        icon: "check-square",
-    },
-    {
-        id: "pipeline-fix",
-        label: "Pipeline fixes",
-        blurb: "The agent started by Fix on a red pipeline.",
-        kind: "run",
-        icon: "wave-pulse",
-    },
-    {
-        id: "deployment-fix",
-        label: "Deployment fixes",
-        blurb: "The agent started by Fix on a deployment that is down.",
-        kind: "run",
-        icon: "server",
-    },
-    {
-        id: "maintenance-chore",
-        label: "Maintenance chores",
-        blurb: "A chore run started from the Maintenance board.",
-        kind: "run",
-        icon: "wrench",
-    },
-    {
-        id: "documentation-run",
-        label: "Documentation runs",
-        blurb: "A pass over a repo's own documentation.",
-        kind: "run",
-        icon: "book",
-    },
-    {
-        id: "acceptance-run",
-        label: "Acceptance runs",
-        blurb: "One session per story in an acceptance fan-out.",
-        kind: "run",
-        icon: "list-check",
-    },
-    {
-        id: "pre-push-fix",
-        label: "Pre-push fixes",
-        blurb: "The fix proposed when a check fails on the way to a push.",
-        kind: "run",
-        icon: "cloud-upload",
-    },
-    {
-        id: "automation-wake",
-        label: "Automation wakes",
-        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
-        kind: "run",
-        icon: "clock",
-    },
-    {
-        id: "approval-queue",
-        label: "Approvals queue",
-        blurb: "The turn that publishes or acts on what you approved.",
-        kind: "run",
-        icon: "check-circle",
-    },
-    {
-        id: "extension-review",
-        label: "Extension update reviews",
-        blurb: "The agent that reads an extension update before it is applied.",
-        kind: "run",
-        icon: "box",
-    },
-    {
-        id: "loop-iteration",
-        label: "Loop iterations",
-        blurb: "Each round of a loop working towards its goal.",
-        kind: "run",
-        icon: "repeat",
-    },
-    {
-        id: "watch-wake",
-        label: "Watch wakes",
-        blurb: "The turn a watch starts when the thing it was watching happens.",
-        kind: "run",
-        icon: "eye",
-    },
-    {
-        id: "verify-nudge",
-        label: "Verify nudges",
-        blurb: "The follow-up turn sent when work was left unverified.",
-        kind: "run",
-        icon: "search",
-    },
-    {
-        /* THE ONE ROLE THAT ANSWERS A CHOICE RATHER THAN FILLING A SILENCE. A spawning agent may name its
-         * child's provider, and when it does that wins, exactly as a caret pick wins on every other run role.
-         * This is what answers when it names none, which used to be a hardcoded "claude". */
-        id: "child-agent",
-        label: "Child agents",
-        blurb: "What an agent's own subagents run on when it names no model for them.",
-        kind: "run",
-        icon: "users",
-    },
-] as const satisfies readonly ModelRoleRow[];
-
-export type ModelRole = (typeof MODEL_ROLES)[number]["id"];
-export type ModelRoleSpec = ModelRoleRow & { readonly id: ModelRole };
-
-export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly ModelRole[];
-
-/* The wire form. An enum rather than a string, unlike most ids in this contract, because there is no case for
- * an unknown one: a role is a place in THIS codebase where a model gets chosen, so a value outside the table
- * names nothing, and a settings file or a turn carrying one is a typo worth a clean error rather than a list
- * silently ignored. */
-export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
-
-const BY_ID = new Map<string, ModelRoleSpec>(MODEL_ROLES.map((role) => [role.id, role]));
-
-/** What this role is, or undefined for an id no build of this table declares. */
-export const modelRole = (id: string): ModelRoleSpec | undefined => BY_ID.get(id);
-
-/** The roles of one kind, in table order: the two blocks the settings page draws. */
-export const modelRolesOfKind = (kind: ModelRoleKind): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => role.kind === kind);

package/src/needs-action.ts

@@ -1,14 +0,0 @@
-import { z } from "zod";
-
-/* ONE "DO THIS BY HAND" LINE, the honesty unit three surfaces share: what an arrival could not do for the
- * owner (arrival.ts), what a derived definition could not express (definition.ts), and where a runner has
- * drifted from its parent (runner-protocol.ts). A subject the UI bolds, a detail written as an instruction.
- *
- * It lives in its own leaf module because runner-protocol.ts speaks it, and THAT file is imported by
- * schemas/agent.ts, which definition.ts imports — the schema living in definition.ts made a cycle that left
- * schemas half-initialized under module-eval.
- *
- * The name says the FIELD it fills (`needsAction`) rather than any one surface, because naming it for the
- * definition is what let the arrival surfaces drift apart in the first place. */
-export const NeedsActionSchema = z.object({ subject: z.string(), detail: z.string() });
-export type NeedsAction = z.infer<typeof NeedsActionSchema>;

package/src/output-fields.ts

@@ -1,111 +0,0 @@
-import { z } from "zod";
-
-/* A DECLARED OUTPUT SHAPE, the answer to "what does this session produce?", written once and used three ways.
- *
- * An agentic session's natural output is prose, and prose is unusable as an input to the next session: a step
- * that must hand "the three files worth changing" to the step after it cannot hand over a paragraph that
- * mentions them. So a session that feeds another one declares its shape here, and that one declaration
- * becomes: the sentence in the prompt that tells the model what to write, the validator that decides whether
- * it complied, and the table the run view renders. Written once because the three drift apart the moment they
- * are written twice, a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
- * says nothing useful about why.
- *
- * WHY A FIELD LIST AND NOT JSON SCHEMA. JSON Schema is strictly more expressive and completely unauthorable in
- * a form: nobody designing a workflow is going to hand-write `{"type":"object","properties":{...}}`, and a UI
- * that generates it becomes a schema editor, which is a product of its own. Four scalar types plus a string
- * list covers what one session actually hands another, a verdict, a count, a list of paths, a summary, and
- * anything past that is better carried as a file the next step reads.
- *
- * `description` IS REQUIRED, and that is the field that decides whether this works at all. `{name: "risk"}`
- * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low, how
- * likely this change is to break something at runtime"}` gets you the answer to the question you asked.
- */
-
-// Restricted to a JS-identifier-ish shape: these become object keys the prompt spells out literally, and a
-// name with a quote or a newline in it produces a prompt that cannot be complied with.
-const FIELD_NAME = /^[a-zA-Z_][a-zA-Z0-9_]{0,39}$/;
-
-export const OutputFieldSchema = z.object({
-    name: z.string().regex(FIELD_NAME),
-    type: z.enum(["string", "number", "boolean", "string[]"]),
-    // What the field means, in the words the model is given. Not optional, see the note above.
-    description: z.string().min(1),
-    // An absent optional field validates; an absent required one does not, and the iteration is told which.
-    required: z.boolean(),
-});
-export type OutputField = z.infer<typeof OutputFieldSchema>;
-
-// How many fields one output may declare. A shape past this is not a handoff, it is a report, and a report is
-// what the prose half of the document is for.
-export const OUTPUT_FIELDS_MAX = 16;
-
-/* Repeated names make the declaration internally contradictory: object validation can only keep one rule for
- * a key, while a consumer looking the field up sees whichever copy it happens to ask for first. Reject them at
- * the declaration boundary, before either interpretation gets a chance to exist. Exported because graph-level
- * validation uses the same fact to explain the fault in the designer before a save is attempted. */
-export const duplicateOutputFieldNames = (fields: readonly Pick<OutputField, "name">[]): string[] => {
-    const seen = new Set<string>();
-    const repeated = new Set<string>();
-    for (const field of fields) {
-        if (seen.has(field.name)) {
-            repeated.add(field.name);
-        }
-        seen.add(field.name);
-    }
-    return [...repeated];
-};
-
-export const OutputFieldsSchema = z
-    .array(OutputFieldSchema)
-    .min(1)
-    .max(OUTPUT_FIELDS_MAX)
-    .superRefine((fields, context) => {
-        for (const name of duplicateOutputFieldNames(fields)) {
-            context.addIssue({ code: "custom", message: `Output field names must be unique; "${name}" is repeated.` });
-        }
-    });
-
-const validatorFor = (field: OutputField): z.ZodType => {
-    if (field.type === "number") {
-        return z.number();
-    }
-    if (field.type === "boolean") {
-        return z.boolean();
-    }
-    if (field.type === "string[]") {
-        return z.array(z.string());
-    }
-    return z.string();
-};
-
-/* The declared shape as a validator. Unknown keys are ALLOWED THROUGH: a model that answered everything asked
- * of it and then added a `notes` key has complied, and failing it there would burn an iteration teaching it to
- * write less. What is enforced is that every required field is present and every present field has the
- * declared type, the two things the reader downstream is entitled to assume.
- */
-export const fieldsValidator = (fields: readonly OutputField[]): z.ZodType =>
-    z.looseObject(Object.fromEntries(fields.map((field) => [field.name, field.required ? validatorFor(field) : validatorFor(field).optional()])));
-
-// A worked example of the declared shape, so the prompt can show rather than describe. Values are the field's
-// own description, a model copying the example's structure has the description in front of it as it fills each
-// slot, which is where it is needed rather than in a legend three lines up.
-export const fieldsExample = (fields: readonly OutputField[]): Record<string, unknown> =>
-    Object.fromEntries(
-        fields.map((field) => {
-            const hint = `${field.description}${field.required ? "" : " (optional, omit if it does not apply)"}`;
-            if (field.type === "number") {
-                return [field.name, 0];
-            }
-            if (field.type === "boolean") {
-                return [field.name, false];
-            }
-            if (field.type === "string[]") {
-                return [field.name, [hint]];
-            }
-            return [field.name, hint];
-        }),
-    );
-
-// One line per field, for surfaces with no room to render an example: "risk (string, required), how likely …".
-export const describeFields = (fields: readonly OutputField[]): string =>
-    fields.map((field) => `- \`${field.name}\` (${field.type}${field.required ? ", required" : ", optional"}), ${field.description}`).join(`\n`);

package/src/overlay-lint.ts

@@ -1,116 +0,0 @@
-/* WHAT AN ENVIRONMENT OVERLAY MAY SAY, read the same way by everyone who handles one.
- *
- * An overlay is the Dockerfile that extends the sandbox image for one sandbox: a pinned FROM, the enabled
- * capabilities' fragments, and the custom section the owner approved. Three readers apply the same grammar
- * at three trust levels, and none of them may trust the one before:
- *   • the daemon admits an EXTENSION's fragment only if it is RUN/ENV (capabilities/handlers/extension.ts at
- *     install, environment/fragment-sources.ts again at compose, in case the checkout changed);
- *   • the daemon pins the composed file's first instruction to the official image (environment.ts);
- *   • the platform builds a HOSTED sandbox's overlay on a machine of its own, from content that reached it
- *     through an agent-writable volume and a browser, so it re-checks all of it before any machine exists.
- * Text in, verdict out. No filesystem and no services, so the platform imports this the way it imports
- * tunnel-ids, and the ic binary's Rust twin (recreate.rs `overlay_base`, runner.rs) reads the same shape. */
-
-// The marker the rebuild executors read runtime privileges from (`# intentic:runtime --privileged`, the
-// docker run flag it becomes is allowlisted there). A fragment that can be written by anything but the
-// daemon's own code must not carry it, in a comment or anywhere else.
-const RUNTIME_DIRECTIVE = "intentic:runtime";
-
-const OFFICIAL_SANDBOX_IMAGE = /^ghcr\.io\/intentic\/sandbox:\S+$/;
-
-// The published sandbox image under any tag, the only base an overlay may extend.
-export const isOfficialSandboxImage = (ref: string): boolean => OFFICIAL_SANDBOX_IMAGE.test(ref);
-
-interface OverlayLine {
-    readonly raw: string;
-    // `body` is a line inside a `\`-continued instruction, which carries no keyword of its own.
-    readonly kind: "blank" | "comment" | "instruction" | "body";
-}
-
-// Continuation-aware: a `\` at the end of any line, comments included, makes the next line a body line.
-const overlayLines = (content: string): OverlayLine[] => {
-    let continued = false;
-    return content.split("\n").map((raw) => {
-        const line = raw.trim();
-        const wasContinued = continued;
-        continued = line.endsWith("\\");
-        const kind = line === "" ? "blank" : line.startsWith("#") ? "comment" : wasContinued ? "body" : "instruction";
-        return { raw, kind };
-    });
-};
-
-const FROM = /^from\s+(\S+)/i;
-const RUN_OR_ENV = /^(run|env)\s/i;
-
-/* An extension fragment may install and set variables, and nothing else. FROM is refused because the daemon
- * owns the base pin; every other instruction because there is no build context to COPY from and nothing an
- * extension has any business doing to USER, ENTRYPOINT or EXPOSE; and the runtime directive anywhere,
- * because an out-of-band executor greps for it and a comment is exactly where it would hide. Answers the
- * offending line, or undefined when the fragment is clean. */
-export const invalidExtensionFragment = (content: string): string | undefined => {
-    for (const { raw, kind } of overlayLines(content)) {
-        if (raw.includes(RUNTIME_DIRECTIVE)) {
-            return raw;
-        }
-        if (kind === "instruction" && !RUN_OR_ENV.test(raw.trim())) {
-            return raw;
-        }
-    }
-    return undefined;
-};
-
-// The image a composed overlay extends: the first instruction, when it is a FROM.
-export const overlayBase = (content: string): string | undefined => {
-    const first = overlayLines(content).find((line) => line.kind === "instruction");
-    return first === undefined ? undefined : FROM.exec(first.raw.trim())?.[1];
-};
-
-// Whether the overlay's first instruction pins it to the official sandbox image.
-export const hasOfficialBase = (content: string): boolean => {
-    const base = overlayBase(content);
-    return base !== undefined && isOfficialSandboxImage(base);
-};
-
-/* A whole composed overlay, as an executor that did not compose it must read it: one leading FROM on the
- * official image, then RUN and ENV only. Comments pass, the runtime directive included, since a composed
- * overlay is where the daemon's own capability fragments put it and the executor that honours it (ic) reads
- * it from there; an executor that cannot honour it (a VM is already privileged) ignores it. Answers the
- * offending line, or undefined. An overlay with no instruction at all is refused: there is nothing to build. */
-export const lintOverlay = (content: string): string | undefined => {
-    let first = true;
-    for (const { raw, kind } of overlayLines(content)) {
-        if (kind !== "instruction") {
-            continue;
-        }
-        const line = raw.trim();
-        if (first) {
-            first = false;
-            const base = FROM.exec(line)?.[1];
-            if (base === undefined || !isOfficialSandboxImage(base)) {
-                return raw;
-            }
-            continue;
-        }
-        if (!RUN_OR_ENV.test(line)) {
-            return raw;
-        }
-    }
-    return first ? "" : undefined;
-};
-
-/* The same overlay on a different base: the first FROM rewritten, everything else byte-identical. An
- * executor applies an approved recipe on the base IT runs (a newer release than the one the daemon composed
- * against, a rollback pin), and hashes the content the owner approved rather than this rewrite, so the
- * environment hash stays the reviewed one. Content whose first instruction is not a FROM is returned as is. */
-export const rewriteOverlayBase = (content: string, base: string): string => {
-    let done = false;
-    return overlayLines(content)
-        .map(({ raw, kind }) => {
-            if (done || kind !== "instruction") {
-                return raw;
-            }
-            done = true;
-            return FROM.test(raw.trim()) ? raw.replace(FROM, `FROM ${base}`) : raw;
-        })
-        .join("\n");
-};