@mercury-fw/confirm-engine 0.25.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @mercury-fw/confirm-engine
+
+## 0.25.0
+
+### Patch Changes
+
+- @mercury-fw/plugin-types@0.25.0
+- @mercury-fw/channel-types@0.25.0

package/README.md

@@ -0,0 +1,5 @@
+# @mercury-fw/confirm-engine
+
+The confirmation mechanism of [Mercury](https://github.com/lucabro81/mercury-fw): stages an action behind a one-time token and runs it when the token comes back. The core uses it and injects it into the channels; you don't depend on it directly.
+
+MIT

package/confirm-flow.ts

@@ -0,0 +1,100 @@
+/**
+ * Deterministic text interception for the "confirm" half of the
+ * confirm-required flow (something stages an action and hands back a token —
+ * see `confirmation-staging.ts` for the "propose" half). `tryConfirm` is called
+ * from each channel BEFORE the model ever sees the message, same pattern as
+ * `/dump` (`tool-log.ts`) and `NO_REPLY` — running a previously-approved
+ * mutation must never depend on the model's own tool-calling judgment.
+ *
+ * It knows nothing about what the staged action is: it runs the opaque `run`
+ * thunk (see `StagedAction`) and reports the outcome. A CLI delete, a future
+ * memory purge — same path, because the doing was closed over at stage time.
+ */
+import type { ConfirmOutcome } from "@mercury-fw/channel-types";
+import { isTokenShaped, type ConfirmationStore } from "./confirmation-store.ts";
+
+/**
+ * Signature of the persistent confirmation-note writer the core injects (the
+ * app's `writeConfirmationNote`, kept in `wiki/`). Declared here so this library
+ * stays free of any app import; the real writer is structurally assignable.
+ */
+export type WriteConfirmationNote = (
+  vaultPath: string,
+  userId: string,
+  token: string,
+  fields: { status: "pending" | "confirmed" | "failed"; requestedAt: string; resolvedAt: string | null; command: string },
+) => Promise<void>;
+
+/**
+ * Returns `null` if `input` doesn't look like a bare confirmation token —
+ * the caller should proceed with its normal flow (`runTurn`, etc.).
+ * Otherwise always returns a user-facing string, resolved without ever
+ * invoking the model: an unknown/expired/wrong-session token gets a
+ * canned message, a valid one actually runs the staged action and
+ * reports the outcome. No `conferma ` keyword to type or match — the
+ * real gate was always `store.take()`'s existence/session/expiry check,
+ * not that prefix (see `isTokenShaped`'s own doc comment). A card button
+ * click on Google Chat and a bare token typed on the terminal both resolve
+ * through this exact same path.
+ */
+export type ConfirmDeps = {
+  store: ConfirmationStore;
+  userId: string;
+  vaultPath: string;
+  writeConfirmationNoteFn: WriteConfirmationNote;
+  now?: () => Date;
+};
+
+/** Resolves a token to a structured {@link ConfirmOutcome} (from `@mercury-fw/channel-types`), running the staged action for a match. See `tryConfirm` for the string-returning wrapper. */
+export async function resolveConfirmation(
+  input: string,
+  sessionKey: string,
+  deps: ConfirmDeps,
+): Promise<ConfirmOutcome> {
+  const token = input.trim();
+  if (!isTokenShaped(token)) {
+    return { status: "not-a-token" };
+  }
+
+  const staged = deps.store.take(sessionKey, token);
+  if (!staged) {
+    return { status: "not-found" };
+  }
+
+  const result = await staged.run();
+  const resolvedAt = (deps.now?.() ?? new Date()).toISOString();
+  // Overwrites the same note the propose half wrote (see
+  // `confirmation-staging.ts`) so the persistent record reflects what actually
+  // happened, never stuck saying "pending" — see the stale-primer bug this
+  // guards against. Same resilience tradeoff as the propose side: a
+  // wiki-write failure must not stop the user from getting their result.
+  try {
+    await deps.writeConfirmationNoteFn(deps.vaultPath, deps.userId, token, {
+      status: result.ok ? "confirmed" : "failed",
+      requestedAt: staged.requestedAt ?? resolvedAt,
+      resolvedAt,
+      command: staged.describe,
+    });
+  } catch (err) {
+    console.error(`[confirm-flow] failed to write confirmation note: ${String(err)}`);
+  }
+  return result.ok ? { status: "ok", data: result.data } : { status: "failed", error: result.error };
+}
+
+export async function tryConfirm(
+  input: string,
+  sessionKey: string,
+  deps: ConfirmDeps,
+): Promise<string | null> {
+  const outcome = await resolveConfirmation(input, sessionKey, deps);
+  switch (outcome.status) {
+    case "not-a-token":
+      return null;
+    case "not-found":
+      return "Nessuna conferma in sospeso per questo token — potrebbe essere scaduta, già usata, o mai esistita.";
+    case "failed":
+      return `Confermato, ma l'esecuzione è fallita: ${outcome.error}`;
+    case "ok":
+      return `Confermato ed eseguito: ${JSON.stringify(outcome.data)}`;
+  }
+}

package/confirmation-staging.ts

@@ -0,0 +1,52 @@
+/**
+ * The "stage" side of the confirm-required flow, as a core-owned closure handed
+ * to whoever needs to defer an irreversible action (today the CLI tool; a
+ * future memory-deleting plugin all the same). It mints the confirmation token,
+ * stashes the opaque action in the `ConfirmationStore`, and writes the "pending"
+ * paper-trail note — so the caller never touches the store internals or the
+ * wiki, and the confirmation subsystem stays the one place that knows an action
+ * is confirmable. The "resolve" side (running the staged thunk once the token
+ * comes back) is `tryConfirm` in `confirm-flow.ts`.
+ *
+ * Bound per session (sessionKey/userId/vaultPath) at the composition root, so
+ * the returned function takes only the action itself. The note lives outside
+ * inferred/users/<userId>/ — see `writeConfirmationNote`'s own doc comment for
+ * why — and its write is best-effort: a failure is logged, never thrown, so it
+ * can't stop the user from seeing and confirming the action.
+ */
+import type { ConfirmationStore } from "./confirmation-store.ts";
+import type { StageConfirmation } from "@mercury-fw/plugin-types";
+import type { WriteConfirmationNote } from "./confirm-flow.ts";
+
+export type { StageConfirmation };
+
+export function createStageConfirmation(deps: {
+  store: ConfirmationStore;
+  sessionKey: string;
+  /** Where/who the pending confirmation note is written for. */
+  userId: string;
+  vaultPath: string;
+  /** The note writer, injected by the core (the app's `writeConfirmationNote`). */
+  writeConfirmationNoteFn: WriteConfirmationNote;
+  /** Test seam; defaults to `() => new Date()`. */
+  nowFn?: () => Date;
+}): StageConfirmation {
+  const write = deps.writeConfirmationNoteFn;
+  const nowFn = deps.nowFn ?? (() => new Date());
+
+  return async (action) => {
+    const requestedAt = nowFn().toISOString();
+    const token = deps.store.stage(deps.sessionKey, { run: action.run, describe: action.describe, requestedAt });
+    try {
+      await write(deps.vaultPath, deps.userId, token, {
+        status: "pending",
+        requestedAt,
+        resolvedAt: null,
+        command: action.describe,
+      });
+    } catch (err) {
+      console.error(`[confirmation-staging] failed to write confirmation note: ${String(err)}`);
+    }
+    return token;
+  };
+}

package/confirmation-store.ts

@@ -0,0 +1,122 @@
+/**
+ * In-memory staging area for an irreversible action that needs explicit
+ * confirmation before it runs. Something stages it here, and the channel gets
+ * the returned token confirmed back to it — a card button click on Google Chat,
+ * a bare token typed on the terminal — before anything actually happens (see
+ * `confirm-flow.ts`). Scoped by `sessionKey` so a token proposed to one session
+ * (terminal, or a given Google Chat space+sender) can't be confirmed by
+ * another.
+ *
+ * The action is opaque: a `run` thunk that performs it and a `describe` string
+ * for the paper trail. The store — and the whole confirmation subsystem — knows
+ * nothing about what kind of action it is: whoever stages it closes over the
+ * doing, and the core just runs the thunk when the token comes back. */
+import type { ActionResult } from "@mercury-fw/plugin-types";
+export type StagedAction = { run: () => Promise<ActionResult>; describe: string; requestedAt?: string };
+
+/** A pending staging as seen from outside, deliberately WITHOUT its token or
+ * its executable thunk: a token is a confirm capability, and the HTTP read
+ * surface is unauthenticated, so listing pending confirmations must never hand
+ * out the tokens (or a way to run the action) — only the human-readable
+ * `summary` (the action's `describe`). */
+export type PendingConfirmation = { sessionKey: string; summary: string; expiresAt: number };
+
+export type ConfirmationStore = {
+  /** Stages `action` for `sessionKey` and returns a fresh token. */
+  stage(sessionKey: string, action: StagedAction): string;
+  /** Consumes and returns the staged action for `sessionKey`/`token`, or
+   * `null` if it doesn't exist, belongs to a different session, or has
+   * expired. Always one-shot: a successful take removes the entry. */
+  take(sessionKey: string, token: string): StagedAction | null;
+  /** The currently staged, non-expired actions, redacted of their tokens — for
+   * read-only introspection (see `PendingConfirmation`). */
+  pending(): PendingConfirmation[];
+};
+
+// Full alphanumeric — a token is only ever copy-pasted, never read or
+// typed from memory, so legibility (avoiding 0/O/1/l/I) was never the
+// actual point. What makes a token distinguishable from ordinary text is
+// its shape below (two groups joined by a fixed hyphen), not a restricted
+// character set — a restricted set doesn't help anyway: it still collides
+// with any real short word that happens to avoid the same few excluded
+// characters (found live: "second", used as plain conversational text,
+// was indistinguishable from a real token under the old bare-6-char shape).
+const TOKEN_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const TOKEN_GROUP_LENGTH = 4;
+const DEFAULT_TTL_MS = 5 * 60_000;
+
+function randomGroup(): string {
+  const bytes = new Uint8Array(TOKEN_GROUP_LENGTH);
+  crypto.getRandomValues(bytes);
+  let group = "";
+  for (const b of bytes) {
+    group += TOKEN_ALPHABET[b % TOKEN_ALPHABET.length];
+  }
+  return group;
+}
+
+/** `<4 alphanumeric>-<4 alphanumeric>`, e.g. `k9m2-x7q4` — see `TOKEN_ALPHABET`'s own doc comment for why this shape, not a restricted character set, is what makes a token distinguishable from ordinary text. */
+function defaultTokenFn(): string {
+  return `${randomGroup()}-${randomGroup()}`;
+}
+
+type Entry = { action: StagedAction; sessionKey: string; expiresAt: number };
+
+export function createConfirmationStore(
+  opts: { now?: () => number; ttlMs?: number; tokenFn?: () => string } = {},
+): ConfirmationStore {
+  const now = opts.now ?? (() => Date.now());
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const tokenFn = opts.tokenFn ?? defaultTokenFn;
+  const entries = new Map<string, Entry>();
+
+  return {
+    stage(sessionKey, action) {
+      const token = tokenFn();
+      entries.set(token, { sessionKey, action, expiresAt: now() + ttlMs });
+      return token;
+    },
+    take(sessionKey, token) {
+      const entry = entries.get(token);
+      if (!entry) {
+        return null;
+      }
+      if (entry.expiresAt <= now()) {
+        entries.delete(token);
+        return null;
+      }
+      if (entry.sessionKey !== sessionKey) {
+        return null;
+      }
+      entries.delete(token);
+      return entry.action;
+    },
+    pending() {
+      const t = now();
+      const out: PendingConfirmation[] = [];
+      for (const entry of entries.values()) {
+        if (entry.expiresAt <= t) continue;
+        out.push({
+          sessionKey: entry.sessionKey,
+          summary: entry.action.describe,
+          expiresAt: entry.expiresAt,
+        });
+      }
+      return out;
+    },
+  };
+}
+
+const TOKEN_SHAPE_RE = new RegExp(`^[${TOKEN_ALPHABET}]{${TOKEN_GROUP_LENGTH}}-[${TOKEN_ALPHABET}]{${TOKEN_GROUP_LENGTH}}$`);
+
+/**
+ * True if `input` (trimmed) has the exact shape of a token this store
+ * mints — same alphabet, same length. Not a security boundary itself
+ * (that's `take()`'s existence/session/expiry check) — just enough to
+ * tell apart "this looks like a confirmation attempt" from "this is an
+ * ordinary message", so a caller (`tryConfirm` in `confirm-flow.ts`) knows
+ * whether to intercept at all before ever touching the store.
+ */
+export function isTokenShaped(input: string): boolean {
+  return TOKEN_SHAPE_RE.test(input.trim());
+}

package/dist/confirm-flow.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Deterministic text interception for the "confirm" half of the
+ * confirm-required flow (something stages an action and hands back a token —
+ * see `confirmation-staging.ts` for the "propose" half). `tryConfirm` is called
+ * from each channel BEFORE the model ever sees the message, same pattern as
+ * `/dump` (`tool-log.ts`) and `NO_REPLY` — running a previously-approved
+ * mutation must never depend on the model's own tool-calling judgment.
+ *
+ * It knows nothing about what the staged action is: it runs the opaque `run`
+ * thunk (see `StagedAction`) and reports the outcome. A CLI delete, a future
+ * memory purge — same path, because the doing was closed over at stage time.
+ */
+import type { ConfirmOutcome } from "@mercury-fw/channel-types";
+import { type ConfirmationStore } from "./confirmation-store.ts";
+/**
+ * Signature of the persistent confirmation-note writer the core injects (the
+ * app's `writeConfirmationNote`, kept in `wiki/`). Declared here so this library
+ * stays free of any app import; the real writer is structurally assignable.
+ */
+export type WriteConfirmationNote = (vaultPath: string, userId: string, token: string, fields: {
+    status: "pending" | "confirmed" | "failed";
+    requestedAt: string;
+    resolvedAt: string | null;
+    command: string;
+}) => Promise<void>;
+/**
+ * Returns `null` if `input` doesn't look like a bare confirmation token —
+ * the caller should proceed with its normal flow (`runTurn`, etc.).
+ * Otherwise always returns a user-facing string, resolved without ever
+ * invoking the model: an unknown/expired/wrong-session token gets a
+ * canned message, a valid one actually runs the staged action and
+ * reports the outcome. No `conferma ` keyword to type or match — the
+ * real gate was always `store.take()`'s existence/session/expiry check,
+ * not that prefix (see `isTokenShaped`'s own doc comment). A card button
+ * click on Google Chat and a bare token typed on the terminal both resolve
+ * through this exact same path.
+ */
+export type ConfirmDeps = {
+    store: ConfirmationStore;
+    userId: string;
+    vaultPath: string;
+    writeConfirmationNoteFn: WriteConfirmationNote;
+    now?: () => Date;
+};
+/** Resolves a token to a structured {@link ConfirmOutcome} (from `@mercury-fw/channel-types`), running the staged action for a match. See `tryConfirm` for the string-returning wrapper. */
+export declare function resolveConfirmation(input: string, sessionKey: string, deps: ConfirmDeps): Promise<ConfirmOutcome>;
+export declare function tryConfirm(input: string, sessionKey: string, deps: ConfirmDeps): Promise<string | null>;

package/dist/confirmation-staging.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The "stage" side of the confirm-required flow, as a core-owned closure handed
+ * to whoever needs to defer an irreversible action (today the CLI tool; a
+ * future memory-deleting plugin all the same). It mints the confirmation token,
+ * stashes the opaque action in the `ConfirmationStore`, and writes the "pending"
+ * paper-trail note — so the caller never touches the store internals or the
+ * wiki, and the confirmation subsystem stays the one place that knows an action
+ * is confirmable. The "resolve" side (running the staged thunk once the token
+ * comes back) is `tryConfirm` in `confirm-flow.ts`.
+ *
+ * Bound per session (sessionKey/userId/vaultPath) at the composition root, so
+ * the returned function takes only the action itself. The note lives outside
+ * inferred/users/<userId>/ — see `writeConfirmationNote`'s own doc comment for
+ * why — and its write is best-effort: a failure is logged, never thrown, so it
+ * can't stop the user from seeing and confirming the action.
+ */
+import type { ConfirmationStore } from "./confirmation-store.ts";
+import type { StageConfirmation } from "@mercury-fw/plugin-types";
+import type { WriteConfirmationNote } from "./confirm-flow.ts";
+export type { StageConfirmation };
+export declare function createStageConfirmation(deps: {
+    store: ConfirmationStore;
+    sessionKey: string;
+    /** Where/who the pending confirmation note is written for. */
+    userId: string;
+    vaultPath: string;
+    /** The note writer, injected by the core (the app's `writeConfirmationNote`). */
+    writeConfirmationNoteFn: WriteConfirmationNote;
+    /** Test seam; defaults to `() => new Date()`. */
+    nowFn?: () => Date;
+}): StageConfirmation;

package/dist/confirmation-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * In-memory staging area for an irreversible action that needs explicit
+ * confirmation before it runs. Something stages it here, and the channel gets
+ * the returned token confirmed back to it — a card button click on Google Chat,
+ * a bare token typed on the terminal — before anything actually happens (see
+ * `confirm-flow.ts`). Scoped by `sessionKey` so a token proposed to one session
+ * (terminal, or a given Google Chat space+sender) can't be confirmed by
+ * another.
+ *
+ * The action is opaque: a `run` thunk that performs it and a `describe` string
+ * for the paper trail. The store — and the whole confirmation subsystem — knows
+ * nothing about what kind of action it is: whoever stages it closes over the
+ * doing, and the core just runs the thunk when the token comes back. */
+import type { ActionResult } from "@mercury-fw/plugin-types";
+export type StagedAction = {
+    run: () => Promise<ActionResult>;
+    describe: string;
+    requestedAt?: string;
+};
+/** A pending staging as seen from outside, deliberately WITHOUT its token or
+ * its executable thunk: a token is a confirm capability, and the HTTP read
+ * surface is unauthenticated, so listing pending confirmations must never hand
+ * out the tokens (or a way to run the action) — only the human-readable
+ * `summary` (the action's `describe`). */
+export type PendingConfirmation = {
+    sessionKey: string;
+    summary: string;
+    expiresAt: number;
+};
+export type ConfirmationStore = {
+    /** Stages `action` for `sessionKey` and returns a fresh token. */
+    stage(sessionKey: string, action: StagedAction): string;
+    /** Consumes and returns the staged action for `sessionKey`/`token`, or
+     * `null` if it doesn't exist, belongs to a different session, or has
+     * expired. Always one-shot: a successful take removes the entry. */
+    take(sessionKey: string, token: string): StagedAction | null;
+    /** The currently staged, non-expired actions, redacted of their tokens — for
+     * read-only introspection (see `PendingConfirmation`). */
+    pending(): PendingConfirmation[];
+};
+export declare function createConfirmationStore(opts?: {
+    now?: () => number;
+    ttlMs?: number;
+    tokenFn?: () => string;
+}): ConfirmationStore;
+/**
+ * True if `input` (trimmed) has the exact shape of a token this store
+ * mints — same alphabet, same length. Not a security boundary itself
+ * (that's `take()`'s existence/session/expiry check) — just enough to
+ * tell apart "this looks like a confirmation attempt" from "this is an
+ * ordinary message", so a caller (`tryConfirm` in `confirm-flow.ts`) knows
+ * whether to intercept at all before ever touching the store.
+ */
+export declare function isTokenShaped(input: string): boolean;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The confirm-required mechanism the core owns end to end: the stateful
+ * `ConfirmationStore` (mints tokens, stashes opaque staged actions with a TTL),
+ * the "stage" half (`createStageConfirmation`, handed to whoever defers an
+ * irreversible action) and the "resolve" half (`resolveConfirmation`/`tryConfirm`,
+ * run before the model ever sees a message so a previously-approved mutation
+ * never depends on the model).
+ *
+ * The core creates the single store instance and binds the store/vault/writer,
+ * then hands channels only the injected `confirm`/`resolveConfirmation` closures
+ * (via `ChannelRuntimeContext`) — a channel never imports this library. Nothing
+ * here imports the app; the note writer is an injected `WriteConfirmationNote`.
+ */
+export { createConfirmationStore, isTokenShaped, type ConfirmationStore, type StagedAction, } from "./confirmation-store.ts";
+export { resolveConfirmation, tryConfirm, type ConfirmDeps, type WriteConfirmationNote, } from "./confirm-flow.ts";
+export { createStageConfirmation, type StageConfirmation } from "./confirmation-staging.ts";

package/index.ts

@@ -0,0 +1,26 @@
+/**
+ * The confirm-required mechanism the core owns end to end: the stateful
+ * `ConfirmationStore` (mints tokens, stashes opaque staged actions with a TTL),
+ * the "stage" half (`createStageConfirmation`, handed to whoever defers an
+ * irreversible action) and the "resolve" half (`resolveConfirmation`/`tryConfirm`,
+ * run before the model ever sees a message so a previously-approved mutation
+ * never depends on the model).
+ *
+ * The core creates the single store instance and binds the store/vault/writer,
+ * then hands channels only the injected `confirm`/`resolveConfirmation` closures
+ * (via `ChannelRuntimeContext`) — a channel never imports this library. Nothing
+ * here imports the app; the note writer is an injected `WriteConfirmationNote`.
+ */
+export {
+  createConfirmationStore,
+  isTokenShaped,
+  type ConfirmationStore,
+  type StagedAction,
+} from "./confirmation-store.ts";
+export {
+  resolveConfirmation,
+  tryConfirm,
+  type ConfirmDeps,
+  type WriteConfirmationNote,
+} from "./confirm-flow.ts";
+export { createStageConfirmation, type StageConfirmation } from "./confirmation-staging.ts";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mercury-fw/confirm-engine",
+  "version": "0.25.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/libs/confirm-engine"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "CHANGELOG.md",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mercury-fw/channel-types": "0.25.0",
+    "@mercury-fw/plugin-types": "0.25.0"
+  },
+  "devDependencies": {
+    "@mercury-fw/typescript-config": "*",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}