typeclaw 0.3.0 → 0.4.0

package/src/skills/typeclaw-plugins/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-plugins
-description: TypeClaw plugin authoring and operation guide. Use when writing, editing, configuring, debugging, or installing a TypeClaw plugin — including any work with definePlugin, defineTool, defineSubagent, plugin hooks (session.start/end/idle/prompt, tool.before/after), plugin cron jobs, plugin skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugins[]', 'typeclaw-plugin-', or any file under src/plugin/ or plugins/.
+description: TypeClaw plugin authoring and operation guide. Use when writing, editing, configuring, debugging, or installing a TypeClaw plugin — including any work with definePlugin, defineTool, defineSubagent, plugin hooks (session.start/end/idle/prompt, tool.before/after), plugin cron jobs, plugin commands (host/container/either CLI subcommands callable as `typeclaw <name>`), plugin skills, the typeclaw/plugin import path, or per-plugin config blocks in typeclaw.json. Also use when you need to bridge a cron `exec` job to LLM-driven work — the canonical pattern is a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, invoked as `typeclaw <command>` from cron's `command` array. Triggers on mentions of 'TypeClaw plugin', 'definePlugin', 'plugin hook', 'plugin cron', 'plugin command', 'PluginCommand', 'ContainerCommand', 'HostCommand', 'EitherCommand', 'ctx.prompt', 'ctx.subagent', 'ctx.exec', 'plugins[]', 'typeclaw-plugin-', or any file under src/plugin/ or plugins/.
 ---
 
 # TypeClaw Plugins
@@ -252,13 +252,59 @@ cronJobs: {
     kind: 'exec',
     command: ['bun', 'run', 'scripts/rotate.ts'],
   },
