typeclaw 0.3.1 → 0.5.0

package/src/cli/container-command-client.ts

@@ -0,0 +1,244 @@
+import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
+import type { ClientMessage, ServerMessage } from '@/shared'
+
+export type ContainerCommandResult = { ok: true; exitCode: number } | { ok: false; exitCode: number; message: string }
+
+export type ContainerProxyOptions = {
+  agentDir: string
+  commandName: string
+  args: unknown
+  isolated?: boolean
+  stdin?: ReadableStream<Uint8Array>
+  stdout?: WritableStream<Uint8Array>
+  stderr?: WritableStream<Uint8Array>
+  abortSignal?: AbortSignal
+  // Explicit parent-origin override. When unset the proxy reads
+  // process.env.TYPECLAW_PARENT_ORIGIN_JSON. Tests pass this directly to
+  // avoid mutating process.env.
+  parentOriginJson?: string
+  // Override hooks for tests. When unset, the live host port + token resolvers
+  // are used. The websocketFactory is also pluggable so tests can drive a
+  // fake server without binding to a real port.
+  resolveUrl?: (opts: { agentDir: string }) => Promise<{ url: string } | { error: string }>
+  websocketFactory?: (url: string) => WebSocketLike
+}
+
+export type WebSocketLike = {
+  send: (data: string) => void
+  close: () => void
+  addEventListener: (
+    event: 'open' | 'message' | 'close' | 'error',
+    listener: (event: { data?: unknown; code?: number; reason?: string }) => void,
+  ) => void
+}
+
+export async function proxyContainerCommand(opts: ContainerProxyOptions): Promise<ContainerCommandResult> {
+  const urlResolution =
+    opts.resolveUrl !== undefined
+      ? await opts.resolveUrl({ agentDir: opts.agentDir })
+      : await resolveUrlFromDocker(opts.agentDir)
+  if ('error' in urlResolution) {
+    return { ok: false, exitCode: 2, message: urlResolution.error }
+  }
+
+  const callId = crypto.randomUUID()
+  const ws =
+    opts.websocketFactory !== undefined
+      ? opts.websocketFactory(urlResolution.url)
+      : (new WebSocket(urlResolution.url) as unknown as WebSocketLike)
+
+  let opened = false
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      try {
+        ws.close()
+      } catch {
+        // Ignore close failures during connect timeout — the original error is
+        // already propagating through reject().
+      }
+      reject(new Error('timed out connecting to agent container WebSocket'))
+    }, 5_000)
+    ws.addEventListener('open', () => {
+      clearTimeout(timer)
+      opened = true
+      resolve()
+    })
+    ws.addEventListener('error', (event) => {
+      clearTimeout(timer)
+      reject(new Error(String((event as { message?: string }).message ?? 'websocket error')))
+    })
+    ws.addEventListener('close', () => {
+      if (!opened) {
+        clearTimeout(timer)
+        reject(new Error('websocket closed before open'))
+      }
+    })
+  })
+
+  return new Promise<ContainerCommandResult>((resolve) => {
+    let settled = false
+    let finalErrorMessage: string | undefined
+
+    const settle = (result: ContainerCommandResult) => {
+      if (settled) return
+      settled = true
+      try {
+        ws.close()
+      } catch {
+        // Already closed.
+      }
+      resolve(result)
+    }
+
+    ws.addEventListener('message', (event) => {
+      const raw = event.data
+      if (typeof raw !== 'string') return
+      let parsed: ServerMessage
+      try {
+        parsed = JSON.parse(raw) as ServerMessage
+      } catch {
+        return
+      }
+      if (!('callId' in parsed) || parsed.callId !== callId) return
+
+      if (parsed.type === 'command_stdout' && opts.stdout) {
+        void writeChunkBase64(opts.stdout, parsed.chunk)
+        return
+      }
+      if (parsed.type === 'command_stderr' && opts.stderr) {
+        void writeChunkBase64(opts.stderr, parsed.chunk)
+        return
+      }
+      if (parsed.type === 'command_error') {
+        finalErrorMessage = parsed.message
+        return
+      }
+      if (parsed.type === 'command_exit') {
+        if (finalErrorMessage !== undefined) {
+          settle({ ok: false, exitCode: parsed.code, message: finalErrorMessage })
+        } else {
+          settle({ ok: true, exitCode: parsed.code })
+        }
+        return
+      }
+    })
+
+    ws.addEventListener('close', () => {
+      if (!settled) {
+        settle({ ok: false, exitCode: 1, message: finalErrorMessage ?? 'websocket closed before command_exit' })
+      }
+    })
+    ws.addEventListener('error', (event) => {
+      if (!settled) {
+        const msg = String((event as { message?: string }).message ?? 'websocket error')
+        settle({ ok: false, exitCode: 1, message: msg })
+      }
+    })
+
+    if (opts.abortSignal !== undefined) {
+      const onAbort = () => {
+        try {
+          const abortFrame: ClientMessage = {
+            type: 'command_abort',
+            callId,
+            reason: opts.abortSignal?.reason instanceof Error ? opts.abortSignal.reason.message : 'aborted',
+          }
+          ws.send(JSON.stringify(abortFrame))
+        } catch {
+          // Best-effort abort; if the send fails the server will close anyway.
+        }
+      }
+      if (opts.abortSignal.aborted) onAbort()
+      else opts.abortSignal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    // Forward TYPECLAW_PARENT_ORIGIN_JSON verbatim when the surrounding
+    // process set it (e.g. a cron exec runner that injected the cron job's
+    // origin into the subprocess env). The server uses this as the
+    // command's spawnedByOrigin so permission resolution chases through
+    // to the parent role instead of defaulting to synthetic-owner.
+    const parentOriginJson = opts.parentOriginJson ?? process.env.TYPECLAW_PARENT_ORIGIN_JSON
+    const exec: ClientMessage = {
+      type: 'exec_command',
+      callId,
+      name: opts.commandName,
+      args: opts.args,
+      ...(opts.isolated !== undefined ? { isolated: opts.isolated } : {}),
+      ...(parentOriginJson !== undefined && parentOriginJson !== '' ? { parentOriginJson } : {}),
+    }
+    ws.send(JSON.stringify(exec))
+
+    if (opts.stdin !== undefined) {
+      pumpStdin(opts.stdin, (chunk) => {
+        const frame: ClientMessage = { type: 'command_stdin', callId, chunk: encodeBase64(chunk) }
+        ws.send(JSON.stringify(frame))
+      })
+        .then(() => {
+          const end: ClientMessage = { type: 'command_stdin_end', callId }
+          ws.send(JSON.stringify(end))
+        })
+        .catch((err: unknown) => {
+          // Local stdin error: tell the server to abandon the in-flight
+          // command so it doesn't wait forever for command_stdin_end, and
+          // settle the host-side promise with a clear error. Without this
+          // .catch the rejection was silent and the command hung.
+          const reason = err instanceof Error ? err.message : String(err)
+          try {
+            const abortFrame: ClientMessage = {
+              type: 'command_abort',
+              callId,
+              reason: `local stdin error: ${reason}`,
+            }
+            ws.send(JSON.stringify(abortFrame))
+          } catch {
+            // ws may have already closed; the close handler will settle below.
+          }
+          settle({ ok: false, exitCode: 1, message: `local stdin error: ${reason}` })
+        })
+    }
+  })
+}
+
+async function resolveUrlFromDocker(agentDir: string): Promise<{ url: string } | { error: string }> {
+  const running = await requireContainerRunning({ cwd: agentDir })
+  if (!running.ok) {
+    return { error: `${running.reason}; start it with \`typeclaw start\`` }
+  }
+  const port = await resolveHostPort({ cwd: agentDir })
+  const token = await resolveTuiToken({ cwd: agentDir })
+  // The dedicated /commands path skips TUI session bootstrap on the server,
+  // saving an AgentSession creation per command invocation. Same auth as
+  // the root /` TUI path; both are owner-equivalent.
+  const url = new URL(`ws://127.0.0.1:${port}/commands`)
+  if (token !== null) url.searchParams.set('token', token)
+  return { url: url.toString() }
+}
+
+async function pumpStdin(stream: ReadableStream<Uint8Array>, send: (chunk: Uint8Array) => void): Promise<void> {
+  const reader = stream.getReader()
+  try {
+    while (true) {
+      const next = await reader.read()
+      if (next.done) return
+      send(next.value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+async function writeChunkBase64(stream: WritableStream<Uint8Array>, chunkBase64: string): Promise<void> {
+  const bytes = Uint8Array.from(atob(chunkBase64), (c) => c.charCodeAt(0))
+  const writer = stream.getWriter()
+  try {
+    await writer.write(bytes)
+  } finally {
+    writer.releaseLock()
+  }
+}
+
+function encodeBase64(bytes: Uint8Array): string {
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i] ?? 0)
+  return btoa(s)
+}

package/src/cli/cron.ts

@@ -0,0 +1,173 @@
+import { defineCommand } from 'citty'
+
+import { requireContainerRunning } from '@/container'
+import { fetchCronList, type CronListBridgeResult } from '@/cron/bridge'
+import { findAgentDir } from '@/init'
+import type { CronListEntryPayload } from '@/shared'
+
+import { c, errorLine } from './ui'
+
+const listSub = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'list all cron jobs (user-authored + plugin-contributed) registered in the running agent',
+  },
+  args: {
+    json: {
+      type: 'boolean',
+      description: 'emit the cron list as JSON',
+      default: false,
+    },
+    url: {
+      type: 'string',
+      description:
+        "agent websocket url (defaults to ws://127.0.0.1:<host port> discovered from the running container's published port)",
+    },
+    timeout: {
+      type: 'string',
+      description: 'milliseconds to wait for the agent to respond',
+      default: '15000',
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const timeoutMs = Number(args.timeout)
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      console.error(errorLine(`invalid --timeout value: ${args.timeout}`))
+      process.exit(1)
+    }
+
+    let url: string | undefined = args.url
+    if (url === undefined) {
+      const precheck = await requireContainerRunning({ cwd })
+      if (!precheck.ok) {
+        console.error(errorLine(precheck.reason))
+        process.exit(1)
+      }
+    }
+
+    const result = await fetchCronList({ cwd, timeoutMs, ...(url !== undefined ? { url } : {}) })
+
+    if (args.json) {
+      process.stdout.write(`${JSON.stringify(toJsonShape(result), null, 2)}\n`)
+      process.exit(result.kind === 'ok' ? 0 : 1)
+    }
+
+    if (result.kind !== 'ok') {
+      console.error(errorLine(describeFailure(result)))
+      process.exit(1)
+    }
+
+    process.stdout.write(`${formatList(result.jobs, result.nowMs)}\n`)
+  },
+})
+
+export const cronCommand = defineCommand({
+  meta: {
+    name: 'cron',
+    description: 'inspect cron jobs registered in the running agent (user-authored + plugin-contributed)',
+  },
+  subCommands: {
+    list: listSub,
+  },
+})
+
+export function describeFailure(result: Exclude<CronListBridgeResult, { kind: 'ok' }>): string {
+  switch (result.kind) {
+    case 'unreachable':
+      return `cannot reach the agent: ${result.reason}`
+    case 'timeout':
+      return 'timed out waiting for the agent to respond'
+    case 'error':
+      return result.reason
+  }
+}
+
+function toJsonShape(result: CronListBridgeResult): unknown {
+  if (result.kind === 'ok') {
+    return { ok: true, nowMs: result.nowMs, jobs: result.jobs }
+  }
+  return { ok: false, reason: describeFailure(result) }
+}
+
+export function formatList(jobs: readonly CronListEntryPayload[], nowMs: number): string {
+  if (jobs.length === 0) {
+    return c.dim('No cron jobs registered.')
+  }
+
+  const lines: string[] = []
+  lines.push(c.bold(`${jobs.length} cron job(s):`))
+  lines.push('')
+  for (const job of jobs) {
+    lines.push(formatEntry(job, nowMs))
+    lines.push('')
+  }
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  return lines.join('\n')
+}
+
+function formatEntry(job: CronListEntryPayload, nowMs: number): string {
+  const lines: string[] = []
+  const sourceLabel =
+    job.source.kind === 'user' ? c.cyan('user') : c.magenta(`plugin:${job.source.pluginName}.${job.source.localId}`)
+  const enabledBadge = job.enabled ? '' : ` ${c.yellow('(disabled)')}`
+  const kindBadge = c.dim(`[${job.kind}]`)
+  lines.push(`${c.bold(displayId(job))} ${kindBadge} ${sourceLabel}${enabledBadge}`)
+
+  const tz = job.timezone !== undefined ? ` ${c.dim(`(${job.timezone})`)}` : ''
+  lines.push(`  ${c.dim('schedule')} ${job.schedule}${tz}`)
+
+  if (job.nextFireMs === null) {
+    const why = job.scheduleError !== undefined ? `: ${job.scheduleError}` : ''
+    lines.push(`  ${c.dim('next    ')} ${c.red('invalid schedule')}${why}`)
+  } else {
+    lines.push(`  ${c.dim('next    ')} ${formatNextFire(job.nextFireMs, nowMs)}`)
+  }
+
+  if (job.scheduledByRole !== undefined) {
+    lines.push(`  ${c.dim('role    ')} ${job.scheduledByRole}`)
+  }
+
+  if (job.kind === 'prompt') {
+    if (job.subagent !== undefined) {
+      lines.push(`  ${c.dim('subagent')} ${job.subagent}`)
+    }
+    if (job.prompt !== undefined && job.subagent === undefined) {
+      lines.push(`  ${c.dim('prompt  ')} ${truncate(job.prompt, 80)}`)
+    }
+  } else if (job.command !== undefined) {
+    lines.push(`  ${c.dim('command ')} ${job.command.join(' ')}`)
+  }
+
+  return lines.join('\n')
+}
+
+function displayId(job: CronListEntryPayload): string {
+  if (job.source.kind === 'plugin') {
+    return `${job.source.pluginName}.${job.source.localId}`
+  }
+  return job.id
+}
+
+export function formatNextFire(nextFireMs: number, nowMs: number): string {
+  const iso = new Date(nextFireMs).toISOString()
+  const diffMs = nextFireMs - nowMs
+  return `${iso} ${c.dim(`(${formatDuration(diffMs)})`)}`
+}
+
+export function formatDuration(diffMs: number): string {
+  if (diffMs <= 0) return 'now'
+  const seconds = Math.round(diffMs / 1000)
+  if (seconds < 60) return `in ${seconds}s`
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `in ${minutes}m`
+  const hours = Math.round(minutes / 60)
+  if (hours < 48) return `in ${hours}h`
+  const days = Math.round(hours / 24)
+  return `in ${days}d`
+}
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s
+  return `${s.slice(0, max - 1)}…`
+}

