@open-everywhere/core 0.1.0

package/dist/agent/subagents/contracts.js

@@ -0,0 +1,114 @@
+// TYPED OUTPUT CONTRACTS for OE's declared subagents (OPE-45).
+//
+// A declared subagent lives in the DEPLOYER app (`agent/subagents/<name>/`, eve's discovery root for
+// it), but its RESULT SHAPE is spine, not per-deploy config: the parent agent, the audit trail, and
+// any future consumer all read these fields. So the schemas live in core and each app-side
+// `agent.ts` is a thin binding — exactly the core/app split every other seam follows (AGENTS.md).
+// It also keeps `zod` out of the root app's dependency surface; core already depends on it.
+//
+// HOW THE SCHEMA BECOMES THE CONTRACT: eve's `defineAgent({ outputSchema })` is the TASK-MODE
+// default. `execution/workflow-steps.js resolveEffectiveOutputSchema` reads it when the session runs
+// in `mode: "task"` (which every subagent invocation does) and the CALLER supplied no per-call
+// schema. So the parent can call `fresh_eyes_review({ message })` with no `outputSchema` and still
+// get this exact shape back, validated, via eve's `final_output` sink. A caller that DOES pass an
+// `outputSchema` overrides it — the declared schema is the floor, not a cage.
+//
+// 🔴 THAT OVERRIDE IS ABOUT DECLARED SUBAGENTS ONLY, AND SAYING SO MATTERS (OPE-1688). The GENERIC
+// `agent` delegation verb no longer takes a caller `outputSchema` at all: OE strips the field and
+// drops it, because an unmet schema fails the child's whole turn and throws away the prose answer
+// the seat was waiting for (access/worker-continuation.ts §OPE-1688 carries the measured loss).
+// Every subagent named here mounts under its OWN tool name, so nothing below is affected.
+//
+// KEEP THESE FLAT AND SMALL. They are rendered into the parent's context as a JSON Schema and then
+// again as the result — every optional field is paid for twice. Descriptions follow the repo's
+// tool-instruction-brevity doctrine: a checkable gloss, never a tutorial.
+// BIND A CONTRACT THROUGH `modelFacingOutputSchema` (OPE-2070). eve lowers the bound schema to JSON
+// Schema at build time and builds its `final_output` tool from that JSON AFTER OE's
+// `__oeProjectToolSet` hook runs, so OPE-2068's nullable rewrite never reaches it. gpt-6-luna sends a
+// value for every property it is shown, so an optional non-nullable field gets an invented value.
+// The wrapper advertises each optional field as nullable. Its `validate` strips those nulls before
+// the contract validates. eve itself validates `final_output` against the lowered JSON only, so a
+// null the model sends reaches the parent as null; the parent's next tool call (post_pr_walkthrough's
+// `narration`) strips it at the OPE-2068 seam.
+import { z } from "zod";
+import { nullableOptionalJsonSchema, stripAddedNulls } from "../access/nullable-optional-fields.js";
+/** A declared subagent's contract, in the form its `agent.ts` binds as `outputSchema`: every optional field is nullable in the JSON Schema the model sees, and `validate` removes those nulls before the contract validates. */
+export function modelFacingOutputSchema(contract) {
+    const std = contract["~standard"];
+    let lowered;
+    const emit = (io) => (options) => nullableOptionalJsonSchema(std.jsonSchema[io]({ target: options.target }));
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "open-everywhere",
+            validate: (value) => {
+                lowered ??= std.jsonSchema.output({ target: "draft-07" });
+                return std.validate(stripAddedNulls(lowered, value));
+            },
+            jsonSchema: { input: emit("input"), output: emit("output") },
+        },
+    };
+}
+/** Severity ladder for a review finding. `nit` is deliberately part of the same scale so a reviewer
+ *  can approve WITH nits rather than inflating them to justify a block. */
+export const REVIEW_SEVERITY = ["critical", "high", "medium", "low", "nit"];
+/** What KIND of problem a finding is. Closed set so findings are groupable across reviews. */
+export const REVIEW_CATEGORY = [
+    "security",
+    "access-control",
+    "correctness",
+    "data-loss",
+    "performance",
+    "maintainability",
+    "tests",
+    "docs",
+];
+/**
+ * `fresh_eyes_review` — an independent second pass over a proposed change.
+ *
+ * FAIL-CLOSED FIELD: `evidenceSeen`. The subagent sees nothing but the caller's `message` (eve's
+ * isolation boundary — no inherited tools, no shared sandbox, no parent history), so "the caller
+ * pasted no actual change" is a state it can and must report. Its instructions require
+ * `recommendation: "block"` whenever `evidenceSeen` is false: silence about a change you were never
+ * shown must never read as approval.
+ */
+export const FRESH_EYES_REVIEW_OUTPUT = z.object({
+    recommendation: z.enum(["approve", "block"]).describe("block if any finding is critical/high, or if evidenceSeen is false"),
+    summary: z.string().describe("One or two sentences: what the change does and the headline verdict."),
+    evidenceSeen: z.boolean().describe("Did the caller actually include the change (diff/patch/file contents)? False forces block."),
+    findings: z
+        .array(z.object({
+        severity: z.enum(REVIEW_SEVERITY),
+        category: z.enum(REVIEW_CATEGORY),
+        title: z.string().describe("One line, imperative or declarative — not a question."),
+        detail: z.string().describe("Why it matters and what to do about it."),
+        location: z.string().optional().describe("file:line or symbol, when the change text gives one."),
+    }))
+        .describe("Empty when the change is clean. Do not pad."),
+    /**
+     * OPE-257 — the PR-WALKTHROUGH extension, and the reason it is OPTIONAL rather than required.
+     *
+     * `findings` answers "what could go wrong". A reviewer being walked through a change first needs
+     * the prior question — *what does this mean for the thing I am deciding about* — and that is not a
+     * problem list: a widening with no problem in it still has to be explained. So the walkthrough
+     * flow (tools/walk_pr.ts) asks for one entry per scope/domain/hook the computed facts name.
+     *
+     * An ordinary second-pass review has nothing to be per-subject ABOUT, so requiring it would force
+     * every plain review to emit an empty array or invent subjects — which is why the field is
+     * optional rather than a fifth required one. `subject` is checked against the facts by the renderer
+     * (review/pr-walkthrough.ts) and labelled anchored or not: a reading about something the facts
+     * never mention is not necessarily wrong, but it must not read with the authority of one that is.
+     */
+    meaning: z
+        .array(z.object({
+        subject: z.string().describe("What this reading is about — a scope/domain/hook/file, named exactly as the facts name it."),
+        says: z.string().describe("One plain sentence: what the change means for that subject."),
+    }))
+        .optional()
+        .describe("Per-subject plain-language readings. Fill it when the caller asked for a walkthrough; omit it otherwise."),
+});
+// `recall_verification` was DELETED OUTRIGHT by OPE-301 (ruled 2026-08-07: "a solution looking for
+// a problem" — no safety property depended on it; a zero-tool entailment check over evidence the
+// caller itself quotes verifies the caller's own framing, not the memory). If a recall-verification
+// need re-emerges, the honest shape is a WORKER that greps the silo itself, not a schema here.
+//# sourceMappingURL=contracts.js.map

