@huynle/hub 0.6.1 → 0.7.2

package/scripts/hub-node.service

@@ -0,0 +1,35 @@
+# Template: keep `hub node` running on Linux (systemd user unit).
+# The node prepares launch workspaces for the hub. It needs an enrolled machine (the plugin's /hub dialog writes the
+# machine token to ~/.config/hub/config.json, which the node only reads) and ~/.config/hub/node.json with at least
+# {"workspaceRoots": ["/home/you/projects"]} (optional: "labels", "slots", "memoryMB").
+# Install: `hub node install` writes this unit to ~/.config/systemd/user with the real paths (the runtime running the
+# CLI and the CLI's entry) and prints the systemctl commands to enable it; it never runs them (--dry-run: only print).
+# By hand (replace __RUNTIME__, __ENTRY__ and __HOME__ first):
+#   mkdir -p ~/.config/systemd/user
+#   sed -e "s|__RUNTIME__|$HOME/.bun/bin/bun|" -e "s|__ENTRY__|$PWD/packages/cli/src/main.ts|" -e "s|__HOME__|$HOME|g" \
+#     scripts/hub-node.service > ~/.config/systemd/user/hub-node.service
+#   systemctl --user daemon-reload && systemctl --user enable --now hub-node
+#   loginctl enable-linger "$USER"   # keep it running while you are logged out
+# Logs: journalctl --user -u hub-node
+# Remove: `hub node uninstall`, or systemctl --user disable --now hub-node && rm ~/.config/systemd/user/hub-node.service
+# Exit 78 means node.json gives the node nothing to do (no workspaceRoots): fix it, then restart the unit.
+# BUN_BE_BUN=1 lets an OpenCode binary act as bun; the CLI removes it from its own environment.
+[Unit]
+Description=Hub node (prepares launch workspaces for the hub)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=__RUNTIME__ __ENTRY__ node run
+Environment=PATH=__HOME__/.bun/bin:/usr/local/bin:/usr/bin:/bin
+Environment=BUN_BE_BUN=1
+Restart=on-failure
+RestartSec=30
+RestartPreventExitStatus=78
+KillSignal=SIGTERM
+TimeoutStopSec=20
+NoNewPrivileges=true
+
+[Install]
+WantedBy=default.target

package/scripts/io.github.huynle.hub-claude-code.plist

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Template: keep the Claude Code spoke daemon (`hub claude-code daemon`) running on macOS (launchd).
+  The daemon follows every Claude Code session on this machine for the hub (the hub plugin's hooks reach it over a
+  private Unix socket) and, with the Claude Code CLI found (HUB_CLAUDE_BIN, else claude on the PATH below), starts
+  Claude Code for hub launches under node.json's workspaceRoots. `hub claude` starts it on demand; this agent keeps it
+  running so launches can be placed here without a `hub claude` run first. It needs an enrolled machine (the plugin's
+  /hub dialog writes the machine token to ~/.config/hub/config.json, which the daemon only reads).
+  Install: `hub claude-code install` writes this file to ~/Library/LaunchAgents with the real paths and prints the
+  launchctl commands to load it; it never runs them (add the dry-run flag to only print). By hand (replace
+  __RUNTIME__, __ENTRY__ and __HOME__ first):
+    sed -e "s|__RUNTIME__|$HOME/.bun/bin/bun|" -e "s|__ENTRY__|$PWD/packages/cli/src/main.ts|" -e "s|__HOME__|$HOME|g" \
+      scripts/io.github.huynle.hub-claude-code.plist > ~/Library/LaunchAgents/io.github.huynle.hub-claude-code.plist
+    mkdir -p ~/.local/state/hub
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.huynle.hub-claude-code.plist
+  Remove: `hub claude-code uninstall`, or
+    launchctl bootout gui/$(id -u)/io.github.huynle.hub-claude-code && rm ~/Library/LaunchAgents/io.github.huynle.hub-claude-code.plist
+  BUN_BE_BUN=1 lets an OpenCode binary act as bun; the CLI removes it from its own environment.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>io.github.huynle.hub-claude-code</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__RUNTIME__</string>
+    <string>__ENTRY__</string>
+    <string>claude-code</string>
+    <string>daemon</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>__HOME__/.local/bin:__HOME__/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <key>BUN_BE_BUN</key>
+    <string>1</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>__HOME__/.local/state/hub/claude-code.log</string>
+  <key>StandardErrorPath</key>
+  <string>__HOME__/.local/state/hub/claude-code.log</string>
+</dict>
+</plist>