package/src/cli/host-command-runner.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod'
+
+import {
+  type EitherCommand,
+  type EitherCommandContext,
+  type HostCommand,
+  type HostCommandContext,
+  type PluginCommand,
+} from '@/plugin'
+import { coerceFlag } from '@/plugin/zod-introspect'
+
+export type HostRunOptions = {
+  agentDir: string
+  pluginName: string
+  pluginVersion: string | undefined
+  command: HostCommand | EitherCommand
+  rawArgs: readonly string[]
+  signal: AbortSignal
+  stdin: ReadableStream<Uint8Array>
+  stdout: WritableStream<Uint8Array>
+  stderr: WritableStream<Uint8Array>
+}
+
+export type HostRunResult = { ok: true; exitCode: number } | { ok: false; exitCode: number; message: string }
+
+export async function runHostCommand(opts: HostRunOptions): Promise<HostRunResult> {
+  const argsParse = parseArgs(opts.command, opts.rawArgs)
+  if (!argsParse.ok) {
+    return { ok: false, exitCode: 2, message: argsParse.message }
+  }
+
+  const logger = makeCommandLogger(opts.pluginName, opts.stderr)
+  const ctxBase = {
+    name: opts.pluginName,
+    version: opts.pluginVersion,
+    agentDir: opts.agentDir,
+    logger,
+    signal: opts.signal,
+    stdin: opts.stdin,
+    stdout: opts.stdout,
+    stderr: opts.stderr,
+  }
+
+  try {
+    if (opts.command.surface === 'host') {
+      const ctx: HostCommandContext = ctxBase
+      const code = await opts.command.run(ctx, argsParse.value)
+      return { ok: true, exitCode: code }
+    }
+    const ctx: EitherCommandContext = ctxBase
+    const code = await opts.command.run(ctx, argsParse.value)
+    return { ok: true, exitCode: code }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    return { ok: false, exitCode: 1, message: detail }
+  }
+}
+
+type ArgsParseResult = { ok: true; value: unknown } | { ok: false; message: string }
+
+export function parseArgs(command: PluginCommand, rawArgs: readonly string[]): ArgsParseResult {
+  if (command.args === undefined) {
+    if (rawArgs.length > 0) {
+      return { ok: false, message: `command accepts no arguments but received: ${rawArgs.join(' ')}` }
+    }
+    return { ok: true, value: undefined }
+  }
+
+  const tokenized = tokenizeFlags(rawArgs)
+  if (!tokenized.ok) return tokenized
+
+  const coerced = coerceAgainstSchema(command.args, tokenized.flags)
+  if (!coerced.ok) return coerced
+
+  const parsed = command.args.safeParse(coerced.value)
+  if (!parsed.success) {
+    const message = parsed.error.issues
+      .map((i) => `${i.path.length > 0 ? i.path.join('.') : '<root>'}: ${i.message}`)
+      .join('; ')
+    return { ok: false, message }
+  }
+  return { ok: true, value: parsed.data }
+}
+
+type TokenizeResult = { ok: true; flags: Record<string, string | true> } | { ok: false; message: string }
+
+// Parses `--key=value` / `--key value` / `--key` (boolean) into a flat map.
+// Positional args are not supported in v1 (constrained by the z.object args
+// shape). Unknown flags surface as Zod errors downstream.
+function tokenizeFlags(rawArgs: readonly string[]): TokenizeResult {
+  const flags: Record<string, string | true> = {}
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i]
+    if (arg === undefined) continue
+    if (!arg.startsWith('--')) {
+      return { ok: false, message: `unexpected positional argument: ${arg}` }
+    }
+    const stripped = arg.slice(2)
+    const eq = stripped.indexOf('=')
+    if (eq >= 0) {
+      const key = stripped.slice(0, eq)
+      const value = stripped.slice(eq + 1)
+      flags[key] = value
+      continue
+    }
+    const key = stripped
+    const next = rawArgs[i + 1]
+    if (next !== undefined && !next.startsWith('--')) {
+      flags[key] = next
+      i++
+    } else {
+      flags[key] = true
+    }
+  }
+  return { ok: true, flags }
+}
+
+function coerceAgainstSchema(
+  schema: z.ZodObject<z.ZodRawShape>,
+  flags: Record<string, string | true>,
+): { ok: true; value: Record<string, unknown> } | { ok: false; message: string } {
+  const shape = schema.shape as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const [key, raw] of Object.entries(flags)) {
+    const leaf = shape[key]
+    if (leaf === undefined) {
+      return { ok: false, message: `unknown flag: --${key}` }
+    }
+    try {
+      out[key] = coerceFlag(leaf, raw, key)
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err)
+      return { ok: false, message: detail }
+    }
+  }
+  return { ok: true, value: out }
+}
+
+function makeCommandLogger(pluginName: string, stderr: WritableStream<Uint8Array>) {
+  const writer = stderr.getWriter()
+  const encoder = new TextEncoder()
+  const write = (level: string, msg: string) => {
+    void writer.write(encoder.encode(`[command:${pluginName}] ${level}: ${msg}\n`))
+  }
+  return {
+    info: (msg: string) => write('info', msg),
+    warn: (msg: string) => write('warn', msg),
+    error: (msg: string) => write('error', msg),
+  }
+}

