typeclaw 0.3.1 → 0.4.0

package/src/server/index.ts

@@ -10,14 +10,28 @@ import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
 import { detectProviderError } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { ChannelRouter } from '@/channels/router'
+import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
 import type { HookBus } from '@/plugin'
 import type { BrokerWsData, ContainerBroker } from '@/portbroker'
 import type { ReloadAllResult, ReloadRegistry } from '@/reload'
 import type { ClaimController, ClaimResultEvent } from '@/role-claim'
 import type { PluginRuntime, PluginRuntimeState } from '@/run/plugin-runtime'
+import type { CommandOutbound, CommandRunner } from '@/server/command-runner'
 import type { SessionFactory } from '@/sessions'
-import type { ClientMessage, PromptDelivery, QueueStateItem, ReloadResultPayload, ServerMessage } from '@/shared'
+import type {
+  ClientMessage,
+  CronListEntryPayload,
+  CronListSourcePayload,
+  PromptDelivery,
+  QueueStateItem,
+  ReloadResultPayload,
+  ServerMessage,
+  TunnelLogsClientMessage,
+  TunnelLogsServerMessage,
+  TunnelSnapshot,
+} from '@/shared'
 import type { Stream, StreamMessage, StreamMessageId, Unsubscribe } from '@/stream'
+import type { TunnelManager } from '@/tunnels'
 
 export type ReloadAllFn = () => Promise<ReloadAllResult>
 export type CreateSessionFn = (options?: CreateSessionOptions) => Promise<AgentSession | CreateSessionResult>
