@open-everywhere/core 0.1.0

package/agent/channels/wake-accounting.ts

@@ -0,0 +1,121 @@
+// wake-accounting — the AUDIT-ONLY per-wake measurement pass. It runs after a turn has ended, reads which shown wakes went unanswered and writes ONE audit row. It changes nothing a turn may do, holds no approval, gates no tool and refuses nothing.
+// A pending, inbound, in-TTL wake registered at or before the turn's own wake is a PROXY for "this turn could have answered it", so the count is an upper bound rather than an exact one. The horizon stamp makes a wake report at most once, and it is a SEPARATE column from the answered mark: an answered mark would take the row out of the answerable-reply fence and change what the freshness gate counts.
+
+import type { PendingUnifiedWake } from "./unified-window.js";
+import { WAKE_TARGET_TTL_MS, wakeAddressingFromTargetJson } from "./unified-window.js";
+
+/** The store slice this module reads — read-only, mirroring reply-freshness.ts's own narrow
+ *  interface so a test can drive it with a small fake. */
+export interface WakeAccountingStore {
+  getUnifiedWakeRecord(org: string, wakeId: string): Promise<{ readonly createdAt: string } | null>;
+  /** This module's OWN listing — pending AND not yet audited. Deliberately not the freshness gate's
+   *  `listPendingUnifiedWakes`; see that method's doc in operational/store.ts for why they are two. */
+  listUnauditedUnifiedWakes(org: string, windowToken: string, limit: number): Promise<readonly PendingUnifiedWake[]>;
+  /** The ONE write this module makes — the horizon stamp (see the header). Never an answered mark. */
+  markUnifiedWakesAudited(org: string, wakeIds: readonly string[], at: string): Promise<void>;
+}
+
+/**
+ * How many rows one turn-end read loads, so a pathological backlog never pulls an unbounded row set onto a completion handler. The read already excludes AUDITED rows in SQL, so this caps the wakes still to consider, never a backlog earlier turns reported.
+ * Past the cap the caller's detail carries `capped: true`, so a reader knows the count is a floor and not an exact total.
+ */
+export const MAX_ACCOUNTING_WAKES = 50;
+
+/**
+ * The audit row family this module writes — ONE row per turn that left at least one shown wake unaccounted.
+ * `detail` carries ids, enums and counts only, never the wake's text (docs/security/audit-and-provenance.md).
+ */
+export const UNACCOUNTED_WAKES_AUDIT_ACTION = "turn.unaccounted_wakes";
+
+/**
+ * The pass's own BAIL, countable and distinct from "the pass ran and reported nothing". The caller writes ONE per turn it could not anchor a read on — never on this module's own read or write failures, which stay silently fail-soft.
+ * `detail.reason` names which precondition was missing: `no-window-token`, `no-turn-id` or `no-turn-wake`. Each is a narrow, low-volume class by construction.
+ */
+export const WAKE_ACCOUNTING_SKIPPED_AUDIT_ACTION = "turn.wake_accounting_skipped";
+
+export type WakeAddressingClass = "addressed" | "ambient";
+
+export interface UnaccountedWake {
+  readonly wakeId: string;
+  readonly addressing: WakeAddressingClass;
+}
+
+/**
+ * `row.targetJson`'s addressing extra field, reduced to the two-value split.
+ * Anything but the one positive `"direct-mention"` stamp — absent, malformed, or another tier's own value — reads as ambient. That is the same predicate identity/binding.ts's `currentTurnAddressed` uses.
+ */
+export function addressingClassOf(targetJson: string): WakeAddressingClass {
+  return wakeAddressingFromTargetJson(targetJson) === "direct-mention" ? "addressed" : "ambient";
+}
+
+/**
+ * PURE diff: given the candidate pending rows a turn-end read already loaded and the set of wake ids THIS turn accounted for, return the ones left over with their addressing class.
+ * Total and side-effect-free, so it is unit-testable with a handful of fixture rows and no store at all.
+ */
+export function unaccountedWakes(
+  pending: readonly PendingUnifiedWake[],
+  accounted: ReadonlySet<string>,
+): readonly UnaccountedWake[] {
+  const out: UnaccountedWake[] = [];
+  for (const row of pending) {
+    if (accounted.has(row.wakeId)) continue;
+    out.push({ wakeId: row.wakeId, addressing: addressingClassOf(row.targetJson) });
+  }
+  return out;
+}
+
+/**
+ * Load this turn's candidate pending-wake rows: every inbound, unanswered, in-TTL, NOT-YET-AUDITED wake on `windowToken` registered AT OR BEFORE `turnWake`'s own registration stamp, since a coalesced sibling is always at or before that anchor.
+ * The not-yet-audited bound is the horizon — a row an earlier turn considered is that turn's business. Best-effort: any store failure or an unresolvable anchor answers an empty list, and `nowMs` is injectable only so the read-time TTL is deterministically testable.
+ */
+export async function loadUnaccountedWakeCandidates(
+  store: WakeAccountingStore,
+  org: string,
+  windowToken: string,
+  turnWake: string,
+  nowMs?: number,
+): Promise<readonly PendingUnifiedWake[]> {
+  let anchorMs: number;
+  try {
+    const anchorRow = await store.getUnifiedWakeRecord(org, turnWake);
+    if (!anchorRow) return [];
+    anchorMs = Date.parse(anchorRow.createdAt);
+    if (!Number.isFinite(anchorMs)) return [];
+  } catch {
+    return [];
+  }
+  let rows: readonly PendingUnifiedWake[];
+  try {
+    rows = await store.listUnauditedUnifiedWakes(org, windowToken, MAX_ACCOUNTING_WAKES);
+  } catch {
+    return [];
+  }
+  const now = nowMs ?? Date.now();
+  return rows.filter((row) => {
+    const at = Date.parse(row.createdAt);
+    if (!Number.isFinite(at) || at > anchorMs) return false; // newer than this turn's own wake — not this turn's to answer
+    if (now - at > WAKE_TARGET_TTL_MS) return false; // read-time TTL, same bound as every other pending-wake reader
+    return true;
+  });
+}
+
+/**
+ * The whole measurement, and the ONE place the horizon advances: load this turn's candidates, diff against what the turn accounted for, stamp EVERY candidate as audited, and return the leftovers.
+ * The stamp covers every candidate, not only the leftovers: a wake answered by `no_reply` or `react` carries no durable answered mark, so stamping it here is the only thing that stops the NEXT turn reporting it. A failed stamp costs a repeated report, never a throw.
+ */
+export async function settleWakeAccounting(
+  store: WakeAccountingStore,
+  org: string,
+  input: { readonly windowToken: string; readonly turnWake: string },
+  accounted: ReadonlySet<string>,
+  nowMs?: number,
+): Promise<readonly UnaccountedWake[]> {
+  const candidates = await loadUnaccountedWakeCandidates(store, org, input.windowToken, input.turnWake, nowMs);
+  const leftover = unaccountedWakes(candidates, accounted);
+  if (candidates.length > 0) {
+    await store
+      .markUnifiedWakesAudited(org, candidates.map((row) => row.wakeId), new Date(nowMs ?? Date.now()).toISOString())
+      .catch(() => undefined);
+  }
+  return leftover;
+}