package/dist/agent/subagents/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../agent/subagents/contracts.ts"],"names":[],"mappings":"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"}

package/dist/agent/subagents/declared.d.ts

@@ -0,0 +1,44 @@
+/** One declared subagent as read off disk: its directory name plus the files that matter. */
+export interface DeclaredSubagentSource {
+    /** Directory name under `agent/subagents/` — also the model-visible tool name. */
+    readonly name: string;
+    /** Source of `agent.ts`, or undefined when the file is missing. */
+    readonly agentSource: string | undefined;
+    /** True when `instructions.md` (or `.ts`) exists. */
+    readonly hasInstructions: boolean;
+    /** File slugs present in `tools/` (basename without extension). */
+    readonly toolFiles: ReadonlyMap<string, string>;
+    /** File slugs present in `hooks/`. */
+    readonly hookFiles: ReadonlySet<string>;
+    /** Directory names present at the subagent root (for the unsupported-slot check). */
+    readonly directories: ReadonlySet<string>;
+}
+/** Names of the declared subagents, sorted — the surface list the two manifest lints consume. */
+export declare function listDeclaredSubagents(subagents: readonly DeclaredSubagentSource[]): string[];
+/**
+ * Verify every declared subagent carries the OE conventions. Pure; returns human-readable problems,
+ * empty = clean.
+ *
+ * `frameworkToolNames` is eve's DEFAULT-MOUNTED set and nothing else — the tools eve registers for
+ * `all-local-nodes`, which is what a declared subagent (a local node, never the root) receives.
+ * Callers read it from packages/core/scripts/eve-framework-tools.ts. The other two classes must NOT be passed:
+ * ROOT-ONLY names (`agent`) and OPT-IN names (`glob`, `grep`) are not
+ * mounted here, and since eve 0.45.0 a `disableTool()` sentinel with nothing under it is a hard
+ * BUILD ERROR ("Source `tools/<x>.ts` disables a slot with no lower-precedence source"), not merely
+ * noise. So this check is exact in both directions: a missing sentinel is a hole, an extra one
+ * fails the deploy. `toolNames` is the root's authored tool surface, for the collision check eve
+ * itself fails the build on.
+ *
+ * `requiredFrameworkToolNames` is the subset of `frameworkToolNames` eve REFUSES to let an app
+ * disable (eve 0.52.0's `compiler/default-tool-policy.js`; callers read it from
+ * packages/core/scripts/eve-framework-tools.ts). Those slots take an authored REPLACEMENT tool
+ * instead of a sentinel — that is eve's own sanctioned route, and it keeps the zero-hands invariant,
+ * because the mounted body is OE's and reaches nothing. The demand stays exact in both directions:
+ * a sentinel in a required slot is a BUILD ERROR, a missing file re-mounts eve's framework default
+ * unfenced, and a real tool in a non-required slot is a posture change. 🔴 This is why the set is
+ * READ from eve rather than listed here: when eve makes a second slot required, this lint reds with
+ * a reason that names the slot and the invariant, instead of the build throwing eve's own message
+ * after every gate went green (OPE-1537).
+ */
+export declare function checkDeclaredSubagents(subagents: readonly DeclaredSubagentSource[], frameworkToolNames: readonly string[], toolNames: readonly string[], requiredFrameworkToolNames?: readonly string[]): string[];
+//# sourceMappingURL=declared.d.ts.map