package/scripts/io.github.huynle.hub-codex-spoke.plist

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Template: keep the Codex spoke (`hub codex-spoke serve`) running on macOS (launchd).
+  The spoke attaches to the shared Codex app-server daemon's threads (CODEX_HOME/app-server-control, read only) for
+  the hub and starts its own `codex app-server` (HUB_CODEX_BIN, else codex on the PATH below) for hub launches. `hub
+  codex` starts it on demand; this agent keeps it running so launches can be placed here without a `hub codex` run
+  first. It needs an enrolled machine (the plugin's /hub dialog writes the machine token to
+  ~/.config/hub/config.json, which the spoke only reads). HUB_CODEX_CONFIG is not carried in: add it below by hand.
+  Install: `hub codex-spoke install` writes this file to ~/Library/LaunchAgents with the real paths and prints the
+  launchctl commands to load it; it never runs them (add the dry-run flag to only print). By hand (replace
+  __RUNTIME__, __ENTRY__ and __HOME__ first):
+    sed -e "s|__RUNTIME__|$HOME/.bun/bin/bun|" -e "s|__ENTRY__|$PWD/packages/cli/src/main.ts|" -e "s|__HOME__|$HOME|g" \
+      scripts/io.github.huynle.hub-codex-spoke.plist > ~/Library/LaunchAgents/io.github.huynle.hub-codex-spoke.plist
+    mkdir -p ~/.local/state/hub
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.huynle.hub-codex-spoke.plist
+  Remove: `hub codex-spoke uninstall`, or
+    launchctl bootout gui/$(id -u)/io.github.huynle.hub-codex-spoke && rm ~/Library/LaunchAgents/io.github.huynle.hub-codex-spoke.plist
+  BUN_BE_BUN=1 lets an OpenCode binary act as bun; the CLI removes it from its own environment.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>io.github.huynle.hub-codex-spoke</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__RUNTIME__</string>
+    <string>__ENTRY__</string>
+    <string>codex-spoke</string>
+    <string>serve</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>__HOME__/.local/bin:__HOME__/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <key>BUN_BE_BUN</key>
+    <string>1</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>__HOME__/.local/state/hub/codex-spoke.log</string>
+  <key>StandardErrorPath</key>
+  <string>__HOME__/.local/state/hub/codex-spoke.log</string>
+</dict>
+</plist>