package/agent/channels/wake-arm.ts

@@ -0,0 +1,244 @@
+// wake-arm — the CONSUMER ARM of the WAKE seam: the built-in name-drop matcher stays exactly as it is, and a deployment may drop in an arm that ADDS a wake beside it. The seam ENFORCES three things rather than trusting the arm for them — an arm can never SUPPRESS a wake, it only runs where the built-in truly ABSTAINED (a policy drop never reaches one), and a surface that declines the seam, or that the table does not know at all, is never offered to an arm.
+// It does not enforce that the wake is WARRANTED: an arm that answers `wake` for everything costs one budgeted, judged turn per message, and this repo claims no per-message cost figure. Nor does it decide what the arm may SEE, which is a DISCLOSURE question — the text reaches the arm before the external-participant policy refuses the wake. Nor does it RE-LABEL the wake: an arm-added wake renders through the name-drop envelope, so the model reads it as an address by name.
+
+import { getConfig, type AppConfig } from "../access/config.js";
+
+/** The closed answer vocabulary. `wake` ADDS a wake the built-in did not give; `abstain` leaves the
+ *  built-in's answer standing. There is deliberately no value meaning "do not wake" — an arm that
+ *  could say it would be able to suppress a name-drop, which rule 4 makes unreachable instead. */
+export type WakeArmAnswer = "wake" | "abstain";
+
+/** The chat surfaces this seam knows. Total over the six that ship (docs/extending/chat-surface-contract.md),
+ *  so a surface has to appear in {@link WAKE_ARM_SURFACE_CONTRACT} with a stated position rather
+ *  than being absent and ambiguous. */
+export type WakeArmSurface = "slack" | "discord" | "teams" | "github" | "linear" | "notion";
+
+/** A field a surface may declare it hands the arm. The vocabulary is closed because the declaration
+ *  is ENFORCED: {@link projectForSurface} fills only the declared fields. */
+export type WakeArmField = "text" | "channelId" | "authorId";
+
+/** One surface's position on this seam. `offers: false` is a full decline — the composer returns the
+ *  built-in answer for that surface without ever calling an arm. */
+export interface WakeArmSurfaceDeclaration {
+  readonly offers: boolean;
+  /** The fields this surface hands the arm. Empty on a decline. */
+  readonly fields: readonly WakeArmField[];
+  /** Why this surface offers or declines. Read by a consumer deciding where an arm can reach. */
+  readonly note: string;
+}
+
+/**
+ * THE PER-SURFACE CONTRACT: each chat surface declares whether it offers this seam the message text, and which fields. A surface may decline and most do, because offering the seam means the surface's ambient route can report a real ABSTENTION.
+ * The declaration is not documentation — {@link wakeAfterArm} refuses to call an arm for a declining surface and {@link projectForSurface} builds the arm's input from `fields`, so a surface cannot widen what an arm sees by passing more. FROZEN, because a provider that imports the barrel could otherwise flip `offers` at runtime and reach an arm from a route that cannot report a real abstention. "Offers" is about a ROUTE, not about a vendor's whole surface.
+ */
+export const WAKE_ARM_SURFACE_CONTRACT: Readonly<Record<WakeArmSurface, WakeArmSurfaceDeclaration>> = Object.freeze({
+  slack: Object.freeze({
+    offers: true,
+    fields: Object.freeze(["text", "channelId", "authorId"]) as readonly WakeArmField[],
+    note:
+      "The NAME-DROP route only (routeNameDropEvent, slack-events.ts): it stages its gates, so it " +
+      "can report that the built-in abstained on the NAME with every other gate passed. 🔴 THAT ROUTE " +
+      "IS NOT EVERY SLACK MESSAGE. A domain running the ambient supervisor never reaches it at all " +
+      "(slack-front.ts diverts to routeSupervisorEvent), and a domain whose `nameDropWake` flag is " +
+      "off — the shipped default — returns before the arm rung. So an arm here is INERT until a " +
+      "domain turns `nameDropWake` on with the ambient supervisor off. `text` is the AUTHORED text " +
+      "only (ParsedMessageEvent.authoredText, OPE-1374) — quoted content a forward dragged in is not in it.",
+  }),
+  discord: Object.freeze({
+    offers: false,
+    fields: Object.freeze([]) as readonly WakeArmField[],
+    note:
+      "nameDropEligible (discord-gateway.ts) folds the name match into one boolean and reports no " +
+      "basis, so this surface cannot tell an abstention from a policy drop. Offering the seam here " +
+      "means splitting that function first — its own change, not this seam's.",
+  }),
+  teams: Object.freeze({ offers: false, fields: Object.freeze([]) as readonly WakeArmField[], note: "No ambient name-drop route at all — there is no abstention to fill." }),
+  github: Object.freeze({ offers: false, fields: Object.freeze([]) as readonly WakeArmField[], note: "No ambient name-drop route at all — there is no abstention to fill." }),
+  linear: Object.freeze({ offers: false, fields: Object.freeze([]) as readonly WakeArmField[], note: "No ambient name-drop route at all — there is no abstention to fill." }),
+  notion: Object.freeze({ offers: false, fields: Object.freeze([]) as readonly WakeArmField[], note: "No ambient name-drop route at all — there is no abstention to fill." }),
+});
+
+/**
+ * The table the composer actually reads; normally {@link WAKE_ARM_SURFACE_CONTRACT}.
+ * A test may swap it to drive {@link projectForSurface} with a narrowed field list, which is the only way to make the projection's enforcement falsifiable — every OFFERING surface today declares every field, so no production input exercises the dropped-field branch.
+ */
+let CONTRACT: Readonly<Partial<Record<WakeArmSurface, WakeArmSurfaceDeclaration>>> = WAKE_ARM_SURFACE_CONTRACT;
+
+/**
+ * One surface's declaration, or `undefined` for a surface the table does not know.
+ * AN UNKNOWN SURFACE IS A DECLINE, NOT A CRASH: these functions are exported for consumer adapters written outside this repo, which are not necessarily TypeScript, and an unguarded index would reject the composer's promise for an unknown surface string — losing the wake instead of failing closed to the built-in.
+ */
+function surfaceDeclaration(surface: WakeArmSurface): WakeArmSurfaceDeclaration | undefined {
+  return CONTRACT[surface];
+}
+
+/** Test seam: narrow or replace the per-surface declarations the composer reads. */
+export function _setWakeArmSurfaceContractForTest(
+  contract: Readonly<Partial<Record<WakeArmSurface, WakeArmSurfaceDeclaration>>>,
+): void {
+  CONTRACT = contract;
+}
+
+/** Test seam: restore the shipped declarations. */
+export function _resetWakeArmSurfaceContractForTest(): void {
+  CONTRACT = WAKE_ARM_SURFACE_CONTRACT;
+}
+
+/**
+ * THE INPUT-LENGTH CAP, and the only cost bound this seam states: the arm is handed at most this many characters of message text.
+ * A model arm's per-consult input is therefore bounded whatever a person pastes into a channel.
+ */
+export const WAKE_ARM_MAX_TEXT_CHARS = 4000;
+
+/** What the arm is told about the message. Built by the SEAM from the surface's declaration — a
+ *  field the surface did not declare is `undefined` here, whatever the route passed. */
+export interface WakeArmInput {
+  /** Which chat surface this message arrived on. */
+  readonly surface: WakeArmSurface;
+  /** The message text, already clipped to {@link WAKE_ARM_MAX_TEXT_CHARS}. Empty when the surface
+   *  did not declare `text` — which today no offering surface does, but the projection is total. */
+  readonly text: string;
+  /** The surface-native channel id, when declared. */
+  readonly channelId?: string;
+  /** The surface-native author id, when declared. */
+  readonly authorId?: string;
+}
+
+/** What the route passes the composer about the message. The composer projects it through the
+ *  surface's declaration before any arm sees it. */
+export interface WakeArmMessage {
+  readonly surface: WakeArmSurface;
+  readonly text: string;
+  readonly channelId: string;
+  readonly authorId?: string;
+}
+
+/**
+ * The built-in's answer, with the one fact an arm rung needs beside it.
+ * `abstained` means the built-in declined AND the only reason it declined is that the text does not name the agent — every other gate would have passed. It is NOT "the built-in said no": a DM, a bot author, a disabled domain and an unconfirmed channel are all `abstained: false`, and none of them reaches an arm.
+ */
+export interface BuiltInWakeAnswer {
+  readonly wakes: boolean;
+  readonly abstained: boolean;
+}
+
+/** How long one consult gets before the seam gives up and keeps the built-in answer. `let` so a test
+ *  can shorten it — the same 8s budget the result-reducing seam and the identity plane's async arms
+ *  give a live vendor round trip. */
+let ARM_TIMEOUT_MS = 8000;
+
+/** The live timeout, for a caller that must report it (and for the test that pins the default). */
+export function wakeArmTimeoutMs(): number {
+  return ARM_TIMEOUT_MS;
+}
+
+/** Test seam: shorten the arm timeout. */
+export function _setWakeArmTimeoutMsForTest(ms: number): void {
+  ARM_TIMEOUT_MS = ms;
+}
+
+/** Test seam: restore the production timeout. */
+export function _resetWakeArmTimeoutMsForTest(): void {
+  ARM_TIMEOUT_MS = 8000;
+}
+
+/** A sentinel the timeout resolves with, so a timeout is distinguishable from the arm's own
+ *  deliberate `undefined` — the two get different notes. */
+const TIMED_OUT = Symbol("wake-arm-timeout");
+
+/**
+ * The registered arm of this seam, or undefined when the deployment registered none. It swallows the config throw deliberately and SILENTLY: this module is reachable from script tests and ingress paths that never register config, and "no config registered" is not an arm failure — it is simply no arm.
+ * The catch is BARE, and it is exact only because `getConfig()` has exactly one throw today. If it grows a second failure reason, narrow this to the not-registered case, or the bare catch will swallow that one and resolve silently to the built-in.
+ */
+function registeredWakeArm(): AppConfig["decideWake"] {
+  try {
+    return getConfig().decideWake;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Would an arm be consulted on this surface at all? SYNCHRONOUS and cheap, for a route that must decide whether to pay the I/O its later gates need before it can offer the seam anything.
+ * A COST CHECK, NOT A CONTROL: deliberately weaker than {@link wakeAfterArm}, so a route that skipped it and called the composer anyway would get the same answer. With nothing registered it is false, which keeps a no-arm deployment on today's exact code path, including the API calls it does NOT make.
+ */
+export function wakeArmOffered(surface: WakeArmSurface): boolean {
+  return (surfaceDeclaration(surface)?.offers ?? false) && registeredWakeArm() !== undefined;
+}
+
+/** Build the arm's input from the surface's declaration. A field the surface did not declare is
+ *  absent here however the route filled it in, and `text` is clipped to the cap. */
+function projectForSurface(msg: WakeArmMessage, declaration: WakeArmSurfaceDeclaration): WakeArmInput {
+  const declared = new Set<WakeArmField>(declaration.fields);
+  return {
+    surface: msg.surface,
+    text: declared.has("text") ? msg.text.slice(0, WAKE_ARM_MAX_TEXT_CHARS) : "",
+    channelId: declared.has("channelId") ? msg.channelId : undefined,
+    authorId: declared.has("authorId") ? msg.authorId : undefined,
+  };
+}
+
+/**
+ * The composed wake decision: the built-in's answer, plus the deployment's arm where one is registered AND the built-in abstained AND the surface offers the seam. Returns true to wake.
+ * With no arm registered this is `builtIn.wakes`, so every caller keeps today's behaviour exactly. It never throws.
+ */
+export async function wakeAfterArm(builtIn: BuiltInWakeAnswer, msg: WakeArmMessage): Promise<boolean> {
+  // 1. THE BUILT-IN ALREADY WAKES. The arm is not consulted, so it cannot suppress. Structural —
+  //    there is no check here to get wrong, and no answer an arm could give.
+  if (builtIn.wakes) return true;
+  // 2. A POLICY DROP IS NOT AN ABSTENTION. Only "the text does not name the agent, and nothing else
+  //    blocked" defers to an arm.
+  if (!builtIn.abstained) return false;
+  // 3. THE PER-SURFACE CONTRACT. A declining surface never calls an arm, and a surface the table
+  //    does not know at all is a DECLINE rather than a throw — see surfaceDeclaration.
+  const declaration = surfaceDeclaration(msg.surface);
+  if (declaration === undefined || !declaration.offers) return false;
+  const arm = registeredWakeArm();
+  if (arm === undefined) return false;
+  return (await runArm(arm, projectForSurface(msg, declaration))) === "wake";
+}
+
+/**
+ * One consult. It returns `"wake"` only for a literal `"wake"` answer; every other outcome is `"abstain"`.
+ * It never throws, and never returns a value the caller has to re-validate.
+ */
+async function runArm(arm: NonNullable<AppConfig["decideWake"]>, input: WakeArmInput): Promise<WakeArmAnswer> {
+  const where = `${input.surface} ${input.channelId ?? "(channel undeclared)"}`;
+  let answer: unknown;
+  // 🔴 THE TIMER IS CLEARED, NOT UNREF'D — the same reasoning as the result-reducing seam's. An
+  // unref'd timer never fires in a process with nothing else pending, which turns a hung arm into a
+  // hang instead of a timeout. Clearing in `finally` gets both halves.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeout = new Promise<typeof TIMED_OUT>((resolve) => {
+      timer = setTimeout(() => resolve(TIMED_OUT), ARM_TIMEOUT_MS);
+    });
+    answer = await Promise.race([Promise.resolve(arm(input)), timeout]);
+  } catch (err) {
+    console.warn(`[open-everywhere:channels] decideWake arm threw for ${where}; kept the built-in answer: ${String(err)}`);
+    return "abstain";
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+  if (answer === TIMED_OUT) {
+    console.warn(`[open-everywhere:channels] decideWake arm exceeded ${ARM_TIMEOUT_MS}ms for ${where}; kept the built-in answer`);
+    return "abstain";
+  }
+  if (answer === undefined || answer === "abstain") return "abstain"; // a deliberate defer — no note
+  if (typeof answer !== "string") {
+    console.warn(
+      `[open-everywhere:channels] decideWake arm returned ${typeof answer} for ${where}, which is not one of "wake" | "abstain"; kept the built-in answer`,
+    );
+    return "abstain";
+  }
+  if (answer !== "wake") {
+    // THE RUNTIME VOCABULARY CHECK IS NOT CEREMONY. The slot is typed, but an arm is consumer
+    // JavaScript, so a typo'd "Wake" must resolve to the built-in rather than to an answer nothing
+    // can rank.
+    console.warn(
+      `[open-everywhere:channels] decideWake arm returned "${answer}" for ${where}, which is outside "wake" | "abstain"; kept the built-in answer`,
+    );
+    return "abstain";
+  }
+  return "wake";
+}