+  // The canonical shape for scheduled imperative LLM work: a handler
+  // function the cron consumer invokes directly. No shell-out, no WS
+  // round-trip, no Bun.spawn — the handler runs in-process with the same
+  // ctx.prompt / ctx.exec surface a container command sees.
+  'inbox-watch': {
+    schedule: '*/15 * * * *',
+    kind: 'handler',
+    handler: async (ctx) => {
+      const { stdout } = await ctx.exec`gmail unread --count`
+      if (Number(stdout.trim()) === 0) return
+      await ctx.prompt(`Triage ${stdout.trim()} new emails…`)
+    },
+  },
 }
 ```
 
 - The map key is a **suffix**. The runtime constructs the global cron id as `__plugin_<plugin-name>_<key>` (e.g., `__plugin_standup-log_weekly-digest`).
 - `cron.json` user job ids cannot start with underscore, so collision is impossible by construction.
 - A `prompt` job's `subagent` and `payload` are **validated against the registry at boot** — bad references fail loudly on disk, not 6 hours later when the job fires.
-- Only two kinds: `prompt` and `exec`. Plugins do not extend the schema.
+- Three kinds: `prompt`, `exec`, `handler`. **`handler` is plugin-only** — it cannot appear in `cron.json` because the handler is a TypeScript function reference (not JSON-serializable). User-authored cron files are validated by `parseCronFile` which rejects anything outside `prompt | exec`.
+
+#### `kind: 'handler'` — direct function dispatch
+
+When the cron job needs imperative control flow (probe → maybe prompt → write file) and the logic lives in the same plugin as the schedule, declare it as a `handler`. The consumer invokes the function directly with a `CronHandlerContext`:
+
+```ts
+type CronHandlerContext = {
+  readonly jobId: string // __plugin_<name>_<key>
+  readonly name: string // plugin name that registered the job
+  readonly agentDir: string // /agent in container
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal // reserved for future cancellation; currently inert
+  readonly permissions: PermissionService
+  readonly origin: SessionOrigin // { kind: 'cron', jobKind: 'handler', ... }
+  readonly prompt: (text: string) => Promise<string> // full agent session, slim system prompt mode
+  readonly subagent: (name, payload?) => Promise<void>
+  readonly exec: (cmd, ...vals) => Promise<CommandExecResult> // tagged template
+}
+```
+
+The `prompt` / `subagent` / `exec` surface is identical to `ContainerCommandContext` (§5.7) and reuses the same underlying implementation — abort semantics, process-group kill, slim system prompt mode are all shared. Differences from `ContainerCommandContext`: no `stdin` / `stdout` / `stderr` (cron has no caller piping bytes), no `args` (handlers are scheduled, not invoked with flags), no return value (throw to signal failure, the consumer logs).
+
+#### When to use which `kind`
+
+| `kind`          | Use for                                                                                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'prompt'`      | One-shot natural-language prompts. Stable instruction, no shell pre-work, no conditional logic.                                                     |
+| `'exec'`        | Pure shell work — `git commit`, log rotation, calling a script. Can also point at a plugin's `surface: 'host'` command via `['typeclaw', '<cmd>']`. |
+| **`'handler'`** | **The default for plugin-internal scheduled imperative work.** Probe + maybe prompt, multi-step orchestration, anything mixing shell and LLM calls. |
+
+A plugin that exposes a `surface: 'container'` command (§5.7) often does NOT need a corresponding cron handler — if the command's whole `run` body is the scheduled work, just factor the body into a shared private function and have BOTH the command and the cron handler call it. The command stays callable from the TUI / manual shell; the cron handler stays callable from the scheduler without shelling out.
+
+The pre-handler workaround (cron `kind: 'exec'` with `command: ['typeclaw', '<plugin-cmd>']` shelling out to its own container) is still valid but no longer the default — reach for it only when the user owns the cadence (`cron.json` scheduling someone else's command) or when the scheduled work is genuinely a host-side command. See `typeclaw-cron` for the full decision tree.
 
 ### 5.4 `skills` — string-form (per-session tmpdir)
 
@@ -326,6 +372,198 @@ Provider prompt caching makes the **prefix** of the system prompt 5–10× cheap
 
 If your content varies per session, **append**. If it's stable across sessions, prepending is fine but understand the cost.
 
+### 5.7 `commands` — typeclaw CLI subcommands
+
+A plugin can register top-level CLI commands invocable as `typeclaw <name>` from any shell sitting in the agent folder. **Unlike every other contribution in §5, `commands` is declared by-value on `definePlugin(...)`, NOT inside the factory return.** This is so the host-stage CLI can dispatch commands without booting the plugin runtime (no `bun install`, no factory, no engine spin-up just to print `--help`).
+
+```ts
+import { z } from 'zod'
+import { definePlugin } from 'typeclaw/plugin'
+
+export default definePlugin({
+  commands: {
+    'standup-now': {
+      surface: 'container',
+      description: 'Generate a standup write-up for today from sessions/.',
+      args: z.object({
+        date: z.string().optional().describe('YYYY-MM-DD; defaults to today'),
+      }),
+      async run(ctx, args) {
+        const text = await ctx.prompt(
+          `Read sessions/ for ${args.date ?? 'today'} and write a 3-bullet standup to standup/${args.date ?? 'today'}.md.`,
+        )
+        const writer = ctx.stdout.getWriter()
+        await writer.write(new TextEncoder().encode(text + '\n'))
+        writer.releaseLock()
+        return 0
+      },
+    },
+  },
+  plugin: async (ctx) => ({
+    /* tools, hooks, cron, ... */
+  }),
+})
+```
+
+Once installed, the user (or a cron `exec` job) runs `typeclaw standup-now --date=2026-05-18`. `typeclaw --help` lists all discovered plugin commands automatically — no separate registration.
+
+#### The three surfaces
+
+| `surface`     | Runs where                                                          | `ctx` has                                                                 | Use when                                                                                                                                                                                                                                                                                                                              |
+| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'container'` | Inside the running agent container, proxied over WS by the host CLI | `prompt`, `subagent`, `exec`, `permissions`, `origin`, `signal` + streams | The command needs the agent runtime — LLM calls (`ctx.prompt`), subagent invocation, permission checks. Reusable from TUI, manual shell, `compose`, and (as a narrower fallback when reusability is required) cron `exec`. For plugin-internal scheduled `exec → LLM` work, prefer `kind: 'handler'` (§5.3) — see "Cron usage" below. |
+| `'host'`      | On the user's machine, no container required                        | `streams`, `signal`, `logger`, `agentDir` (host path)                     | The command only touches host-side state (files, host binaries, prompts the user). Container does NOT need to be running.                                                                                                                                                                                                             |
+| `'either'`    | Whichever stage invoked it — same author code runs in both          | The intersection (`streams`, `signal`, `logger`, `agentDir`)              | The command's logic is stage-agnostic. `agentDir` resolves to `/agent` in the container and the host path on the host, automatically.                                                                                                                                                                                                 |
+
+The `surface: 'container'` command requires the container to be running. The host CLI opens a WebSocket to `/commands` on the agent's port, sends `exec_command`, and streams stdout/stderr back. Ctrl-C on the host propagates as `AbortSignal` to `ctx.signal` inside the container.
+
+#### `ContainerCommandContext` — what you get inside `run`
+
+```ts
+type ContainerCommandContext = {
+  readonly name: string // plugin name (e.g. 'standup-log'), NOT command name
+  readonly version: string | undefined
+  readonly agentDir: string // /agent inside the container
+  readonly logger: PluginLogger
+  readonly permissions: PermissionService
+  readonly origin: SessionOrigin // caller's origin — cron job, TUI op, etc.
+  readonly signal: AbortSignal // aborts on ws close or host Ctrl-C
+  readonly stdin: ReadableStream<Uint8Array>
+  readonly stdout: WritableStream<Uint8Array>
+  readonly stderr: WritableStream<Uint8Array>
+  readonly prompt: (text: string) => Promise<string> // full LLM session, full toolset, returns last assistant text
+  readonly subagent: (name: string, payload?: unknown) => Promise<void>
+  readonly exec: (cmd: TemplateStringsArray, ...values: unknown[]) => Promise<CommandExecResult>
+}
+```
+
+Key facts about each capability:
+
+- **`ctx.prompt(text)`** opens a brand-new `AgentSession` with the full agent toolset (read/bash/edit/write/grep/find/ls + plugin tools), sends `text` as if a user typed it, and returns the last assistant message. The session is created and disposed inside the call. The session uses **slim system prompt mode** (subagent-shaped origin) so you save ~2000 tokens per LLM call versus a normal TUI session.
+- **`ctx.subagent(name, payload)`** invokes a registered subagent (yours or another plugin's). Returns when the subagent's `runSession` resolves.
+- **`ctx.exec` is a tagged template** — `await ctx.exec\`git log --oneline -10\``runs the command in the agent folder with`ctx.signal` threaded through. Aborts kill the entire process group (SIGTERM → 5s grace → SIGKILL) so daemonized grandchildren don't outlive the abort.
+- **`ctx.origin`** carries the caller's `SessionOrigin`. For host-invoked (TUI op) calls it's `{ kind: 'tui', ... }`; for cron-invoked calls it's the cron job's origin including `scheduledByRole`. **No silent role elevation** — a cron job running as `scheduledByRole: 'member'` invokes the command with that same role, and permission checks inside the command resolve accordingly.
+
+#### Cron usage: prefer `kind: 'handler'` over shelling out to your own command
+
+Plugin cron jobs support `kind: 'handler'` (§5.3) which invokes a TypeScript function directly with a `CronHandlerContext`. The handler ctx exposes the SAME `ctx.prompt` / `ctx.subagent` / `ctx.exec` surface a container command sees — same slim-mode session, same process-group abort semantics — but without the shell-out, the WS round-trip, or the args-parse round-trip.
+
+**If the cron job and the command both live in the same plugin, prefer a handler.** Factor any shared logic into a private function and have BOTH the command's `run` body and the cron handler call it. The command stays callable from the TUI / manual `typeclaw` invocations; the cron handler stays callable from the scheduler with zero shell-out cost.
+
+The shell-out pattern below (cron `exec` → `typeclaw <plugin-cmd>`) is still supported and stays valid in three narrow cases, all rooted in **the same logic needing a callable surface beyond cron**:
+
+1. **The logic is also a reusable CLI command.** The user wants to run it manually as `typeclaw <cmd> --flag=...` from the TUI / shell / `compose`, or another caller needs the same args contract. Write the logic once inside a `surface: 'container'` command's `run`; reuse it from cron by pointing an `exec` job at the same command. "Scheduled work that needs LLM judgement" alone is NOT this case — without an external caller, prefer `kind: 'handler'` and avoid the shell-out overhead.
+2. **The user owns the cadence.** `cron.json` schedules someone else's plugin command at a custom cadence the plugin author didn't anticipate. The user doesn't fork the plugin to change the schedule.
+3. **The scheduled work needs a `surface: 'host'` command.** Host commands run outside the container with no agent runtime, so `ctx.prompt` is unavailable; the shell-out via `typeclaw <host-cmd>` is the only path.
+
+#### The cron-exec → typeclaw shell-out (narrower use case)
+
+For plugin-internal scheduled `exec → LLM` work, `kind: 'handler'` (§5.3) is the best practice — see "Cron usage" above. The pattern below — write a `surface: 'container'` plugin command whose `run` calls `ctx.prompt(...)`, then point a `cron.json` `exec` job at it — is the fallback when **reusability is the actual requirement**: the same logic must also be invocable as a CLI command from TUI / manual shell / `compose`, or the user owns the cadence for a command they didn't write, or the work needs `surface: 'host'` (where `ctx.prompt` doesn't exist).
+
+User-authored `cron.json` itself supports only `prompt` and `exec` — that's by design. `kind: 'handler'` is plugin-only because the handler is a function reference, not JSON-serializable.
+
+```json
+// cron.json
+{
+  "jobs": [
+    {
+      "id": "daily-standup",
+      "schedule": "30 9 * * 1-5",
+      "timezone": "Asia/Seoul",
+      "kind": "exec",
+      "command": ["typeclaw", "standup-now"]
+    }
+  ]
+}
+```
+
+```ts
+// packages/standup-log/index.ts
+export default definePlugin({
+  commands: {
+    'standup-now': {
+      surface: 'container',
+      description: 'Generate today’s standup.',
+      async run(ctx) {
+        await ctx.prompt(
+          `Read sessions/$(date +%F)*.jsonl and append a 3-bullet standup to memory/standups/$(date +%F).md.`,
+        )
+        return 0
+      },
+    },
+  },
+  plugin: async () => ({}),
+})
+```
+
+This `cron.json → typeclaw <cmd>` shape is the right choice in the three narrow cases listed above. For plugin-internal scheduled work where the cadence belongs to the plugin author and nothing outside cron needs to invoke the logic, write a `kind: 'handler'` job (§5.3) instead — same `ctx.prompt` / `ctx.exec` shape, none of the shell-out overhead.
+
+Why a CLI command is worth defining (and exposing via cron `exec`) when one of the three cases applies:
+
+- The command is reusable from the TUI, from `compose` orchestration, or from a manual `typeclaw standup-now` invocation by the user.
+- Args (`--date`, `--dry-run`, etc.) are declared once via `args: z.object({...})` and parsed/validated by the runtime — both at the host CLI and as defense-in-depth in the container.
+- A user who wants a different cadence than the plugin's default can drop a `cron.json` entry pointing at the command without forking the plugin.
+
+If none of those benefits actually apply to your case, the CLI command shape is overhead — write a handler.
+
+For the cron-side decision rules (when to pick `handler` vs `prompt` vs `exec → typeclaw <cmd>`, and how to gate `ctx.prompt` behind a cheap `ctx.exec` probe) read `typeclaw-cron`.
+
+#### `args` — Zod object schema with primitive leaves
+
+```ts
+args: z.object({
+  date: z.string().optional().describe('YYYY-MM-DD; defaults to today'),
+  dryRun: z.boolean().default(false),
+  count: z.number().int().min(1).max(100).default(10),
+})
+```
+
+- The top level **MUST** be `z.object({...})`. Leaves should be primitives (`string`, `number`, `boolean`, `literal`, `enum`) so `--help` can render `--<name>=<type>`.
+- Args are validated locally by the host CLI **before** any WS round-trip, so bad args fail fast with a clean error and exit code 2. The container re-validates as defense-in-depth.
+- `.describe(...)` populates `--help` output. Use it.
+- Omit `args` entirely if the command takes no flags.
+
+#### `permissions: [...]` on the command
+
+```ts
+{
+  surface: 'container',
+  permissions: ['standup-log.write.standup'],
+  async run(ctx, args) {
+    ctx.permissions.assert(ctx.origin, 'standup-log.write.standup')
+    // ...
+  },
+}
+```
+
+Declared permissions are surfaced in `--help` and (for container commands) checked against the caller's origin. Same `<plugin>.<verb>.<noun>` shape as the rest of the permission system; see `typeclaw-permissions`.
+
+#### `isolated: true` (container surface only)
+
+```ts
+{
+  surface: 'container',
+  isolated: true,  // currently degrades to in-process with a warning on stderr
+  async run(ctx, args) { /* ... */ },
+}
+```
+
+Reserved for a future subprocess sandbox. Today the runtime accepts the flag and emits a warning on the per-command stderr (visible to the invoking CLI) but executes in-process anyway. Set it now if you genuinely want the isolation when it lands; otherwise omit.
+
+#### Discovery and naming
+
+- Command names are **global across all plugins**. Two plugins registering `standup-now` is a discovery error — the second one is dropped and logged on `--help`.
+- Command names are NOT auto-prefixed with the plugin name. Pick discriminating names (`standup-now`, not `run`).
+- `typeclaw --help` (in any agent folder) lists every discovered plugin command with description, surface, and which plugin owns it.
+- `typeclaw <name> --help` renders args, surface, plugin name + version. Free.
+
+#### What's NOT supported
+
+- **No host-stage CLI commands that mutate the live container without going through `restart` / `reload`.** A host command can `Bun.spawn('typeclaw', ['reload'])` if it needs to push a config change, but there's no privileged backdoor.
+- **No tool-style `content: ContentPart[]` return.** Commands write to `ctx.stdout` and return an exit code. They are CLI processes, not LLM tool calls.
+- **No streaming token output from `ctx.prompt`** yet — the full LLM response arrives as one stdout burst. Chunked streaming is on the roadmap.
+- **No nested command dispatch.** A command cannot invoke `typeclaw <other-cmd>` and expect to share state; spawn a subprocess or share a subagent instead.
+
 ---
 
 ## 6. PluginContext
