switchroom 0.5.0 → 0.7.8

package/skills/switchroom-manage/SKILL.md

@@ -19,7 +19,7 @@ When the user invokes `/switchroom` or asks to add, create, remove, reinstall, r
 | `/switchroom start <name>` | `switchroom agent start <name>` |
 | `/switchroom stop <name>` | `switchroom agent stop <name>` |
 | `/switchroom restart <name>` | `switchroom restart <name>` |
-| `/switchroom reinstall <name>` or "reinstall my agents" | `switchroom update` |
+| `/switchroom reinstall <name>` or "reinstall my agents" | `switchroom apply && docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d` |
 | `/switchroom status` | `switchroom auth status` |
 | `/switchroom memory <query>` | `switchroom memory search "<query>"` |
 | `/switchroom memory <query> --agent <name>` | `switchroom memory search "<query>" --agent <name>` |
@@ -30,11 +30,11 @@ When the user invokes `/switchroom` or asks to add, create, remove, reinstall, r
 
 ### Add / create a new agent
 
-When the user says "add a new agent", "add an agent to my switchroom setup", or "create a new agent", ask for a name (if not provided) and run `switchroom agent create <name>`. This scaffolds the agent directory, installs systemd timers, and wires it into the config cascade.
+When the user says "add a new agent", "add an agent to my switchroom setup", or "create a new agent", ask for a name (if not provided) and run `switchroom agent create <name>`. This scaffolds the agent directory and wires it into the config cascade. Follow up with `switchroom apply` and `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d` to materialise the new agent + scheduler containers.
 
 ### Reinstall / reprovision agents
 
-"Reinstall my agents" is a fleet-level reprovisioning operation, **not** a fresh switchroom install. It means: pull the latest code, re-apply `switchroom.yaml`, and restart the agents. Run `switchroom update` for the full fleet. Ask the user to confirm before running if the scope is ambiguous.
+"Reinstall my agents" is a fleet-level reprovisioning operation, **not** a fresh switchroom install. It means: pull the latest code, re-apply `switchroom.yaml`, and restart the agents. Run `switchroom apply` (scaffold + write compose), then `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d` to bring the fleet back up. Ask the user to confirm before running if the scope is ambiguous.
 
 ### Anthropic accounts (one OAuth, many agents)
 
@@ -84,7 +84,7 @@ Switchroom commands:
   /switchroom topics         List Telegram topics
 
 Fleet operations (run directly, not via /switchroom <sub>):