package/agent/channels/wake-container.ts

@@ -0,0 +1,50 @@
+// wake-container — the host-resolved address the chat READ verbs read. They expose no target parameter, so a cross-container read is not expressible rather than refused at execute time.
+// Each provider bundle states its own `ReadAdapter.wakeAddress` and core never guesses one: a turn whose surface names no container throws {@link WakeContainerError} instead of falling back to the partition's surface segment, which is sanitized for storage and not always the vendor id an API call needs.
+
+import type { BindableContext } from "../identity/binding.js";
+import { resolveReadAdapter, type ReadAdapter } from "./channel-read.js";
+import type { Domain } from "../memory/domain.js";
+
+/** Thrown when this turn's wake names no readable container (or no thread root). Its own class so a
+ *  caller can tell "this turn has no address" from a refused or unsupported one — nothing was
+ *  gated, so nothing is audited. */
+export class WakeContainerError extends Error {}
+
+/** The platform, read adapter and container id one read resolves to — derived entirely host-side, from no model input. */
+export interface WakeReadTarget {
+  readonly platform: string;
+  readonly adapter: ReadAdapter;
+  readonly container: string;
+  /** The thread root this turn is anchored on, when the surface names one. */
+  readonly threadRoot?: string;
+}
+
+/**
+ * Resolve THIS turn's own read address. No model input reaches it.
+ * The {@link resolveReadAdapter} gate chain still runs in the same order — the window's sources, the per-turn origin fence, a wired read adapter — so a misconfigured window degrades the way it always did.
+ */
+export function resolveWakeChannel(ctx: BindableContext, domains: readonly Domain[]): WakeReadTarget {
+  const { platform, adapter } = resolveReadAdapter(ctx, undefined, domains);
+  const address = adapter.wakeAddress(ctx);
+  if (!address?.container) {
+    throw new WakeContainerError(
+      `read: this ${platform} turn's wake names no container to read, so there is nothing to fetch. Say what ` +
+        "you can see and what you cannot; do not state message content you have not read.",
+    );
+  }
+  return { platform, adapter, container: address.container, ...(address.threadRoot ? { threadRoot: address.threadRoot } : {}) };
+}
+
+/**
+ * The thread root of a resolved wake target, or a loud refusal.
+ * A turn with none is a top-level turn, and the honest answer is that there is no thread — never an empty one.
+ */
+export function requireWakeThreadRoot(target: WakeReadTarget): string {
+  if (!target.threadRoot) {
+    throw new WakeContainerError(
+      "read_thread: this turn is not in a thread — it arrived at the top level of its container. Use " +
+        "`read_channel` to read the room instead.",
+    );
+  }
+  return target.threadRoot;
+}