@open-everywhere/core 0.1.0

package/agent/subagents/declared.ts

@@ -0,0 +1,201 @@
+// 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.
+
+/** 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>;
+}
+
+/** 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: readonly DeclaredSubagentSource[]): string[] {
+  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: readonly DeclaredSubagentSource[],
+  frameworkToolNames: readonly string[],
+  toolNames: readonly string[],
+  requiredFrameworkToolNames: readonly string[] = [],
+): string[] {
+  const problems: string[] = [];
+  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;
+}

package/agent/testing/driver-allowlist.ts

@@ -0,0 +1,239 @@
+// E2E driver-bot allowlist — the ONE deliberate, narrow exception to the "never act on
+// another bot" loop-safety rule (item 29). Full-path
+// integration testing needs a second bot that acts like a user in a real guild channel so
+// the REAL agent replies; Discord bans user-token automation (selfbots), so the driver must
+// be a bot — and without this seam the gateway drops its messages before any gate runs.
+//
+// SAFETY POSTURE (all four load-bearing):
+//   - FAIL-CLOSED, DEFAULT OFF: no `OE_TEST_DRIVER_IDS` env → empty set → behaviour is
+//     byte-for-byte the unconditional bot-drop. Malformed entries are DISCARDED, never
+//     widened; a parse surprise can only shrink the allowlist.
+//   - GUILD-PINNED BY FORMAT: entries are `guildId:botUserId` pairs — there is no syntax
+//     for "this bot everywhere", so a leaked driver token is only ever a problem in the
+//     test guild it was pinned to.
+//   - EXACT-MATCH on ids (no prefixes, no wildcards), and DMs never match (a DM has no
+//     guild — the driver exists to exercise guild surfaces).
+//   - LOUD: every acceptance is the caller's duty to log/audit (the gateway stamps it);
+//     this module just decides. Loop safety holds — the agent still can't wake ITSELF
+//     (its own id is not on the list), and the capped test channel is the circuit breaker.
+//
+// The Slack driver was PLANNED as seam-free ("xoxp = genuine user messages") — DISPROVEN
+// live 2026-07-07: Slack stamps `bot_id` on messages an app posts even with a USER token,
+// so the driver's posts trip every bot gate (eve's author.isBot on mentions → our
+// onInbound null-auth → session binds external/memoryless; slack-events' authorIsBot →
+// engaged/stop/name-drop wakes dropped). The mention leg still REPLIED (eve wakes without
+// our auth), which is why the break looked partial. So Slack rides the same allowlist,
+// pinned `teamId:botId` (the app's B… bot record — NOT the installing user's U… id, which
+// is a real human).
+//
+// THE SEAT DOORS RIDE A SECOND, NARROWER LEVER — NOT THIS ONE (OPE-1023, OPE-1754). This allowlist
+// admits a driver at the Slack engagement and mention doors. The Slack DM door and the standing
+// seat's admission policy read `wake.e2eDrivers`, a settings entry naming one bot identity per
+// entry, empty by default. The split is deliberate: a seat holds a window token, delegation and
+// memory, so admitting a bot there is a strictly larger grant than admitting one in a watched
+// channel, and it is made by its own reviewed diff. The lever holds a LIST because our own e2e pack
+// drives with more than one driver account (OPE-1739) — every element is still one NAMED identity,
+// and nothing in the grammar reaches wider.
+
+const DISCORD_PAIR = /^\d+:\d+$/; // guildId:botUserId — snowflakes only
+
+/**
+ * The Slack driver-pair GRAMMAR: `teamId:botId` — a `T…` workspace and the posting app's `B…` bot
+ * record. MODULE-PRIVATE, and it stays that way: both levers that spell this pair live in this file
+ * — the `OE_TEST_DRIVER_IDS` allowlist below, and {@link e2eDriversProblem}, which validates the
+ * `slack` entries of the `wake.e2eDrivers` setting (OPE-1023, generalised by OPE-1754). One
+ * definition, so the two can never disagree about what a Slack driver identity looks like.
+ */
+const SLACK_DRIVER_PAIR = /^T[A-Z0-9]+:B[A-Z0-9]+$/;
+
+/**
+ * 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;
+}
+
+/** The `surface` GRAMMAR: the platform segment of a surface key — lowercase, no separators. */
+const DRIVER_SURFACE = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * 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 function e2eDriversProblem(value: unknown): string | undefined {
+  const bad = "must be an array of { surface, principal } entries, each naming ONE bot identity (e.g. { surface: \"slack\", principal: \"T0123ABCD:B0456EFGH\" })";
+  if (!Array.isArray(value)) return bad;
+  for (const entry of value) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return bad;
+    const { surface, principal } = entry as { surface?: unknown; principal?: unknown };
+    if (typeof surface !== "string" || !DRIVER_SURFACE.test(surface)) return bad;
+    if (typeof principal !== "string" || principal.trim() === "" || /\s/u.test(principal)) return bad;
+    // The one surface whose principal grammar this repository can check: Slack's pair is shared with
+    // the `OE_TEST_DRIVER_IDS` allowlist above, so a typo there is catchable rather than a mystery
+    // at the DM door. The other surfaces carry opaque vendor ids and get the shape check only.
+    if (surface === "slack" && !SLACK_DRIVER_PAIR.test(principal)) {
+      return 'a "slack" principal must be a `teamId:botId` pair (e.g. "T0123ABCD:B0456EFGH")';
+    }
+  }
+  return 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 function e2eDriverPrincipals(configured: readonly E2eDriverIdentity[], surface: string): readonly string[] {
+  return configured.filter((d) => d.surface === surface).map((d) => d.principal);
+}
+
+/**
+ * THE PRINCIPAL one surface spells a driver identity with, built from the surface-neutral pair every
+ * plane already holds: the WORKSPACE (a Slack team, a Discord guild, a Notion workspace — the second
+ * segment of a domain-grain channel key) and the message's own AUTHOR id.
+ *
+ * 🔴 IT IS MODULE-PRIVATE, AND THAT IS THE POINT (OPE-1969). A second copy of this spelling is how
+ * the two planes disagreed: the Slack DM door built `teamId:botId` while the seat's catch-up handed
+ * the raw `bot_id` straight to the match, so a driver the door admitted was refused by the seat for
+ * a WORKSPACE that was never in the string. One definition, called by one predicate
+ * ({@link isE2eDriver}), so no caller can spell a third.
+ *
+ * Slack alone is a PAIR, because a Slack `bot_id` is unique only inside its workspace and the
+ * settings grammar ({@link e2eDriversProblem}) pins the `T…:B…` shape. Every other surface carries a
+ * globally unique vendor id and the author id IS the principal. A missing half yields `undefined`,
+ * which matches nothing. Pure.
+ */
+function driverPrincipalFor(surface: string, workspace: string | undefined, authorId: string | undefined): string | undefined {
+  if (authorId === undefined || authorId === "") return undefined;
+  if (surface !== "slack") return authorId;
+  if (workspace === undefined || workspace === "") return undefined;
+  return `${workspace}:${authorId}`;
+}
+
+/**
+ * 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 function isE2eDriver(
+  configured: readonly E2eDriverIdentity[],
+  surface: string,
+  workspace: string | undefined,
+  authorId: string | undefined,
+): boolean {
+  const principal = driverPrincipalFor(surface, workspace, authorId);
+  if (principal === undefined) return false;
+  return configured.some((d) => d.surface === surface && d.principal === principal);
+}
+
+/** 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 function parseDriverAllowlist(raw: string | undefined): ReadonlySet<string> {
+  const out = new Set<string>();
+  if (!raw) return out;
+  for (const entry of raw.split(",")) {
+    const pair = entry.trim();
+    if (DISCORD_PAIR.test(pair) || SLACK_DRIVER_PAIR.test(pair)) out.add(pair);
+  }
+  return out;
+}
+
+/**
+ * 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 function isAllowedDriver(
+  guildId: string | undefined,
+  botUserId: string,
+  allowlist: ReadonlySet<string> = parseDriverAllowlist(process.env.OE_TEST_DRIVER_IDS),
+): boolean {
+  if (!guildId || !botUserId) return false;
+  return allowlist.has(`${guildId}:${botUserId}`);
+}
+
+/**
+ * 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 function isAllowedSlackDriver(
+  teamId: string | undefined,
+  botId: string | undefined,
+  allowlist: ReadonlySet<string> = parseDriverAllowlist(process.env.OE_TEST_DRIVER_IDS),
+): boolean {
+  if (!teamId || !botId) return false;
+  return allowlist.has(`${teamId}:${botId}`);
+}
+
+/**
+ * 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 function isAllowlistedDriverAuthor(
+  workspace: string | undefined,
+  authorId: string | undefined,
+  allowlist: ReadonlySet<string> = parseDriverAllowlist(process.env.OE_TEST_DRIVER_IDS),
+): boolean {
+  if (!workspace || !authorId) return false;
+  return allowlist.has(`${workspace}:${authorId}`);
+}

package/agent/tools/add_label.ts

@@ -0,0 +1,68 @@
+// add_label is the neutral, entity-gated ticket-labeling verb: ONE platform-neutral tool taking a `{ platform, id }` ref, because a core tool's params never encode surface identity. The shared resolve-and-gate core — topology, support and per-surface authz — is what this tool and its two sibling verbs all ride.
+// OPEN tier: trivially reversible, the same class as a react, so no approval card — it runs on the spot and audits. Entity-gated: it mounts whenever this session has ANY work destination with a ticket-action adapter, and gates PER-PLATFORM at execute, so an unsupported surface refuses cleanly rather than hiding or faking a mutation.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { resolveEntityAction, currentTurnEntityRef, supportedEntityActionPlatforms } from "../channels/entity-actions.js";
+import { workDestinationPlatforms } from "../channels/work-destinations.js";
+import { type BindableContext } from "../identity/binding.js";
+import { getConfig } from "../access/config.js";
+import { auditToolAction } from "../audit/tool-action.js";
+import { preRegisterDynamicEntry } from "../access/window-gated.js";
+import type { Domain } from "../memory/domain.js";
+
+/** Domains, fail-soft — mirrors read_channel.ts's safeDomains (a mount/execute resolver may run
+ *  before config is registered; an empty list fails resolveWindowSources closed, never wide). */
+function safeDomains(): readonly Domain[] {
+  try {
+    return getConfig().loadDomains();
+  } catch {
+    return [];
+  }
+}
+
+const refSchema = z
+  .object({
+    platform: z.string().min(1).describe('Ticketing surface — "linear" or "github".'),
+    id: z.string().min(1).describe('Entity id — a Linear issue UUID/identifier (e.g. "ENG-42"), or GitHub "owner/repo#123".'),
+  })
+  .optional()
+  .describe("The ticket to act on. Defaults to the current turn's entity (the Linear issue or GitHub issue/PR this turn is on).");
+
+// Factored as a top-level const, because a code-owned durable step id is what lets a resumed session replay this tool instead of refusing it. Exported for the unit test.
+export const addLabelEntry = defineTool({
+  description:
+    "Add a label to a ticket — a Linear issue or a GitHub issue/PR. Entity-gated: only works on a " +
+    "ticketing surface; refuses cleanly on chat or Notion. ADDITIVE (never replaces existing labels). " +
+    "Defaults to the current turn's ticket. Reversible, no approval needed.",
+  inputSchema: z.object({
+    ref: refSchema,
+    label: z.string().min(1).describe('The label name — e.g. "bug" (must already exist on the entity\'s team/repo).'),
+  }),
+  outputSchema: z.object({ platform: z.string(), id: z.string(), label: z.string(), message: z.string() }),
+  // NO `approval:` — this is a DYNAMIC tool (defineDynamic below); a dynamic-tool approval fn
+  // fails replay lookup on a resumed session in a fresh invocation (repo-wide pin, scripts/
+  // approval-tools-test.ts's source scan) — absent === never() either way, and it's open-tier
+  // anyway (no gate needed).
+  async execute(input, ctx) {
+    const bctx = ctx as BindableContext;
+    const { ref, run } = await resolveEntityAction(bctx, "addLabel", input.ref, safeDomains());
+    const message = await run(input.label);
+    await auditToolAction(bctx, "ticket.add_label", { platform: ref.platform, entityId: ref.id, label: input.label });
+    return { platform: ref.platform, id: ref.id, label: input.label, message };
+  },
+});
+preRegisterDynamicEntry("add_label", "_single", addLabelEntry);
+
+export default defineDynamic({
+  events: {
+    "session.started": (_event, ctx) => {
+      const bctx = ctx as BindableContext;
+      // Mount on the SAME set the resolver gates on: a work destination with a ticket-action adapter — the window's sources PLUS the connectors this domain holds a work grant on — or a resolvable default entity for this turn.
+      const destinations = workDestinationPlatforms(bctx, safeDomains());
+      const adapterPlatforms = supportedEntityActionPlatforms();
+      if (!destinations.some((s) => adapterPlatforms.includes(s)) && !currentTurnEntityRef(bctx)) return null;
+      return addLabelEntry;
+    },
+  },
+});