typeclaw 0.3.0 → 0.4.0

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()
 
@@ -105,7 +122,13 @@ export async function startAgent({
     ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })
 
-  reloadRegistry.register(createConfigReloadable({ cwd, permissions: pluginsLoaded.permissions }))
+  reloadRegistry.register(
+    createConfigReloadable({
+      cwd,
+      permissions: pluginsLoaded.permissions,
+      skipMountValidation: containerName !== undefined,
+    }),
+  )
   const pluginRegistry = pluginsLoaded.registry
   const pluginHooks = pluginsLoaded.hooks
 
@@ -117,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({
@@ -143,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,
@@ -238,6 +273,47 @@ export async function startAgent({
   const cronConsumer = createCronConsumer({
     stream,
     cwd,
+    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) => {
       const snap = pluginRuntime.get()
       const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
@@ -279,6 +355,7 @@ export async function startAgent({
         sessionId,
         agentDir: cwd,
         origin: cronOrigin,
+        session,
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }
@@ -303,10 +380,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,
@@ -321,11 +403,13 @@ export async function startAgent({
       agentDir: cwd,
       userPrompt: '',
       payload,
+      onProviderError: (message) => console.error(`[subagent] ${name}: LLM call failed: ${message}`),
       ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
       ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
       ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
     })
-  })
+  }
+  pluginsLoaded.setSpawnSubagent(dispatchSpawnSubagent)
   pluginsLoaded.markBooted()
 
   if (pluginsLoaded.loadedPlugins.length > 0) {
@@ -357,6 +441,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(),
@@ -367,12 +462,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
@@ -382,6 +486,8 @@ export async function startAgent({
     subagentConsumer.stop()
     server.stop(true)
     void disposeMaterializedSkills(pluginRuntime)
+    tunnelBridge.stop()
+    await tunnelManager.stop()
     await channelManager.stop()
   }
 
@@ -428,6 +534,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>