package/dist/agent/subagents/declared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared.d.ts","sourceRoot":"","sources":["../../../agent/subagents/declared.ts"],"names":[],"mappings":"AAuBA,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3C;AAaD,iGAAiG;AACjG,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,EAAE,CAE5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,sBAAsB,EAAE,EAC5C,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,0BAA0B,GAAE,SAAS,MAAM,EAAO,GACjD,MAAM,EAAE,CAmHV"}

package/dist/agent/subagents/declared.js

@@ -0,0 +1,152 @@
+// DECLARED-SUBAGENT ENUMERATION + STRUCTURAL CHECK (OPE-45).
+//
+// eve mounts every directory under the app's `agent/subagents/` as a specialist agent and lowers it
+// into a model-visible tool named after the DIRECTORY — bare, unprefixed, in the same runtime tool
+// namespace as `agent/tools/*` (eve docs, subagents.mdx). Three consequences drive this module:
+//
+//   1. The name is STATICALLY KNOWN, so the two fail-closed manifests (access/consequence.ts and
+//      access/window-gate-manifest.ts) can and must cover it — a new subagent must not be able to
+//      land on the model's tool surface un-tiered and un-postured. Both lints call
+//      {@link listDeclaredSubagents} for that third surface source.
+//   2. eve's ISOLATION BOUNDARY means a declared subagent inherits nothing authored from the root —
+//      not tools, not hooks, not skills, not the sandbox. An absent slot falls back to the FRAMEWORK
+//      default, never to the root's narrowed version. So "author nothing" is fail-OPEN: the child
+//      would hold bash/web_fetch/web_search/write_file with no egress hook behind them, since hooks
+//      are not inherited either. {@link checkDeclaredSubagents} pins the opposite invariant —
+//      every registered framework tool disabled, explicitly, per subagent.
+//   3. Spend has the same shape of hole: without an authored `hooks/spend.ts` the child's model calls
+//      never reach OE's ledger, so delegated work burns tokens off the books. Pinned here too.
+//
+// PURE — no eve import, no filesystem: the caller (scripts/subagents-lint.ts) reads the tree and
+// passes it in, the same shape checkConsequenceRegistry / checkWindowGateManifest use, so the unit
+// test can exercise every failure mode against a crafted tree.
+/** A subagent directory name must be a legal tool name AND match the repo's tool-naming convention:
+ *  lower snake_case. eve accepts any directory name, but the lowered tool sits beside `read_file` /
+ *  `open_pull_request` in one namespace, and a stray dash there reads as a different vocabulary.
+ *  (The plugin EXTRACTOR generates dashed, `__`-namespaced dirs on purpose — those are machine-owned
+ *  and namespaced by plugin; this rule governs hand-authored ones.) */
+const SUBAGENT_NAME_RE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+/** Directory slots eve supports inside a local subagent package (discover-subagent.js). `schedules`
+ *  is deliberately absent — eve REJECTS the build for it (schedules are root-only). */
+const SUPPORTED_SUBAGENT_DIRS = new Set(["tools", "skills", "hooks", "connections", "sandbox", "lib", "subagents"]);
+/** Names of the declared subagents, sorted — the surface list the two manifest lints consume. */
+export function listDeclaredSubagents(subagents) {
+    return subagents.map((s) => s.name).sort();
+}
+/**
+ * Verify every declared subagent carries the OE conventions. Pure; returns human-readable problems,
+ * empty = clean.
+ *
+ * `frameworkToolNames` is eve's DEFAULT-MOUNTED set and nothing else — the tools eve registers for
+ * `all-local-nodes`, which is what a declared subagent (a local node, never the root) receives.
+ * Callers read it from packages/core/scripts/eve-framework-tools.ts. The other two classes must NOT be passed:
+ * ROOT-ONLY names (`agent`) and OPT-IN names (`glob`, `grep`) are not
+ * mounted here, and since eve 0.45.0 a `disableTool()` sentinel with nothing under it is a hard
+ * BUILD ERROR ("Source `tools/<x>.ts` disables a slot with no lower-precedence source"), not merely
+ * noise. So this check is exact in both directions: a missing sentinel is a hole, an extra one
+ * fails the deploy. `toolNames` is the root's authored tool surface, for the collision check eve
+ * itself fails the build on.
+ *
+ * `requiredFrameworkToolNames` is the subset of `frameworkToolNames` eve REFUSES to let an app
+ * disable (eve 0.52.0's `compiler/default-tool-policy.js`; callers read it from
+ * packages/core/scripts/eve-framework-tools.ts). Those slots take an authored REPLACEMENT tool
+ * instead of a sentinel — that is eve's own sanctioned route, and it keeps the zero-hands invariant,
+ * because the mounted body is OE's and reaches nothing. The demand stays exact in both directions:
+ * a sentinel in a required slot is a BUILD ERROR, a missing file re-mounts eve's framework default
+ * unfenced, and a real tool in a non-required slot is a posture change. 🔴 This is why the set is
+ * READ from eve rather than listed here: when eve makes a second slot required, this lint reds with
+ * a reason that names the slot and the invariant, instead of the build throwing eve's own message
+ * after every gate went green (OPE-1537).
+ */
+export function checkDeclaredSubagents(subagents, frameworkToolNames, toolNames, requiredFrameworkToolNames = []) {
+    const problems = [];
+    const tools = new Set(toolNames);
+    const required = new Set(requiredFrameworkToolNames);
+    // A required slot eve does not mount is a contradiction the caller must resolve, not something to
+    // silently drop: it would demand a replacement file in a slot that never mounts, and a name in
+    // this set also EXEMPTS its slot from the sentinel demand, which is the fail-open direction. The
+    // reader (packages/core/scripts/eve-framework-tools.ts) throws on it too; this is the pure half's
+    // own guard, so `subagent-session-test.ts` can drive it without an installed eve.
+    const mounted = new Set(frameworkToolNames);
+    for (const name of [...required].sort()) {
+        if (!mounted.has(name)) {
+            problems.push(`"${name}" is declared a REQUIRED framework tool slot but is not in the default-mounted set — one of the two reads of the installed eve is stale, and until that is resolved this lint cannot say whether the slot takes a replacement tool or a disableTool() sentinel`);
+        }
+    }
+    for (const s of subagents) {
+        const at = `agent/subagents/${s.name}`;
+        if (!SUBAGENT_NAME_RE.test(s.name)) {
+            problems.push(`subagent directory "${s.name}" is not lower snake_case — the directory name IS the model-visible tool name and shares one namespace with agent/tools/*; rename it to match (e.g. fresh_eyes_review)`);
+        }
+        if (tools.has(s.name)) {
+            problems.push(`subagent "${s.name}" collides with the tool of the same name — eve rejects the build rather than picking a winner (subagents.mdx); rename one`);
+        }
+        // The config module. eve itself fails the build without a `description`; the OUTPUT SCHEMA is
+        // OE's own rule — an untyped subagent returns prose, and a prose result is not something the
+        // caller (or the audit trail) can act on. Source-level (a regex over the authored file) for the
+        // same reason every other manifest lint here is: it must fail in CI without resolving the graph.
+        if (s.agentSource === undefined) {
+            problems.push(`${at}/agent.ts is missing — every declared subagent needs a defineAgent() config module (eve fails the build without one)`);
+        }
+        else {
+            if (!/\bdescription\s*:/u.test(s.agentSource)) {
+                problems.push(`${at}/agent.ts has no \`description\` — it is the tool description the parent reads to decide whether to delegate, and eve rejects the build without it`);
+            }
+            if (!/\boutputSchema\s*:/u.test(s.agentSource)) {
+                problems.push(`${at}/agent.ts has no \`outputSchema\` — a declared subagent must return a TYPED result (eve applies the authored schema in task mode when the caller passes none); declare it in packages/core/agent/subagents/contracts.ts and bind it here`);
+            }
+            else if (!/\boutputSchema\s*:\s*modelFacingOutputSchema\(/u.test(s.agentSource)) {
+                problems.push(`${at}/agent.ts binds \`outputSchema\` without \`modelFacingOutputSchema(...)\` — eve builds the final_output tool after OE's tool-set hook, so an optional field stays non-nullable and the model fills it with an invented value (OPE-2070); bind \`outputSchema: modelFacingOutputSchema(<contract>)\``);
+            }
+        }
+        if (!s.hasInstructions) {
+            problems.push(`${at}/instructions.md is missing — a subagent inherits NO instructions from the root (eve's isolation boundary), so without its own file it runs on the framework default prompt`);
+        }
+        // ZERO HANDS — the fail-closed invariant. Every registered framework tool must be explicitly
+        // taken over, because an absent tools/ entry mounts eve's built-in, unfenced (no inherited
+        // egress hook). HOW it is taken over depends on what eve permits for that slot: a sentinel
+        // where eve allows one, an authored no-op replacement where eve requires the slot filled.
+        // Anything else in tools/ is a real authored tool and must be a deliberate, reviewed act.
+        for (const fw of frameworkToolNames) {
+            const src = s.toolFiles.get(fw);
+            const isRequired = required.has(fw);
+            const fill = isRequired
+                ? "Author a no-op replacement tool that reaches nothing — eve REQUIRES this slot and refuses `disableTool()` for it."
+                : "Add `export default disableTool();`";
+            if (src === undefined) {
+                problems.push(`${at}/tools/${fw}.ts is missing — an absent slot falls back to eve's FRAMEWORK default, not to the root's narrowed version, and the root's egress/spend hooks are not inherited either, so ${fw} would mount UNFENCED here. ${fill}`);
+                continue;
+            }
+            // 🔴 THE DEFAULT EXPORT, NOT A MENTION (OPE-1537). This used to be `/\bdisableTool\s*\(\s*\)/`
+            // over the whole file, which reads a COMMENT as a sentinel — so a real, hands-on tool whose
+            // header merely discussed `disableTool()` passed the zero-hands check. Every sentinel in the
+            // tree is the same one line, so pinning the export is both stricter and exact.
+            const isSentinel = /^\s*export\s+default\s+disableTool\s*\(\s*\)\s*;?\s*$/mu.test(src);
+            if (isRequired && isSentinel) {
+                problems.push(`${at}/tools/${fw}.ts is a \`disableTool()\` sentinel, but eve declares "${fw}" a REQUIRED framework tool slot and throws at build on a sentinel for it. Export a no-op replacement tool from this file instead — one that reaches nothing, so the slot is filled and the subagent still holds no hands. Deleting the file is NOT the fix: it re-mounts eve's framework default unfenced.`);
+            }
+            else if (!isRequired && !isSentinel) {
+                problems.push(`${at}/tools/${fw}.ts is not a \`disableTool()\` sentinel — a declared subagent is a zero-hands reasoning pass; giving it a real tool is a posture change that must also move its rows in access/consequence.ts and access/window-gate-manifest.ts`);
+            }
+        }
+        for (const authored of s.toolFiles.keys()) {
+            if (!frameworkToolNames.includes(authored)) {
+                problems.push(`${at}/tools/${authored}.ts is an authored tool — declared subagents are zero-hands by convention (a subagent session carries no surface binding, so any tool there must invent or trust a scope). If this is deliberate, re-tier "${s.name}" in access/consequence.ts and give it a grain matrix in access/window-gate-manifest.ts first, then update this lint.`);
+            }
+        }
+        // Spend attribution — hooks are not inherited, so without this the child's tokens are invisible.
+        if (!s.hookFiles.has("spend")) {
+            problems.push(`${at}/hooks/spend.ts is missing — hooks are NOT inherited from the root, so a delegated child's model calls would never reach OE's ledger or the monthly cap. Add \`export { default } from "@open-everywhere/core/agent/hooks/spend.js";\``);
+        }
+        for (const dir of s.directories) {
+            if (dir === "schedules") {
+                problems.push(`${at}/schedules/ is not supported — schedules are root-only and eve fails the build for a subagent that declares them`);
+            }
+            else if (!SUPPORTED_SUBAGENT_DIRS.has(dir)) {
+                problems.push(`${at}/${dir}/ is not a slot eve discovers inside a subagent package — it will be ignored with a diagnostic; remove it or move it under one of: ${[...SUPPORTED_SUBAGENT_DIRS].sort().join(", ")}`);
+            }
+        }
+    }
+    return problems;
+}
+//# sourceMappingURL=declared.js.map

package/dist/agent/subagents/declared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared.js","sourceRoot":"","sources":["../../../agent/subagents/declared.ts"],"names":[],"mappings":"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"}

package/dist/agent/testing/driver-allowlist.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ONE e2e driver identity: the SURFACE it drives, and the PRINCIPAL that surface's own normalized
+ * read carries for it (OPE-1754).
+ *
+ * 🔴 IT IS ONE IDENTITY, NEVER A SET. There is no syntax here for "any bot on this surface" and
+ * none is wanted: the grant is "these named identities", and a longer list is a longer roll of
+ * named identities rather than a wider door. The same property the Slack-only lever this replaced
+ * already had.
+ *
+ * `principal` is spelled in the vocabulary the SURFACE's own door or fetch already uses, because a
+ * translation layer here would be a second place for the two to disagree:
+ *   • `slack` — `teamId:botId`, the workspace and the posting app's `B…` bot record. BOTH planes
+ *     build that pair through {@link isE2eDriver} from a workspace and an author id: the DM door
+ *     from the event's `teamId` and `bot_id`, the seat's catch-up from its channel key's workspace
+ *     segment and the fetched line's `bot_id` (`slack-wake-backscroll.ts` `normalizeOne`).
+ *   • `discord` — the driver bot's USER id (a snowflake), which is what
+ *     `discord-backscroll.ts` puts in `NormalizedMessage.authorId` for a foreign bot.
+ *   • `notion` — the driver integration's bot id (a UUID), which is what `notion-catch-up.ts` puts
+ *     in `NormalizedMessage.authorId`.
+ *     🔴 AND ON THIS SURFACE THE ENTRY IS USUALLY INERT (OPE-1857). The seat carve-out only fires on
+ *     a `bot` sender (`withE2eDriverAdmission`, channels/seat-catch-up.ts), and Notion serves a
+ *     comment's `created_by` as a partial user with NO `type` — so a catch-up read cannot call the
+ *     author a machine and `wide` admits the comment as a person's. The entry still covers the case
+ *     where Notion DOES state a `type`; it is not what admits the driver on an ordinary comment.
+ */
+export interface E2eDriverIdentity {
+    /** The surface's platform segment, exactly as a surface key spells it (`slack`, `discord`, …). */
+    readonly surface: string;
+    /** The ONE identity this entry admits, in that surface's own id vocabulary. */
+    readonly principal: string;
+}
+/**
+ * Why a configured `wake.e2eDrivers` value is not one, or `undefined` when it is well-formed.
+ *
+ * The settings schema's validator, kept HERE beside the grammars it enforces so the door and the
+ * schema read one definition. Pure, and it takes `unknown` because `defineSettings` hands a
+ * JS-authored value straight through.
+ *
+ * 🔴 IT REFUSES A BLANK FIELD. A `""` principal would otherwise be an entry no identity can equal
+ * that still reads, in the operator table, as a driver being vouched for — the one shape where the
+ * declaration and the behaviour disagree silently.
+ */
+export declare function e2eDriversProblem(value: unknown): string | undefined;
+/**
+ * The principals `configured` names for ONE surface — the list a door matches a candidate against.
+ *
+ * 🔴 EMPTY IN, EMPTY OUT, AND EMPTY MEANS "ADMIT NOBODY". An unconfigured deployment yields no
+ * principals for any surface, so every door's bot drop is byte-identical to what it was before this
+ * lever existed. Pure.
+ */
+export declare function e2eDriverPrincipals(configured: readonly E2eDriverIdentity[], surface: string): readonly string[];
+/**
+ * Does `configured` name this exact identity on this exact surface? The ONE match, and BOTH doors
+ * call it — the Slack DM door (`dmDoorAdmitsDriver`) and the standing seat's carve-out
+ * (`withE2eDriverAdmission`, channels/seat-catch-up.ts) — so neither can spell a looser one.
+ *
+ * 🔴 IT TAKES THE WORKSPACE AND THE AUTHOR ID, NEVER A PRE-BUILT PRINCIPAL (OPE-1969). A caller that
+ * built the string itself was a caller that could build it differently, and one did: the seat's
+ * catch-up passed a Slack `bot_id` with no workspace, which no `T…:B…` entry can equal, so the
+ * carve-out was inert on Slack seats while the DM door admitted the same bot. The spelling now lives
+ * in {@link driverPrincipalFor} alone.
+ *
+ * 🔴 WHOLE-VALUE EQUALITY, on BOTH fields. No prefixes, no wildcards, no case folding, and an absent
+ * or empty author id matches nothing rather than matching the first entry. 🔴 THE PRINCIPAL IS WHAT
+ * BOUNDS THE REACH, and it differs per surface: a Slack entry carries its workspace in the pair, so
+ * a driver named for one workspace has no standing in another; a Discord or Notion entry names a
+ * globally unique vendor id and so reaches that identity wherever it speaks on its surface. Pure.
+ */
+export declare function isE2eDriver(configured: readonly E2eDriverIdentity[], surface: string, workspace: string | undefined, authorId: string | undefined): boolean;
+/** Parse `OE_TEST_DRIVER_IDS` — comma-separated pairs: Discord `guildId:botUserId`
+ *  (snowflakes) or Slack `teamId:botId` (`T…:B…`). Malformed or empty segments are
+ *  dropped silently (fail-closed: parsing can only narrow). Pure. */
+export declare function parseDriverAllowlist(raw: string | undefined): ReadonlySet<string>;
+/**
+ * Is this bot author an allowlisted e2e driver FOR THIS GUILD? False for everything else:
+ * no guild (DMs), no allowlist, wrong guild, wrong bot. Pure given an injected set; the
+ * default reads the env once per call (cheap string ops; env is stable per instance).
+ */
+export declare function isAllowedDriver(guildId: string | undefined, botUserId: string, allowlist?: ReadonlySet<string>): boolean;
+/**
+ * Is this Slack bot record an allowlisted e2e driver FOR THIS WORKSPACE? Same posture as
+ * the Discord check: exact `teamId:botId` match, false on any missing half, no allowlist →
+ * always false. `botId` is the message's `bot_id` (the posting APP's B… record) — the
+ * driver's user-token posts carry it alongside the human `user`, and it's the app, not the
+ * human, we vouch for. OE's own replies carry a different bot record, so loop safety holds.
+ */
+export declare function isAllowedSlackDriver(teamId: string | undefined, botId: string | undefined, allowlist?: ReadonlySet<string>): boolean;
+/**
+ * SURFACE-AGNOSTIC membership check: is `workspace:authorId` an allowlisted e2e driver pair,
+ * whatever the platform? The generalisation both isAllowedDriver (Discord `guildId:botUserId`)
+ * and isAllowedSlackDriver (Slack `teamId:botId`) specialise — the allowlist stores plain
+ * `workspace:id` strings, so the wake-trust SEAM (identity/wake-trust.ts), which holds only a
+ * surface-neutral workspace + author id (the workspace segment of the domain-grain channelKey +
+ * the message author id), can decide membership without knowing which surface it is on. This is
+ * the ONE place trust is lifted for a driver, so it is deliberately the same fail-closed posture:
+ * any missing half, or an empty allowlist (default, no OE_TEST_DRIVER_IDS), → false. Pure given an
+ * injected set; the default reads the env once (cheap, env stable per instance). Note the Slack
+ * driver never reaches this lift — it posts via a human xoxp token, so it arrives authorIsBot=false
+ * and its author id is the human `user`, not the `B…` bot record the allowlist stores; only a bot
+ * author (Discord's driver) is ever floored to relay and needs the carve-out.
+ */
+export declare function isAllowlistedDriverAuthor(workspace: string | undefined, authorId: string | undefined, allowlist?: ReadonlySet<string>): boolean;
+//# sourceMappingURL=driver-allowlist.d.ts.map

package/dist/agent/testing/driver-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver-allowlist.d.ts","sourceRoot":"","sources":["../../../agent/testing/driver-allowlist.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,iBAAiB;IAChC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAgBpE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEhH;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAIT;AAED;;qEAEqE;AACrE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAQjF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,WAAW,CAAC,MAAM,CAAwD,GACpF,OAAO,CAGT;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,GAAE,WAAW,CAAC,MAAM,CAAwD,GACpF,OAAO,CAGT;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,GAAE,WAAW,CAAC,MAAM,CAAwD,GACpF,OAAO,CAGT"}