typeclaw 0.3.1 → 0.5.0

package/src/plugin/types.ts

@@ -92,7 +92,58 @@ export type PluginExecCronJob = {
   timezone?: string
 }
 
-export type PluginCronJob = PluginPromptCronJob | PluginExecCronJob
+// In-process handler. Invoked directly by the cron consumer; no shell-out, no
+// WS round-trip, no Bun.spawn. Use this when the cron job needs imperative
+// control flow (probe → maybe prompt → write file) and lives in the same
+// plugin as the logic — there is no need to dress the work up as a CLI
+// command just to schedule it from yourself.
+//
+// `handler` is a TypeScript function reference, so this kind CANNOT appear in
+// cron.json (only plugin-contributed cron registrations can carry it). The
+// schema gate (`parseCronFile` in src/cron/schema.ts) keeps user files limited
+// to `prompt` and `exec`.
+export type PluginHandlerCronJob = {
+  schedule: string
+  kind: 'handler'
+  handler: (ctx: CronHandlerContext) => Promise<void>
+  enabled?: boolean
+  timezone?: string
+}
+
+export type PluginCronJob = PluginPromptCronJob | PluginExecCronJob | PluginHandlerCronJob
+
+// Surface passed into a plugin cron handler. Mirrors the LLM-call capabilities
+// of `ContainerCommandContext` (`prompt`, `subagent`, `exec`) without the
+// CLI-shaped fields (stdin/stdout/stderr, args, exit code) because cron has
+// no caller to pipe to.
+//
+// `signal` is reserved for future cancellation and is currently never aborted
+// by the runtime — the consumer matches the existing prompt/exec cron jobs
+// which also let in-flight work finish on container shutdown. The signal IS
+// already threaded into `ctx.prompt` and `ctx.exec`, so the moment the
+// runtime starts aborting it (e.g. via a future graceful-shutdown path),
+// propagation works without handler-author changes. Handler authors who
+// want to respect future cancellation should still check `ctx.signal.aborted`
+// in long-running loops; nothing fires it today.
+//
+// `origin` is a cron-shaped SessionOrigin so any session the handler spawns
+// via `ctx.prompt` carries the cron job's provenance — same role-inheritance
+// semantics as a `kind: 'exec'` job that shells out to `typeclaw <cmd>`.
+export type CronHandlerContext = {
+  readonly jobId: string
+  // The plugin that registered this cron job (e.g. 'inbox-watch'). Matches
+  // `ContainerCommandContext.name`. Useful for log lines that should be
+  // attributable to the plugin, not just the cron id.
+  readonly name: string
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal
+  readonly permissions: PermissionService
+  readonly origin: SessionOrigin
+  readonly prompt: (text: string) => Promise<string>
+  readonly subagent: (name: string, payload?: unknown) => Promise<void>
+  readonly exec: (cmd: TemplateStringsArray, ...values: unknown[]) => Promise<CommandExecResult>
+}
 
 export type PluginSkill = {
   description: string
@@ -267,5 +318,97 @@ export type PluginFixResult = {
 export type DefinedPlugin<TConfig = never> = {
   readonly configSchema?: z.ZodType<TConfig>
   readonly permissions?: readonly string[]
+  // Permission strings the owner wildcard sentinel MUST NOT auto-expand
+  // to. Used by the bundled security plugin to keep audience-leak
+  // (high-tier) bypasses off the owner role unless an operator grants
+  // them explicitly in roles.owner.permissions[]. Generic by design so
+  // any future plugin can carve specific permissions out of the wildcard.
+  readonly ownerWildcardExclusions?: readonly string[]
+  // Declared by-value (not built inside the factory) so the host-stage CLI
+  // can dispatch commands without booting plugin runtime state.
+  readonly commands?: Record<string, PluginCommand>
   readonly plugin: (ctx: PluginContext<TConfig>) => Promise<PluginExports>
 }
+
+// `surface` controls where a plugin command may run: `'container'` requires
+// the agent runtime (prompt/subagent/exec); `'host'` runs on the user's
+// machine with no agent runtime; `'either'` accepts the intersection ctx
+// and runs on whichever stage the user invoked it from.
+export type PluginCommand = ContainerCommand | HostCommand | EitherCommand
+
+export type ContainerCommand<A = unknown> = {
+  readonly surface: 'container'
+  readonly description: string
+  // v1 constraint: `z.object({...})` with primitive (string/number/boolean/
+  // literal/enum) leaves so `--help` can render `--<name>=<type>`.
+  readonly args?: z.ZodObject<z.ZodRawShape>
+  readonly permissions?: readonly string[]
+  // When true, runtime spawns a fresh Bun subprocess instead of dispatching
+  // in-process. Costs ~150ms cold-start; trade for isolation from the agent.
+  readonly isolated?: boolean
+  readonly run: (ctx: ContainerCommandContext, args: A) => Promise<number>
+}
+
+export type HostCommand<A = unknown> = {
+  readonly surface: 'host'
+  readonly description: string
+  readonly args?: z.ZodObject<z.ZodRawShape>
+  readonly run: (ctx: HostCommandContext, args: A) => Promise<number>
+}
+
+export type EitherCommand<A = unknown> = {
+  readonly surface: 'either'
+  readonly description: string
+  readonly args?: z.ZodObject<z.ZodRawShape>
+  readonly run: (ctx: EitherCommandContext, args: A) => Promise<number>
+}
+
+export type CommandStreams = {
+  readonly stdin: ReadableStream<Uint8Array>
+  readonly stdout: WritableStream<Uint8Array>
+  readonly stderr: WritableStream<Uint8Array>
+}
+
+export type CommandExecResult = {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+export type ContainerCommandContext = CommandStreams & {
+  // The plugin name (e.g. `'my-utilities'`), NOT the command name. Matches
+  // `PluginContext.name`. Use the command's own static name if you need it.
+  readonly name: string
+  readonly version: string | undefined
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly permissions: PermissionService
+  // Caller's origin (cron job, TUI op, parent session). Drives permission
+  // resolution inside the command. Dispatcher refuses to run without one.
+  readonly origin: SessionOrigin
+  readonly signal: AbortSignal
+  readonly prompt: (text: string) => Promise<string>
+  readonly subagent: (name: string, payload?: unknown) => Promise<void>
+  readonly exec: (cmd: TemplateStringsArray, ...values: unknown[]) => Promise<CommandExecResult>
+}
+
+export type HostCommandContext = CommandStreams & {
+  // The plugin name, NOT the command name. See `ContainerCommandContext.name`.
+  readonly name: string
+  readonly version: string | undefined
+  // Host path of the agent folder (e.g. the absolute path to the agent
+  // folder), NOT `/agent`.
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal
+}
+
+export type EitherCommandContext = CommandStreams & {
+  // The plugin name, NOT the command name. See `ContainerCommandContext.name`.
+  readonly name: string
+  readonly version: string | undefined
+  // Resolves to `/agent` in container, host path on host — same author code.
+  readonly agentDir: string
+  readonly logger: PluginLogger
+  readonly signal: AbortSignal
+}

package/src/plugin/zod-introspect.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod'
+
+export type LeafKind = 'string' | 'number' | 'boolean' | 'unknown'
+
+export type LeafDescription = {
+  kind: LeafKind
+  required: boolean
+  defaultValue: string | undefined
+  description: string | undefined
+}
+
+// Walks the chain of Zod 4 wrappers (optional, default, nullable) and returns
+// the inner-most leaf node. Reads `_def.type` (Zod 4's lowercase discriminator)
+// directly because the public `instanceof ZodOptional` checks don't work for
+// `.innerType` — Zod 4 types it as the base `$ZodType`, not the public class
+// hierarchy. If Zod ships a breaking change to `_def.type`, this is the only
+// file that needs to update.
+export function describeLeaf(leaf: unknown): LeafDescription {
+  let cur: unknown = leaf
+  let required = true
+  let defaultValue: string | undefined
+  let description: string | undefined
+
+  while (cur !== null && typeof cur === 'object') {
+    const node = cur as {
+      _def?: { type?: string; innerType?: unknown; defaultValue?: unknown }
+      description?: string
+    }
+    if (typeof node.description === 'string') description = node.description
+    const def = node._def
+    if (def === undefined) break
+    if (def.type === 'optional') {
+      required = false
+      cur = def.innerType
+      continue
+    }
+    if (def.type === 'default') {
+      required = false
+      const raw = typeof def.defaultValue === 'function' ? (def.defaultValue as () => unknown)() : def.defaultValue
+      defaultValue = raw === undefined ? undefined : JSON.stringify(raw)
+      cur = def.innerType
+      continue
+    }
+    if (def.type === 'nullable') {
+      cur = def.innerType
+      continue
+    }
+    return { kind: classify(def.type), required, defaultValue, description }
+  }
+  return { kind: 'unknown', required, defaultValue, description }
+}
+
+function classify(t: string | undefined): LeafKind {
+  switch (t) {
+    case 'string':
+    case 'literal':
+    case 'enum':
+      return 'string'
+    case 'number':
+    case 'int':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    default:
+      return 'unknown'
+  }
+}
+
+// Coerces a single CLI flag value (string from argv or `true` when bare) to the
+// type the leaf expects. Throws a precise error referencing the flag key when
+// coercion fails; the caller surfaces the message to stderr.
+export function coerceFlag(leaf: unknown, raw: string | true, key: string): unknown {
+  const info = describeLeaf(leaf)
+  if (info.kind === 'boolean') {
+    if (raw === true || raw === 'true') return true
+    if (raw === 'false') return false
+    throw new Error(`--${key}: expected true/false, got "${raw}"`)
+  }
+  if (info.kind === 'number') {
+    if (raw === true) throw new Error(`--${key} requires a numeric value`)
+    if (raw === '') throw new Error(`--${key}: empty value rejected; pass a number`)
+    const n = Number(raw)
+    if (Number.isNaN(n)) throw new Error(`--${key}: not a number: "${raw}"`)
+    return n
+  }
+  if (raw === true) throw new Error(`--${key} requires a value`)
+  return raw
+}
+
+// Returns true when `schema` is a Zod 4 z.object whose leaf properties are all
+// primitive-shaped (string/number/boolean, with optional/default/nullable
+// wrappers). Plugin command args schemas MUST satisfy this in v1.
+export function isPrimitiveZodObject(schema: unknown): schema is z.ZodObject<z.ZodRawShape> {
+  if (!(schema instanceof z.ZodObject)) return false
+  const shape = (schema as z.ZodObject<z.ZodRawShape>).shape as Record<string, unknown>
+  for (const leaf of Object.values(shape)) {
+    if (describeLeaf(leaf).kind === 'unknown') return false
+  }
+  return true
+}

package/src/role-claim/match-rule.ts

@@ -21,9 +21,10 @@ export type PartialChannelOrigin = {
   authorId: string
 }
 
-const ADAPTER_TO_PLATFORM: Record<ChannelKey['adapter'], 'slack' | 'discord' | 'telegram' | 'kakao'> = {
+const ADAPTER_TO_PLATFORM: Record<ChannelKey['adapter'], 'slack' | 'discord' | 'telegram' | 'kakao' | 'github'> = {
   'slack-bot': 'slack',
   'discord-bot': 'discord',
+  github: 'github',
   'telegram-bot': 'telegram',
   kakaotalk: 'kakao',
 }

package/src/run/index.ts

@@ -12,6 +12,7 @@ import {
 } from '@/agent/subagents'
 import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import { createChannelManager, createChannelsReloadable, type ChannelManager } from '@/channels'
+import { createTunnelBridge, type TunnelBridge } from '@/channels/tunnel-bridge'
 import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync } from '@/config'
 import {
   type CronConsumer,
@@ -26,14 +27,24 @@ import {
 } from '@/cron'
 import { CLI_VERSION } from '@/init/cli-version'
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
+import { createPluginLogger } from '@/plugin/context'
+import type { CronHandlerContext } from '@/plugin/types'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
 import { createClaimController } from '@/role-claim'
 import { hydrateChannelEnvFromSecrets } from '@/secrets'
 import { createServer, type Server } from '@/server'
+import {
+  createCommandRunner,
+  type CommandRunner,
+  type CommandSpawnSubagent,
+  runExecForCommand,
+  runPromptForCommand,
+} from '@/server/command-runner'
 import { createSessionFactory, type SessionFactory } from '@/sessions'
 import { createStream, type Stream } from '@/stream'
 import { createTui as createTuiDefault, type TuiOptions } from '@/tui'
+import { createTunnelManager, type TunnelManager, type TunnelManagerOptions } from '@/tunnels'
 
 import { BUNDLED_PLUGINS } from './bundled-plugins'
 import { buildChannelSessionFactory } from './channel-session-factory'
@@ -45,6 +56,8 @@ export type TuiFactory = (options: TuiOptions) => { run: () => Promise<void> }
 
 export type LoadCronFn = (agentDir: string, options?: { subagents?: SubagentRegistry }) => Promise<LoadCronResult>
 export type SchedulerFactory = (options: { cwd: string; file: CronFile; onFire: (job: CronJob) => void }) => Scheduler
+export type ChannelManagerFactory = typeof createChannelManager
+export type TunnelManagerFactory = (options: TunnelManagerOptions) => TunnelManager
 
 export type StartAgentOptions = {
   port: number
@@ -56,6 +69,8 @@ export type StartAgentOptions = {
   createSchedulerFor?: SchedulerFactory
   sessionFactory?: SessionFactory
   stream?: Stream
+  createChannelManager?: ChannelManagerFactory
+  createTunnelManager?: TunnelManagerFactory
 }
 
 export type StartAgentResult = {
@@ -82,6 +97,8 @@ export async function startAgent({
   createSchedulerFor,
   sessionFactory = createSessionFactory({ agentDir: cwd }),
   stream = createStream(),
+  createChannelManager: createChannelManagerFor = createChannelManager,
+  createTunnelManager: createTunnelManagerFor = createTunnelManager,
 }: StartAgentOptions): Promise<StartAgentResult> {
   const reloadRegistry = new ReloadRegistry()
 
@@ -123,6 +140,7 @@ export async function startAgent({
     pluginRegistry.cronJobs.length > 0 ||
     pluginRegistry.skills.length > 0 ||
     pluginRegistry.skillsDirs.length > 0 ||
+    pluginRegistry.commands.length > 0 ||
     pluginsLoaded.loadedPlugins.length > 0
 
   const pluginRuntime = createPluginRuntime({
@@ -149,10 +167,21 @@ export async function startAgent({
     rolesProvider: () => getConfig().roles,
   })
 
-  const channelManager = createChannelManager({
+  const tunnelManager: TunnelManager = createTunnelManagerFor({
+    tunnels: getConfig().tunnels,
+    stream,
+    resolveChannelUpstreamPort: (name) => {
+      if (name === 'github') return getConfig().channels.github?.webhookPort ?? null
+      return null
+    },
+  })
+
+  const channelManager = createChannelManagerFor({
     agentDir: cwd,
     channelsConfigRef: () => getConfig().channels,
     aliasesRef: () => getConfig().alias,
+    tunnelUrlForChannel: (name) => resolveTunnelUrlForChannel(name, tunnelManager),
+    tunnelConfiguredForChannel: (name) => isTunnelConfiguredForChannel(name),
     createSessionForChannel: buildChannelSessionFactory({
       cwd,
       sessionFactory,
@@ -244,7 +273,48 @@ export async function startAgent({
   const cronConsumer = createCronConsumer({
     stream,
     cwd,
-    createSessionForCron: async (job) => {
+    invokeHandler: async (job) => {
+      const snap = pluginRuntime.get()
+      const registered = snap.registry.cronJobs.find((j) => j.globalId === job.id)
+      const pluginName = registered?.pluginName ?? '<unknown>'
+      const logger = createPluginLogger(pluginName)
+      const abortController = new AbortController()
+      const origin: SessionOrigin = {
+        kind: 'cron',
+        jobId: job.id,
+        jobKind: 'handler',
+        ...(job.scheduledByRole !== undefined ? { scheduledByRole: job.scheduledByRole } : {}),
+        scheduledByOrigin: (job.scheduledByOrigin as SessionOrigin | undefined) ?? { kind: 'config-file' },
+      }
+      const ctx: CronHandlerContext = {
+        jobId: job.id,
+        name: pluginName,
+        agentDir: cwd,
+        logger,
+        signal: abortController.signal,
+        permissions: pluginsLoaded.permissions,
+        origin,
+        prompt: (text: string) =>
+          runPromptForCommand({
+            text,
+            origin,
+            runtime: pluginRuntime,
+            agentDir: cwd,
+            permissions: pluginsLoaded.permissions,
+            signal: abortController.signal,
+            runtimeVersion: runtimeVersionOpt.runtimeVersion,
+            containerName: containerNameOpt.containerName,
+          }),
+        subagent: (subName: string, payload?: unknown) =>
+          dispatchSpawnSubagent(subName, payload, {
+            spawnedByOrigin: origin,
+          }),
+        exec: (strings: TemplateStringsArray, ...values: unknown[]) =>
+          runExecForCommand(strings, values, { cwd, signal: abortController.signal }),
+      }
+      await job.handler(ctx)
+    },
+    createSessionForCron: async (job, refOverride) => {
       const snap = pluginRuntime.get()
       const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
       const sessionId = sessionManager.getSessionId()
@@ -266,6 +336,7 @@ export async function startAgent({
         channelRouter: channelManager.router,
         origin: cronOrigin,
         permissions: pluginsLoaded.permissions,
+        ...(refOverride !== undefined ? { refOverride } : {}),
         ...(snap.hasAnyPluginContent
           ? {
               plugins: {
@@ -310,10 +381,15 @@ export async function startAgent({
     )
   }
 
+  const tunnelBridge: TunnelBridge = createTunnelBridge({ stream, channelManager })
+
   reloadRegistry.register(createChannelsReloadable({ manager: channelManager }))
   await channelManager.start()
 
-  pluginsLoaded.setSpawnSubagent(async (name, payload, options) => {
+  // Captured separately from setSpawnSubagent so both the plugin context and
+  // the plugin-command runner can dispatch through the same path. The setter
+  // returns void, so without this local binding we couldn't reuse the fn.
+  const dispatchSpawnSubagent: CommandSpawnSubagent = async (name, payload, options) => {
     // Resolve the spawning session's role from its origin so the subagent
     // inherits it. Callers (hooks like session.idle) pass the parent origin
     // verbatim; we look up the role rather than letting the caller forge it,
@@ -333,7 +409,8 @@ export async function startAgent({
       ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
       ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
     })
-  })
+  }
+  pluginsLoaded.setSpawnSubagent(dispatchSpawnSubagent)
   pluginsLoaded.markBooted()
 
   if (pluginsLoaded.loadedPlugins.length > 0) {
@@ -365,6 +442,17 @@ export async function startAgent({
       : undefined
   const containerBrokerOpt = containerBroker ? { containerBroker } : {}
 
+  const commandRunnerFactory = (outbound: import('@/server/command-runner').CommandOutbound): CommandRunner =>
+    createCommandRunner({
+      pluginRuntime,
+      permissions: pluginsLoaded.permissions,
+      spawnSubagent: dispatchSpawnSubagent,
+      agentDir: cwd,
+      runtimeVersion: CLI_VERSION,
+      containerName,
+      outbound,
+    })
+
   const server = createServer({
     port,
     reloadAll: () => reloadRegistry.reloadAll(),
@@ -375,12 +463,21 @@ export async function startAgent({
     agentDir: cwd,
     pluginRuntime,
     claimController,
+    commandRunnerFactory,
+    tunnelManager,
     ...containerNameOpt,
     ...runtimeVersionOpt,
     ...tuiTokenOpt,
     ...containerBrokerOpt,
   }).start()
 
+  // Tunnel manager starts AFTER the WS server is up so a slow/hanging
+  // provider (PR 2's cloudflared first-URL wait) cannot block TUI, reload,
+  // or channel adapter availability. External providers resolve URLs
+  // synchronously; future managed providers will resolve asynchronously
+  // and broadcast URL events when ready.
+  await tunnelManager.start()
+
   let stopped = false
   const stop = async () => {
     if (stopped) return
@@ -390,6 +487,8 @@ export async function startAgent({
     subagentConsumer.stop()
     server.stop(true)
     void disposeMaterializedSkills(pluginRuntime)
+    tunnelBridge.stop()
+    await tunnelManager.stop()
     await channelManager.stop()
   }
 
@@ -436,6 +535,15 @@ function buildLocalTuiUrl(port: number, token: string | null): string {
   return url.toString()
 }
 
+function resolveTunnelUrlForChannel(channelName: string, tunnelManager: TunnelManager): string | null {
+  const tunnel = getConfig().tunnels.find((entry) => entry.for.kind === 'channel' && entry.for.name === channelName)
+  return tunnel ? tunnelManager.urlFor(tunnel.name) : null
+}
+
+function isTunnelConfiguredForChannel(channelName: string): boolean {
+  return getConfig().tunnels.some((entry) => entry.for.kind === 'channel' && entry.for.name === channelName)
+}
+
 async function disposeMaterializedSkills(pluginRuntime: PluginRuntime): Promise<void> {
   const pending = pluginRuntime.drainPendingDisposal()
   const current = pluginRuntime.get().materializedSkills

package/src/secrets/index.ts

@@ -1,4 +1,4 @@
-export { type Channels } from './schema'
+export { type Channels, type GithubSecretsBlock } from './schema'
 
 export { createSecretsStoreForAgent, SecretsBackend } from './storage'
 

package/src/secrets/schema.ts

@@ -40,6 +40,23 @@ const telegramBotChannelSchema = z.object({
   token: secretFieldSchema.optional(),
 })
 
+const githubPatAuthSchema = z.object({
+  type: z.literal('pat'),
+  token: secretFieldSchema,
+})
+
+const githubAppAuthSchema = z.object({
+  type: z.literal('app'),
+  appId: z.number().int().positive(),
+  privateKey: secretFieldSchema,
+  installationId: z.number().int().positive().optional(),
+})
+
+const githubChannelSchema = z.object({
+  auth: z.discriminatedUnion('type', [githubPatAuthSchema, githubAppAuthSchema]),
+  webhookSecret: secretFieldSchema,
+})
+
 // Encrypted password envelope produced by src/secrets/encryption.ts. Optional
 // in the schema because legacy v2 accounts (pre-renewal feature) don't have
 // one; the renewal cron treats a missing envelope as "reauth required" and
@@ -92,6 +109,7 @@ export const channelsSchema = z
   .object({
     'slack-bot': slackBotChannelSchema.optional(),
     'discord-bot': discordBotChannelSchema.optional(),
+    github: githubChannelSchema.optional(),
     'telegram-bot': telegramBotChannelSchema.optional(),
     kakaotalk: kakaoChannelBlockSchema.optional(),
   })
@@ -113,6 +131,9 @@ export const secretsFileSchema = z.object({
 export type ProviderCredential = z.infer<typeof providerCredentialSchema>
 export type Providers = z.infer<typeof providersSchema>
 export type Channels = z.infer<typeof channelsSchema>
+export type GithubPatAuthBlock = z.infer<typeof githubPatAuthSchema>
+export type GithubAppAuthBlock = z.infer<typeof githubAppAuthSchema>
+export type GithubSecretsBlock = z.infer<typeof githubChannelSchema>
 export type KakaoAccountRecord = z.infer<typeof kakaoAccountRecordSchema>
 export type PendingLoginRecord = z.infer<typeof kakaoPendingLoginRecordSchema>
 export type KakaoChannelBlock = z.infer<typeof kakaoChannelBlockSchema>