switchroom 0.5.0

package/telegram-plugin/active-pins.ts

@@ -0,0 +1,146 @@
+/**
+ * Pure helpers for tracking pinned progress-card message IDs across
+ * restarts.
+ *
+ * The progress-card driver pins a per-turn card on first emit and
+ * unpins on turn complete. That lifecycle is in-memory only, so a
+ * crash or kill mid-turn leaves a pinned message with no cleanup
+ * path — on restart, the in-memory map is empty and Telegram still
+ * shows the stale pin.
+ *
+ * This module persists the set of currently-pinned cards to a
+ * `.active-pins.json` sidecar under `$AGENT_DIR`. The server adds an
+ * entry right after `pinChatMessage` succeeds, removes the entry
+ * after `unpinChatMessage`, and on startup reads the file to sweep
+ * any stale entries (best-effort unpin) before the driver starts.
+ *
+ * All helpers are filesystem-only — no Telegram side effects — so
+ * they're unit-testable in isolation, mirroring `handoff-continuity.ts`.
+ */
+
+import { readFileSync, writeFileSync, renameSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+export const ACTIVE_PINS_FILENAME = ".active-pins.json";
+
+export interface ActivePin {
+  chatId: string;
+  messageId: number;
+  turnKey: string;
+  pinnedAt: number;
+  /**
+   * Per-agent identity for the pin. Optional in the on-disk shape so
+   * sidecars written before per-agent cards (#per-agent-cards) still
+   * parse cleanly — readers should treat a missing field as the parent
+   * sentinel (`__parent__`).
+   */
+  agentId?: string;
+}
+
+function pinsPath(agentDir: string): string {
+  return join(agentDir, ACTIVE_PINS_FILENAME);
+}
+
+/**
+ * Read the active-pins sidecar. Missing, empty, or malformed files
+ * return an empty array — callers never have to handle parse errors.
+ * Entries that fail shape validation are dropped silently so a
+ * corrupted file can't brick the startup sweep.
+ */
+export function readActivePins(agentDir: string): ActivePin[] {
+  const p = pinsPath(agentDir);
+  if (!existsSync(p)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(p, "utf-8");
+  } catch {
+    return [];
+  }
+  if (raw.trim().length === 0) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const out: ActivePin[] = [];
+  for (const item of parsed) {
+    if (
+      item != null &&
+      typeof item === "object" &&
+      typeof (item as ActivePin).chatId === "string" &&
+      typeof (item as ActivePin).messageId === "number" &&
+      typeof (item as ActivePin).turnKey === "string" &&
+      typeof (item as ActivePin).pinnedAt === "number"
+    ) {
+      const aid = (item as ActivePin).agentId;
+      const entry: ActivePin = aid != null && typeof aid === "string"
+        ? (item as ActivePin)
+        : { ...(item as ActivePin), agentId: undefined };
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * Atomically overwrite the sidecar with the given list. Writing an
+ * empty list deletes the file so a fresh restart sees no state.
+ */
+export function writeActivePins(agentDir: string, pins: ActivePin[]): void {
+  const p = pinsPath(agentDir);
+  if (pins.length === 0) {
+    try {
+      unlinkSync(p);
+    } catch {
+      /* already gone */
+    }
+    return;
+  }
+  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(pins) + "\n", "utf-8");
+    renameSync(tmp, p);
+  } catch {
+    /* best-effort — failsafe cleanup is cosmetic, not safety-critical */
+  }
+}
+
+/**
+ * Append a new pin to the sidecar. Idempotent on `(chatId, messageId)`
+ * — a duplicate add replaces the existing entry so `pinnedAt` reflects
+ * the most recent pin.
+ */
+export function addActivePin(agentDir: string, pin: ActivePin): void {
+  const existing = readActivePins(agentDir).filter(
+    (p) => !(p.chatId === pin.chatId && p.messageId === pin.messageId),
+  );
+  existing.push(pin);
+  writeActivePins(agentDir, existing);
+}
+
+/**
+ * Remove the pin matching `(chatId, messageId)`. No-op when the
+ * sidecar or entry is absent.
+ */
+export function removeActivePin(agentDir: string, chatId: string, messageId: number): void {
+  const existing = readActivePins(agentDir);
+  const next = existing.filter(
+    (p) => !(p.chatId === chatId && p.messageId === messageId),
+  );
+  if (next.length === existing.length) return;
+  writeActivePins(agentDir, next);
+}
+
+/**
+ * Delete the sidecar outright. Called after the startup sweep so the
+ * next run starts clean regardless of unpin success.
+ */
+export function clearActivePins(agentDir: string): void {
+  try {
+    unlinkSync(pinsPath(agentDir));
+  } catch {
+    /* already gone */
+  }
+}

package/telegram-plugin/active-reactions-sweep.ts

@@ -0,0 +1,79 @@
+/**
+ * Sweep logic for the active-reactions sidecar.
+ *
+ * The sidecar (see `active-reactions.ts`) records every in-flight
+ * status reaction the bot has set but not yet resolved to a terminal
+ * state (👍 done or 😱 error). Two lifecycle events consume it:
+ *
+ *   1. Startup — when a new gateway process boots, it sweeps any
+ *      entries left over from a prior session that crashed or was
+ *      killed mid-turn. Without this, reactions stay stuck on
+ *      intermediate emoji (🤔, 🔥, etc.) forever because the
+ *      in-memory map that tracks them died with the old process.
+ *
+ *   2. Pre-restart — when /restart, /reconcile --restart, or /update
+ *      commands fire a self-restart, the gateway proactively promotes
+ *      any still-active reactions to 👍 before it gets SIGTERM'd.
+ *
+ * Both consumers call `sweepActiveReactions`, which is shaped as a
+ * pure function that takes the setDone callback as an argument. That
+ * keeps it testable in isolation — the tests pass a fake callback and
+ * assert which reactions were visited and whether the sidecar was
+ * cleared.
+ */
+
+import { readActiveReactions, clearActiveReactions, type ActiveReaction } from "./active-reactions.js";
+
+export type SetDoneReactionFn = (chatId: string, messageId: number) => Promise<unknown>;
+
+export interface SweepOptions {
+  timeoutMs?: number;
+  log?: (msg: string) => void;
+}
+
+export interface SweepResult {
+  swept: ActiveReaction[];
+  timedOut: boolean;
+}
+
+/**
+ * Promote every entry in the sidecar to 👍, then clear it. Bounded by
+ * `timeoutMs` (default 2s) so a slow Telegram API can't block a
+ * restart indefinitely. Failures are logged and swallowed — the
+ * sidecar is cleared regardless so stale entries don't pile up on
+ * subsequent boots.
+ */
+export async function sweepActiveReactions(
+  agentDir: string,
+  setDone: SetDoneReactionFn,
+  options: SweepOptions = {},
+): Promise<SweepResult> {
+  const log = options.log ?? (() => {});
+  const timeoutMs = options.timeoutMs ?? 2000;
+  const reactions = readActiveReactions(agentDir);
+  if (reactions.length === 0) return { swept: [], timedOut: false };
+
+  log(`sweeping ${reactions.length} stale reaction(s)`);
+  const attempts = reactions.map((r) =>
+    Promise.resolve()
+      .then(() => setDone(r.chatId, r.messageId))
+      .catch((err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        log(`reaction sweep failed for ${r.chatId}/${r.messageId}: ${msg}`);
+      }),
+  );
+
+  let timedOut = false;
+  await Promise.race([
+    Promise.allSettled(attempts),
+    new Promise<void>((resolve) =>
+      setTimeout(() => {
+        timedOut = true;
+        resolve();
+      }, timeoutMs),
+    ),
+  ]);
+
+  clearActiveReactions(agentDir);
+  return { swept: reactions, timedOut };
+}

package/telegram-plugin/active-reactions.ts

@@ -0,0 +1,134 @@
+/**
+ * Pure helpers for tracking in-flight status reactions across gateway
+ * restarts.
+ *
+ * The status-reaction lifecycle is in-memory only (`activeStatusReactions`
+ * Map in gateway.ts). When the *gateway* crashes mid-turn, the Map is
+ * lost and Telegram still shows the intermediate emoji (🤔, 🔥, etc.)
+ * with no cleanup path.
+ *
+ * This module persists the set of currently-active reactions to a
+ * `.active-reactions.json` sidecar under `$AGENT_DIR`. The gateway adds
+ * an entry right after creating a StatusReactionController, removes it
+ * when the reaction reaches a terminal state, and on startup reads the
+ * file to sweep any stale entries (best-effort promotion to 👍).
+ *
+ * All helpers are filesystem-only — no Telegram side effects — so
+ * they're unit-testable in isolation, mirroring `active-pins.ts`.
+ */
+
+import { readFileSync, writeFileSync, renameSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+export const ACTIVE_REACTIONS_FILENAME = ".active-reactions.json";
+
+export interface ActiveReaction {
+  chatId: string;
+  messageId: number;
+  threadId: number | null;
+  reactedAt: number;
+}
+
+function reactionsPath(agentDir: string): string {
+  return join(agentDir, ACTIVE_REACTIONS_FILENAME);
+}
+
+/**
+ * Read the active-reactions sidecar. Missing, empty, or malformed files
+ * return an empty array — callers never have to handle parse errors.
+ * Entries that fail shape validation are dropped silently so a
+ * corrupted file can't brick the startup sweep.
+ */
+export function readActiveReactions(agentDir: string): ActiveReaction[] {
+  const p = reactionsPath(agentDir);
+  if (!existsSync(p)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(p, "utf-8");
+  } catch {
+    return [];
+  }
+  if (raw.trim().length === 0) return [];
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const out: ActiveReaction[] = [];
+  for (const item of parsed) {
+    if (
+      item != null &&
+      typeof item === "object" &&
+      typeof (item as ActiveReaction).chatId === "string" &&
+      typeof (item as ActiveReaction).messageId === "number" &&
+      (typeof (item as ActiveReaction).threadId === "number" || (item as ActiveReaction).threadId === null) &&
+      typeof (item as ActiveReaction).reactedAt === "number"
+    ) {
+      out.push(item as ActiveReaction);
+    }
+  }
+  return out;
+}
+
+/**
+ * Atomically overwrite the sidecar with the given list. Writing an
+ * empty list deletes the file so a fresh restart sees no state.
+ */
+export function writeActiveReactions(agentDir: string, reactions: ActiveReaction[]): void {
+  const p = reactionsPath(agentDir);
+  if (reactions.length === 0) {
+    try {
+      unlinkSync(p);
+    } catch {
+      /* already gone */
+    }
+    return;
+  }
+  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(reactions) + "\n", "utf-8");
+    renameSync(tmp, p);
+  } catch {
+    /* best-effort — failsafe cleanup is cosmetic, not safety-critical */
+  }
+}
+
+/**
+ * Append a new reaction to the sidecar. Idempotent on `(chatId, messageId)`
+ * — a duplicate add replaces the existing entry so `reactedAt` reflects
+ * the most recent reaction.
+ */
+export function addActiveReaction(agentDir: string, reaction: ActiveReaction): void {
+  const existing = readActiveReactions(agentDir).filter(
+    (r) => !(r.chatId === reaction.chatId && r.messageId === reaction.messageId),
+  );
+  existing.push(reaction);
+  writeActiveReactions(agentDir, existing);
+}
+
+/**
+ * Remove the reaction matching `(chatId, messageId)`. No-op when the
+ * sidecar or entry is absent.
+ */
+export function removeActiveReaction(agentDir: string, chatId: string, messageId: number): void {
+  const existing = readActiveReactions(agentDir);
+  const next = existing.filter(
+    (r) => !(r.chatId === chatId && r.messageId === messageId),
+  );
+  if (next.length === existing.length) return;
+  writeActiveReactions(agentDir, next);
+}
+
+/**
+ * Delete the sidecar outright. Called after the startup sweep so the
+ * next run starts clean regardless of sweep success.
+ */
+export function clearActiveReactions(agentDir: string): void {
+  try {
+    unlinkSync(reactionsPath(agentDir));
+  } catch {
+    /* already gone */
+  }
+}

package/telegram-plugin/admin-commands/dispatch.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest'
+import { dispatchAdminCommand, parseCommandName, ADMIN_COMMAND_NAMES } from './index.js'
+
+// ─── parseCommandName ────────────────────────────────────────────────────────
+
+describe('parseCommandName', () => {
+  it('extracts a simple command', () => {
+    expect(parseCommandName('/agents')).toBe('agents')
+  })
+
+  it('strips a @botname suffix', () => {
+    expect(parseCommandName('/agents@mybot')).toBe('agents')
+  })
+
+  it('ignores arguments after a space', () => {
+    expect(parseCommandName('/logs 50')).toBe('logs')
+  })
+
+  it('normalises to lowercase', () => {
+    expect(parseCommandName('/Agents')).toBe('agents')
+  })
+
+  it('returns null for non-slash text', () => {
+    expect(parseCommandName('hello')).toBeNull()
+    expect(parseCommandName('')).toBeNull()
+    expect(parseCommandName('agents')).toBeNull()
+  })
+
+  it('returns an empty string for a bare slash', () => {
+    expect(parseCommandName('/ ')).toBe('')
+  })
+})
+
+// ─── ADMIN_COMMAND_NAMES ─────────────────────────────────────────────────────
+
+describe('ADMIN_COMMAND_NAMES', () => {
+  it('contains the fleet-management admin commands', () => {
+    const required = ['agents', 'logs', 'restart', 'update', 'reconcile', 'stop', 'agentstart', 'grant', 'dangerous', 'permissions', 'vault']
+    for (const cmd of required) {
+      expect(ADMIN_COMMAND_NAMES.has(cmd)).toBe(true)
+    }
+  })
+
+  it('does not contain per-agent auth ops (must work without model)', () => {
+    // /auth, /reauth, /authfallback are handled by the gateway directly so
+    // the user can re-authenticate even when the model is rate-limited or the
+    // token is expired. Routing them through Claude would defeat the point.
+    expect(ADMIN_COMMAND_NAMES.has('auth')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('reauth')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('authfallback')).toBe(false)
+  })
+
+  it('does not contain interrupt (cancellation must always work)', () => {
+    expect(ADMIN_COMMAND_NAMES.has('interrupt')).toBe(false)
+  })
+
+  it('does not contain the permission-response flow', () => {
+    // /approve, /deny, /pending are intercepted by the gateway before the
+    // model is invoked anyway — they have nothing to do with admin gating.
+    expect(ADMIN_COMMAND_NAMES.has('approve')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('deny')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('pending')).toBe(false)
+  })
+
+  it('does not contain info commands (must work when model is down)', () => {
+    expect(ADMIN_COMMAND_NAMES.has('version')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('doctor')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('usage')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('commands')).toBe(false)
+  })
+
+  it('does not contain session-reset commands', () => {
+    expect(ADMIN_COMMAND_NAMES.has('new')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('reset')).toBe(false)
+  })
+
+  it('does not contain create-agent (out of scope for phase 1)', () => {
+    expect(ADMIN_COMMAND_NAMES.has('create-agent')).toBe(false)
+  })
+
+  it('does not contain legacy verbs upgrade or rebuild', () => {
+    expect(ADMIN_COMMAND_NAMES.has('upgrade')).toBe(false)
+    expect(ADMIN_COMMAND_NAMES.has('rebuild')).toBe(false)
+  })
+})
+
+// ─── dispatchAdminCommand ────────────────────────────────────────────────────
+
+describe('dispatchAdminCommand', () => {
+  describe('when admin=true', () => {
+    it('handles a known admin command', () => {
+      expect(dispatchAdminCommand('/agents', true)).toEqual({ handled: true })
+      expect(dispatchAdminCommand('/logs', true)).toEqual({ handled: true })
+      expect(dispatchAdminCommand('/restart', true)).toEqual({ handled: true })
+      expect(dispatchAdminCommand('/update', true)).toEqual({ handled: true })
+      expect(dispatchAdminCommand('/vault', true)).toEqual({ handled: true })
+      expect(dispatchAdminCommand('/permissions', true)).toEqual({ handled: true })
+    })
+
+    it('does NOT handle per-agent ops (auth/interrupt/info/session)', () => {
+      // These are intentionally NOT admin-gated — they always run via the
+      // gateway, regardless of admin status, so the user can recover when
+      // the model is unreachable.
+      expect(dispatchAdminCommand('/auth', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/reauth', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/interrupt', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/version', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/doctor', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/usage', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/new', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/reset', true)).toEqual({ handled: false })
+    })
+
+    it('handles a known command with arguments', () => {
+      expect(dispatchAdminCommand('/logs 50', true)).toEqual({ handled: true })
+      expect(dispatchAdminCommand('/restart myagent', true)).toEqual({ handled: true })
+    })
+
+    it('handles a known command with @botname suffix', () => {
+      expect(dispatchAdminCommand('/agents@switchroombot', true)).toEqual({ handled: true })
+    })
+
+    it('does NOT handle an unknown slash command', () => {
+      expect(dispatchAdminCommand('/nope', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/unknown-command', true)).toEqual({ handled: false })
+    })
+
+    it('does NOT handle plain text (non-slash)', () => {
+      expect(dispatchAdminCommand('hello', true)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('show me the agents', true)).toEqual({ handled: false })
+    })
+
+    it('does NOT handle empty string', () => {
+      expect(dispatchAdminCommand('', true)).toEqual({ handled: false })
+    })
+  })
+
+  describe('when admin=false', () => {
+    it('does NOT handle any command — all fall through to Claude', () => {
+      // Belt-and-braces: even if the gateway calls the dispatcher for a known
+      // admin command, it must return handled=false when admin is off.
+      expect(dispatchAdminCommand('/agents', false)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/logs', false)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/restart', false)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('/nope', false)).toEqual({ handled: false })
+      expect(dispatchAdminCommand('hello', false)).toEqual({ handled: false })
+    })
+  })
+})

package/telegram-plugin/admin-commands/index.ts

@@ -0,0 +1,106 @@
+/**
+ * admin-commands/index.ts
+ *
+ * Shared dispatcher for switchroom admin slash commands. Used by both:
+ *  - gateway.ts  (when SWITCHROOM_AGENT_ADMIN=true in the agent's systemd unit)
+ *  - server.ts   (legacy monolith — always acts as its own admin)
+ *
+ * The dispatcher is intentionally thin: it only decides whether an inbound
+ * text message matches a known admin command AND should be handled locally
+ * (intercepted before Claude sees it). Actual command execution lives in the
+ * Grammy bot.command() handlers in gateway.ts / server.ts; this module
+ * provides the gating logic and the canonical command list so both paths
+ * stay in sync.
+ *
+ * Architecture
+ * ────────────
+ * Grammy routes a message to whichever handler matches first. `bot.command()`
+ * handlers fire BEFORE `bot.on('message:text')`, so a `/agents` message never
+ * reaches `handleInbound` under normal circumstances. However, when admin=false
+ * we WANT those commands to fall through to Claude. The gateway registers a
+ * middleware (via `makeAdminCommandMiddleware`) BEFORE its bot.command() calls;
+ * the middleware redirects to handleInbound when admin=false.
+ *
+ * Out of scope for Phase 1
+ * ────────────────────────
+ * `/create-agent` has a complex multi-turn state machine (persisted wizard
+ * state across messages). It is intentionally NOT included here and remains
+ * foreman/server-only until Phase 2 or later.
+ */
+
+/**
+ * The set of command names that are treated as "admin commands" — intercepted
+ * by the gateway when SWITCHROOM_AGENT_ADMIN=true, forwarded to Claude otherwise.
+ *
+ * Scope: ONLY fleet-management verbs (lifecycle, scaffolding, privileges,
+ * secrets). Per-agent / per-chat ops — auth, interrupt, permission flow,
+ * info commands (`/version`, `/doctor`, `/usage`), session reset (`/new`,
+ * `/reset`), and `/commands` — must always be gateway-handled
+ * regardless of admin status, because they need to work even when the model
+ * is unreachable (rate-limited, expired token, network down). Routing those
+ * through Claude defeats the entire point of the slash-command UX.
+ *
+ * Keep in sync with the bot.command() registrations in gateway.ts.
+ */
+export const ADMIN_COMMAND_NAMES = new Set<string>([
+  // Fleet lifecycle
+  'agents',
+  'logs',
+  'restart',
+  'stop',
+  'agentstart',
+  'update',
+  'reconcile',
+  // Privileges + secrets
+  'grant',
+  'dangerous',
+  'permissions',
+  'vault',
+  // Per-agent ops that read shared fleet state via the switchroom CLI
+  'memory',
+  'topics',
+])
+
+/**
+ * Parse a slash command name from a text message, accounting for bot@username
+ * suffixes (e.g. `/agents@mybot`). Returns null for non-command text.
+ */
+export function parseCommandName(text: string): string | null {
+  if (!text.startsWith('/')) return null
+  // Extract the part after / up to the first space or end-of-string,
+  // stripping an optional @botname suffix.
+  const raw = text.split(' ')[0]!.slice(1)
+  const atIdx = raw.indexOf('@')
+  return atIdx === -1 ? raw.toLowerCase() : raw.slice(0, atIdx).toLowerCase()
+}
+
+/**
+ * Decide whether an inbound message should be intercepted as an admin command.
+ *
+ * Returns `{ handled: true }` when:
+ *   - `adminEnabled` is true (SWITCHROOM_AGENT_ADMIN=true)
+ *   - `text` starts with `/`
+ *   - The command name is in ADMIN_COMMAND_NAMES
+ *
+ * Returns `{ handled: false }` in all other cases — the message should fall
+ * through to normal processing (forwarded to Claude via IPC).
+ *
+ * Note: this function does NOT execute the command. Execution is performed by
+ * Grammy's bot.command() handlers in gateway.ts. This function is used:
+ *  1. By the gateway middleware to decide whether to forward non-admin-gated
+ *     commands to Claude (when adminEnabled=false).
+ *  2. By tests to verify the dispatch table is correct without starting a bot.
+ */
+export function dispatchAdminCommand(
+  text: string,
+  adminEnabled: boolean,
+): { handled: boolean } {
+  // Belt-and-braces: even if the caller forgot to check, we never intercept
+  // when admin is off.
+  if (!adminEnabled) return { handled: false }
+  if (!text.startsWith('/')) return { handled: false }
+  const cmd = parseCommandName(text)
+  if (!cmd) return { handled: false }
+  if (ADMIN_COMMAND_NAMES.has(cmd)) return { handled: true }
+  return { handled: false }
+}