switchroom 0.5.0 → 0.7.9

package/telegram-plugin/gateway/approval-callback.ts

@@ -0,0 +1,126 @@
+/**
+ * Generic `apv:` callback handler (RFC B §6.1, §8).
+ *
+ * Owns the post-tap state-machine for every approval card, regardless of
+ * which surface (secret/vault/MCP) opened the request:
+ *
+ *   1. Parse the callback_data via parseApprovalCallback.
+ *   2. Round-trip to the broker: approval_consume.
+ *      - If consumed=false (already-tapped, expired, unknown): show a
+ *        toast and edit the card to its post-tap text.
+ *   3. On `deny`: approval_record(granted=false).
+ *      On `once`: approval_record(granted=true, ttl_ms=undefined) — the
+ *        record exists for /approvals revoke targeting; it's harmless if
+ *        the agent only ever calls approval_lookup once.
+ *      On `always`: approval_record(granted=true, ttl_ms=null).
+ *      On `ttl:1h|24h|7d`: approval_record(granted=true, ttl_ms=<n>).
+ *   4. Edit the card text in-place to reflect the decision; remove the
+ *      inline keyboard so the buttons can't be re-tapped.
+ *
+ * The agent that opened the request is responsible for short-polling
+ * approval_lookup (RFC §10) to discover the outcome and proceed.
+ */
+
+import type { Context } from "grammy";
+import { parseApprovalCallback, ttlMsFromToken } from "./approval-card.js";
+import {
+  approvalConsume,
+  approvalRecord,
+} from "../../src/vault/approvals/client.js";
+import type { ApprovalDecisionMode } from "../../src/vault/approvals/schema.js";
+
+export async function handleApprovalCallback(
+  ctx: Context,
+  data: string,
+): Promise<void> {
+  const parsed = parseApprovalCallback(data);
+  if (parsed === null) {
+    await ctx.answerCallbackQuery({ text: "malformed approval callback" });
+    return;
+  }
+
+  const consumed = await approvalConsume(parsed.request_id);
+  if (consumed === null) {
+    await ctx.answerCallbackQuery({ text: "approval kernel unreachable" });
+    return;
+  }
+  if (!consumed.consumed) {
+    // Single-use enforcement: someone already tapped, or the nonce
+    // expired/unknown. Match the RFC §8.1 wording.
+    await ctx.answerCallbackQuery({ text: "this prompt expired" });
+    return;
+  }
+
+  // Compute decision + ttl from the choice variant.
+  let decision: ApprovalDecisionMode;
+  let granted: boolean;
+  let ttl_ms: number | null = null;
+  let displayMode: string;
+  switch (parsed.choice.kind) {
+    case "deny":
+      decision = "deny";
+      granted = false;
+      displayMode = "denied";
+      break;
+    case "once":
+      decision = "allow_once";
+      granted = true;
+      // No expiry — recorded as a one-shot grant; the agent calls
+      // approval_lookup at most once, then proceeds. /approvals revoke
+      // can still target the row by id.
+      displayMode = "granted once";
+      break;
+    case "always":
+      decision = "allow_always";
+      granted = true;
+      displayMode = "granted always";
+      break;
+    case "ttl": {
+      decision = "allow_ttl";
+      granted = true;
+      const ms = ttlMsFromToken(parsed.choice.param);
+      if (ms === null) {
+        await ctx.answerCallbackQuery({ text: "bad ttl token" });
+        return;
+      }
+      ttl_ms = ms;
+      displayMode = `granted for ${parsed.choice.param}`;
+      break;
+    }
+  }
+
+  const granted_by_user_id = ctx.from?.id ?? 0;
+  // Approver set at decision time = the chat that received the card. We
+  // store the singleton for now; the gateway-side approver-set lookup
+  // (drift detection input) will widen this in the per-callsite wire-up
+  // when each surface migrates and starts passing access.allowFrom.
+  const approver_set = [String(granted_by_user_id)];
+
+  const decision_id = await approvalRecord({
+    request_id: parsed.request_id,
+    decision,
+    approver_set,
+    granted_by_user_id,
+    ttl_ms,
+  });
+
+  if (decision_id === null) {
+    await ctx.answerCallbackQuery({ text: "kernel record failed" });
+    return;
+  }
+
+  // Edit the original card to its post-tap state and drop the keyboard.
+  const icon = granted ? "✅" : "🚫";
+  const newBody =
+    `${icon} ${displayMode}` +
+    (granted
+      ? ` · /approvals revoke <code>${decision_id}</code>`
+      : "");
+
+  try {
+    await ctx.editMessageText(newBody, { parse_mode: "HTML", reply_markup: undefined });
+  } catch {
+    // Best-effort: card may have been edited or deleted under us.
+  }
+  await ctx.answerCallbackQuery({ text: granted ? "Approved" : "Denied" });
+}