@@ -46,6 +60,7 @@ export type ServerOptions = {
   // sessions. Omit to keep TUI-only behavior (used by tests + non-container
   // dev runs).
   containerBroker?: ContainerBroker
+  tunnelManager?: TunnelManager
   // Optional logger for server-side events. Defaults to `consoleLogger`
   // which writes to stdout/stderr so `typeclaw logs` surfaces every event.
   // Tests inject a fake logger to assert on captured output.
@@ -56,6 +71,14 @@ export type ServerOptions = {
   // `claim_started` / `claim_completed` / `claim_error` back over the
   // same connection. Omitted in tests that don't exercise the flow.
   claimController?: ClaimController
+  // Optional command runner factory. The server invokes this once at start
+  // with an `outbound` callback wired to send `command_stdout` / `command_stderr`
+  // / `command_exit` / `command_error` frames back to the originating WS for
+  // a given callId. The server owns the callId→ws map; the runner is
+  // transport-agnostic. Omitted in tests that don't exercise plugin commands;
+  // without it the four `exec_command`-family messages are answered with
+  // `command_error` so the host CLI sees a clean failure.
+  commandRunnerFactory?: (outbound: CommandOutbound) => CommandRunner
 }
 
 const consoleLogger: ServerLogger = {
@@ -67,8 +90,17 @@ const consoleLogger: ServerLogger = {
 export type Server = ReturnType<typeof createServer>
 
 type TuiWsData = { kind: 'tui'; sessionId: string }
-type WsData = TuiWsData | BrokerWsData
+// Command-class connections skip TUI session bootstrap. Used by the host
+// CLI's container-command-client. Authenticated with the same TUI token
+// because both surfaces are owner-equivalent (a process that holds the
+// TUI token can already do anything the TUI can).
+type CommandWsData = { kind: 'command' }
+type TunnelLogsWsData = { kind: 'tunnel-logs'; unsubscribe: Unsubscribe | null }
+type WsData = TuiWsData | CommandWsData | TunnelLogsWsData | BrokerWsData
 type Ws = ServerWebSocket<TuiWsData>
+type CommandWs = ServerWebSocket<CommandWsData>
+type TunnelLogsWs = ServerWebSocket<TunnelLogsWsData>
+type AnyOwnerWs = Ws | CommandWs
 
 type QueuedPrompt = {
   streamMessageId: StreamMessageId
@@ -95,8 +127,35 @@ type SessionState = {
   dispose: () => Promise<void>
 }
 
-function send(ws: Ws, msg: ServerMessage) {
-  ws.send(JSON.stringify(msg))
+// Swallows the Bun-thrown error when a command's async cleanup emits a
+// final frame after its ws has begun closing. Returns false on failure so
+// callers can debounce subsequent sends for the same callId.
+export function safeWsSend(ws: { send: (data: string) => void }, msg: ServerMessage): boolean {
+  try {
+    ws.send(JSON.stringify(msg))
+    return true
+  } catch {
+    return false
+  }
+}
+
+function send(ws: Ws, msg: ServerMessage): boolean {
+  return safeWsSend(ws, msg)
+}
+
+function sendTunnelLog(ws: TunnelLogsWs, msg: TunnelLogsServerMessage): boolean {
+  try {
+    ws.send(JSON.stringify(msg))
+    return true
+  } catch {
+    return false
+  }
+}
+
+function encodeBase64(bytes: Uint8Array): string {
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i] ?? 0)
+  return btoa(s)
 }
 
 export function createServer({
@@ -113,10 +172,107 @@ export function createServer({
   runtimeVersion,
   tuiToken,
   containerBroker,
+  tunnelManager,
   logger = consoleLogger,
   claimController,
+  commandRunnerFactory,
 }: ServerOptions) {
   const sessionStates = new WeakMap<Ws, SessionState>()
+  const callIdToWs = new Map<string, AnyOwnerWs>()
+  const commandRunner: CommandRunner | undefined = commandRunnerFactory
+    ? commandRunnerFactory({
+        stdout(callId, chunk) {
+          const ws = callIdToWs.get(callId)
+          if (ws) safeWsSend(ws, { type: 'command_stdout', callId, chunk: encodeBase64(chunk) })
+        },
+        stderr(callId, chunk) {
+          const ws = callIdToWs.get(callId)
+          if (ws) safeWsSend(ws, { type: 'command_stderr', callId, chunk: encodeBase64(chunk) })
+        },
+        exit(callId, code) {
+          const ws = callIdToWs.get(callId)
+          callIdToWs.delete(callId)
+          if (ws) safeWsSend(ws, { type: 'command_exit', callId, code })
+        },
+        error(callId, message) {
+          const ws = callIdToWs.get(callId)
+          if (ws) safeWsSend(ws, { type: 'command_error', callId, message })
+        },
+      })
+    : undefined
+
+  // Shared command-frame dispatcher: both TUI-class and command-class
+  // connections route through here. Non-command ClientMessage types are
+  // silently dropped so command-class connections (which only ever speak
+  // exec_command/command_stdin/command_stdin_end/command_abort) can reuse
+  // the same handler as the TUI without spreading switch logic.
+  function handleCommandFrame(ws: AnyOwnerWs, msg: ClientMessage): void {
+    if (msg.type === 'exec_command') {
+      if (!commandRunner) {
+        safeWsSend(ws, {
+          type: 'command_error',
+          callId: msg.callId,
+          message: 'plugin commands are not enabled on this agent',
+        })
+        safeWsSend(ws, { type: 'command_exit', callId: msg.callId, code: 1 })
+        return
+      }
+      // Guard at the WS layer BEFORE registering the callId→ws mapping:
+      // if another connection (or this one) is already running a command
+      // with this callId, refuse the replay. Without this check, a stale
+      // or malicious client could overwrite the mapping and steal the
+      // original command's output frames.
+      if (callIdToWs.has(msg.callId)) {
+        safeWsSend(ws, {
+          type: 'command_error',
+          callId: msg.callId,
+          message: `callId "${msg.callId}" is already in flight`,
+        })
+        safeWsSend(ws, { type: 'command_exit', callId: msg.callId, code: 1 })
+        return
+      }
+      // Parse the optional parent-origin JSON: invalid JSON falls back to
+      // the synthetic owner origin rather than rejecting the command, so a
+      // malformed env var on the caller's side doesn't break the whole
+      // dispatch. The runner uses the parsed value as spawnedByOrigin
+      // verbatim — the trust boundary is the WS auth token, not JSON shape.
+      let parentOrigin: SessionOrigin | undefined
+      if (msg.parentOriginJson !== undefined) {
+        try {
+          parentOrigin = JSON.parse(msg.parentOriginJson) as SessionOrigin
+        } catch {
+          parentOrigin = undefined
+        }
+      }
+      callIdToWs.set(msg.callId, ws)
+      commandRunner.start(
+        {
+          callId: msg.callId,
+          name: msg.name,
+          args: msg.args,
+          ...(msg.isolated !== undefined ? { isolated: msg.isolated } : {}),
+          ...(parentOrigin !== undefined ? { parentOrigin } : {}),
+        },
+        ws,
+      )
+      return
+    }
+    if (msg.type === 'command_stdin') {
+      if (!commandRunner) return
+      commandRunner.feedStdin(msg.callId, msg.chunk)
+      return
+    }
+    if (msg.type === 'command_stdin_end') {
+      if (!commandRunner) return
+      commandRunner.endStdin(msg.callId)
+      return
+    }
+    if (msg.type === 'command_abort') {
+      if (!commandRunner) return
+      commandRunner.abort(msg.callId, msg.reason)
+      return
+    }
+  }
 
   function start(): BunServer<WsData> {
     const bunServer = Bun.serve<WsData>({
@@ -129,6 +285,30 @@ export function createServer({
           if (server.upgrade(req, { data })) return
           return new Response('upgrade failed', { status: 400 })
         }
+        if (url.pathname === '/tunnel-logs') {
+          if (isWebSocketUpgrade(req) && tuiToken !== undefined && url.searchParams.get('token') !== tuiToken) {
+            return new Response('unauthorized', { status: 401 })
+          }
+          const data: TunnelLogsWsData = { kind: 'tunnel-logs', unsubscribe: null }
+          if (server.upgrade(req, { data })) return
+          return new Response('upgrade failed', { status: 400 })
+        }
+        // `/commands` is the dedicated host-CLI proxy path. It skips TUI
+        // session creation (which costs an AgentSession spawn per command
+        // invocation) but uses the same tuiToken because both surfaces
+        // are owner-equivalent.
+        // `/commands` is the dedicated host-CLI proxy path. It skips TUI
+        // session creation (which costs an AgentSession spawn per command
+        // invocation) but uses the same tuiToken because both surfaces
+        // are owner-equivalent.
+        if (url.pathname === '/commands') {
+          if (isWebSocketUpgrade(req) && tuiToken !== undefined && url.searchParams.get('token') !== tuiToken) {
+            return new Response('unauthorized', { status: 401 })
+          }
+          const data: CommandWsData = { kind: 'command' }
+          if (server.upgrade(req, { data })) return
+          return new Response('upgrade failed', { status: 400 })
+        }
         if (isWebSocketUpgrade(req) && tuiToken !== undefined && url.searchParams.get('token') !== tuiToken) {
           return new Response('unauthorized', { status: 401 })
         }
@@ -143,6 +323,15 @@ export function createServer({
             containerBroker?.open(rawWs as ServerWebSocket<BrokerWsData>)
             return
           }
+          if (rawWs.data.kind === 'command') {
+            // Command-class connections are pure transport for plugin-command
+            // dispatch. No AgentSession is created, no plugin lifecycle hooks
+            // fire, no `connected` frame is sent. The host CLI proxy sends
+            // exec_command immediately on open and tears the socket down
+            // when command_exit arrives.
+            return
+          }
+          if (rawWs.data.kind === 'tunnel-logs') return
           const ws = rawWs as Ws
           try {
             const sessionManager = sessionFactory?.createPersisted()
@@ -213,7 +402,11 @@ export function createServer({
               })
             }
 
-            send(ws, { type: 'connected', sessionId: sessionFileId })
+            send(ws, {
+              type: 'connected',
+              sessionId: sessionFileId,
+              ...(runtimeVersion !== undefined ? { serverVersion: runtimeVersion } : {}),
+            })
             console.log(`session ${sessionFileId}: open`)
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
@@ -227,6 +420,22 @@ export function createServer({
             await containerBroker?.message(rawWs as ServerWebSocket<BrokerWsData>, raw as string | Buffer)
             return
           }
+          // Command-class connections accept ONLY the four exec_command-
+          // family frames. Anything else (prompt, reload, claim_*, etc.) is
+          // silently dropped because there's no AgentSession or claim
+          // controller attached to this kind of connection. Routing through
+          // safeWsSend + the callIdToWs map keeps the outbound path
+          // transport-agnostic.
+          if (rawWs.data.kind === 'command') {
+            const cws = rawWs as CommandWs
+            const msg = JSON.parse(String(raw)) as ClientMessage
+            handleCommandFrame(cws, msg)
+            return
+          }
+          if (rawWs.data.kind === 'tunnel-logs') {
+            handleTunnelLogsMessage(rawWs as TunnelLogsWs, raw, tunnelManager)
+            return
+          }
           const ws = rawWs as Ws
           const msg = JSON.parse(String(raw)) as ClientMessage
           const state = sessionStates.get(ws)
@@ -313,6 +522,21 @@ export function createServer({
             return
           }
 
+          if (msg.type === 'cron_list') {
+            await handleCronList(ws, msg.requestId, pluginRuntime, agentDir)
+            return
+          }
+
+          if (msg.type === 'tunnel_list_request') {
+            handleTunnelList(ws, msg.requestId, tunnelManager)
+            return
+          }
+
+          if (msg.type === 'tunnel_status_request') {
+            handleTunnelStatus(ws, msg.requestId, msg.name, tunnelManager)
+            return
+          }
+
           if (msg.type === 'abort') {
             if (!state) return
             await state.session.abort()
@@ -370,12 +594,31 @@ export function createServer({
             }
             return
           }
+
+          handleCommandFrame(ws, msg)
         },
         async close(rawWs) {
           if (rawWs.data.kind === 'portbroker') {
             containerBroker?.close(rawWs as ServerWebSocket<BrokerWsData>)
             return
           }
+          if (rawWs.data.kind === 'command') {
+            // Command-class connections have no AgentSession, no claim
+            // state, and no broadcast subscriptions to tear down. Just
+            // abort in-flight commands tied to this ws and purge the
+            // callId→ws mapping so late frames don't try to route here.
+            const cws = rawWs as CommandWs
+            commandRunner?.abortForOwner(cws)
+            for (const [callId, owner] of callIdToWs) {
+              if (owner === cws) callIdToWs.delete(callId)
+            }
+            return
+          }
+          if (rawWs.data.kind === 'tunnel-logs') {
+            rawWs.data.unsubscribe?.()
+            rawWs.data.unsubscribe = null
+            return
+          }
           const ws = rawWs as Ws
           const state = sessionStates.get(ws)
           state?.unsubBroadcast?.()
@@ -384,6 +627,10 @@ export function createServer({
           if (state?.activeClaimCode !== null && state?.activeClaimCode !== undefined && claimController) {
             claimController.cancelClaim(state.activeClaimCode)
           }
+          commandRunner?.abortForOwner(ws)
+          for (const [callId, owner] of callIdToWs) {
+            if (owner === ws) callIdToWs.delete(callId)
+          }
           try {
             if (state && state.runtimeSnapshot !== null) {
               await state.runtimeSnapshot.hooks.runSessionEnd({ sessionId: state.sessionFileId, origin: state.origin })
@@ -616,6 +863,142 @@ async function handleDoctorFix(
   send(ws, { type: 'doctor_fix_result', requestId, result })
 }
 
+async function handleCronList(
+  ws: Ws,
+  requestId: string,
+  pluginRuntime: PluginRuntime | undefined,
+  agentDir: string | undefined,
+): Promise<void> {
+  if (agentDir === undefined) {
+    send(ws, { type: 'cron_list_result', requestId, result: { ok: false, reason: 'agentDir not configured' } })
+    return
+  }
+  try {
+    // Snapshot the runtime once so subagent validation and the plugin
+    // cron-job list see the same generation, the way TUI sessions do.
+    // Without one snapshot, a reload landing mid-request can show user
+    // jobs validated against an old subagent registry alongside plugin
+    // jobs from a newer registry.
+    const snapshot = pluginRuntime?.get()
+    const loadResult = await loadCron(agentDir, {
+      // Read-only path: do not rewrite cron.json or commit the
+      // migration just because the user (or the agent) asked to see
+      // the schedule. Boot/reload still own the persistent migration.
+      persistMigrations: false,
+      ...(snapshot !== undefined ? { subagents: snapshot.subagents } : {}),
+    })
+    if (!loadResult.ok) {
+      send(ws, { type: 'cron_list_result', requestId, result: { ok: false, reason: loadResult.reason } })
+      return
+    }
+    const userJobs = loadResult.file?.jobs ?? []
+    const pluginJobs = snapshot?.registry.cronJobs ?? []
+    const nowMs = Date.now()
+    const entries = aggregateCronList({ userJobs, pluginJobs, now: nowMs })
+    send(ws, {
+      type: 'cron_list_result',
+      requestId,
+      result: { ok: true, jobs: entries.map(toPayload), nowMs },
+    })
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    send(ws, { type: 'cron_list_result', requestId, result: { ok: false, reason } })
+  }
+}
+
+function handleTunnelList(ws: Ws, requestId: string, tunnelManager: TunnelManager | undefined): void {
+  if (tunnelManager === undefined) {
+    send(ws, { type: 'tunnel_list_response', requestId, ok: false, error: 'tunnel manager not configured' })
+    return
+  }
+  send(ws, { type: 'tunnel_list_response', requestId, ok: true, tunnels: toTunnelSnapshots(tunnelManager.snapshot()) })
+}
+
+function handleTunnelStatus(ws: Ws, requestId: string, name: string, tunnelManager: TunnelManager | undefined): void {
+  if (tunnelManager === undefined) {
+    send(ws, { type: 'tunnel_status_response', requestId, ok: false, error: 'tunnel manager not configured' })
+    return
+  }
+  const tunnel = toTunnelSnapshots(tunnelManager.snapshot()).find((entry) => entry.name === name)
+  if (tunnel === undefined) {
+    send(ws, { type: 'tunnel_status_response', requestId, ok: false, error: `unknown tunnel: ${name}` })
+    return
+  }
+  send(ws, { type: 'tunnel_status_response', requestId, ok: true, tunnel })
+}
+
+function handleTunnelLogsMessage(
+  ws: TunnelLogsWs,
+  raw: string | Buffer,
+  tunnelManager: TunnelManager | undefined,
+): void {
+  let msg: TunnelLogsClientMessage
+  try {
+    msg = JSON.parse(String(raw)) as TunnelLogsClientMessage
+  } catch {
+    sendTunnelLog(ws, { type: 'error', message: 'invalid JSON' })
+    sendTunnelLog(ws, { type: 'end' })
+    ws.close()
+    return
+  }
+  if (msg.type !== 'subscribe' || typeof msg.name !== 'string' || typeof msg.follow !== 'boolean') {
+    sendTunnelLog(ws, { type: 'error', message: 'invalid tunnel log subscription' })
+    sendTunnelLog(ws, { type: 'end' })
+    ws.close()
+    return
+  }
+  if (tunnelManager === undefined || !tunnelManager.snapshot().some((entry) => entry.name === msg.name)) {
+    sendTunnelLog(ws, { type: 'error', message: `unknown tunnel: ${msg.name}` })
+    sendTunnelLog(ws, { type: 'end' })
+    ws.close()
+    return
+  }
+
+  sendTunnelLog(ws, { type: 'snapshot', lines: tunnelManager.tail(msg.name) })
+  if (!msg.follow) {
+    sendTunnelLog(ws, { type: 'end' })
+    ws.close()
+    return
+  }
+  ws.data.unsubscribe?.()
+  ws.data.unsubscribe = tunnelManager.subscribeToLogs(msg.name, (line) => {
+    sendTunnelLog(ws, { type: 'line', line })
+  })
+}
+
+function toTunnelSnapshots(states: ReturnType<TunnelManager['snapshot']>): TunnelSnapshot[] {
+  return states.map((state) => ({
+    name: state.name,
+    provider: state.provider,
+    for: state.for,
+    url: state.url,
+    status: state.status,
+    lastUrlAt: state.lastUrlAt,
+    detail: state.detail,
+  }))
+}
+
+function toPayload(entry: CronListEntry): CronListEntryPayload {
+  const source: CronListSourcePayload =
+    entry.source.kind === 'plugin'
+      ? { kind: 'plugin', pluginName: entry.source.pluginName, localId: entry.source.localId }
+      : { kind: 'user' }
+  return {
+    id: entry.id,
+    source,
+    kind: entry.kind,
+    schedule: entry.schedule,
+    enabled: entry.enabled,
+    nextFireMs: entry.nextFireMs,
+    ...(entry.timezone !== undefined ? { timezone: entry.timezone } : {}),
+    ...(entry.scheduledByRole !== undefined ? { scheduledByRole: entry.scheduledByRole } : {}),
+    ...(entry.scheduleError !== undefined ? { scheduleError: entry.scheduleError } : {}),
+    ...(entry.prompt !== undefined ? { prompt: entry.prompt } : {}),
+    ...(entry.subagent !== undefined ? { subagent: entry.subagent } : {}),
+    ...(entry.command !== undefined ? { command: entry.command } : {}),
+  }
+}
+
 async function handleReload(
   ws: Ws,
   reloadAll: ReloadAllFn | undefined,

package/src/shared/index.ts

@@ -4,6 +4,10 @@ export {
   type ClaimRoleChoice,
   type ClaimStartedPayload,
   type ClientMessage,
+  type CronListEntryPayload,
+  type CronListRequestId,
+  type CronListResultPayload,
+  type CronListSourcePayload,
   type DoctorCheckPayload,
   type DoctorFixPayload,
   type DoctorRequestId,
@@ -11,6 +15,10 @@ export {
   type QueueStateItem,
   type ReloadResultPayload,
   type ServerMessage,
+  type TunnelLogsClientMessage,
+  type TunnelLogsServerMessage,
+  type TunnelRequestId,
+  type TunnelSnapshot,
 } from './protocol'
 
 export { formatLocalDate, formatLocalDateTime } from './local-time'

package/src/shared/protocol.ts

@@ -24,6 +24,26 @@ export type DoctorFixPayload =
 
 export type ClaimRoleChoice = 'owner' | 'member' | 'trusted' | (string & {})
 
+export type TunnelRequestId = string
+
+export type TunnelSnapshot = {
+  name: string
+  provider: 'external' | 'cloudflare-quick'
+  for: { kind: 'channel'; name: string } | { kind: 'manual' }
+  url: string | null
+  status: 'stopped' | 'starting' | 'healthy' | 'unhealthy' | 'permanently-failed'
+  lastUrlAt: number | null
+  detail: string
+}
+
+export type TunnelLogsClientMessage = { type: 'subscribe'; name: string; follow: boolean }
+
+export type TunnelLogsServerMessage =
+  | { type: 'snapshot'; lines: string[] }
+  | { type: 'line'; line: string }
+  | { type: 'error'; message: string }
+  | { type: 'end' }
+
 export type ClientMessage =
   | { type: 'prompt'; text: string; delivery?: PromptDelivery }
   | { type: 'reload'; scope?: string }
@@ -31,8 +51,50 @@ export type ClientMessage =
   | { type: 'queue_cancel'; messageId: string }
   | { type: 'doctor'; requestId: DoctorRequestId }
   | { type: 'doctor_fix'; requestId: DoctorRequestId; checkId: string }
+  | { type: 'cron_list'; requestId: CronListRequestId }
+  | { type: 'tunnel_list_request'; requestId: TunnelRequestId }
+  | { type: 'tunnel_status_request'; requestId: TunnelRequestId; name: string }
   | { type: 'claim_start'; code: string; role: ClaimRoleChoice; channel?: string; ttlMs: number }
   | { type: 'claim_cancel' }
+  | {
+      type: 'exec_command'
+      callId: string
+      name: string
+      args: unknown
+      isolated?: boolean
+      // Parent origin to stamp as spawnedByOrigin on the command's session.
+      // When unset, the runner stamps a synthetic TUI origin (host CLI
+      // operator). When set, the runner trusts the JSON verbatim as a
+      // SessionOrigin (e.g. cron-shaped, carrying scheduledByRole).
+      // Permission resolution chases through to the parent origin's role.
+      parentOriginJson?: string
+    }
+  | { type: 'command_stdin'; callId: string; chunk: string }
+  | { type: 'command_stdin_end'; callId: string }
+  | { type: 'command_abort'; callId: string; reason: string }
+
+export type CronListRequestId = string
+
+export type CronListSourcePayload = { kind: 'user' } | { kind: 'plugin'; pluginName: string; localId: string }
+
+export type CronListEntryPayload = {
+  id: string
+  source: CronListSourcePayload
+  kind: 'prompt' | 'exec' | 'handler'
+  schedule: string
+  timezone?: string
+  enabled: boolean
+  scheduledByRole?: string
+  nextFireMs: number | null
+  scheduleError?: string
+  prompt?: string
+  subagent?: string
+  command?: readonly string[]
+}
+
+export type CronListResultPayload =
+  | { ok: true; jobs: CronListEntryPayload[]; nowMs: number }
+  | { ok: false; reason: string }
 
 export type QueueStateItem = { id: string; text: string; ts: number }
 
@@ -57,7 +119,11 @@ export type ClaimErrorPayload = {
 }
 
 export type ServerMessage =
-  | { type: 'connected'; sessionId: string }
+  // serverVersion is optional so an old CLI talking to a new server still
+  // parses cleanly. The server impl always emits it; consumers that care
+  // about host/agent skew (the TUI command in particular) read it to warn
+  // the user when their CLI is on a different version than the container.
+  | { type: 'connected'; sessionId: string; serverVersion?: string }
   | { type: 'text_delta'; delta: string }
   | { type: 'tool_start'; toolCallId: string; name: string; args: unknown }
   | { type: 'tool_end'; toolCallId: string; name: string; error: boolean; result: unknown; durationMs: number }
@@ -69,6 +135,19 @@ export type ServerMessage =
   | { type: 'prompt_started'; messageId: string; text: string }
   | { type: 'doctor_result'; requestId: DoctorRequestId; checks: DoctorCheckPayload[] }
   | { type: 'doctor_fix_result'; requestId: DoctorRequestId; result: DoctorFixPayload }
+  | { type: 'cron_list_result'; requestId: CronListRequestId; result: CronListResultPayload }
+  | ({ type: 'tunnel_list_response'; requestId: TunnelRequestId } & (
+      | { ok: true; tunnels: TunnelSnapshot[] }
+      | { ok: false; error: string }
+    ))
+  | ({ type: 'tunnel_status_response'; requestId: TunnelRequestId } & (
+      | { ok: true; tunnel: TunnelSnapshot }
+      | { ok: false; error: string }
+    ))
   | { type: 'claim_started'; payload: ClaimStartedPayload }
   | { type: 'claim_completed'; payload: ClaimCompletedPayload }
   | { type: 'claim_error'; payload: ClaimErrorPayload }
+  | { type: 'command_stdout'; callId: string; chunk: string }
+  | { type: 'command_stderr'; callId: string; chunk: string }
+  | { type: 'command_exit'; callId: string; code: number }
+  | { type: 'command_error'; callId: string; message: string }

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: typeclaw-channel-github
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
+---
+
+GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
+
+- Do not send attachments on GitHub chats; the adapter rejects them.
+- There is no typing indicator.
+- For PR review threads, keep `thread` set to reply in-place. Omit `thread` for a top-level PR/issue comment.
+
+## Opening new issues and PRs
+
+The `gh` CLI is pre-authenticated via `GH_TOKEN` (injected by the adapter at startup). Use it to open new issues or PRs:
+
+```sh
+# Open a new issue
+gh issue create --repo owner/repo --title "Bug: ..." --body "..."
+
+# Open a new PR
+gh pr create --repo owner/repo --title "Fix: ..." --head my-branch --base main --body "..."
+```
+
+For App auth, `GH_TOKEN` is an installation access token that refreshes automatically — it stays current as long as the adapter is running.