@open-everywhere/core 0.1.0

package/dist/agent/settings/settings.d.ts

@@ -0,0 +1,935 @@
+import { e2eDriversProblem, type E2eDriverIdentity } from "../testing/driver-allowlist.js";
+import { sandboxRegionProblem } from "../sandbox/vercel-create.js";
+/** Whether the source-tier table DECIDES (`enforced`) or merely observes (`dryrun`). */
+export type TaintTierMode = "enforced" | "dryrun";
+/**
+ * Whether the TAINTED-TURN MODEL runs at all (OPE-399). `on` is everything this repo describes;
+ * `off` is a deployer's reviewed opt-out — no marks, no gates, no roster shrink, no disclosure.
+ * Orthogonal to {@link TaintTierMode}, which only chooses HOW a live model decides a mark.
+ */
+export type TaintMode = "on" | "off";
+/**
+ * What a chat wake on an UNDECLARED surface does (OPE-489). `clean` (shipped) marks nothing and
+ * relocates the loudness to preflight; `mark` restores per-turn pressure at ROOM grain.
+ */
+export type TaintUndeclaredSurface = "clean" | "mark";
+/** The LLM approval judge's arming mode. */
+export type ApprovalJudgeMode = "off" | "shadow" | "enforce";
+/**
+ * What the agent does with a message an EXCLUDED author wrote (OPE-507). The classification of an
+ * author is a SEPARATE axis and this union never touches it — access/external-policy.ts explains
+ * why the two stay apart.
+ *
+ * `taint` (shipped) — the text ENTERS the context, wrapped as untrusted content, and the tainted-turn
+ * model carries the consequence to the approval plane. This is what every deployment does today.
+ * `withhold` — the text NEVER ENTERS. The author cannot task the agent, the agent never wakes on
+ * their message, and a reply of theirs inside a permitted member's thread reaches the model as a
+ * marker that says a message arrived, with no body.
+ */
+export type ExternalAuthorGrain = "taint" | "withhold";
+/**
+ * Whether the agent engages at all in a room the classification calls external (OPE-504).
+ * `engage` (shipped) — today's behaviour, unchanged. `silent` — the agent does not wake in that
+ * room, and it says so exactly twice: once when it joins, once on the first wake it suppresses.
+ */
+export type ExternalRoomGrain = "engage" | "silent";
+/**
+ * Every behaviour opinion this deployment holds, resolved. Grouped by the subsystem that reads it,
+ * because that is the axis a reviewer navigates by.
+ *
+ * ⚠️ PROCESS-GLOBAL, ALL OF IT. Nothing here is per-org, per-domain or per-surface — those live in
+ * the scoped registries (bundles, domains, model policy, spend budgets) that `getConfig()` serves.
+ * A setting that ever needs a scope belongs THERE, not here; adding a scope argument to this module
+ * would quietly turn a deployment switch into policy the resolver has to reason about.
+ */
+export interface AgentSettings {
+    readonly agent: {
+        /** eve `limits.maxInputTokensPerSession` — the graceful bound under the hosted hard kill. */
+        readonly sessionInputTokenBudget: number;
+        /** eve `compaction.thresholdPercent` — the fraction of the context window compaction fires at. */
+        readonly compactionThresholdPercent: number;
+    };
+    readonly approvals: {
+        /** The LLM approval judge's arming mode (access/approval-judge.ts). */
+        readonly judgeMode: ApprovalJudgeMode;
+        /** TTL (hours) before a pending approval action lazily expires. */
+        readonly ttlHours: number;
+        /** TTL (hours) for a `pr.open` session-approval memo (the `approve_session` verb). */
+        readonly sessionTtlHours: number;
+        /** TTL (hours) for the session-checkpoint continue/asked memos. */
+        readonly checkpointTtlHours: number;
+        /** Seconds an unattended routine fire waits for its permission card before auto-declining. */
+        readonly routineCardWaitSeconds: number;
+    };
+    readonly audit: {
+        /** Write the judged-SILENCE audit rows (`unified.no_reply` + the `reply.no_reply` tool row). */
+        readonly silences: boolean;
+    };
+    readonly browser: {
+        /** The browser master flag — unarmed, the capability does not exist at all. The reach itself is
+         *  the host DECLARATION in `agent/access/browser-hosts.ts`, not a setting: a browse target
+         *  carries verbs, a credential and a page-scripting arm, and a setting value cannot hold them. */
+        readonly enabled: boolean;
+    };
+    readonly bash: {
+        /** Wall-clock cap on ONE `bash` call, ms. `0` disables the timeout entirely. */
+        readonly timeoutMs: number;
+        /** Layer 1 of the hang guard: refuse a bare `&` that redirects neither stdout nor stderr. */
+        readonly backgroundGuard: boolean;
+    };
+    readonly connectors: {
+        /** The connector DM-only wall — connector ops refuse any non-DM surface. */
+        readonly dmOnly: boolean;
+        /** A1: the per-user (Connect user-subject) credential path. */
+        readonly userPrincipal: boolean;
+        /** C.3: the shared user-OAuth vault, keyed by link-set subject. */
+        readonly linkSetVault: boolean;
+        /** A2: the per-op read/write consequence gate (vs the blanket `once()`). */
+        readonly opTiering: boolean;
+        /** OPE-944: the MEMBER plane — a member's own credential in a shared room, reads only. */
+        readonly memberPlane: boolean;
+    };
+    readonly identityLinking: {
+        /** The code-back strictness knob on the DIRECTORY transport (OPE-617). */
+        readonly codeBack: boolean;
+    };
+    readonly delegation: {
+        /** The reshaped one-shot `agent` delegation model. */
+        readonly oneshotAgent: boolean;
+    };
+    readonly models: {
+        /** The named model STACK this deployment runs — an alias the app's stack registry defines. */
+        readonly stack: string;
+    };
+    readonly discord: {
+        /** Reply in a thread when the bot is @mentioned in a Discord text/announcement channel. */
+        readonly autoThread: boolean;
+        /** The "working" affordances — the 👀/✅ reaction and the holding message edited into the reply. */
+        readonly statusUx: boolean;
+    };
+    readonly egress: {
+        /** Apply the compiled egress policy for real (`false` ⇒ dry-run: compile, audit, don't apply). */
+        readonly enforce: boolean;
+        /** Let a session continue when the sandbox backend cannot enforce the policy at all. */
+        readonly allowUnenforced: boolean;
+    };
+    readonly externalPolicy: {
+        /** What the agent does with a message an EXCLUDED author wrote (access/external-policy.ts). */
+        readonly authorGrain: ExternalAuthorGrain;
+        /** Whether the agent engages at all in a room the classification calls external. */
+        readonly roomGrain: ExternalRoomGrain;
+    };
+    readonly governance: {
+        /** Memoisation TTL for the room roster + governance attestation behind the audience floor, ms. */
+        readonly floorTtlMs: number;
+    };
+    readonly identity: {
+        /** Memo TTL for every live partner/room trust verification a surface performs, ms. */
+        readonly dmTrustTtlMs: number;
+        /** The deployment's CANONICAL agent name — one name on every surface. `""` ⇒ unset. */
+        readonly name: string;
+    };
+    readonly memory: {
+        /** Per-silo judge budget for the dream/tidy sweep. */
+        readonly dreamCandidateCap: number;
+        /** Whether a Mode-1 skill proposal opens a pull request on the config repo. */
+        readonly skillProposalPr: boolean;
+    };
+    readonly policyPages: {
+        /** The operator's privacy-policy text, served as `GET /privacy`. Empty ⇒ the placeholder page. */
+        readonly privacy: string;
+        /** The operator's terms-of-use text, served as `GET /terms`. Empty ⇒ the placeholder page. */
+        readonly terms: string;
+    };
+    readonly routines: {
+        /** Max routines one inbound EVENT may fan out to; the rest are audited as skipped. */
+        readonly eventMaxFanout: number;
+        /** Max routine ROOT sessions started per dispatcher tick. */
+        readonly maxConcurrency: number;
+        /** Fire cap on a fresh durable-job bound. */
+        readonly jobMaxFires: number;
+        /** Wall-clock grace on a fresh durable-job bound, in days. */
+        readonly jobMaxDays: number;
+    };
+    readonly rotation: {
+        /** Idleness threshold that rotates a standing seat's generation on its next wake, in hours. */
+        readonly quietGapHours: number;
+        /** Age at which a standing generation is retired for context freshness, in days. `0` disables. */
+        readonly expiryDays: number;
+        /** Token BACKSTOP: measured cumulative input + cache-read tokens on one generation. */
+        readonly tokenBudget: number;
+        /** Turn BACKSTOP: turn count on one generation, derived from the workflow event wall. */
+        readonly turnBudget: number;
+        /** Context-size BACKSTOP: last-request input tokens above which a standing seat re-mints. */
+        readonly contextSizeTokens: number;
+        /** Token cap on the recorded last-generation tail carried into a fresh generation's first wake. */
+        readonly tailTokenCap: number;
+    };
+    readonly sandbox: {
+        /** Stop the sandbox VM at each turn's end instead of letting it idle out. */
+        readonly stopAfterTurn: boolean;
+        /** Per-call cap on `extend_workspace_time`, in minutes. */
+        readonly extendMaxMinutes: number;
+        /** The per-session sandbox window (the backstop fuse), ms. Applied at sandbox CREATE. */
+        readonly timeoutMs: number;
+        /** Snapshot auto-GC age, ms. Applied at sandbox CREATE. */
+        readonly snapshotExpirationMs: number;
+        /** Off-Vercel `docker()` container image. Empty ⇒ the backend's own default. */
+        readonly image: string;
+        /** Vercel region to create sandboxes in. Empty ⇒ no pin. Fail-closed — see `sandbox/vercel-create.ts`. */
+        readonly region: string;
+    };
+    readonly spend: {
+        /** Retention window for the per-event `usage_events` table, in days. */
+        readonly usageEventsTtlDays: number;
+        /** Sandbox memory size the $ estimate prices against, in GiB. */
+        readonly sandboxMemoryGiB: number;
+        /** Sandbox "Provisioned Memory" rate the $ estimate prices against, $/GiB-hr. */
+        readonly sandboxGiBHourUsd: number;
+    };
+    readonly skills: {
+        /** Max runtime-authored domain skills per domain. */
+        readonly domainSkillCap: number;
+    };
+    readonly soak: {
+        /** Record every model call's composed request body for the soak lane's prefix replay. */
+        readonly capture: boolean;
+        /**
+         * Narrow capture to surface keys starting with any of these prefixes (OPE-864). A bare string
+         * is shorthand for a one-prefix list — `"slack/T1/"` means the same as `["slack/T1/"]`. Empty
+         * (the shipped `""`, or `[]`, or any list containing `""`) means every surface on the
+         * deployment — the deliberate escape hatch for a run that spans multiple platform families
+         * (the soak domain touches slack/notion/linear/github, each its own key family, and a single
+         * prefix cannot cover more than one).
+         */
+        readonly captureSurfacePrefix: string | readonly string[];
+    };
+    readonly stall: {
+        /** Identical-(tool,args,result) run length before the NEXT identical call is nudged. `0` disables. */
+        readonly repeatThreshold: number;
+    };
+    readonly taint: {
+        /** Whether the tainted-turn model runs at all (OPE-399). `off` is a code-only opt-out. */
+        readonly mode: TaintMode;
+        /** Whether the source-tier table decides or merely observes. Inert when `mode` is `off`. */
+        readonly tierMode: TaintTierMode;
+        /** What a chat wake on a surface the operator never declared does. Inert when `mode` is `off`. */
+        readonly undeclaredSurface: TaintUndeclaredSurface;
+    };
+    readonly tools: {
+        /** Per-tool-result character cap applied inside the untrusted-ingestion funnel. */
+        readonly maxResultChars: number;
+    };
+    readonly turn: {
+        /** SOFT per-turn boundary: model round-trips before the wrap-up instruction rides every call. */
+        readonly stepBudget: number;
+        /** HARD backstop as a multiple of the budget: the text-only stub replaces the model past it. */
+        readonly stepBackstopMultiple: number;
+    };
+    readonly wake: {
+        /** Extra name tokens the Slack/Discord AMBIENT name-drop wake fires on, beyond the surface's
+         *  live display name and `identity.name` (OPE-571). Case-insensitive. Empty ships. */
+        readonly nameDropInclude: readonly string[];
+        /** Name tokens the Slack/Discord name-drop wake NEVER fires on — wins over `nameDropInclude`
+         *  AND over the automatic base (the live display name and `identity.name`). Empty ships. */
+        readonly nameDropExclude: readonly string[];
+        /** The e2e DRIVER identities the seat doors admit — one `{ surface, principal }` entry per bot
+         *  identity, on the surfaces the pack drives. Empty ships, and with it empty NO bot author
+         *  reaches a seat on any surface, which is the pre-OPE-1023 behaviour exactly. */
+        readonly e2eDrivers: readonly E2eDriverIdentity[];
+    };
+    readonly webhooks: {
+        /** Accept a DECLARED hook's delivery when that hook has no secret configured. Off ships. */
+        readonly allowUnverified: boolean;
+        /** Accept a GitHub delivery this deployment cannot verify a signature for. Off ships. */
+        readonly allowUnverifiedGithub: boolean;
+        /** Accept a Notion delivery this deployment cannot verify a signature for. Off ships. */
+        readonly allowUnverifiedNotion: boolean;
+    };
+    readonly window: {
+        /** The standing-WINDOW apparatus — the ONE gate governing solo AND unified windows. */
+        readonly topology: boolean;
+    };
+}
+/** One setting's declaration: its shipped opinion, its validator, and its prose. */
+export interface SettingSpec<T> {
+    /** Dotted path into {@link AgentSettings} — the name docs, lints and errors use. */
+    readonly path: string;
+    /**
+     * 🔴 A TEST-HARNESS SEAM, NOT AN OPS OVERRIDE, AND THERE IS EXACTLY ONE (OPE-411).
+     *
+     * When present — and only `models.stack` has it — the named variable's recognised value WINS over
+     * the registered settings and the shipped default. Every BEHAVIOUR setting in this schema is
+     * code-only: the field is absent, `env` is never read for it, and changing it costs a diff. See
+     * this file's header for why the other forty-eight mirrors were deleted rather than kept.
+     */
+    readonly env?: string;
+    /** What every clone gets with nothing configured. The open-source default. */
+    readonly shipped: T;
+    /**
+     * Parse one raw env value, for the single spec that still has an `env`. Returning `undefined`
+     * means "not in my vocabulary" and falls through to the registered value, then the shipped
+     * default.
+     *
+     * 🔴 ABSENT ⇒ THE SETTING HAS NO ENV PATH AT ALL, which is a STRUCTURAL statement, not a
+     * behavioural one: there is no parser to reach, so no string in any environment can move the
+     * value. It pairs with an absent `env` (the settings test pins the two as one invariant), and it
+     * is the shape EVERY behaviour setting in this schema now takes.
+     */
+    readonly parseEnv?: (raw: string) => T | undefined;
+    /**
+     * Reject a bad APP override at `defineSettings` time. Returns a problem string, or undefined.
+     *
+     * ⚠️ THIS IS NOW THE ONLY VALIDATION A VALUE GETS, so it carries weight it did not before. With
+     * the env parsers deleted there is no fail-soft path left: a value is either the shipped default
+     * or something a human wrote in `agent/settings/settings.ts`, and a bad one should fail the boot loudly
+     * rather than resolve to a surprising posture. Prefer declaring a validator over omitting one.
+     */
+    readonly validate?: (value: T) => string | undefined;
+    /**
+     * The `typeof` of this spec's SECOND accepted arm, for a union-typed setting.
+     *
+     * The typeof gate in {@link defineSettings} compares a value against ONE arm — the shipped
+     * default's — so a union spec's other arm always fails it and falls through to the spec's own
+     * validator. Declaring the arm here is what lets a refusal tell the two cases apart: a value on a
+     * DECLARED arm is a supported spelling whose CONTENT is wrong, so the refusal quotes the
+     * validator's grammar; anything else really is the wrong type, and "expected number, got string"
+     * is the right thing to say. Without this field both read as a shape complaint, which sends the
+     * author of an ordinary typo off to rewrite a spelling the summary recommends.
+     */
+    readonly alsoAccepts?: "string" | "object";
+    /** One line for the generated operator table. Keep it a sentence. */
+    readonly summary: string;
+    /** How the shipped default renders in that table. */
+    readonly format?: (value: T) => string;
+}
+declare const positiveInt: (value: number) => string | undefined;
+declare const positiveNumber: (value: number) => string | undefined;
+/** A policy document is free text, so the only wrong non-empty value is one that RENDERS blank —
+ *  an operator who pasted whitespace has published nothing while believing they published. Empty
+ *  itself is legal and means "not published yet" (the page then renders its placeholder). */
+declare const policyTextProblem: (value: string) => string | undefined;
+declare const stringArray: (value: readonly string[]) => string | undefined;
+/** OPE-864: a spec whose shipped shape is a bare string but which also accepts a list — the
+ *  ergonomic single-value case stays a plain string in `SETTINGS_OVERRIDES` and never has to
+ *  become a one-element array just to satisfy the type. */
+declare const stringOrStringArray: (value: string | readonly string[]) => string | undefined;
+/**
+ * THE SPEC TABLE — the single declaration of every behaviour setting.
+ *
+ * Every row is `path` + `shipped` + `summary`, plus a `validate` where the type alone does not
+ * pin the legal range and a `format` where the raw value does not read well in the generated
+ * operator table. No row carries an env parser except `models.stack`, whose `env` is the harness
+ * seam the header describes.
+ */
+export declare const SETTINGS: {
+    agent: {
+        sessionInputTokenBudget: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+        };
+        compactionThresholdPercent: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be a fraction strictly between 0 and 1" | undefined;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    approvals: {
+        judgeMode: {
+            path: string;
+            shipped: "off";
+            validate: (v: ApprovalJudgeMode) => "must be \"off\", \"shadow\" or \"enforce\"" | undefined;
+            summary: string;
+        };
+        ttlHours: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        sessionTtlHours: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        checkpointTtlHours: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        routineCardWaitSeconds: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be a whole number of seconds between 0 and 300" | undefined;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    audit: {
+        silences: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    browser: {
+        enabled: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    bash: {
+        timeoutMs: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be a non-negative integer (0 disables the timeout)" | undefined;
+            summary: string;
+            format: (v: number) => string;
+        };
+        backgroundGuard: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+    };
+    connectors: {
+        dmOnly: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+        userPrincipal: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+        linkSetVault: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+        opTiering: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+        memberPlane: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    identityLinking: {
+        codeBack: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    delegation: {
+        oneshotAgent: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+    };
+    models: {
+        stack: {
+            path: string;
+            env: string;
+            shipped: string;
+            parseEnv: (raw: string) => string | undefined;
+            validate: (v: string) => "must be a non-empty stack alias" | undefined;
+            summary: string;
+        };
+    };
+    discord: {
+        autoThread: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+        statusUx: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+    };
+    egress: {
+        enforce: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+        allowUnenforced: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    externalPolicy: {
+        authorGrain: {
+            path: string;
+            shipped: "taint";
+            validate: (v: ExternalAuthorGrain) => "must be \"taint\" or \"withhold\"" | undefined;
+            summary: string;
+        };
+        roomGrain: {
+            path: string;
+            shipped: "engage";
+            validate: (v: ExternalRoomGrain) => "must be \"engage\" or \"silent\"" | undefined;
+            summary: string;
+        };
+    };
+    governance: {
+        floorTtlMs: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    identity: {
+        dmTrustTtlMs: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        name: {
+            path: string;
+            shipped: string;
+            validate: (v: string) => "must be at most 64 characters" | "must not contain a line break" | undefined;
+            summary: string;
+            format: (v: string) => string;
+        };
+    };
+    memory: {
+        dreamCandidateCap: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+        };
+        skillProposalPr: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    policyPages: {
+        privacy: {
+            path: string;
+            shipped: string;
+            validate: typeof policyTextProblem;
+            summary: string;
+            format: (v: string) => "`` (unset — `/privacy` serves the placeholder page)" | "the operator's own text";
+        };
+        terms: {
+            path: string;
+            shipped: string;
+            validate: typeof policyTextProblem;
+            summary: string;
+            format: (v: string) => "`` (unset — `/terms` serves the placeholder page)" | "the operator's own text";
+        };
+    };
+    routines: {
+        eventMaxFanout: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+        };
+        maxConcurrency: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+        };
+        jobMaxFires: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+        };
+        jobMaxDays: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    rotation: {
+        quietGapHours: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        expiryDays: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be a finite number of days (0 or negative disables the expiry trigger)" | undefined;
+            summary: string;
+            format: (v: number) => string;
+        };
+        tokenBudget: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+        };
+        turnBudget: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+        };
+        contextSizeTokens: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+        };
+        tailTokenCap: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+        };
+    };
+    sandbox: {
+        stopAfterTurn: {
+            path: string;
+            shipped: true;
+            summary: string;
+        };
+        extendMaxMinutes: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+            format: (v: number) => string;
+        };
+        timeoutMs: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+            format: (v: number) => string;
+        };
+        snapshotExpirationMs: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+            format: (v: number) => string;
+        };
+        image: {
+            path: string;
+            shipped: string;
+            summary: string;
+            format: (v: string) => string;
+        };
+        region: {
+            path: string;
+            shipped: string;
+            validate: typeof sandboxRegionProblem;
+            summary: string;
+            format: (v: string) => string;
+        };
+    };
+    skills: {
+        domainSkillCap: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+        };
+    };
+    soak: {
+        capture: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+        captureSurfacePrefix: {
+            path: string;
+            shipped: string | readonly string[];
+            alsoAccepts: "object";
+            validate: typeof stringOrStringArray;
+            summary: string;
+            format: (v: string | readonly string[]) => string;
+        };
+    };
+    spend: {
+        usageEventsTtlDays: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        sandboxMemoryGiB: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+        sandboxGiBHourUsd: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveNumber;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    stall: {
+        repeatThreshold: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be a non-negative integer (0 disables the stall guard)" | undefined;
+            summary: string;
+        };
+    };
+    taint: {
+        mode: {
+            path: string;
+            shipped: "on";
+            validate: (v: TaintMode) => "must be \"on\" or \"off\"" | undefined;
+            summary: string;
+        };
+        tierMode: {
+            path: string;
+            shipped: "enforced";
+            validate: (v: TaintTierMode) => "must be \"enforced\" or \"dryrun\"" | undefined;
+            summary: string;
+        };
+        undeclaredSurface: {
+            path: string;
+            shipped: "clean";
+            validate: (v: TaintUndeclaredSurface) => "must be \"clean\" or \"mark\"" | undefined;
+            summary: string;
+        };
+    };
+    tools: {
+        maxResultChars: {
+            path: string;
+            shipped: number;
+            validate: typeof positiveInt;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    turn: {
+        stepBudget: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be a whole number of round-trips (0 disables the boundary)" | undefined;
+            summary: string;
+            format: (v: number) => string;
+        };
+        stepBackstopMultiple: {
+            path: string;
+            shipped: number;
+            validate: (v: number) => "must be at least 1 (a backstop below the soft boundary would fire before the model is ever asked to wrap up)" | undefined;
+            summary: string;
+            format: (v: number) => string;
+        };
+    };
+    wake: {
+        nameDropInclude: {
+            path: string;
+            shipped: readonly string[];
+            validate: typeof stringArray;
+            summary: string;
+            format: (v: readonly string[]) => string;
+        };
+        nameDropExclude: {
+            path: string;
+            shipped: readonly string[];
+            validate: typeof stringArray;
+            summary: string;
+            format: (v: readonly string[]) => string;
+        };
+        e2eDrivers: {
+            path: string;
+            shipped: readonly E2eDriverIdentity[];
+            validate: typeof e2eDriversProblem;
+            summary: string;
+            format: (v: readonly E2eDriverIdentity[]) => string;
+        };
+    };
+    webhooks: {
+        allowUnverified: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+        allowUnverifiedGithub: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+        allowUnverifiedNotion: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+    window: {
+        topology: {
+            path: string;
+            shipped: false;
+            summary: string;
+        };
+    };
+};
+/** A partial {@link AgentSettings} — every group and key optional. What `defineSettings` takes. */
+export type AgentSettingsOverrides = {
+    readonly [G in keyof AgentSettings]?: {
+        readonly [K in keyof AgentSettings[G]]?: AgentSettings[G][K];
+    };
+};
+/**
+ * Validate a deployment's behaviour overrides and freeze them. Called at MODULE LOAD in the app's
+ * own `agent/settings/settings.ts`, exactly like `defineModelPolicy` / `defineSpendBudgets` — so a bad
+ * value fails the boot (and CI, and `npm run validate:config`) rather than surfacing as a weird
+ * runtime posture nobody can trace.
+ *
+ * Rejects an unknown group or key by name. TypeScript already refuses one at compile time; this
+ * catches the JS-authored and codemod-written cases, and a typo'd knob silently doing nothing is
+ * precisely the failure config-as-code exists to remove.
+ *
+ * ⚠️ SINCE OPE-411 THIS IS THE ONLY GATE A BEHAVIOUR VALUE PASSES THROUGH. With the env parsers
+ * deleted there is no second, fail-soft path a value can arrive by — so a spec's `validate` running
+ * here is the whole of the schema's runtime type safety, not a belt beside a brace.
+ */
+export declare function defineSettings(overrides: AgentSettingsOverrides): AgentSettingsOverrides;
+/**
+ * Register this deployment's behaviour overrides. Called once at boot from
+ * `agent/lib/register-config.ts`, beside `registerConfig`.
+ *
+ * ⚠️ NOT FAIL-LOUD, unlike `registerConfig` — and the difference is deliberate. An unregistered
+ * `AppConfig` means core has no bundles, domains or bindings, so every resolve would silently deny
+ * and a throw is the only honest answer. An unregistered SETTINGS object means the deployment holds
+ * no opinion beyond the shipped ones, which is a completely valid state: it is what a fresh clone
+ * is, and what every unit test that imports one gate module in isolation is. Throwing there would
+ * make the schema's own defaults unreachable.
+ *
+ * ⭐ ALSO THE TEST SEAM. Since OPE-411 deleted the env mirrors, a test that needs a non-default
+ * posture calls this — `registerSettings({ window: { topology: true } })` — rather than assigning
+ * the setting's old variable into the environment. Pair it with {@link resetSettingsForTest}, or
+ * with {@link overrideSettingsForTest} when the test has to hold one flag while varying another, in
+ * the same way the env-flipping tests paired a save with a restore.
+ *
+ * ⚠️ DO NOT SPELL A SETTING'S OLD VARIABLE NAME NEXT TO A LITERAL `process` `.env` IN THIS FILE.
+ * `scripts/env-docs-lint.ts` inventories env reads by matching that text against raw source, with no
+ * parser and therefore no idea it is inside a comment — an illustrative example in prose registers
+ * as a real runtime read and GROWS the ratchet that this ticket exists to shrink.
+ */
+export declare function registerSettings(overrides: AgentSettingsOverrides): void;
+/** Reset to the shipped defaults — test bootstrap only. The restore half of `registerSettings`. */
+export declare function resetSettingsForTest(): void;
+/**
+ * MERGE a patch into the registered overrides — test bootstrap only.
+ *
+ * 🔴 WHY THIS EXISTS, AND WHY A TEST SHOULD USUALLY REACH FOR IT RATHER THAN `registerSettings`.
+ * `registerSettings` REPLACES the whole object, which is right for BOOT — a deployment has one
+ * settings declaration and one authority, and a second call meaning "merge" would make the final
+ * posture depend on module evaluation order. It is wrong for a TEST, which routinely varies one flag
+ * while holding another fixed, and where the replace semantics fail SILENTLY: a file that pins
+ * `delegation.oneshotAgent: false` for the whole run and then calls
+ * `registerSettings({ connectors: { dmOnly: true } })` has just re-armed delegation and every mount
+ * assertion after it is answering a different question than its label claims.
+ *
+ * That is the exact failure the env mirrors used to hide, because assigning a single variable was
+ * naturally a per-key patch. This restores the ergonomic without the two-sources-of-truth problem.
+ *
+ * Group-shallow, by design: it merges per group and per key, so patching `connectors.dmOnly` leaves
+ * a previously-patched `connectors.opTiering` alone. Values are NOT validated — `defineSettings` is
+ * the gate for anything a deployment declares, and a test that wants an out-of-range value to prove
+ * a clamp should be able to set one.
+ */
+export declare function overrideSettingsForTest(patch: AgentSettingsOverrides): void;
+/**
+ * The resolved behaviour settings for this process.
+ *
+ * PRECEDENCE, uniform across every setting: the app's registered overrides, then the shipped
+ * default. `models.stack` alone consults an environment variable first, and it is a harness seam
+ * rather than a behaviour opinion (see the header).
+ *
+ * 🔴 RESOLVED FRESH ON EVERY CALL — no module-level cache, by design and pinned by
+ * `packages/core/scripts/settings-test.ts`. The reason is REGISTRATION ORDER, not env freshness:
+ * ESM evaluates a core module's body BEFORE `agent/lib/register-config.ts` runs `registerSettings`,
+ * so any value cached at first read risks being the pre-registration one — the deployment's own
+ * config file silently doing nothing. Resolving per call also makes the test seam work, since
+ * `registerSettings` mid-run must be observed by the next read. The cost is a dozen property reads
+ * per call, which is nothing beside anything that consults them.
+ *
+ * 🔴 NEVER RESOLVE ONE OF THESE INTO A MODULE-LEVEL `const` IN `packages/core`, for that same
+ * reason. If a value has to be shared, export a FUNCTION that calls this per invocation (the shape
+ * `channels/turn-delivery.ts` and `channels/backscroll-cluster.ts` use since OPE-409; before it they
+ * were `const`s, and the schema had to refuse `rotation.*` app overrides by name to say so). Only
+ * APP-tier modules — `agent/agent.ts`, `agent/sandbox/sandbox.ts` — may read at module load, because
+ * they import `register-config.js` BEFORE THEIR OWN READ (`sandbox.ts` imports fourteen other
+ * modules ahead of it, so "first" would be wrong). `npm run lint:settings-boot-order` (OPE-1137) enforces
+ * this rule on the BOOT GRAPHS OF THE DECLARED ENTRIES rather than only stating it: it boots each
+ * of them with a recorder in the override slot, and reds on any read that resolves the registered
+ * slot before `registerSettings` runs. A module neither entry reaches before registration is out
+ * of its scope — see the 🔴 limits list in `scripts/settings-read-probe.ts`.
+ *
+ * 🔴 AND NEVER PUT A DATABASE READ BEHIND THIS. `rotationTrigger` and the backscroll bounds call it
+ * PER WAKE; it is on the hot path of every turn and must stay a pure in-memory resolution.
+ *
+ * `env` is a parameter so a caller that has to prove what happens on an absent or unreadable
+ * environment states it as an argument instead of mutating the process. Default `process.env` ⇒
+ * every production call site is unchanged.
+ *
+ * `overrides` is a parameter because a caller that runs BEFORE `registerSettings` cannot use the
+ * registered slot, and reading it anyway would be an import-order race with a silent losing branch
+ * (OPE-398). `agent/model/models.ts` is exactly that caller —
+ * it is imported by the config that registers — so it passes the app's `SETTINGS_OVERRIDES`
+ * directly. Default `registered` ⇒ every other call site is unchanged.
+ */
+export declare function getSettings(env?: NodeJS.ProcessEnv, overrides?: AgentSettingsOverrides): AgentSettings;
+/** One row of the generated operator table — see `scripts/settings-docs.ts`. */
+export interface SettingDoc {
+    readonly path: string;
+    readonly env?: string;
+    /** The shipped default, rendered. */
+    readonly shipped: string;
+    readonly summary: string;
+}
+/**
+ * Every setting, flattened and sorted by path — what `scripts/settings-docs.ts` renders into
+ * `docs/deploy/configuration-reference.md` and what `npm run lint:settings-docs` checks the doc
+ * against. Deriving the table from the schema is what makes the module (not the prose) the source
+ * of truth for the flags it owns.
+ */
+export declare function settingDocs(): readonly SettingDoc[];
+/**
+ * Every env var name this schema OWNS — the lint's list of names no other module may parse.
+ *
+ * Since OPE-411 this is a ONE-ENTRY list (`OE_MODEL_STACK`, the harness seam). It stays a derived
+ * list rather than a constant so that the ratchet in `scripts/settings-docs.ts` keeps working if a
+ * second seam is ever argued for, and so that deleting the last one leaves the gate coherent.
+ */
+export declare function settingEnvNames(): readonly string[];
+export {};
+//# sourceMappingURL=settings.d.ts.map