package/telegram-plugin/gateway/approval-card.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Tests for the approval card primitive (RFC B §8).
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  buildApprovalCard,
+  parseApprovalCallback,
+  ttlMsFromToken,
+} from "./approval-card.js";
+
+describe("approval card", () => {
+  it("renders the pristine card with default buttons", () => {
+    const card = buildApprovalCard({
+      request_id: "a3f1b9c2",
+      agent: "klanker",
+      scope_humanized: "secret:OPENAI_API_KEY",
+      why: "needs to call OpenAI",
+    });
+    expect(card.text).toContain("klanker");
+    expect(card.text).toContain("secret:OPENAI_API_KEY");
+    expect(card.text).toContain("needs to call OpenAI");
+
+    // Validate the inline_keyboard structure carries our four callback shapes
+    const flat = card.reply_markup.inline_keyboard.flat();
+    const datas = flat.map((b) => ("callback_data" in b ? b.callback_data : ""));
+    expect(datas).toContain("apv:a3f1b9c2:once");
+    expect(datas).toContain("apv:a3f1b9c2:deny");
+    expect(datas).toContain("apv:a3f1b9c2:always");
+  });
+
+  it("respects offer_always=false and offer_ttl=true", () => {
+    const card = buildApprovalCard({
+      request_id: "a3f1b9c2",
+      agent: "k",
+      scope_humanized: "x",
+      offer_always: false,
+      offer_ttl: true,
+    });
+    const datas = card.reply_markup.inline_keyboard
+      .flat()
+      .map((b) => ("callback_data" in b ? b.callback_data : ""));
+    expect(datas).not.toContain("apv:a3f1b9c2:always");
+    expect(datas).toContain("apv:a3f1b9c2:ttl:1h");
+  });
+
+  it("escapes HTML metacharacters in agent and scope", () => {
+    const card = buildApprovalCard({
+      request_id: "deadbeef",
+      agent: "<script>",
+      scope_humanized: "a&b",
+    });
+    expect(card.text).not.toContain("<script>");
+    expect(card.text).toContain("&lt;script&gt;");
+    expect(card.text).toContain("a&amp;b");
+  });
+});
+
+describe("parseApprovalCallback", () => {
+  it("parses every choice variant", () => {
+    expect(parseApprovalCallback("apv:a3f1b9c2:once"))
+      .toEqual({ request_id: "a3f1b9c2", choice: { kind: "once" } });
+    expect(parseApprovalCallback("apv:a3f1b9c2:always"))
+      .toEqual({ request_id: "a3f1b9c2", choice: { kind: "always" } });
+    expect(parseApprovalCallback("apv:a3f1b9c2:deny"))
+      .toEqual({ request_id: "a3f1b9c2", choice: { kind: "deny" } });
+    expect(parseApprovalCallback("apv:a3f1b9c2:ttl:1h"))
+      .toEqual({ request_id: "a3f1b9c2", choice: { kind: "ttl", param: "1h" } });
+  });
+
+  it("rejects malformed prefixes and bad ids", () => {
+    expect(parseApprovalCallback("perm:more:abc")).toBeNull();
+    expect(parseApprovalCallback("apv:NOTHEX12:once")).toBeNull();
+    expect(parseApprovalCallback("apv:a3f1b9c2:bogus")).toBeNull();
+    expect(parseApprovalCallback("apv:a3f1b9c2:ttl")).toBeNull();
+  });
+});
+
+describe("ttlMsFromToken", () => {
+  it("parses h and d units", () => {
+    expect(ttlMsFromToken("1h")).toBe(60 * 60 * 1000);
+    expect(ttlMsFromToken("24h")).toBe(24 * 60 * 60 * 1000);
+    expect(ttlMsFromToken("7d")).toBe(7 * 24 * 60 * 60 * 1000);
+  });
+  it("rejects garbage", () => {
+    expect(ttlMsFromToken("0h")).toBeNull();
+    expect(ttlMsFromToken("1m")).toBeNull();
+    expect(ttlMsFromToken("h")).toBeNull();
+  });
+});

package/telegram-plugin/gateway/approval-card.ts