-  switchroom update          Pull latest + reconcile + restart everything
+  switchroom apply           Reconcile + (re)write compose; bring up via `docker compose ... up -d`
   switchroom version         Show versions + running agent health summary
   switchroom auth refresh-accounts  Refresh OAuth tokens + fan out (cron entrypoint)
 ```

package/skills/switchroom-status/SKILL.md

@@ -29,7 +29,7 @@ If that succeeds, parse the output and present the running agent list with full
 
 When you have real output, for each agent show:
 - **Name** and topic
-- **Status**: running / stopped / error (from systemd unit state)
+- **Status**: running / stopped / error (from the docker-compose container state)
 - **Uptime**: how long it's been running (for running agents, always include the word "uptime" and the duration)
 - **Model**: which Claude model it's using
 - **Memory**: Hindsight collection name (if configured)

package/skills/webapp-testing/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

package/skills/xlsx/VENDORED.md

@@ -7,7 +7,7 @@ Pinned to commit: 5128e1865d670f5d6c9cef000e6dfc4e951fb5b9
 ## Why vendored
 
 Switchroom ships this skill as a built-in default so every agent gets it
-on scaffold (and on `switchroom update` for pre-existing agents).
+on scaffold (and on `switchroom apply` for pre-existing agents).
 Vendoring keeps the skill content available offline and version-pinned.
 
 Opt out with:

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

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { dispatchAdminCommand, parseCommandName, ADMIN_COMMAND_NAMES } from './index.js'
+import {
+  dispatchAdminCommand,
+  parseCommandName,
+  parseCommandArg,
+  classifyAdminGate,
+  ADMIN_COMMAND_NAMES,
+} from './index.js'
 
 // ─── parseCommandName ────────────────────────────────────────────────────────
 
@@ -147,3 +153,115 @@ describe('dispatchAdminCommand', () => {
     })
   })
 })
+
+// ─── parseCommandArg ─────────────────────────────────────────────────────────
+
+describe('parseCommandArg', () => {
+  it('returns empty string when no arg', () => {
+    expect(parseCommandArg('/restart')).toBe('')
+  })
+  it('returns empty string when only whitespace', () => {
+    expect(parseCommandArg('/restart   ')).toBe('')
+  })
+  it('returns single arg', () => {
+    expect(parseCommandArg('/restart foo')).toBe('foo')
+  })
+  it('returns multi-word arg trimmed', () => {
+    expect(parseCommandArg('/restart   foo bar  ')).toBe('foo bar')
+  })
+  it('works with @botname suffix', () => {
+    expect(parseCommandArg('/restart@bot foo')).toBe('foo')
+  })
+  it('returns empty string for non-slash text', () => {
+    expect(parseCommandArg('hello world')).toBe('')
+  })
+  it('returns empty string for @botname suffix with no arg', () => {
+    expect(parseCommandArg('/restart@bot')).toBe('')
+  })
+})
+
+// ─── classifyAdminGate ───────────────────────────────────────────────────────
+
+describe('classifyAdminGate', () => {
+  const me = 'clerk'
+
+  it('passes through plain text', () => {
+    expect(classifyAdminGate('hello there', me)).toEqual({ action: 'pass-through' })
+  })
+
+  it('passes through unknown slash commands', () => {
+    expect(classifyAdminGate('/whatever', me)).toEqual({ action: 'pass-through' })
+  })
+
+  it('passes through non-admin commands', () => {
+    expect(classifyAdminGate('/version', me)).toEqual({ action: 'pass-through' })
+    expect(classifyAdminGate('/auth', me)).toEqual({ action: 'pass-through' })
+    expect(classifyAdminGate('/new', me)).toEqual({ action: 'pass-through' })
+  })
+
+  describe('/restart', () => {
+    it('passes through with no arg (self-restart)', () => {
+      expect(classifyAdminGate('/restart', me)).toEqual({ action: 'pass-through' })
+    })
+    it('passes through with whitespace-only arg', () => {
+      expect(classifyAdminGate('/restart   ', me)).toEqual({ action: 'pass-through' })
+    })
+    it('passes through when arg matches my agent name', () => {
+      expect(classifyAdminGate('/restart clerk', me)).toEqual({ action: 'pass-through' })
+    })
+    it('passes through when arg matches my agent name case-insensitively', () => {
+      expect(classifyAdminGate('/restart Clerk', me)).toEqual({ action: 'pass-through' })
+      expect(classifyAdminGate('/restart CLERK', me)).toEqual({ action: 'pass-through' })
+      expect(classifyAdminGate('/restart clerk', 'Clerk')).toEqual({ action: 'pass-through' })
+    })
+    it('passes through with @botname suffix and self target', () => {
+      expect(classifyAdminGate('/restart@switchroombot clerk', me)).toEqual({
+        action: 'pass-through',
+      })
+    })
+    it('blocks when targeting a different agent', () => {
+      expect(classifyAdminGate('/restart finn', me)).toEqual({
+        action: 'block',
+        reason: 'other-agent',
+        cmd: 'restart',
+      })
+    })
+    it('blocks when targeting `all`', () => {
+      expect(classifyAdminGate('/restart all', me)).toEqual({
+        action: 'block',
+        reason: 'other-agent',
+        cmd: 'restart',
+      })
+    })
+  })
+
+  describe('other admin commands', () => {
+    it('blocks /logs with admin-required reason', () => {
+      expect(classifyAdminGate('/logs', me)).toEqual({
+        action: 'block',
+        reason: 'admin-required',
+        cmd: 'logs',
+      })
+    })
+    it('blocks /grant with admin-required reason regardless of args', () => {
+      expect(classifyAdminGate('/grant clerk telegram', me)).toEqual({
+        action: 'block',
+        reason: 'admin-required',
+        cmd: 'grant',
+      })
+    })
+    it('blocks /agents, /update, /vault, /permissions', () => {
+      for (const c of ['agents', 'update', 'vault', 'permissions', 'stop', 'agentstart', 'reconcile', 'dangerous', 'memory', 'topics']) {
+        const r = classifyAdminGate(`/${c}`, me)
+        expect(r).toEqual({ action: 'block', reason: 'admin-required', cmd: c })
+      }
+    })
+    it('handles @botname suffix', () => {
+      expect(classifyAdminGate('/logs@switchroombot 50', me)).toEqual({
+        action: 'block',
+        reason: 'admin-required',
+        cmd: 'logs',
+      })
+    })
+  })
+})

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

@@ -74,6 +74,77 @@ export function parseCommandName(text: string): string | null {
   return atIdx === -1 ? raw.toLowerCase() : raw.slice(0, atIdx).toLowerCase()
 }
 
+/**
+ * Parse the argument portion of a slash command (everything after the command
+ * token, trimmed). Returns '' when no argument is present.
+ *
+ *   parseCommandArg('/restart')           === ''
+ *   parseCommandArg('/restart   ')        === ''
+ *   parseCommandArg('/restart foo')       === 'foo'
+ *   parseCommandArg('/restart@bot foo')   === 'foo'
+ *   parseCommandArg('/restart foo bar')   === 'foo bar'
+ */
+export function parseCommandArg(text: string): string {
+  if (!text.startsWith('/')) return ''
+  const spaceIdx = text.indexOf(' ')
+  if (spaceIdx === -1) return ''
+  return text.slice(spaceIdx + 1).trim()
+}
+
+/**
+ * Result of admin-gate classification used by the gateway middleware to decide
+ * how to handle an inbound slash command when admin gating is OFF.
+ *
+ *  - `pass-through` — let the command fall through to the gateway's local
+ *    bot.command() handler. Used for non-admin commands AND for `/restart`
+ *    targeting the current agent (self-restart is always allowed).
+ *  - `block` — the gateway should reply with an "admin required" warning and
+ *    NOT forward the message to Claude.
+ *
+ * `reason` distinguishes the two block cases for the audit log:
+ *  - `other-agent` — `/restart` aimed at a different agent
+ *  - `admin-required` — any other ADMIN_COMMAND_NAMES verb
+ */
+export type AdminGateDecision =
+  | { action: 'pass-through' }
+  | { action: 'block'; reason: 'other-agent' | 'admin-required'; cmd: string }
+
+/**
+ * Decide what the gateway middleware should do with an inbound text message
+ * when SWITCHROOM_AGENT_ADMIN=false.
+ *
+ * Rules:
+ *  - Non-slash text → pass-through.
+ *  - Unknown / non-admin slash command → pass-through.
+ *  - `/restart` with no arg, or arg matching `myAgentName` → pass-through
+ *    (gateway's local bot.command('restart', …) handles self-restart).
+ *  - `/restart <other-agent>` → block (reason='other-agent').
+ *  - Any other ADMIN_COMMAND_NAMES verb → block (reason='admin-required').
+ *
+ * This function is pure and synchronous so it can be unit-tested without a
+ * Grammy context. The middleware in gateway.ts does the side effects.
+ */
+export function classifyAdminGate(
+  text: string,
+  myAgentName: string,
+): AdminGateDecision {
+  if (!text.startsWith('/')) return { action: 'pass-through' }
+  const cmd = parseCommandName(text)
+  if (cmd === null || !ADMIN_COMMAND_NAMES.has(cmd)) {
+    return { action: 'pass-through' }
+  }
+  if (cmd === 'restart') {
+    const arg = parseCommandArg(text)
+    // Case-insensitive: assertSafeAgentName allows mixed case, so `/restart Clerk`
+    // must still self-target an agent named `clerk`.
+    if (arg === '' || arg.toLowerCase() === myAgentName.toLowerCase()) {
+      return { action: 'pass-through' }
+    }
+    return { action: 'block', reason: 'other-agent', cmd }
+  }
+  return { action: 'block', reason: 'admin-required', cmd }
+}
+
 /**
  * Decide whether an inbound message should be intercepted as an admin command.
  *

package/telegram-plugin/ask-user.ts

@@ -1,3 +1,4 @@
+// Ask-user uses pendingAskUser, not the approval kernel — see #769 for rationale.
 /**
  * Pure helpers for the `ask_user` MCP tool.
  *

package/telegram-plugin/card-event-log.ts

@@ -0,0 +1,138 @@
+/**
+ * Structured logger for the pinned progress-card lifecycle.
+ *
+ * Mirrors `pin-event-log.ts` in shape: an append-only JSON-line writer with
+ * a stable schema. Every meaningful card-driver state transition emits one
+ * line so operators can grep / replay days-old sessions and answer "did the
+ * card render? when did it finalize? was a sub-agent row ever attached?"
+ * without parsing free-form `progress-card:` traces.
+ *
+ * Output target:
+ *   - If `$STATE_DIR` is set, `<STATE_DIR>/card-events.jsonl` (append-only).
+ *   - Otherwise the line is forwarded to stderr (which the plugin-logger
+ *     captures into `~/.switchroom/logs/telegram-plugin.log`).
+ *
+ * No rotation in this PR — the file is the durable audit trail and a
+ * follow-up can add retention once the size envelope is understood.
+ *
+ * Pure helper. No globals. The write target is injectable for tests.
+ */
+
+import { appendFileSync, mkdirSync } from 'fs'
+import { dirname, join } from 'path'
+
+export type CardEventName =
+  | 'rendered'
+  | 'edited'
+  | 'finalized'
+  | 'suppressed'
+  | 'deferred'
+  | 'force-completed'
+  | 'deleted'
+
+export interface CardEvent {
+  /** Unix-ms wall clock. */
+  ts: number
+  /** Agent slug (e.g. SWITCHROOM_AGENT_NAME). Empty string if unknown. */
+  agent: string
+  /** Telegram chat id as string (matches the rest of the plugin). */
+  chatId: string
+  /** Driver-assigned per-turn key (chatId:threadId:seq). */
+  turnKey: string
+  /** The pinned card message_id once known. Optional pre-render. */
+  cardMessageId?: number
+  event: CardEventName
+  /**
+   * Free-text qualifier — e.g. the reason a turn was deferred
+   * ("in-flight-sub-agents"), the API class for a 4xx abandon, the
+   * synthetic kind for a force-complete. Single-line, ≤200 chars.
+   */
+  reason?: string
+  /** sha1-12 of the rendered HTML, when relevant. Lets us spot edit storms. */
+  htmlHash?: string
+  /** Sub-agent ids attached to the card at the time of the event. */
+  subagents?: string[]
+  /** Elapsed ms since turn start, when the call site has it cheaply. */
+  durationMs?: number
+}
+
+export type CardEventWriter = (line: string) => void
+
+let resolvedPath: string | null | undefined
+
+/**
+ * Compute the target path once and memoize. `$STATE_DIR` set → write to
+ * `<STATE_DIR>/card-events.jsonl`; otherwise return null (the default
+ * writer falls back to stderr in that case).
+ *
+ * Exposed so tests can assert resolution without actually writing.
+ */
+export function resolveCardEventPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const dir = env.STATE_DIR
+  if (!dir || dir.length === 0) return null
+  return join(dir, 'card-events.jsonl')
+}
+
+/**
+ * Reset the memoized path. Tests only.
+ */
+export function _resetForTests(): void {
+  resolvedPath = undefined
+}
+
+const defaultWriter: CardEventWriter = (line) => {
+  if (resolvedPath === undefined) {
+    resolvedPath = resolveCardEventPath()
+  }
+  const target = resolvedPath
+  if (target == null) {
+    // Fall back to stderr (the plugin-logger captures stderr into the
+    // freeform log). Prefix lets operators grep just like pin-event:.
+    try {
+      process.stderr.write(`card-event: ${line}`)
+    } catch {
+      // Never throw from a logger.
+    }
+    return
+  }
+  try {
+    mkdirSync(dirname(target), { recursive: true })
+    appendFileSync(target, line)
+  } catch {
+    // Best-effort: if the structured sink fails, surface to stderr so the
+    // event is at least in the freeform log.
+    try {
+      process.stderr.write(`card-event: ${line}`)
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export function logCardEvent(event: CardEvent, write: CardEventWriter = defaultWriter): void {
+  // Drop undefined fields so the JSON output stays compact and grep-friendly.
+  const cleaned: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(event)) {
+    if (v !== undefined) cleaned[k] = v
+  }
+  const payload = JSON.stringify(cleaned)
+  write(`${payload}\n`)
+}
+
+/**
+ * Convenience constructor — fills `ts` automatically. Most call sites only
+ * have agent / chatId / turnKey / event / a few qualifiers; this keeps the
+ * boilerplate low.
+ */
+export function emitCardEvent(
+  partial: Omit<CardEvent, 'ts'> & { ts?: number },
+  write: CardEventWriter = defaultWriter,
+): void {
+  logCardEvent(
+    {
+      ts: partial.ts ?? Date.now(),
+      ...partial,
+    } as CardEvent,
+    write,
+  )
+}