@open-everywhere/core 0.1.0

package/agent/commands/core.ts

@@ -0,0 +1,737 @@
+// The "/oe" ZERO-INFERENCE slash command core — backlog item 23. Slash commands are the
+// control-plane escape hatch: pure logic, instant code-rendered responses, NO model turn —
+// so they keep working regardless of spend caps (a ⛔'d channel still answers "/oe budget"),
+// engagement state, or a model/gateway outage. This module is PLATFORM-NEUTRAL: it owns the
+// command grammar (`OeCommand`), the pure renderers, and the (I/O-light) execution glue.
+// Discord's wire-shape parsing lives in discord-commands.ts (nested SUB_COMMAND_GROUP
+// options); Slack's free-text parsing lives here (`parseSlackCommandText`) since it's just
+// whitespace-splitting; the Slack HTTP route itself lives in channels/slack-commands.ts.
+//
+// DELIBERATELY NOT SPEND-GATED: nothing in this file calls spend/check.ts's scopeOverBudget
+// (the turn-declining gate). That would defeat the entire point of a zero-inference command —
+// it must answer even while the scope is over budget. `/oe budget raise|clear` still goes
+// through the REAL approval-card machinery (requestApproval), which is a proposal, not a
+// spend event — an admin's click is what actually mutates anything.
+//
+// Command set (v1), namespace "oe":
+//   /oe budget                 — status: effective caps (tokens + USD) + current-month spend
+//                                 for this surface AND its workspace.
+//   /oe budget raise <usd>     — freeze + post a spend.set approval card (reuses
+//                                 tools/set_spend_limit.ts's planSetSpendLimit verbatim).
+//   /oe budget clear           — freeze + post a spend.clear approval card (reuses
+//                                 tools/clear_spend_limit.ts's planClearSpendLimit verbatim).
+//   /oe status                 — deploy sanity: deployment sha, eve pin, primary/utility model,
+//                                 memory provider, telemetry. TWO LINES ARE CONDITIONAL, and
+//                                 their absence is design rather than defect: the app version
+//                                 rides the title only where the build carries a real one
+//                                 (OPE-1057 — this repo never bumps its root package.json, so a
+//                                 stock deploy prints none and the sha is the build identity),
+//                                 and the context-window/compaction-threshold line renders only
+//                                 where the app registered both numbers (OPE-715).
+//   /oe stop                   — STOP the turn running in this channel (OPE-418). The free,
+//                                 pre-model, over-cap-proof half of the stop affordance: it
+//                                 resolves the channel's in-flight turn from the durable anchor
+//                                 registry and cancels it WITHOUT minting a session. Inference
+//                                 cannot do this job — the agent is the thing that is busy, and a
+//                                 mid-turn message queues behind the very turn it would stop.
+//   /oe rate <1-5>             — mark the model A/B test (OPE-34): record a human rating of the
+//                                 room's last champion/challenger turn. Lives in commands/rate.ts;
+//                                 this file only dispatches to it. Says "nothing to rate" — the
+//                                 normal answer — on a deployment that has not armed the test.
+//   /oe help                   — list the commands.
+//
+// Every response is EPHEMERAL (only the invoker sees the text reply) except the approval
+// card itself, which posts PUBLICLY in the channel — exactly like the model-driven
+// set_spend_limit/clear_spend_limit tools already do; slash commands just skip the model turn
+// that would otherwise have called those tools.
+
+import { unattendedFrom, type SurfaceBinding } from "../identity/binding.js";
+import { cancelAnchoredTurn, type AttachSessionForCancel } from "../channels/turn-cancel.js";
+import { turnChannelKey } from "../channels/turn-registry.js";
+import { type Caps } from "../spend/spend.js";
+import { periodOf } from "../spend/spend.js";
+import { effectiveCaps, domainNameForScope } from "../spend/caps.js";
+import { surfaceTokens, workspaceTokens } from "../spend/store.js";
+import { scopeUsdSpend } from "../spend/check.js";
+import { getProvider } from "../memory/provider.js";
+import { getConfig } from "../access/config.js";
+import { telemetryStatusLine } from "../observability/telemetry.js";
+import { domainForChannel, type Domain } from "../memory/domain.js";
+import { requestApproval } from "../approvals/flow.js";
+import { friendlyScopeLabel } from "../approvals/scope-label.js";
+import {
+  defaultScopeKey,
+  approvalPostDeps,
+  planSetSpendLimit,
+  requireCardPathHere,
+  readSpendCoverage,
+  frozenCoverage,
+  type SetSpendLimitInput,
+  type CurrentCaps,
+} from "../tools/set_spend_limit.js";
+import { planClearSpendLimit, type ClearSpendLimitInput } from "../tools/clear_spend_limit.js";
+import { domainSpendWindow, reportDomainForBinding } from "../spend/reporting.js";
+import type { SkillDomainRefusal } from "../skills/domain-skills.js";
+import { parseRateTokens, runRate, RATE_HELP_LINE, type RateCommand } from "./rate.js";
+
+/** The command namespace every registered command name / prefix rides under. */
+export const OE_COMMAND_NAME = "oe";
+
+// --- app info (deploy sanity for "/oe status") --------------------------------------------
+// Core has no import path to the deployer app's package.json or its model constants (agent.ts
+// picks the primary/utility model ids) — the SAME dependency-inversion doctrine access/config.ts
+// documents for bundles/domains/webhooks. So the app REGISTERS this small, display-only fact
+// bag at boot (agent/agent.ts, alongside the existing registerGatewayImageDescriber/
+// registerGatewayDreamJudge calls), mirroring that seam exactly. Unregistered → "unknown"
+// fields, never a thrown error — `/oe status` must always answer something.
+
+export interface AppInfo {
+  /**
+   * The deploying app's own package version — and it is NOT this deployment's build identity. Read
+   * {@link normalizeAppVersion} before you use it for anything: a repo that never bumps its root
+   * `package.json` registers the npm placeholder here, and the field then answers `unversioned`
+   * rather than a number that looks like an answer. `deploymentSha` below is the identity that
+   * separates two builds.
+   */
+  readonly version: string;
+  readonly primaryModel: string;
+  readonly utilityModel: string;
+  /**
+   * The primary model's context window, in tokens, and the absolute count at which compaction
+   * fires (OPE-715). BOTH OPTIONAL, and both must be present for the line to render: an app that
+   * registers neither is not broken, it just answers one line less. The pair is DERIVED, never
+   * authored — the window comes from the active stack's primary role and the threshold is that
+   * window times `agent.compactionThresholdPercent`. Printing it is the point: before this, an
+   * operator asking "when does this deploy compact" had to multiply two values that live in two
+   * different files, and the number in every comment about it had gone stale.
+   */
+  readonly contextWindowTokens?: number;
+  readonly compactionThresholdTokens?: number;
+  /**
+   * OPE-991 — the running-version seam. `deploymentSha` is the platform-provided commit sha
+   * (Vercel's `VERCEL_GIT_COMMIT_SHA`, read once at boot) this process was built from; `"unknown"`
+   * off Vercel (local `eve dev`) or on any platform that doesn't set it — NEVER a guess, and never
+   * a repo read (a running process cannot trust its own checkout to still match what it booted
+   * from). `evePin` is the installed `eve` package's own version, resolved from ITS `package.json`
+   * at boot rather than parsed out of this app's dependency range string, so it reports what
+   * actually got installed, not what the range merely allows.
+   */
+  readonly deploymentSha: string;
+  readonly evePin: string;
+}
+
+/**
+ * What the app-version field answers when the build carries no version of its own (OPE-1057).
+ *
+ * THE PROBLEM IT CLOSES. `/oe status` printed `v0.0.0` on every build this repo has ever made, and
+ * `0.0.0` was the HONEST value: the root `package.json` is `private` and never bumps, so the number
+ * conveyed nothing and could not separate any two builds. A reader assumes a version field means
+ * something, so a field that is always the same is worse than no field at all.
+ *
+ * WHY A SENTINEL AND NOT A NEW VERSIONING RITUAL. This repo already decided what identifies a
+ * build: the commit sha. The release records key on it
+ * (docs/deploy/self-upgrade-release-records.md), `deploymentSha` reports it, and no npm package is
+ * published to key a semantic version against. Bumping a root version on release would add a step a
+ * maintainer has to remember for a field nothing consumes.
+ *
+ * WHY THE FIELD SURVIVES AT ALL. It is inert for THIS repo, not for every deployment. An operator
+ * fork that versions its own deploy registers a real value here and keeps a real answer. The
+ * sentinel says "this build carries no version", which is a fact; `0.0.0` said "this build is
+ * version zero", which reads as one.
+ */
+export const APP_VERSION_UNVERSIONED = "unversioned";
+
+/** The npm placeholder a repo that never bumps its root `package.json` carries. */
+const UNVERSIONED_PLACEHOLDER = "0.0.0";
+
+/**
+ * Map a raw registered version to what the two version surfaces answer. The npm placeholder and an
+ * empty string both mean "this build carries no version", so both collapse to
+ * {@link APP_VERSION_UNVERSIONED}. Everything else passes through untouched, so a fork that versions
+ * itself is unaffected.
+ *
+ * 🔴 `"unknown"` IS LEFT ALONE, and the two words are not synonyms. `unknown` means this deployment
+ * does not expose the fact — the unregistered default, and the same word `deploymentSha` and
+ * `evePin` use for the same reason (OPE-991). `unversioned` means the app DID register, and what it
+ * registered was a placeholder. Collapsing them would delete the difference between "nobody told us"
+ * and "there is nothing to tell".
+ *
+ * Applied at REGISTRATION, which is the only place both consumers share. `/oe status` and the
+ * `agent_version` tool read the same fact bag on purpose (tools/agent_version.ts), and a normaliser
+ * either of them applied for itself could drift from the other's.
+ */
+export function normalizeAppVersion(raw: string): string {
+  const v = raw.trim();
+  if (v === "" || v === UNVERSIONED_PLACEHOLDER) return APP_VERSION_UNVERSIONED;
+  return v;
+}
+
+/** Does this deployment carry a version worth printing as one? False for BOTH non-answers — a
+ *  placeholder build and an app that never registered. Neither should render as `v<something>`. */
+export function hasRealAppVersion(info: AppInfo): boolean {
+  return info.version !== APP_VERSION_UNVERSIONED && info.version !== "unknown";
+}
+
+const UNKNOWN_APP_INFO: AppInfo = {
+  version: "unknown",
+  primaryModel: "unknown",
+  utilityModel: "unknown",
+  deploymentSha: "unknown",
+  evePin: "unknown",
+};
+let registeredAppInfo: AppInfo = UNKNOWN_APP_INFO;
+
+/** Register the deploy's display info for `/oe status`. Called once at startup. The version is
+ *  normalised HERE so both version surfaces answer the same word — see {@link normalizeAppVersion}. */
+export function registerAppInfo(info: AppInfo): void {
+  registeredAppInfo = { ...info, version: normalizeAppVersion(info.version) };
+}
+
+export function getAppInfo(): AppInfo {
+  return registeredAppInfo;
+}
+
+/** Test seam: reset to the unregistered default. */
+export function resetAppInfo(): void {
+  registeredAppInfo = UNKNOWN_APP_INFO;
+}
+
+// --- command grammar (pure) ---------------------------------------------------------------
+
+export type OeCommand =
+  | { readonly kind: "help" }
+  | { readonly kind: "status" }
+  | { readonly kind: "budget-status" }
+  | { readonly kind: "budget-raise"; readonly usd: number }
+  | { readonly kind: "budget-clear" }
+  /** Stand down the turn running in this channel (OPE-418) — free, pre-model, over-cap-proof. */
+  | { readonly kind: "stop" }
+  /** Mark the model A/B test (OPE-34) — the whole command lives in commands/rate.ts. */
+  | RateCommand
+  /** Malformed/unknown input — the message is already user-facing (rendered verbatim). */
+  | { readonly kind: "error"; readonly message: string };
+
+/**
+ * Parse a "budget" subcommand's rest-tokens (shared by Slack's whitespace-split text).
+ * Exported so both the Slack parser below and tests can exercise it directly.
+ */
+function parseBudgetTokens(rest: readonly string[]): OeCommand {
+  const [action, amountRaw] = rest;
+  if (!action || action === "status") return { kind: "budget-status" };
+  if (action === "clear") return { kind: "budget-clear" };
+  if (action === "raise") {
+    const usd = Number(amountRaw);
+    if (!amountRaw || !Number.isFinite(usd) || usd <= 0) {
+      return {
+        kind: "error",
+        message: `"/oe budget raise" needs a positive USD amount, e.g. "/oe budget raise 25" (got ${JSON.stringify(amountRaw ?? "")}).`,
+      };
+    }
+    return { kind: "budget-raise", usd };
+  }
+  return { kind: "error", message: `Unknown "budget" action "${action}" — try "budget", "budget raise <usd>", or "budget clear".` };
+}
+
+/**
+ * Parse a whitespace-split token list into an `OeCommand` — Slack's grammar (free `text`).
+ * No tokens (bare `/oe`) defaults to help, the friendliest landing. NEVER throws: any garbage
+ * input resolves to an `"error"` variant with a user-facing message, never an exception.
+ */
+export function parseOeCommandTokens(tokens: readonly string[]): OeCommand {
+  const [sub, ...rest] = tokens;
+  if (!sub || sub === "help") return { kind: "help" };
+  if (sub === "status") return { kind: "status" };
+  if (sub === "stop") return { kind: "stop" };
+  if (sub === "rate") return parseRateTokens(rest);
+  if (sub === "budget") return parseBudgetTokens(rest);
+  return { kind: "error", message: `Unknown command "${sub}" — try "/oe help" to see what's available.` };
+}
+
+/** Parse Slack's slash-command free `text` field ("budget raise 5", "status", "", …). */
+export function parseSlackCommandText(text: string | undefined): OeCommand {
+  const tokens = (text ?? "")
+    .trim()
+    .split(/\s+/)
+    .filter((t) => t.length > 0);
+  return parseOeCommandTokens(tokens);
+}
+
+// --- pure renderers -------------------------------------------------------------------------
+
+export function renderHelp(): string {
+  return [
+    "*/oe* — zero-inference control-plane commands (pure logic, code-rendered, no model turn — " +
+      "these work even during a spend-cap decline or a model/gateway outage):",
+    // NAMES ONLY WHAT IT ALWAYS PRINTS, then names the two conditional lines AS conditional. The
+    // app version rides the title only on a build that carries one (OPE-1057) and the window line
+    // renders only where the app registered both numbers (OPE-715), so listing either as a plain
+    // field made its absence read as a defect.
+    "• `/oe status` — deploy sanity: deployment sha, eve pin, model config, memory provider, telemetry — plus the app version and the context window with its compaction threshold, each where this deployment carries one.",
+    "• `/oe stop` — stand down the turn running in this channel (free, instant, works over a spend cap).",
+    "• `/oe budget` — this channel's and workspace's effective spend caps + current-month spend.",
+    "• `/oe budget raise <usd>` — propose a new monthly USD cap for this channel (posts an approval card; an admin decides).",
+    "• `/oe budget clear` — propose clearing this channel's spend-limit override back to config (posts an approval card).",
+    RATE_HELP_LINE,
+    "• `/oe help` — this message.",
+  ].join("\n");
+}
+
+/** Group a token count with commas. NOT `toLocaleString()`: that reads the host's locale, so the
+ *  same deploy would render `1,050,000` or `1.050.000` depending on the machine, and a test that
+ *  pins the string would go red on a runner with a different `LANG`. */
+function fmtTokenCount(n: number): string {
+  return String(Math.trunc(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+export function renderStatus(info: AppInfo, memoryProviderId: string, telemetryStatus = "unknown"): string {
+  const { contextWindowTokens: windowTokens, compactionThresholdTokens: thresholdTokens } = info;
+  return [
+    // OPE-1057 — the version rides the title ONLY when the build carries a real one. A deployment
+    // that never bumps its root package.json prints no version at all: the line below is the
+    // identity that answers "which build am I?", and a constant `v0.0.0` above it read as a second
+    // answer to the same question while conveying nothing.
+    hasRealAppVersion(info) ? `*Open Everywhere* v${info.version}` : "*Open Everywhere*",
+    `• deployment sha: \`${info.deploymentSha}\``,
+    `• eve: \`${info.evePin}\``,
+    `• primary model: \`${info.primaryModel}\``,
+    `• utility model: \`${info.utilityModel}\``,
+    // Rendered only when the app registered BOTH. The percent is recomputed from the pair rather
+    // than carried as a third field: it is display sugar, and one derived number cannot disagree
+    // with itself the way two registered ones can.
+    // The `> 0` is not defensive noise: a zero window would make the percent below `NaN%`, and a
+    // status line is the last surface that should render one.
+    ...(windowTokens !== undefined && thresholdTokens !== undefined && windowTokens > 0
+      ? [
+          `• context window: \`${fmtTokenCount(windowTokens)}\` tokens — compaction fires at ` +
+            `\`${fmtTokenCount(thresholdTokens)}\` (${Math.round((thresholdTokens / windowTokens) * 100)}%)`,
+        ]
+      : []),
+    `• memory provider: \`${memoryProviderId}\``,
+    `• telemetry: \`${telemetryStatus}\``,
+  ].join("\n");
+}
+
+/** Token caps group through {@link fmtTokenCount} for the same reason the status line does: one
+ *  grouping rule for every token count this file prints, and none of them locale-dependent. */
+function fmtCap(n: number | null | undefined, unit: "tokens" | "usd"): string {
+  if (n == null) return "uncapped";
+  return unit === "usd" ? `$${n.toFixed(2)}` : fmtTokenCount(n);
+}
+
+export interface BudgetStatusFacts {
+  readonly surfaceKey: string;
+  readonly workspaceKey: string;
+  readonly surfaceTokens: number;
+  readonly workspaceTokens: number;
+  readonly surfaceUsd: number;
+  readonly workspaceUsd: number;
+  readonly caps: Caps;
+}
+
+export function renderBudgetStatus(f: BudgetStatusFacts): string {
+  return [
+    "*Spend status* (current calendar month)",
+    // The SPENT counts group through `fmtTokenCount` exactly as the caps beside them do. They used
+    // `toLocaleString()`, which is the one thing that helper's own comment forbids: it reads the
+    // host's locale, so one deploy rendered `1,050,000` or `1.050.000` by the runner's `LANG`, and
+    // the two halves of a single line could disagree about what a thousands separator is.
+    `• this channel (\`${f.surfaceKey}\`): ${fmtTokenCount(f.surfaceTokens)} / ${fmtCap(f.caps.surfaceMonthlyTokens, "tokens")} tokens · ` +
+      `~$${f.surfaceUsd.toFixed(2)} / ${fmtCap(f.caps.surfaceMonthlyUsd, "usd")}`,
+    `• whole workspace (\`${f.workspaceKey}\`): ${fmtTokenCount(f.workspaceTokens)} / ${fmtCap(f.caps.workspaceMonthlyTokens, "tokens")} tokens · ` +
+      `~$${f.workspaceUsd.toFixed(2)} / ${fmtCap(f.caps.workspaceMonthlyUsd, "usd")}`,
+    "_propose a change with `/oe budget raise <usd>` or `/oe budget clear`._",
+  ].join("\n");
+}
+
+/** `<@id>` renders as a mention on BOTH Slack (mrkdwn) and Discord (message content) —
+ *  the one piece of wire syntax the two platforms happen to share. Falls back to a plain
+ *  label on the (should-never-happen) case a command reached here with no principal. */
+function mentionFor(binding: SurfaceBinding): string {
+  return binding.principalId ? `<@${binding.principalId}>` : "an unidentified user";
+}
+
+// --- I/O glue: budget status -----------------------------------------------------------------
+// Reuses the EXACT functions spend/check.ts's scopeOverBudget (the enforcement gate) calls —
+// effectiveCaps, surfaceTokens, workspaceTokens, scopeUsdSpend — never re-derived, so the
+// figures `/oe budget` shows are BYTE-IDENTICAL to what the gate enforces right now.
+
+export interface BudgetStatusDeps {
+  readonly effectiveCaps?: typeof effectiveCaps;
+  readonly surfaceTokens?: typeof surfaceTokens;
+  readonly workspaceTokens?: typeof workspaceTokens;
+  readonly scopeUsdSpend?: typeof scopeUsdSpend;
+  readonly nowISO?: () => string;
+}
+
+export async function computeBudgetStatusFacts(binding: SurfaceBinding, deps: BudgetStatusDeps = {}): Promise<BudgetStatusFacts> {
+  const effectiveCapsFn = deps.effectiveCaps ?? effectiveCaps;
+  const surfaceTokensFn = deps.surfaceTokens ?? surfaceTokens;
+  const workspaceTokensFn = deps.workspaceTokens ?? workspaceTokens;
+  const scopeUsdSpendFn = deps.scopeUsdSpend ?? scopeUsdSpend;
+  const nowISO = deps.nowISO ? deps.nowISO() : new Date().toISOString();
+
+  // Reuse defaultScopeKey (set_spend_limit.ts) — the SAME `${platform}/${workspace}[/${surface}]`
+  // derivation the propose tools use, so the scope keys shown here are exactly the ones a
+  // follow-up "/oe budget raise"/"clear" (or the model's own set_spend_limit) would target.
+  const surfaceKey = defaultScopeKey(binding, "surface");
+  const workspaceKey = defaultScopeKey(binding, "workspace");
+  const period = periodOf(nowISO);
+  // The perDomain layer (explicit domain, or the dm/public criteria domain — binding
+  // already carries both mode + trust here, so the full classification applies).
+  const domainName = domainNameForScope(surfaceKey, binding.mode, binding.trust);
+
+  const [caps, st, wt, usd] = await Promise.all([
+    effectiveCapsFn(binding.org, workspaceKey, surfaceKey, domainName),
+    surfaceTokensFn(binding.org, surfaceKey, period),
+    workspaceTokensFn(binding.org, workspaceKey, period),
+    scopeUsdSpendFn(binding.org, workspaceKey, surfaceKey, nowISO),
+  ]);
+
+  return {
+    surfaceKey,
+    workspaceKey,
+    surfaceTokens: st,
+    workspaceTokens: wt,
+    surfaceUsd: usd.surfaceUsd,
+    workspaceUsd: usd.workspaceUsd,
+    caps,
+  };
+}
+
+// --- I/O glue: budget raise / clear ----------------------------------------------------------
+// Byte-for-byte the same freeze+card path as tools/set_spend_limit.ts / clear_spend_limit.ts's
+// `execute()` — planSetSpendLimit/planClearSpendLimit validate + freeze, requestApproval posts
+// the SAME code-rendered card (approvalPostDeps swaps in Discord's REST poster; Slack keeps the
+// default Block Kit path). The only difference from the model-driven tool: the "reason" is
+// synthesized here (there is no model turn to author one), and a slash command can only target
+// its OWN surface (level "surface", no scopeKey override) — v1 scope, matching the command's
+// documented grammar (`/oe budget raise <usd>` takes no other arguments).
+//
+// 🔴 …AND, SINCE OPE-312, ONE MORE: THE CARD-PATH FENCE LIVES HERE, not in the shared planner.
+// The model-driven tools stopped asking "can this room host a card" and started asking the venue
+// (approvals/card-venue.ts) instead, so a Teams room's card lands in the domain's Slack channel and
+// the tool result tells the model to say so. A slash command has no model turn to relay that, and
+// the ephemeral ack it returns — "Card posted in this channel" — is the ENTIRE user-facing answer,
+// so redirecting under it would make the one sentence the user reads false. Both commands keep the
+// old refusal, verbatim in substance, via `requireCardPathHere`. Today it can never fire (`/oe` is
+// only registered by the Slack and Discord bundles, both card-capable), which is exactly why it
+// must be written down rather than assumed: the next surface to wire a command inherits the fence.
+
+export interface OeApprovalDeps {
+  readonly effectiveCaps?: typeof effectiveCaps;
+  readonly requestApproval?: typeof requestApproval;
+  readonly friendlyScopeLabel?: typeof friendlyScopeLabel;
+  /** The pricing-coverage read frozen onto a `/oe budget raise` card (OPE-1482). Injectable for the
+   *  same reason the caps read is: this door is tested without a usage ledger. */
+  readonly readSpendCoverage?: typeof readSpendCoverage;
+  /** The unprivileged own-domain ledger scan `/oe budget raise` shows its requester (OPE-1631).
+   *  Raise-only, like the coverage read above, and injectable for the same reason. */
+  readonly domainSpendWindow?: typeof domainSpendWindow;
+  /** The configured domains the scan's own-domain resolution reads. Injectable so a test pins the
+   *  roster rather than the deployment's. */
+  readonly domains?: readonly Domain[];
+  readonly nowISO?: () => string;
+}
+
+/**
+ * Why a `/oe budget raise` ack shows no domain spend — the SLASH-COMMAND wording for the shared
+ * refusal reasons.
+ *
+ * This is a third wording, and it exists for the reason `spend/reporting.ts`'s
+ * `reportDomainRefusalMessage` is a second one. That sentence tells its reader to `pass
+ * scope:"org"`. `scope` is an argument of a model-driven TOOL. A slash command takes no such
+ * argument, so the hint would send its reader after something they cannot do. The REASONS still
+ * come from the one shared resolver; only the sentence is per-surface.
+ */
+function noDomainSpendReason(reason: SkillDomainRefusal): string {
+  switch (reason) {
+    case "dm":
+      return "a DM belongs to no memory domain";
+    case "mpim":
+      return "a group chat belongs to no memory domain";
+    case "external":
+      return "an externally-shared or unconfirmed channel reports no domain spend";
+    case "unassigned":
+      return "this channel is in no memory domain, and no org-wide default domain is configured";
+  }
+}
+
+/** The window `/oe budget raise` scans — the ticket's ask (OPE-1631), and the same NOMINAL 30 days
+ *  the pricing-coverage read uses. The two are not the same read: coverage walks `usage_events`
+ *  over a rolling 30 days, while this scan sums `spend_ledger` over whole calendar months, because
+ *  a ledger row is keyed by month and holds no finer window. */
+export const BUDGET_RAISE_SCAN_DAYS = 30;
+
+/**
+ * The own-domain spend sentence `/oe budget raise` appends to its ack (OPE-1631) — the requester's
+ * evidence for the number they just proposed, read WITHOUT any privileged capability.
+ *
+ * 🔴 THE SCAN NEVER REACHES THE CARD. This sentence is built after the card is posted and goes only
+ * into the ephemeral ack the requester alone sees. Freezing it into `plan.args` would put an
+ * aggregate the approver did not ask for onto a governance record, and would change the `spend.set`
+ * dedup identity — the coverage freeze (OPE-1482) is on the card because the APPROVER needs it; this
+ * read is for the ASKER, and it stays out.
+ *
+ * 🔴 THE RAISE STAYS ADMIN-GATED. Nothing here touches `planSetSpendLimit`, `requestApproval` or the
+ * approver chain: an unprivileged caller reads a number and still cannot raise a cap.
+ *
+ * FAIL-SOFT, and it says which way it failed — the same contract `readSpendCoverage` keeps. A
+ * broken ledger read must not turn a working proposal into an error, so it returns a sentence
+ * saying the ledger could not be read. It never returns silence on a failure: silence beside a
+ * proposal would read as "your domain spent nothing".
+ */
+async function budgetRaiseSpendSentence(binding: SurfaceBinding, deps: OeApprovalDeps): Promise<string> {
+  // ONE domain roster, read once and passed to both halves. The resolution below decides which
+  // domain the line NAMES and the scan decides which rows it SUMS: reading the config twice would
+  // let a mid-call config swap make the two disagree, which is the one way this line could name a
+  // domain whose figures it is not showing.
+  const domains = deps.domains ?? getConfig().loadDomains();
+  const resolved = reportDomainForBinding(binding, domains);
+  // No domain, no scan — a DM, a group chat, an external channel, or an unassigned channel with no
+  // `org` pseudo-domain. Saying so is the point: an absent figure must not read as a zero one.
+  if (resolved.domain === null) return `\n_No domain spend to show — ${noDomainSpendReason(resolved.reason)}._`;
+  try {
+    const scan = await (deps.domainSpendWindow ?? domainSpendWindow)(
+      binding.org,
+      resolved.domain,
+      deps.nowISO ? deps.nowISO() : new Date().toISOString(),
+      BUDGET_RAISE_SCAN_DAYS,
+      { domains },
+    );
+    // The periods are named, never implied. The ledger is keyed by calendar month, so this window
+    // covers WHOLE months — it over-covers the last 30 days, and a line that claimed exactly 30
+    // days would claim more than the ledger can support (spend/reporting.ts).
+    return (
+      `\n_Domain \`${scan.domain}\` spent ~$${scan.usd.toFixed(2)} on ${fmtTokenCount(scan.tokens)} tokens over ${fmtTokenCount(scan.calls)} calls ` +
+      `in ${scan.periods.join(", ")} — the whole calendar months holding the last ${BUDGET_RAISE_SCAN_DAYS} days, which is the finest window the spend ledger keeps._`
+    );
+  } catch (e) {
+    const why = e instanceof Error ? e.message : String(e);
+    console.warn(`[open-everywhere:spend] "/oe budget raise" could not scan domain "${resolved.domain}" spend: ${why}`);
+    return `\n_Domain spend NOT shown — the spend ledger could not be read on this turn._`;
+  }
+}
+
+function requireChannelId(binding: SurfaceBinding): string {
+  const channelId = typeof binding.target?.channelId === "string" ? binding.target.channelId : undefined;
+  if (!channelId) {
+    throw new Error("couldn't resolve this channel's id — try this from a real channel or DM, not a synthetic context.");
+  }
+  return channelId;
+}
+
+export async function runBudgetRaise(binding: SurfaceBinding, usd: number, deps: OeApprovalDeps = {}): Promise<string> {
+  requireCardPathHere('"/oe budget raise"', binding.platform);
+  const effectiveCapsFn = deps.effectiveCaps ?? effectiveCaps;
+  const requestApprovalFn = deps.requestApproval ?? requestApproval;
+  const friendlyScopeLabelFn = deps.friendlyScopeLabel ?? friendlyScopeLabel;
+
+  const level = "surface" as const;
+  const scopeKey = defaultScopeKey(binding, level);
+  const workspaceKey = defaultScopeKey(binding, "workspace");
+  // Approver domain = the TARGET scope's explicit domain (see set_spend_limit.ts's execute()
+  // for why: it decides WHO may approve, so it must be resolved from the scope being changed).
+  const domain = domainForChannel(scopeKey, getConfig().loadDomains())?.name ?? null;
+  const caps = await effectiveCapsFn(binding.org, workspaceKey, scopeKey, domainNameForScope(scopeKey, binding.mode, binding.trust));
+  const current: CurrentCaps = { tokens: caps.surfaceMonthlyTokens ?? null, usd: caps.surfaceMonthlyUsd ?? null };
+
+  const input: SetSpendLimitInput = {
+    monthlyUsd: usd,
+    reason: `requested via "/oe budget raise" by ${mentionFor(binding)}`,
+  };
+  // Throws a user-facing error for: no verified sender (the no-card-path refusal is the
+  // `requireCardPathHere` guard at the top of this function since OPE-312) — every message is
+  // already written for a human to read, so callers can render it verbatim on failure.
+  //
+  // A DM does NOT throw here (OPE-267). `level` above is fixed at "surface", and a DM's own
+  // surface key is enforced by the gate now that `checkCap`'s blanket `mode: "dm"` exemption is
+  // gone — so "/oe budget raise" from a DM proposes a cap on that DM, which is both meaningful
+  // and the most natural ask from one. The `workspace`/`domain` defaults are still refused from
+  // a DM (assertScopableFromHere), but this command never asks for either.
+  const plan = planSetSpendLimit(binding, input, current, domain);
+
+  const channelId = requireChannelId(binding);
+  const scopeLabel = await friendlyScopeLabelFn(plan.scopeKey);
+  // 🔴 THIS DOOR FREEZES COVERAGE TOO (OPE-1482). "/oe budget raise" proposes a USD cap every single
+  // time, so a door that skipped the read would post exactly the card the ticket exists to remove:
+  // a $ figure with no statement of which traffic it fails to meter. The reader is shared with the
+  // model-driven tool, and it fails soft — a broken ledger read freezes "not measured", never an
+  // empty list that would read as a clean bill.
+  const coverageReport = await (deps.readSpendCoverage ?? readSpendCoverage)(plan.args.org, plan.args.level, plan.args.scopeKey, plan.args.monthlyUsd);
+  const coverage = coverageReport === undefined ? undefined : frozenCoverage(coverageReport);
+  // approval-authority: headless — slash commands execute without a model turn or wake envelope.
+  const posted = await requestApprovalFn(
+    {
+      org: plan.args.org,
+      kind: plan.kind,
+      args: { ...plan.args, ...(scopeLabel ? { scopeLabel } : {}), ...(coverage ? { coverage } : {}) },
+      scopeKey: plan.scopeKey,
+      domain: plan.domain,
+      requestedBy: binding.principalId!,
+      channelId,
+      // Slash commands carry no thread anchor — a fresh top-level card, same as a Discord
+      // model-driven proposal (Discord turns never carry a threadTs either).
+      threadTs: binding.threadTs ?? null,
+      chain: { unattended: unattendedFrom(binding) },
+    },
+    approvalPostDeps(binding.platform),
+  );
+  // OPE-1631 — the requester's own evidence, read after the proposal is recorded so it reports the
+  // ledger as of the moment they read the ack. Both branches carry it: both are `/oe budget raise`
+  // answers, and the number that informs a raise informs it either way.
+  const spendSentence = await budgetRaiseSpendSentence(binding, deps);
+  // Chain-lowered (OPE-296) ⇒ no card and no click: the cap is already in force. The slash-command
+  // reply IS the whole user-facing answer here (there is no model turn to relay a tool result), so
+  // it says what happened rather than pointing at a card that was never posted.
+  if (posted.autoApproved) {
+    return (
+      `Done — $${usd.toFixed(2)}/month on \`${plan.scopeKey}\` is already in force: the approver chain auto-approved it ` +
+      `(${posted.autoApproved.resolvedBy}), so no card was posted — ${posted.autoApproved.outcome}` +
+      spendSentence
+    );
+  }
+  return (
+    `Card posted in this channel — proposing $${usd.toFixed(2)}/month on \`${plan.scopeKey}\` ` +
+    `(pending \`${posted.id}\`, expires ${posted.expiresAt}). An admin needs to Approve it.` +
+    spendSentence
+  );
+}
+
+export async function runBudgetClear(binding: SurfaceBinding, deps: OeApprovalDeps = {}): Promise<string> {
+  requireCardPathHere('"/oe budget clear"', binding.platform);
+  const effectiveCapsFn = deps.effectiveCaps ?? effectiveCaps;
+  const requestApprovalFn = deps.requestApproval ?? requestApproval;
+  const friendlyScopeLabelFn = deps.friendlyScopeLabel ?? friendlyScopeLabel;
+
+  const level = "surface" as const;
+  const scopeKey = defaultScopeKey(binding, level);
+  const workspaceKey = defaultScopeKey(binding, "workspace");
+  const domain = domainForChannel(scopeKey, getConfig().loadDomains())?.name ?? null;
+  const caps = await effectiveCapsFn(binding.org, workspaceKey, scopeKey, domainNameForScope(scopeKey, binding.mode, binding.trust));
+  const current: CurrentCaps = { tokens: caps.surfaceMonthlyTokens ?? null, usd: caps.surfaceMonthlyUsd ?? null };
+
+  const input: ClearSpendLimitInput = {};
+  const plan = planClearSpendLimit(binding, input, current, domain);
+
+  const channelId = requireChannelId(binding);
+  const scopeLabel = await friendlyScopeLabelFn(plan.scopeKey);
+  // approval-authority: headless — slash commands execute without a model turn or wake envelope.
+  const posted = await requestApprovalFn(
+    {
+      org: plan.args.org,
+      kind: plan.kind,
+      args: { ...plan.args, ...(scopeLabel ? { scopeLabel } : {}) },
+      scopeKey: plan.scopeKey,
+      domain: plan.domain,
+      requestedBy: binding.principalId!,
+      channelId,
+      threadTs: binding.threadTs ?? null,
+      chain: { unattended: unattendedFrom(binding) },
+    },
+    approvalPostDeps(binding.platform),
+  );
+  // Chain-lowered (OPE-296) — see runBudgetRaise above for why this branch exists.
+  if (posted.autoApproved) {
+    return (
+      `Done — the override on \`${plan.scopeKey}\` is already back to the config-as-code cap: the approver chain auto-approved it ` +
+      `(${posted.autoApproved.resolvedBy}), so no card was posted — ${posted.autoApproved.outcome}`
+    );
+  }
+  return (
+    `Card posted in this channel — proposing to clear the override on \`${plan.scopeKey}\` back to the config-as-code cap ` +
+    `(pending \`${posted.id}\`, expires ${posted.expiresAt}). An admin needs to Approve it.`
+  );
+}
+
+// --- I/O glue: stop (OPE-418) -----------------------------------------------------------------
+//
+// 🔴 THE ONE COMMAND THAT NEEDS SOMETHING FROM THE ROUTE. Every other "/oe" branch is pure logic
+// plus store reads; a cancel needs eve's `attachSession`, which exists ONLY as `args.attachSession`
+// inside a channel route handler. It is therefore INJECTED rather than imported — and when a caller
+// hasn't wired it, the command says so plainly instead of silently doing nothing.
+//
+// WHY THE CHANNEL KEY IS THE QUERY HERE, and the only one available: a slash command carries no
+// message ts and no continuation token. Slack's slash payload has a channel id and nothing else
+// that addresses a turn. So this resolves the channel's MOST RECENT in-flight turn — the only
+// ambiguous arm of the anchor registry, used only where no sharper key exists. The reaction
+// affordance, which knows its exact message, never falls through to it.
+//
+// NOT SPEND-GATED, like every other command in this file — and here that is the WHOLE POINT rather
+// than a nicety. An over-cap scope can no longer run a turn, so an inference-priced stop would stop
+// working for exactly the person most likely to be shouting at the agent to stop.
+
+/** Route capabilities injected into `runOeCommand`. Only `stop` needs any — see above. */
+export interface OeCommandDeps {
+  readonly attachSession?: AttachSessionForCancel;
+}
+
+/** Stand down whatever turn is running in this binding's channel. */
+export async function runStop(binding: SurfaceBinding, attachSession: AttachSessionForCancel | undefined): Promise<string> {
+  if (!attachSession) {
+    // A wiring bug, not a user error — but a user is the one reading this, so it names the other
+    // affordance they can reach for rather than an internal seam they cannot.
+    return "Stop isn't wired on this surface yet — react with the raised-hand emoji on the thread instead.";
+  }
+  const channelId = typeof binding.target?.channelId === "string" ? binding.target.channelId : undefined;
+  const channelKey = turnChannelKey(binding.platform, channelId);
+  if (!channelKey) {
+    return "Couldn't resolve this channel — try `/oe stop` from a real channel or DM, not a synthetic context.";
+  }
+  const result = await cancelAnchoredTurn({
+    org: binding.org,
+    platform: binding.platform,
+    workspace: binding.workspace,
+    ...(binding.principalId ? { requestedBy: binding.principalId } : {}),
+    via: "command",
+    query: { channelKey },
+    attachSession,
+  });
+  return result.message;
+}
+
+// --- top-level orchestrator ------------------------------------------------------------------
+
+/**
+ * Execute one parsed `/oe` command against a resolved binding, returning the EPHEMERAL reply
+ * text (the caller wraps it in its platform's response envelope). CAN THROW for
+ * `budget-raise`/`budget-clear` (planSetSpendLimit/planClearSpendLimit's own validation errors,
+ * or a store/network failure from requestApproval) — every message is already user-facing, so
+ * callers should catch and render `err.message` verbatim rather than a generic failure text.
+ * `help`/`status`/`budget-status` never throw (status wraps its own memory-provider read in a
+ * try/catch — "/oe status" must always answer something).
+ */
+export async function runOeCommand(cmd: OeCommand, binding: SurfaceBinding, deps: OeCommandDeps = {}): Promise<string> {
+  switch (cmd.kind) {
+    case "error":
+      return cmd.message;
+    case "help":
+      return renderHelp();
+    case "status": {
+      let memoryProviderId = "unknown";
+      try {
+        memoryProviderId = getProvider().id;
+      } catch {
+        /* best-effort — status must never throw on a misconfigured/unregistered provider */
+      }
+      let telemetryStatus = "unknown";
+      try {
+        telemetryStatus = telemetryStatusLine();
+      } catch {
+        /* best-effort — status must never throw */
+      }
+      return renderStatus(getAppInfo(), memoryProviderId, telemetryStatus);
+    }
+    case "budget-status": {
+      const facts = await computeBudgetStatusFacts(binding);
+      return renderBudgetStatus(facts);
+    }
+    case "budget-raise":
+      return runBudgetRaise(binding, cmd.usd);
+    case "budget-clear":
+      return runBudgetClear(binding);
+    case "stop":
+      return runStop(binding, deps.attachSession);
+    case "rate":
+      return runRate(binding, cmd.score);
+  }
+}