@@ -0,0 +1,127 @@
+/**
+ * Generic Telegram approval card primitive (RFC B §8).
+ *
+ * One shape, every surface (secrets / vault grants / MCP tools). Builds
+ * the inline keyboard with [Allow once] [Allow always] [Deny] (and an
+ * optional [⏱ For 1h] when ttl is offered) and the matching `apv:` callback
+ * data. The `apv:` namespace is reserved for the approval kernel; the
+ * gateway dispatch table routes those callbacks into kernel.consumeNonce
+ * + kernel.recordDecision.
+ *
+ * Callback wire format (RFC §6.1, fits Telegram's 64-byte cap):
+ *   apv:<8-hex request_id>:<choice>[:<param>]
+ *     choice = once | always | deny | ttl
+ *     param  = (for ttl) 1h | 24h | 7d
+ */
+
+import { InlineKeyboard } from "grammy";
+
+export interface ApprovalCardOptions {
+  request_id: string;       // 8-hex from kernel.requestApproval
+  agent: string;            // shown in the title
+  scope_humanized: string;  // human-readable scope (resolver may patch later)
+  why?: string;             // optional context paragraph
+  offer_always?: boolean;   // hide [Allow always] when scope is too narrow to bind a rule
+  offer_ttl?: boolean;      // show [⏱ For 1h] secondary button
+}
+
+export interface BuiltApprovalCard {
+  text: string;
+  reply_markup: InlineKeyboard;
+}
+
+/**
+ * Build the pristine approval card. Granted/denied/expired states are
+ * rendered by the gateway after the user taps — those use editMessageText
+ * with a fresh body, no buttons.
+ */
+export function buildApprovalCard(opts: ApprovalCardOptions): BuiltApprovalCard {
+  const lines: string[] = [];
+  lines.push(`🔐 <b>${escapeHtml(opts.agent)}</b> wants approval`);
+  lines.push(`<code>${escapeHtml(opts.scope_humanized)}</code>`);
+  if (opts.why && opts.why.trim().length > 0) {
+    lines.push("");
+    lines.push(escapeHtml(opts.why.trim()));
+  }
+  const text = lines.join("\n");
+
+  const kb = new InlineKeyboard()
+    .text("✅ Allow once", `apv:${opts.request_id}:once`)
+    .text("🚫 Deny", `apv:${opts.request_id}:deny`);
+
+  // Secondary row — Always + TTL when offered
+  const secondary: Array<[string, string]> = [];
+  if (opts.offer_always !== false) {
+    secondary.push(["🔁 Always", `apv:${opts.request_id}:always`]);
+  }
+  if (opts.offer_ttl === true) {
+    secondary.push(["⏱ For 1h", `apv:${opts.request_id}:ttl:1h`]);
+  }
+  if (secondary.length > 0) {
+    kb.row();
+    for (const [label, data] of secondary) {
+      kb.text(label, data);
+    }
+  }
+
+  return { text, reply_markup: kb };
+}
+
+/**
+ * Parse an `apv:` callback. Returns null on a malformed string so the
+ * caller can fall through to whatever generic-callback handling exists.
+ */
+export type ApprovalChoice =
+  | { kind: "once" }
+  | { kind: "always" }
+  | { kind: "deny" }
+  | { kind: "ttl"; param: string };
+
+export interface ParsedApprovalCallback {
+  request_id: string;
+  choice: ApprovalChoice;
+}
+
+export function parseApprovalCallback(data: string): ParsedApprovalCallback | null {
+  if (!data.startsWith("apv:")) return null;
+  const parts = data.split(":");
+  // apv:<id>:<choice>[:<param>]
+  if (parts.length < 3) return null;
+  const request_id = parts[1];
+  const choiceStr = parts[2];
+  if (!/^[0-9a-f]{8}$/.test(request_id ?? "")) return null;
+  switch (choiceStr) {
+    case "once":
+      return { request_id: request_id as string, choice: { kind: "once" } };
+    case "always":
+      return { request_id: request_id as string, choice: { kind: "always" } };
+    case "deny":
+      return { request_id: request_id as string, choice: { kind: "deny" } };
+    case "ttl": {
+      const param = parts[3];
+      if (!param) return null;
+      return { request_id: request_id as string, choice: { kind: "ttl", param } };
+    }
+    default:
+      return null;
+  }
+}
+
+/** Map a TTL token like '1h' / '24h' / '7d' to milliseconds. */
+export function ttlMsFromToken(token: string): number | null {
+  const m = /^(\d+)([hd])$/.exec(token);
+  if (!m) return null;
+  const n = parseInt(m[1] ?? "", 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const unit = m[2];
+  if (unit === "h") return n * 60 * 60 * 1000;
+  if (unit === "d") return n * 24 * 60 * 60 * 1000;
+  return null;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/telegram-plugin/gateway/approvals-commands.ts

@@ -0,0 +1,126 @@
+/**
+ * `/approvals` command surface (RFC B §9).
+ *
+ * Self-contained module that registers `/approvals list` and
+ * `/approvals revoke <id>` against a grammy Bot. Wired in from
+ * `gateway.ts` with one line:
+ *
+ *   import { registerApprovalsCommands } from './approvals-commands.js'
+ *   registerApprovalsCommands(bot, { allowFromCheck })
+ *
+ * Out of scope for this commit: `/approvals add` (grant wizard) and
+ * `/approvals stats` (RFC §9). Those are Phase 1.5 — straightforward to
+ * add on top of the same client. Tracked in the migration TODO inline.
+ */
+
+import type { Bot, Context } from "grammy";
+import {
+  approvalList,
+  approvalRevoke,
+} from "../../src/vault/approvals/client.js";
+
+export interface RegisterApprovalsCommandsOpts {
+  /**
+   * Caller-provided gate that returns true if the message sender is
+   * permitted to run /approvals commands. Mirrors the existing pattern
+   * used by other administrative commands (e.g. /pending) — the gateway
+   * already has its `allowFrom` check; we don't duplicate the policy
+   * lookup here.
+   */
+  isApprover: (ctx: Context) => boolean | Promise<boolean>;
+}
+
+export function registerApprovalsCommands(
+  bot: Bot,
+  opts: RegisterApprovalsCommandsOpts,
+): void {
+  bot.command("approvals", async (ctx) => {
+    if (!(await opts.isApprover(ctx))) {
+      await ctx.reply("Not authorized to view approvals.", { reply_markup: undefined });
+      return;
+    }
+
+    const args = (ctx.match ?? "").toString().trim().split(/\s+/).filter(Boolean);
+    const sub = args[0]?.toLowerCase();
+
+    // /approvals  → list
+    if (sub === undefined || sub === "list") {
+      const agentFilter = sub === "list" ? args[1] : undefined;
+      const decisions = await approvalList(agentFilter);
+      if (decisions === null) {
+        await ctx.reply("Approval kernel unreachable (vault broker not running?).");
+        return;
+      }
+      if (decisions.length === 0) {
+        await ctx.reply(
+          agentFilter
+            ? `No active approvals for <code>${escapeHtml(agentFilter)}</code>.`
+            : "No active approvals.",
+          { parse_mode: "HTML" },
+        );
+        return;
+      }
+      // Top-level summary by agent, mirroring the GitHub-style permissions UI
+      // referenced in RFC §9.
+      const byAgent = new Map<string, number>();
+      for (const d of decisions) byAgent.set(d.agent_unit, (byAgent.get(d.agent_unit) ?? 0) + 1);
+      const summary = Array.from(byAgent.entries())
+        .map(([a, n]) => `• <b>${escapeHtml(a)}</b>: ${n}`)
+        .join("\n");
+      const detail = decisions
+        .slice(0, 20)
+        .map((d) => {
+          const ttl =
+            d.ttl_expires_at === null
+              ? "always"
+              : `until ${new Date(d.ttl_expires_at).toISOString().slice(0, 16).replace("T", " ")}`;
+          return (
+            `<code>${escapeHtml(d.id.slice(0, 8))}</code> ` +
+            `${escapeHtml(d.agent_unit)} → ` +
+            `<code>${escapeHtml(d.scope)}</code> ` +
+            `(${escapeHtml(d.action)}, ${ttl}) ` +
+            `· /approvals revoke ${escapeHtml(d.id)}`
+          );
+        })
+        .join("\n");
+      await ctx.reply(`<b>Active approvals</b>\n\n${summary}\n\n${detail}`, {
+        parse_mode: "HTML",
+      });
+      return;
+    }
+
+    // /approvals revoke <id>
+    if (sub === "revoke") {
+      const id = args[1];
+      if (!id) {
+        await ctx.reply("Usage: <code>/approvals revoke &lt;id&gt;</code>", {
+          parse_mode: "HTML",
+        });
+        return;
+      }
+      const actor = ctx.from?.id?.toString() ?? "unknown";
+      const ok = await approvalRevoke(id, actor, "manual /approvals revoke");
+      if (ok === null) {
+        await ctx.reply("Approval kernel unreachable.");
+        return;
+      }
+      await ctx.reply(
+        ok ? `Revoked <code>${escapeHtml(id)}</code>.` : `No such active decision <code>${escapeHtml(id)}</code>.`,
+        { parse_mode: "HTML" },
+      );
+      return;
+    }
+
+    // /approvals add and /approvals stats — TODO Phase 1.5
+    await ctx.reply(
+      `Unknown subcommand <code>${escapeHtml(sub)}</code>. ` +
+      `Use <code>/approvals list</code> or <code>/approvals revoke &lt;id&gt;</code>. ` +
+      `(<code>add</code> and <code>stats</code> are coming in a follow-up.)`,
+      { parse_mode: "HTML" },
+    );
+  });
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/telegram-plugin/gateway/boot-card.ts

@@ -41,7 +41,10 @@ import {
   probeGateway,
   probeQuota,
   probeHindsight,
-  probeCronTimers,
+  probeScheduler,
+  probeBroker,
+  probeKernel,
+  probeSkills,
   watchAgentProcess,
   AGENT_LIVE_WINDOW_MS,
   AGENT_LIVE_POLL_INTERVAL_MS,
@@ -89,7 +92,16 @@ export function resolvePersonaName(
 
 export type RestartReason = 'planned' | 'graceful' | 'crash' | 'fresh'
 
-export type ProbeKey = 'account' | 'agent' | 'gateway' | 'quota' | 'hindsight' | 'crons'
+export type ProbeKey =
+  | 'account'
+  | 'agent'
+  | 'gateway'
+  | 'quota'
+  | 'hindsight'
+  | 'scheduler'
+  | 'broker'
+  | 'kernel'
+  | 'skills'
 
 export type ProbeMap = Partial<Record<ProbeKey, ProbeResult | null>>
 
@@ -204,11 +216,15 @@ const PROBE_LABELS: Record<ProbeKey, string> = {
   gateway:   'Gateway',
   quota:     'Quota',
   hindsight: 'Hindsight',
-  crons:     'Crons',
+  scheduler: 'Scheduler',
+  broker:    'Broker',
+  kernel:    'Kernel',
+  skills:    'Skills',
 }
 
 const PROBE_KEYS: ReadonlyArray<ProbeKey> = [
-  'account', 'agent', 'gateway', 'quota', 'hindsight', 'crons',
+  'account', 'agent', 'gateway', 'quota', 'hindsight',
+  'scheduler', 'broker', 'kernel', 'skills',
 ]
 
 const REASON_EMOJI: Record<RestartReason, string> = {
@@ -390,6 +406,11 @@ export interface RunProbesOpts {
   /** When true, resolve the agent PID via cgroup walk instead of MainPID
    *  (which is the tmux server pid under tmux supervisor). */
   tmuxSupervisor?: boolean
+  /** When true, the gateway is running inside an agent docker container.
+   *  Probes that depend on systemctl (Agent, Crons) switch to /proc walks
+   *  and externally-managed surface text instead of execing systemctl
+   *  (which doesn't exist in the agent image). See `runtime-mode.ts`. */
+  dockerMode?: boolean
 }
 
 /** Run all six probes concurrently with their own per-probe timeouts.
@@ -404,11 +425,14 @@ export async function runAllProbes(opts: RunProbesOpts): Promise<ProbeMap> {
 
   await Promise.allSettled([
     probeAccount(opts.agentDir).then(r => { probes.account = r }),
-    probeAgentProcess(slug, { execFileImpl: opts.probeExecFileImpl, tmuxSupervisor: opts.tmuxSupervisor }).then(r => { probes.agent = r }),
+    probeAgentProcess(slug, { execFileImpl: opts.probeExecFileImpl, tmuxSupervisor: opts.tmuxSupervisor, dockerMode: opts.dockerMode }).then(r => { probes.agent = r }),
     probeGateway(opts.gatewayInfo).then(r => { probes.gateway = r }),
     probeQuota(claudeDir, opts.agentDir, opts.fetchImpl).then(r => { probes.quota = r }),
     probeHindsight(opts.bankName, opts.fetchImpl).then(r => { probes.hindsight = r }),
-    probeCronTimers(slug, { execFileImpl: opts.probeExecFileImpl }).then(r => { probes.crons = r }),
+    probeScheduler(slug, { dockerMode: opts.dockerMode }).then(r => { probes.scheduler = r }),
+    probeBroker(undefined, { dockerMode: opts.dockerMode }).then(r => { probes.broker = r }),
+    probeKernel(undefined, { dockerMode: opts.dockerMode }).then(r => { probes.kernel = r }),
+    probeSkills(opts.agentDir).then(r => { probes.skills = r }),
   ])
 
   return probes
@@ -530,6 +554,7 @@ export async function startBootCard(
           sleepImpl: opts.agentLiveSleepImpl,
           execFileImpl: opts.agentLiveExecFileImpl,
           tmuxSupervisor: opts.tmuxSupervisor,
+          dockerMode: opts.dockerMode,
         })
 
         for await (const agentResult of watcher) {