package/src/cli/index.ts

@@ -3,6 +3,8 @@
 import { defineCommand, runMain } from 'citty'
 
 import { CLI_VERSION } from '../init/cli-version'
+import { BUILTIN_COMMAND_NAMES } from './builtins'
+import { dispatchPluginCommand, type PluginCommandDispatchOutcome } from './plugin-commands-dispatch'
 
 const main = defineCommand({
   meta: {
@@ -23,6 +25,8 @@ const main = defineCommand({
     shell: () => import('./shell').then((m) => m.shellCommand),
     compose: () => import('./compose').then((m) => m.composeCommand),
     channel: () => import('./channel').then((m) => m.channelCommand),
+    cron: () => import('./cron').then((m) => m.cronCommand),
+    tunnel: () => import('./tunnel').then((m) => m.tunnelCommand),
     role: () => import('./role').then((m) => m.roleCommand),
     provider: () => import('./provider').then((m) => m.providerCommand),
     model: () => import('./model').then((m) => m.modelCommand),
@@ -32,4 +36,41 @@ const main = defineCommand({
   },
 })
 
-runMain(main)
+await runWithPluginDispatch()
+
+async function runWithPluginDispatch(): Promise<void> {
+  const argv = process.argv.slice(2)
+  const first = argv[0]
+
+  if (first === '--help' || first === '-h') {
+    // citty calls process.exit() after rendering help, so anything we print
+    // AFTER `runMain(main)` is never reached. Print the plugin commands
+    // section first; citty's own help follows and the user reads top-down.
+    const { renderPluginCommandsSection } = await import('./plugin-command-help')
+    const { discoverCommands } = await import('./plugin-commands')
+    const discovery = await discoverCommands({ cwd: process.cwd() })
+    const section = renderPluginCommandsSection(discovery.commands)
+    if (section !== null) process.stdout.write(`${section}\n\n`)
+    await runMain(main)
+    return
+  }
+
+  if (
+    first !== undefined &&
+    !first.startsWith('-') &&
+    !BUILTIN_COMMAND_NAMES.includes(first as (typeof BUILTIN_COMMAND_NAMES)[number])
+  ) {
+    const outcome = await dispatchPluginCommand({ name: first, rawArgs: argv.slice(1), cwd: process.cwd() })
+    if (outcome.kind === 'dispatched') {
+      process.exit(outcome.exitCode)
+    }
+    if (outcome.kind === 'error') {
+      process.stderr.write(`${outcome.message}\n`)
+      process.exit(outcome.exitCode)
+    }
+    // outcome.kind === 'not-found' → fall through to citty for unknown-command error
+  }
+  await runMain(main)
+}
+
+export type { PluginCommandDispatchOutcome }