package/scripts/io.github.huynle.hub-node.plist

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  Template: keep `hub node` running on macOS (launchd).
+  The node prepares launch workspaces for the hub. It needs an enrolled machine (the plugin's /hub dialog writes
+  the machine token to ~/.config/hub/config.json, which the node only reads) and ~/.config/hub/node.json with at
+  least {"workspaceRoots": ["/Users/you/projects"]} (optional: "labels", "slots", "memoryMB").
+  Install: `hub node install` writes this file to ~/Library/LaunchAgents with the real paths (the runtime running
+  the CLI and the CLI's entry) and prints the launchctl commands to load it; it never runs them. Add the dry-run
+  flag to only print. By hand (replace __RUNTIME__, __ENTRY__ and __HOME__ first):
+    sed -e "s|__RUNTIME__|$HOME/.bun/bin/bun|" -e "s|__ENTRY__|$PWD/packages/cli/src/main.ts|" -e "s|__HOME__|$HOME|g" \
+      scripts/io.github.huynle.hub-node.plist > ~/Library/LaunchAgents/io.github.huynle.hub-node.plist
+    mkdir -p ~/.local/state/hub
+    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/io.github.huynle.hub-node.plist
+  Remove: `hub node uninstall`, or
+    launchctl bootout gui/$(id -u)/io.github.huynle.hub-node && rm ~/Library/LaunchAgents/io.github.huynle.hub-node.plist
+  Exit 78 means node.json gives the node nothing to do (no workspaceRoots): fix it, then kickstart the agent.
+  BUN_BE_BUN=1 lets an OpenCode binary act as bun; the CLI removes it from its own environment.
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>io.github.huynle.hub-node</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>__RUNTIME__</string>
+    <string>__ENTRY__</string>
+    <string>node</string>
+    <string>run</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>__HOME__/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <key>BUN_BE_BUN</key>
+    <string>1</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>__HOME__/.local/state/hub/node.log</string>
+  <key>StandardErrorPath</key>
+  <string>__HOME__/.local/state/hub/node.log</string>
+</dict>
+</plist>

package/src/central/actions.ts

@@ -0,0 +1,233 @@
+// The shared action executor (design §5, §11.4): answer a permission or form, prompt a session (steer while its
+// tree runs, else a locked turn) and stop it. The console routes and the agent act verbs both call these; each
+// returns an outcome instead of an HTTP response, so every caller maps it to its own errors (the console answers
+// gone with 409, the agent API with 410) and adds its own checks (grants, audit) around the same execution.
+// Core ops are features (CORE_OPS): an OpenCode spoke serves them all, a spoke of another harness only those it
+// announced. Each action checks the feature it sends (stop; turn or steer; permission; form) and answers
+// unsupported {feature, harness} instead of sending an op the spoke would not serve.
+import type { CoreOp, FormAnswer, PermissionDecision, PromptImage, ResultFor, TurnResult } from "../protocol"
+import { randomUUID } from "node:crypto"
+import { MemoryKv } from "./backend/memory-kv"
+import type { Kv, Locks } from "./backend/types"
+import { BusyError, type Registry } from "./registry"
+import type { SpokeHub } from "./spoke-ws"
+
+/** The registry calls the executor needs (a fake in tests). */
+export type ActionRegistry = Pick<
+  Registry,
+  "permissionTargets" | "dropPermission" | "formTargets" | "dropForm" | "owner" | "running" | "exposed" | "beginTurn" | "cancelTurns" | "supports" | "harnessOf"
+>
+export type ActionSpokes = Pick<SpokeHub, "request">
+
+export interface ActionDeps {
+  readonly registry: ActionRegistry
+  readonly spokes: ActionSpokes
+  /** The user prompted the session: its message hop chain starts over (never fails). */
+  readonly humanTurn: (sessionID: string) => Promise<void>
+  /** Where requests answered through the hub are recorded (default: this process; Valkey in a cluster). */
+  readonly kv?: Kv
+  /**
+   * Cluster mode: a turn also holds the session's lease in the shared Locks (turn:<sessionID>, for ttlMs at most),
+   * so two pods never start turns in the same session within the cluster view's publish window.
+   */
+  readonly turns?: { readonly locks: Locks; readonly owner: string; readonly ttlMs: number }
+}
+
+/** The action ran. */
+export interface Done {
+  readonly outcome: "done"
+}
+/** The request or form is not pending any more: answered elsewhere, expired or ended. */
+export interface Gone {
+  readonly outcome: "gone"
+}
+/** No connected process owns the session. */
+export interface Offline {
+  readonly outcome: "offline"
+}
+/** The process that would run the action does not serve its core op (`feature`); `harness` is that process's. */
+export interface Unsupported {
+  readonly outcome: "unsupported"
+  readonly feature: CoreOp
+  readonly harness: string
+}
+
+export interface PermissionInput {
+  /** Root of the session tree whose status holds the pending request. */
+  readonly rootID: string
+  readonly requestID: string
+  readonly decision: PermissionDecision
+  /** Why (a reject's reason, for spokes announcing "permissionMessage"; the caller checks the feature). */
+  readonly message?: string
+}
+
+export type FormInput =
+  | { readonly rootID: string; readonly formID: string; readonly answer: FormAnswer; readonly cancel?: undefined }
+  | { readonly rootID: string; readonly formID: string; readonly cancel: true; readonly answer?: undefined }
+
+export interface PromptInput {
+  readonly sessionID: string
+  /** Validated and trimmed by the caller. */
+  readonly text: string
+  /** Validated by the caller; omit (or empty) for none. */
+  readonly images?: readonly PromptImage[]
+  /** True for the user's own prompts; agent prompts never reset the hop chain (decision wvqeuis0 §8). */
+  readonly resetHops: boolean
+}
+
+/** Typed input steered into the running tree. */
+export interface Steered extends Done {
+  readonly mode: "steer"
+  readonly inboxID: string
+}
+/** A new turn holds the session's lock until `result` settles (a stop ends it at once as interrupted). */
+export interface TurnStarted extends Done {
+  readonly mode: "turn"
+  readonly result: Promise<TurnResult>
+}
+
+export interface Stopped extends Done {
+  /** The spoke's answer, as it gave it. */
+  readonly result: ResultFor["stop"]
+}
+
+export interface Actions {
+  /** Unsupported when no process holding the request serves "permission". */
+  answerPermission(input: PermissionInput): Promise<Done | Gone | Unsupported>
+  /** Unsupported when no process holding the form serves "form". */
+  answerForm(input: FormInput): Promise<Done | Gone | Unsupported>
+  /** Throws BusyError when another turn holds the lock. Unsupported when the owner lacks steer (running) or turn (idle). */
+  prompt(input: PromptInput): Promise<Offline | Steered | TurnStarted | Unsupported>
+  stop(sessionID: string): Promise<Offline | Stopped | Unsupported>
+}
+
+/** How callers word an Unsupported outcome (as the read routes do). */
+export const unsupportedMessage = ({ feature, harness }: { readonly feature: string; readonly harness: string }): string => `The ${harness} spoke does not support ${feature}`
+
+const DONE: Done = { outcome: "done" }
+const GONE: Gone = { outcome: "gone" }
+const OFFLINE: Offline = { outcome: "offline" }
+const STOPPED: TurnResult = { outcome: "interrupted", message: "Stopped", reply: "" }
+
+/** How long a request answered through the hub stays answered when its harness never reports the reply. */
+const ANSWERED_MS = 10 * 60_000
+const answeredKey = (requestID: string) => `action:answered:${requestID}`
+
+export function createActions({ registry, spokes, humanTurn, kv = new MemoryKv(), turns }: ActionDeps): Actions {
+  const unsupported = (connID: string, feature: CoreOp): Unsupported | undefined =>
+    registry.supports(connID, feature) ? undefined : { outcome: "unsupported", feature, harness: registry.harnessOf(connID) ?? "unknown" }
+  /** The targets serving `feature`, or unsupported when there are targets but none serves it. */
+  const serving = <T extends { readonly connID: string }>(all: readonly T[], feature: CoreOp): T[] | Unsupported => {
+    const targets = all.filter((t) => registry.supports(t.connID, feature))
+    return targets.length || !all.length ? targets : unsupported(all[0]!.connID, feature)!
+  }
+  /** Takes the session's cluster-wide turn lease (BusyError when another pod's turn holds it); resolves its release. */
+  const shareTurn = async (sessionID: string): Promise<() => void> => {
+    if (!turns) return () => {}
+    const key = `turn:${sessionID}`
+    const holder = `${turns.owner}:${randomUUID()}`
+    if (!(await turns.locks.acquire(key, holder, turns.ttlMs))) throw new BusyError()
+    return () => void turns.locks.release(key, holder).catch(() => false)
+  }
+  return {
+    async answerPermission({ rootID, requestID, decision, message }) {
+      if ((await kv.get(answeredKey(requestID))) !== undefined) return GONE
+      const targets = serving(registry.permissionTargets(rootID, requestID), "permission")
+      if (!Array.isArray(targets)) return targets
+      if (!targets.length) return GONE
+      // Requests answered through the hub (on any pod) are gone for a second answer, even before (or without)
+      // permission.replied; claimed before sending, so two pods racing never both send it.
+      if (!(await kv.set(answeredKey(requestID), "1", { px: ANSWERED_MS, nx: true }))) return GONE
+      // Try every process that saw the request: only the one (and the location) running the session holds it.
+      let failure: unknown
+      for (const target of targets) {
+        try {
+          const result = await spokes.request(target.connID, { op: "permission", sessionID: target.sessionID, requestID, decision, ...(message !== undefined ? { message } : {}) })
+          if (!result?.gone) return DONE
+        } catch (cause) {
+          // Older spokes pass OpenCode's "Permission request not found" through as an error.
+          if (!/not found/i.test(cause instanceof Error ? cause.message : String(cause))) failure ??= cause
+        }
+      }
+      // Nobody took it: the claim goes, so a later answer (here or on another pod) is tried again.
+      await kv.del(answeredKey(requestID))
+      if (failure) throw failure
+      registry.dropPermission(requestID)
+      return GONE
+    },
+
+    async answerForm(input) {
+      const targets = serving(registry.formTargets(input.rootID, input.formID), "form")
+      if (!Array.isArray(targets)) return targets
+      if (!targets.length) return GONE
+      let failure: unknown
+      for (const target of targets) {
+        const req = input.cancel
+          ? { op: "form" as const, sessionID: target.sessionID, formID: input.formID, cancel: true as const }
+          : { op: "form" as const, sessionID: target.sessionID, formID: input.formID, answer: input.answer }
+        try {
+          const result = await spokes.request(target.connID, req)
+          if (!result?.gone) return DONE
+        } catch (cause) {
+          failure ??= cause
+        }
+      }
+      if (failure) throw failure
+      registry.dropForm(input.formID)
+      return GONE
+    },
+
+    async prompt({ sessionID, text, images, resetHops }) {
+      const connID = registry.owner(sessionID)
+      if (!connID) return OFFLINE
+      const steer = registry.running(sessionID)
+      const lacking = unsupported(connID, steer ? "steer" : "turn")
+      if (lacking) return lacking
+      const attached = images?.length ? { images: [...images] } : {}
+      if (resetHops) await humanTurn(sessionID)
+      // While anything in the tree runs, typed input redirects the current work instead of queueing.
+      if (steer) {
+        const { inboxID } = await spokes.request(connID, { op: "steer", sessionID, text, ...attached })
+        return { outcome: "done", mode: "steer", inboxID }
+      }
+      // A stop or interrupt releases the lock and ends the turn at once, even if the spoke never answers.
+      let cancel = () => {}
+      const stopped = new Promise<TurnResult>((resolve) => {
+        cancel = () => resolve(STOPPED)
+      })
+      const releaseLocal = registry.beginTurn(sessionID, () => cancel())
+      let releaseShared: () => void
+      try {
+        releaseShared = await shareTurn(sessionID)
+      } catch (cause) {
+        releaseLocal()
+        throw cause
+      }
+      const release = () => {
+        releaseLocal()
+        releaseShared()
+      }
+      const voiceStyle = registry.exposed(sessionID) === true
+      let result: Promise<TurnResult>
+      try {
+        result = Promise.race([spokes.request(connID, { op: "turn", sessionID, text, voiceStyle, ...attached }), stopped])
+      } catch (cause) {
+        release()
+        throw cause
+      }
+      // The lock is held until the turn ends, whether anyone waits for it or not.
+      void result.then(release, release)
+      return { outcome: "done", mode: "turn", result }
+    },
+
+    async stop(sessionID) {
+      const connID = registry.owner(sessionID)
+      if (!connID) return OFFLINE
+      const lacking = unsupported(connID, "stop")
+      if (lacking) return lacking
+      const result = await spokes.request(connID, { op: "stop", sessionID })
+      registry.cancelTurns(sessionID)
+      return { outcome: "done", result }
+    },
+  }
+}

package/src/central/agent/acting-routes.ts

@@ -0,0 +1,133 @@
+// The act verbs on /api/agent (design §5, §8; decision wvqeuis0): thin HTTP over the acting engine (acting.ts).
+//
+//   POST /api/agent/sessions/:addr/approve {requestID, always?, why?}
+//   POST /api/agent/sessions/:addr/deny    {requestID, why?}               why → the harness, with who denied it
+//   POST /api/agent/sessions/:addr/answer  {formID, answer | cancel: true, why?}
+//   POST /api/agent/sessions/:addr/prompt  {text, images? (users), delivery? "queue"|"steer", wake?, why?}
+//   POST /api/agent/sessions/:addr/stop    {why?} (body optional)
+//
+// Users always; sessions only through their act token (allow.act; a shell token never acts); app tokens with
+// scope sessions:act. Answers 200 with the engine's result, never cached. Errors: invalid 400, needs_user /
+// forbidden 403 (needs_user carries `evaluation` and, once P3-T8 escalates, `decisionID`), not_found 404, gone 410,
+// unsupported 422, paused 423, rate_limited 429, offline 503.
+import { DELIVER_ID_MAX, DELIVERY_MODES, type DeliveryMode, type FormAnswer, formAnswerProblem, type PromptImage, promptImagesProblem } from "../../protocol"
+import type { Acting } from "./acting"
+import { AgentError } from "./errors"
+import type { AgentRoute } from "./routes"
+
+// A literal: routes.ts imports this module (AGENT_PREFIX is not initialised yet when it loads).
+const PREFIX = "/api/agent/sessions/:addr"
+const NO_STORE = { "cache-control": "no-store" }
+const ACT = { act: true, scope: "sessions:act" } as const
+/** Longest `why`. */
+export const WHY_MAX = 1000
+
+const invalid = (message: string) => new AgentError("invalid", message)
+
+type Body = Record<string, unknown>
+
+async function bodyOf(request: Request, optional = false): Promise<Body> {
+  const raw = await request.text()
+  if (!raw.trim() && optional) return {}
+  const value: unknown = JSON.parse(raw)
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid("Body must be a JSON object")
+  return value as Body
+}
+
+function id(body: Body, key: string): string {
+  const value = body[key]
+  if (typeof value !== "string" || !value || value.length > DELIVER_ID_MAX) throw invalid(`${key} must be 1–${DELIVER_ID_MAX} characters`)
+  return value
+}
+
+function why(body: Body): { why?: string } {
+  const value = body.why
+  if (value === undefined) return {}
+  if (typeof value !== "string" || value.length > WHY_MAX) throw invalid(`why must be a string of at most ${WHY_MAX} characters`)
+  return value.trim() ? { why: value.trim() } : {}
+}
+
+function flag(body: Body, key: string): boolean | undefined {
+  const value = body[key]
+  if (value !== undefined && typeof value !== "boolean") throw invalid(`${key} must be true or false`)
+  return value
+}
+
+const ok = (result: unknown) => Response.json(result, { headers: NO_STORE })
+
+export function actingRoutes(acting: Acting): AgentRoute[] {
+  return [
+    {
+      method: "POST",
+      path: `${PREFIX}/approve`,
+      allow: ACT,
+      async handle({ request, params, actor, user }) {
+        const body = await bodyOf(request)
+        const always = flag(body, "always")
+        return ok(await acting.approve({ actor, userID: user.id }, params.addr!, { requestID: id(body, "requestID"), ...(always ? { always } : {}), ...why(body) }))
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/deny`,
+      allow: ACT,
+      async handle({ request, params, actor, user }) {
+        const body = await bodyOf(request)
+        return ok(await acting.deny({ actor, userID: user.id }, params.addr!, { requestID: id(body, "requestID"), ...why(body) }))
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/answer`,
+      allow: ACT,
+      async handle({ request, params, actor, user }) {
+        const body = await bodyOf(request)
+        const formID = id(body, "formID")
+        const cancel = flag(body, "cancel") === true
+        if (cancel ? body.answer !== undefined : body.cancel !== undefined) throw invalid("Send either an answer or cancel: true")
+        const caller = { actor, userID: user.id }
+        if (cancel) return ok(await acting.answer(caller, params.addr!, { formID, cancel: true, ...why(body) }))
+        const problem = formAnswerProblem(body.answer)
+        if (problem) throw invalid(problem)
+        return ok(await acting.answer(caller, params.addr!, { formID, answer: body.answer as FormAnswer, ...why(body) }))
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/prompt`,
+      allow: ACT,
+      async handle({ request, params, actor, user }) {
+        const body = await bodyOf(request)
+        if (typeof body.text !== "string") throw invalid("text must be a string")
+        const delivery = body.delivery
+        if (delivery !== undefined && !(DELIVERY_MODES as readonly unknown[]).includes(delivery)) throw invalid(`delivery must be one of ${DELIVERY_MODES.join(", ")}`)
+        const wake = flag(body, "wake")
+        let images: PromptImage[] | undefined
+        if (body.images !== undefined) {
+          const problem = promptImagesProblem(body.images)
+          if (problem) throw invalid(problem)
+          // Only the validated fields go on.
+          images = (body.images as PromptImage[]).map(({ mime, data, name }) => ({ mime, data, ...(name ? { name } : {}) }))
+        }
+        return ok(
+          await acting.prompt({ actor, userID: user.id }, params.addr!, {
+            text: body.text,
+            ...(images ? { images } : {}),
+            ...(delivery ? { delivery: delivery as DeliveryMode } : {}),
+            ...(wake !== undefined ? { wake } : {}),
+            ...why(body),
+          }),
+        )
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/stop`,
+      allow: ACT,
+      async handle({ request, params, actor, user }) {
+        const body = await bodyOf(request, true)
+        return ok(await acting.stop({ actor, userID: user.id }, params.addr!, why(body)))
+      },
+    },
+  ]
+}

package/src/central/agent/acting-switch.ts

@@ -0,0 +1,93 @@
+// Kill switches and the hub-wide never rules for agent actions (design §5, §7; decision wvqeuis0).
+// - Per user: AgentData.actingPaused, set by the user through GET/PUT /api/agent/acting (users only; sessions and
+//   apps never turn it on or off). Each change is in the user's agent audit (acting.pause / acting.resume).
+// - Hub-wide: the admin's switch in the Store (PUT /api/admin/agents/acting in http.ts); it applies to everyone.
+// - Either one pauses every agent action (approve, deny, answer, prompt, stop, launch, roles): the acting code
+//   (agent/acting.ts) calls ensureActing() first and again before the spoke request; it answers 423 paused.
+//   Reading and messaging keep working (messaging has its own switch, AgentData.messagingPaused).
+// - hubNever(): hub.json `agents.never` (already validated by config.ts), checked before every grant.
+import type { Store } from "../store"
+import type { AgentActor } from "./actor"
+import type { AgentAudit } from "./audit"
+import { partyFromActor } from "./envelope"
+import { AgentError } from "./errors"
+import { parsePattern, type Pattern } from "./policy"
+import { AGENT_PREFIX, type AgentRoute } from "./routes"
+
+export interface ActingSwitchDeps {
+  readonly store: Pick<Store, "agentData" | "updateAgentData" | "actingPaused" | "audit">
+  /** hub.json `agents.never` patterns (CentralConfig.agentsNever). */
+  readonly never?: readonly string[]
+  /** The agent audit (P3-T5): records each per-user change; the hub audit when absent. */
+  readonly audit?: AgentAudit
+}
+
+export class ActingSwitch {
+  private readonly never: readonly Pattern[]
+
+  constructor(private readonly deps: ActingSwitchDeps) {
+    this.never = (deps.never ?? []).flatMap((text) => parsePattern(text) ?? [])
+  }
+
+  /** The user turned agent actions off. */
+  userPaused(userID: string): boolean {
+    return this.deps.store.agentData(userID).actingPaused === true
+  }
+
+  /** The admin turned agent actions off for the whole hub. */
+  hubPaused(): boolean {
+    return this.deps.store.actingPaused()
+  }
+
+  /** Agent actions are off for this user: their own switch or the hub-wide one. */
+  isActingPaused(userID: string): boolean {
+    return this.hubPaused() || this.userPaused(userID)
+  }
+
+  /** Throws paused (423) while a kill switch is on for this user. */
+  ensureActing(userID: string): void {
+    if (this.hubPaused()) throw new AgentError("paused", "Agent actions are paused by the hub admin", { hint: "Ask the hub admin to turn them back on (Settings → Agents → Agent actions on this hub)" })
+    if (this.userPaused(userID)) {
+      throw new AgentError("paused", "Agent actions are off for this user", { hint: "Turn them back on in the console: Settings → Agents → Agent actions" })
+    }
+  }
+
+  /** The hub-wide never rules (hub.json agents.never), for every user; they beat any grant. */
+  hubNever(): readonly Pattern[] {
+    return this.never
+  }
+
+  /** Turns the user's agent actions on or off, and audits it. */
+  async setUserActing(userID: string, actor: AgentActor, enabled: boolean): Promise<void> {
+    await this.deps.store.updateAgentData(userID, (data) => {
+      if (enabled) delete data.actingPaused
+      else data.actingPaused = true
+    })
+    const verb = enabled ? "acting.resume" : "acting.pause"
+    if (this.deps.audit) {
+      await this.deps.audit.record(userID, { actor: partyFromActor(actor), verb, target: {}, decision: "allow", outcome: "ok" })
+    } else await this.deps.store.audit({ actor: userID, action: verb })
+  }
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+
+/** GET/PUT /api/agent/acting {enabled}: the caller's own switch (users only); hubEnabled shows the admin's. */
+export function actingSwitchRoutes(acting: ActingSwitch): AgentRoute[] {
+  const view = (userID: string) => Response.json({ enabled: !acting.userPaused(userID), hubEnabled: !acting.hubPaused() }, { headers: NO_STORE })
+  return [
+    { method: "GET", path: `${AGENT_PREFIX}/acting`, allow: {}, handle: ({ user }) => view(user.id) },
+    {
+      method: "PUT",
+      path: `${AGENT_PREFIX}/acting`,
+      allow: {},
+      async handle({ request, user, actor }) {
+        const body: unknown = await request.json()
+        const enabled = typeof body === "object" && body !== null && !Array.isArray(body) ? (body as Record<string, unknown>).enabled : undefined
+        if (typeof enabled !== "boolean") throw new AgentError("invalid", "enabled must be true or false")
+        await acting.setUserActing(user.id, actor, enabled)
+        return view(user.id)
+      },
+    },
+  ]
+}