@@ -530,9 +768,8 @@ If you find yourself wanting any of these, the design has gone wrong somewhere
 - **Stream subscriptions**. Plugins observe through the typed `hooks` surface; they cannot subscribe to the in-process pub/sub directly.
 - **Server-side TUI push notifications** from plugin code. Tool calls reach the TUI via existing `tool_start`/`tool_end` events.
 - **Dockerfile fragments** contributed by plugins. The Dockerfile is core-managed.
-- **New cron job kinds** beyond `prompt` and `exec`. (Subagent invocation is a `prompt` variant, not a separate kind.)
+- **New cron job kinds for user-authored `cron.json`** beyond `prompt` and `exec`. (Subagent invocation is a `prompt` variant, not a separate kind. Plugin cron jobs additionally support `kind: 'handler'` — see §5.3 — but that's plugin-only because the handler is a TypeScript function reference, not JSON-serializable.)
 - **Reload-registry scopes** for plugin-owned state.
-- **Host-stage CLI commands** registered by plugins. Plugins are container-stage only.
 - **`extendConfig`** for arbitrary top-level fields outside the plugin's own config block.
 - **Per-LLM-call hooks** (`llm.params` / `llm.headers`). Wait until a real plugin needs them.
 
@@ -575,6 +812,10 @@ export default definePlugin({
   configSchema: z.object({
     /* ... */
   }), // optional
+  commands: {
+    /* name: { surface, run, args?, ... } */
+  }, // optional, declared BY-VALUE (not inside factory)
+  permissions: ['my-plugin.write.x'], // optional
   plugin: async (ctx) => ({
     // required
     tools,
@@ -582,7 +823,8 @@ export default definePlugin({
     cronJobs,
     skills,
     skillsDirs,
-    hooks, // all optional
+    hooks,
+    doctorChecks, // all optional
   }),
 })
 ```
@@ -591,4 +833,8 @@ export default definePlugin({
 
 **Plugin name = derived**: scope-stripped, `typeclaw-plugin-` prefix stripped (npm), or basename minus extension (local).
 
+**Command name = global**: NOT prefixed with plugin name. Two plugins registering the same command name is a discovery error (second is dropped, logged on `--help`).
+
+**`exec → LLM` from cron** (best practice): plugin `cronJobs` entry with `kind: 'handler'` — a TypeScript function the cron consumer invokes directly with `ctx.prompt` / `ctx.subagent` / `ctx.exec`. No shell-out, no WS round-trip. Fall back to `surface: 'container'` command + cron `exec` pointing at `["typeclaw", "<cmd>"]` ONLY when the same logic must also be invocable as a reusable CLI command, the user owns the cadence for someone else's command, or the work needs `surface: 'host'`.
+
 **Boundary**: `src/plugin/**` MUST NOT import `@mariozechner/*`.

package/src/skills/typeclaw-tunnels/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: typeclaw-tunnels
+description: Use when the user mentions tunnel, ngrok, webhook URL, cloudflared, expose to internet, show my friend, public URL, GitHub webhook, port forward to public, reverse proxy, trycloudflare, or making a container-local service reachable from the internet. Read it before suggesting tunnel add/remove/status/logs or editing typeclaw.json tunnels[].
+---
+
+# typeclaw-tunnels
+
+TypeClaw tunnels expose a container-private HTTP/TCP service to the public internet. Use them for inbound webhooks (especially GitHub) or short-lived demos where the user wants a public URL for a local port.
+
+## When to suggest `typeclaw tunnel add`
+
+Suggest a tunnel when the user asks for any of these:
+
+- "give GitHub a webhook URL", "make GitHub webhooks work", or similar webhook delivery work.
+- "expose this to the internet", "show my friend", "public URL", or "share this dashboard".
+- "use ngrok" or "cloudflared" for a port running inside the agent container.
+
+Do **not** suggest a tunnel for host-local browsing only. If the user just needs to open a dev server on their own machine, TypeClaw's port-forwarder usually already maps container LISTEN ports to `127.0.0.1:<port>` on the host. Tunnels are for public internet ingress.
+
+## Provider choices
+
+### Cloudflare Quick Tunnel
+
+Choose Cloudflare Quick when the user wants the easiest path:
+
+- No Cloudflare account or signup.
+- No host-side binary install; `cloudflared` runs inside the container.
+- The URL looks like `https://<random>.trycloudflare.com`.
+- The URL rotates on container restart or tunnel restart. That is expected.
+
+For GitHub channel setup, `typeclaw channel add github` can write a channel-owned Cloudflare Quick tunnel named `github-webhook` and set `docker.file.cloudflared: true`. The first `typeclaw start` or `restart` after that rebuilds the image with `cloudflared` installed.
+
+### External URL
+
+Choose External when the user already has their own reverse proxy or tunnel:
+
+- ngrok, a Cloudflare named tunnel managed outside TypeClaw, Caddy on a VPS, Tailscale Funnel, or any HTTPS reverse proxy.
+- The URL is stable because the user owns it.
+- TypeClaw does not spawn a subprocess for this provider; it records the URL and broadcasts it to channel consumers.
+
+Use `provider: "external"` with `externalUrl: "https://..."`. External URLs must be HTTPS.
+
+## Commands
+
+- `typeclaw tunnel add <name>` — add a manual tunnel to `typeclaw.json`.
+- `typeclaw tunnel list` — show all configured tunnels and their current URL/health.
+- `typeclaw tunnel status <name>` — inspect one tunnel in detail.
+- `typeclaw tunnel logs <name>` — print the tunnel's recent log ring.
+- `typeclaw tunnel logs <name> -f` — follow live tunnel logs.
+- `typeclaw tunnel remove <name>` — remove a manual tunnel. Channel-owned tunnels should be removed through the owning channel flow, not by hand.
+
+Tunnel config is **restart-required**. After adding/removing/changing `tunnels[]` or `docker.file.cloudflared`, the user must run `typeclaw restart` from the host stage.
+
+## Reading `tunnel status`
+
+Healthy Cloudflare Quick tunnels should show:
+
+- provider `cloudflare-quick`.
+- a current `https://...trycloudflare.com` URL after cloudflared has emitted one.
+- health like `healthy` or equivalent live/running state.
+- restart count near zero for a stable tunnel.
+
+Unhealthy signs:
+
+- no URL after startup.
+- repeated restarts or increasing restart count.
+- `unhealthy` / `permanently-failed` state.
+- last error mentioning spawn failure, missing binary, or cloudflared exit.
+
+For External tunnels, the URL should be the configured `externalUrl`; there may be no subprocess health to inspect.
+
+## Reading `tunnel logs`
+
+Healthy Cloudflare Quick logs usually include:
+
+- cloudflared startup lines.
+- a line containing the public `https://...trycloudflare.com` URL.
+- no rapid repeated exit/restart sequence.
+
+Unhealthy logs often show:
+
+- `cloudflared` not found or spawn failure.
+- repeated process exits followed by backoff/restart lines.
+- Cloudflare connection errors or network failures.
+- no URL emission before the process exits.
+
+Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to watch URL discovery live.
+
+## Common failure modes
+
+### `cloudflared` is not installed
+
+The Cloudflare Quick provider requires `docker.file.cloudflared: true`. If it is missing, add it to `typeclaw.json` or re-run the GitHub channel setup choosing Cloudflare Quick, then run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+
+### Quick tunnel URL changed
+
+This is normal. Quick Tunnel URLs rotate on restart. GitHub channel-owned tunnels handle this by flowing the resolved URL through the channel manager's `tunnelUrl()` callback and restarting the adapter; do not persist the rotating URL into `typeclaw.json`.
+
+### Repeated restarts
+
+Inspect `typeclaw tunnel status <name>` and `typeclaw tunnel logs <name>`. Look for spawn errors, network restrictions, or cloudflared exiting before URL discovery. The tunnel manager backs off and eventually stops retrying after repeated failures without a URL.
+
+### GitHub webhooks are not delivered
+
+Check in this order:
+
+1. `typeclaw tunnel status github-webhook` has a current URL.
+2. `typeclaw tunnel logs github-webhook` shows a URL and no crash loop.
+3. The GitHub channel config has repos listed under `channels.github.repos`.
+4. The channel adapter was restarted after the URL arrived. Channel-owned tunnel URLs should flow through `tunnelUrl()` into adapter `start()`, not through config mutation.
+5. GitHub repo webhook settings point at the current URL if using External; for Cloudflare Quick, expect TypeClaw to re-register on URL changes.

package/src/test-helpers/wait-for.ts

@@ -0,0 +1,50 @@
+export type WaitForOptions = {
+  timeoutMs?: number
+  intervalMs?: number
+  description?: string
+}
+
+const DEFAULT_TIMEOUT_MS = 1_000
+const DEFAULT_INTERVAL_MS = 1
+
+export async function waitFor<T>(
+  predicate: () => T | Promise<T>,
+  options: WaitForOptions = {},
+): Promise<NonNullable<T>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS
+  const deadline = Date.now() + timeoutMs
+
+  const initial = await predicate()
+  if (initial) return initial as NonNullable<T>
+
+  while (Date.now() < deadline) {
+    await new Promise<void>((resolve) => setTimeout(resolve, intervalMs))
+    const result = await predicate()
+    if (result) return result as NonNullable<T>
+  }
+
+  const label = options.description ?? 'condition'
+  throw new Error(`waitFor: ${label} did not become truthy within ${timeoutMs}ms`)
+}
+
+// Asserts that `predicate` STAYS falsy for the full `durationMs`. Unlike
+// `waitFor`, this MUST pay the full duration — you cannot observe the absence
+// of an event faster than waiting for it. Use sparingly, and keep durations
+// tight.
+export async function expectStable<T>(
+  predicate: () => T | Promise<T>,
+  options: { durationMs: number; intervalMs?: number; description?: string },
+): Promise<void> {
+  const intervalMs = options.intervalMs ?? 5
+  const deadline = Date.now() + options.durationMs
+
+  while (Date.now() < deadline) {
+    const result = await predicate()
+    if (result) {
+      const label = options.description ?? 'condition'
+      throw new Error(`expectStable: ${label} became truthy before ${options.durationMs}ms elapsed`)
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, intervalMs))
+  }
+}

package/src/tui/index.ts

@@ -9,6 +9,8 @@ export type TerminalFactory = () => Terminal
 
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 30_000
 
+export type VersionMismatch = { expected: string; actual: string }
+
 export type TuiOptions = {
   url: string
   initialPrompt?: string
@@ -16,6 +18,13 @@ export type TuiOptions = {
   createTerminal?: TerminalFactory
   handshakeTimeoutMs?: number
   exit?: (code: number) => void
+  // Locally-known typeclaw version the host CLI is running. When provided
+  // and the connected frame's serverVersion is defined and differs,
+  // onVersionMismatch is invoked AND a yellow warning line is rendered
+  // into the TUI history. The container-side local TUI omits this so no
+  // mismatch check fires when client and server are guaranteed in lockstep.
+  expectedVersion?: string
+  onVersionMismatch?: (info: VersionMismatch) => void
 }
 
 export function createTui({
@@ -25,6 +34,8 @@ export function createTui({
   createTerminal = () => new ProcessTerminal(),
   handshakeTimeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS,
   exit = process.exit.bind(process),
+  expectedVersion,
+  onVersionMismatch,
 }: TuiOptions) {
   async function run(): Promise<void> {
     const terminal = createTerminal()
@@ -44,7 +55,7 @@ export function createTui({
       throw err
     })
 
-    const sessionId = await waitForConnected(client, displayUrl, handshakeTimeoutMs).catch((err) => {
+    const handshake = await waitForConnected(client, displayUrl, handshakeTimeoutMs).catch((err) => {
       status.setText(colors.red(`connection error: ${err instanceof Error ? err.message : String(err)}`))
       tui.requestRender()
       client.close()
@@ -52,6 +63,7 @@ export function createTui({
       exit(1)
       throw err
     })
+    const { sessionId, serverVersion } = handshake
     status.setText(colors.dim(`session: ${sessionId}`))
     tui.requestRender()
 
@@ -217,6 +229,14 @@ export function createTui({
     tui.setFocus(editor)
     tui.requestRender()
 
+    if (expectedVersion !== undefined && serverVersion !== undefined && serverVersion !== expectedVersion) {
+      const mismatch: VersionMismatch = { expected: expectedVersion, actual: serverVersion }
+      const warning = formatVersionMismatchWarning(mismatch)
+      appendHistory(new Text(colors.yellow(warning), 0, 0))
+      tui.requestRender()
+      onVersionMismatch?.(mismatch)
+    }
+
     if (initialPrompt) {
       await send(initialPrompt)
     }
@@ -238,8 +258,12 @@ function redactUrl(url: string): string {
   }
 }
 
-async function waitForConnected(client: Client, url: string, timeoutMs: number): Promise<string> {
-  return await new Promise<string>((resolve, reject) => {
+async function waitForConnected(
+  client: Client,
+  url: string,
+  timeoutMs: number,
+): Promise<{ sessionId: string; serverVersion?: string }> {
+  return await new Promise<{ sessionId: string; serverVersion?: string }>((resolve, reject) => {
     const timer = setTimeout(() => {
       cleanup()
       reject(new Error(`timed out waiting for connected message from ${url} after ${timeoutMs}ms`))
@@ -253,7 +277,10 @@ async function waitForConnected(client: Client, url: string, timeoutMs: number):
       client.onMessage((msg) => {
         if (msg.type === 'connected') {
           cleanup()
-          resolve(msg.sessionId)
+          resolve({
+            sessionId: msg.sessionId,
+            ...(msg.serverVersion !== undefined ? { serverVersion: msg.serverVersion } : {}),
+          })
         }
         if (msg.type === 'error') {
           cleanup()
@@ -275,3 +302,7 @@ async function waitForConnected(client: Client, url: string, timeoutMs: number):
     )
   })
 }
+
+export function formatVersionMismatchWarning({ expected, actual }: VersionMismatch): string {
+  return `WARN: host CLI is v${expected}, agent container is v${actual}. Some commands may hang or fail. Try \`typeclaw restart --build\`.`
+}

package/src/tunnels/__fixtures__/cloudflared-quick-stderr.txt

@@ -0,0 +1,11 @@
+# Fixture source: cloudflare/cloudflared cmd/cloudflared/tunnel/quick_tunnel.go
+# RunQuickTunnel logs the disclaimer, "Requesting new quick Tunnel on trycloudflare.com...",
+# then AsciiBox(...) lines containing the resolved https://<subdomain>.trycloudflare.com URL.
+# Reference fetched from:
+# https://raw.githubusercontent.com/cloudflare/cloudflared/master/cmd/cloudflared/tunnel/quick_tunnel.go
+2026-01-01T00:00:00Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to experiment and try it out. However, be aware that these account-less Tunnels have no uptime guarantee, are subject to the Cloudflare Online Services Terms of Use (https://www.cloudflare.com/website-terms/), and Cloudflare reserves the right to investigate your use of Tunnels for violations of such terms. If you intend to use Tunnels in production you should use a pre-created named tunnel by following: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
+2026-01-01T00:00:00Z INF Requesting new quick Tunnel on trycloudflare.com...
+2026-01-01T00:00:00Z INF +--------------------------------------------------------------------------------------------------+
+2026-01-01T00:00:00Z INF |  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):  |
+2026-01-01T00:00:00Z INF |  https://wave-one-fixture.trycloudflare.com                                                   |
+2026-01-01T00:00:00Z INF +--------------------------------------------------------------------------------------------------+

package/src/tunnels/events.ts

@@ -0,0 +1,14 @@
+import type { TunnelUrlChangedPayload } from './types'
+
+export function isTunnelUrlChangedPayload(value: unknown): value is TunnelUrlChangedPayload {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  if (v.kind !== 'tunnel-url-changed') return false
+  if (typeof v.tunnelName !== 'string') return false
+  if (typeof v.url !== 'string') return false
+  if (typeof v.rotatedAt !== 'string') return false
+  if (v.for === null || typeof v.for !== 'object') return false
+  const forKind = (v.for as Record<string, unknown>).kind
+  if (forKind !== 'channel' && forKind !== 'manual') return false
+  return true
+}

package/src/tunnels/index.ts

@@ -0,0 +1,12 @@
+export { createTunnelManager, type TunnelManager, type TunnelManagerOptions, type TunnelManagerLogger } from './manager'
+export { createCloudflareQuickProvider, type CloudflareQuickProviderOptions } from './providers/cloudflare-quick'
+export {
+  type TunnelConfig,
+  type TunnelFor,
+  type TunnelProvider,
+  type TunnelProviderHandle,
+  type TunnelState,
+  type TunnelStatus,
+  type TunnelUrlChangedPayload,
+} from './types'
+export { isTunnelUrlChangedPayload } from './events'