typeclaw 0.3.1 → 0.5.0

package/README.md

@@ -35,6 +35,7 @@ TypeClaw is the agent I wanted to use:
 - 🔄 **Hot reload** — change `typeclaw.json`, `typeclaw reload` — no restart for most fields
 - 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
 - 🌐 **Auto port-forward** — dev servers inside the container appear on `localhost`, even loopback-only ones
+- 🌍 **Public tunnels** — Cloudflare Quick (zero signup) or bring-your-own external URL; the agent self-registers GitHub webhooks at the resulting public URL
 - 🎼 **Compose** — orchestrate multiple agents across multiple folders
 
 ### 🌱 Self-improving, in detail
@@ -68,20 +69,23 @@ That's it. The agent is now alive, listening on a websocket, ready to receive pr
 
 ## CLI
 
-| Command                             | Purpose                                                                            |
-| ----------------------------------- | ---------------------------------------------------------------------------------- |
-| `typeclaw init`                     | Scaffold a new agent folder                                                        |
-| `typeclaw start`                    | Build and run the container                                                        |
-| `typeclaw stop`                     | Stop the container                                                                 |
-| `typeclaw restart`                  | `stop` then `start`                                                                |
-| `typeclaw status`                   | Show container + daemon registration state                                         |
-| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow               |
-| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                    |
-| `typeclaw shell`                    | Open a shell inside the running container                                          |
-| `typeclaw reload`                   | Push a live config reload to the running agent                                     |
-| `typeclaw compose`                  | Orchestrate multiple agents                                                        |
-| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk)                   |
-| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password |
+| Command                             | Purpose                                                                             |
+| ----------------------------------- | ----------------------------------------------------------------------------------- |
+| `typeclaw init`                     | Scaffold a new agent folder                                                         |
+| `typeclaw start`                    | Build and run the container                                                         |
+| `typeclaw stop`                     | Stop the container                                                                  |
+| `typeclaw restart`                  | `stop` then `start`                                                                 |
+| `typeclaw status`                   | Show container + daemon registration state                                          |
+| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow                |
+| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                     |
+| `typeclaw shell`                    | Open a shell inside the running container                                           |
+| `typeclaw reload`                   | Push a live config reload to the running agent                                      |
+| `typeclaw compose`                  | Orchestrate multiple agents                                                         |
+| `typeclaw cron list`                | List every cron job registered in the running agent (user `cron.json` + plugins)    |
+| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk, GitHub)            |
+| `typeclaw channel set <kind>`       | Rotate the credentials of an already-configured channel (bot/app tokens, PAT, etc.) |
+| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password  |
+| `typeclaw tunnel ...`               | Add/list/status/remove public tunnels and inspect tunnel logs                       |
 
 ## Configuration
 
@@ -107,7 +111,8 @@ my-agent/
 - `plugins` — list of plugin module specifiers
 - `channels` — `slack-bot` / `discord-bot` config
 - `portForward` — allow/deny list for auto port forwarding (default: `*`)
-- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, plus `append` lines
+- `tunnels` — declare public URLs for inbound webhooks and ad-hoc exposure (`cloudflare-quick` or `external`)
+- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, `cjkFonts`, plus `append` lines
 - `memory` — idle window and dreaming schedule for the memory plugin
 
 `Dockerfile` and `.gitignore` are owned by TypeClaw and rewritten on every `start` — edit `src/init/dockerfile.ts` and re-run `start --build` to ship template changes.

package/auth.schema.json

@@ -142,6 +142,119 @@
             }
           }
         },
+        "github": {
+          "type": "object",
+          "properties": {
+            "auth": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "pat"
+                    },
+                    "token": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "token"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "app"
+                    },
+                    "appId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "privateKey": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    },
+                    "installationId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "appId",
+                    "privateKey"
+                  ]
+                }
+              ]
+            },
+            "webhookSecret": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "value": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "env": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "required": [
+            "auth",
+            "webhookSecret"
+          ]
+        },
         "telegram-bot": {
           "type": "object",
           "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/secrets.schema.json

@@ -142,6 +142,119 @@
             }
           }
         },
+        "github": {
+          "type": "object",
+          "properties": {
+            "auth": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "pat"
+                    },
+                    "token": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "token"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string",
+                      "const": "app"
+                    },
+                    "appId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    },
+                    "privateKey": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "minLength": 1
+                        },
+                        {
+                          "type": "object",
+                          "properties": {
+                            "value": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "env": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          }
+                        }
+                      ]
+                    },
+                    "installationId": {
+                      "type": "integer",
+                      "exclusiveMinimum": 0,
+                      "maximum": 9007199254740991
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "appId",
+                    "privateKey"
+                  ]
+                }
+              ]
+            },
+            "webhookSecret": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "minLength": 1
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "value": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "env": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "required": [
+            "auth",
+            "webhookSecret"
+          ]
+        },
         "telegram-bot": {
           "type": "object",
           "properties": {

package/src/agent/auth.ts

@@ -83,8 +83,10 @@ export function getAuthFor(providerId: KnownProviderId): Auth {
 
 // Back-compat shim for callers that still want the `default` profile's auth
 // (the main session path). Equivalent to `getAuthFor(provider-of-default)`.
+// Uses the head of the fallback chain; auth for the rest of the chain is
+// resolved lazily when fallback actually fires.
 export function getAuth(): Auth {
-  const defaultRef = getConfig().models.default
+  const defaultRef = getConfig().models.default[0]!
   return getAuthFor(providerForModelRef(defaultRef))
 }
 
@@ -98,7 +100,7 @@ function hasAnyCredentialInEnv(apiKeyEnv: string | null): boolean {
 
 function missingCredentialMessage(providerId: KnownProviderId): string {
   const provider = KNOWN_PROVIDERS[providerId]
-  const defaultRef = getConfig().models.default
+  const defaultRef = getConfig().models.default[0]!
   const defaultProviderId = providerForModelRef(defaultRef)
   // For the `default` profile, name the model in the error message (matches
   // pre-multi-model behavior). For any other profile, the user is mixing

package/src/agent/index.ts

@@ -8,7 +8,7 @@ import type { AgentSession, ToolDefinition } from '@mariozechner/pi-coding-agent
 import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
-import { providerForModelRef } from '@/config/providers'
+import { providerForModelRef, type KnownModelRef } from '@/config/providers'
 import type { PermissionService } from '@/permissions'
 import type {
   BuiltinToolRef,
@@ -134,6 +134,12 @@ export type CreateSessionOptions = {
   // overrides) so different sessions on the same agent can run different
   // models without per-session config edits.
   profile?: string
+  // Override the resolved ref directly, bypassing `profile` resolution. Used
+  // by the model-fallback helper (`promptWithFallback`) to recreate a session
+  // pinned to the next ref in the chain after the previous one failed. When
+  // set, `profile` is still recorded for the fallback-warning bookkeeping;
+  // the profile→refs resolution is skipped.
+  refOverride?: KnownModelRef
   // Defensive ceiling on cumulative bytes of tool-result text per session,
   // applied to the named tools only. See `src/agent/tool-result-budget.ts`
   // for the rationale. Intended for subagents that read large files
@@ -161,10 +167,14 @@ export async function createSession(options: CreateSessionOptions = {}): Promise
 
 export async function createSessionWithDispose(options: CreateSessionOptions = {}): Promise<CreateSessionResult> {
   const resolved = resolveProfile(getConfig().models, options.profile)
-  if (resolved.fellBackToDefault && options.profile !== undefined && options.profile !== 'default') {
-    warnProfileFallbackOnce(options.profile, resolved.ref)
-  }
-  const { authStorage, modelRegistry } = getAuthFor(providerForModelRef(resolved.ref))
+  // Unknown profiles silently fall back to `default`. The fallback is by design
+  // (see `resolveProfile`) and surfacing a warning here just creates noise on
+  // every memory-logger / dreaming subagent spawn for advanced users who know
+  // exactly what they're doing.
+  // `refOverride` lets the model-fallback helper pin a specific entry from
+  // the chain when it recreates a session after the previous ref failed.
+  const activeRef: KnownModelRef = options.refOverride ?? resolved.ref
+  const { authStorage, modelRegistry } = getAuthFor(providerForModelRef(activeRef))
 
   const materializedSkills =
     options.plugins && options.plugins.registry.skills.length > 0
@@ -279,7 +289,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
       ? customToolsPreBudget.map((t) => wrapToolDefinitionWithBudget(t, sessionBudget, sessionBudgetState))
       : customToolsPreBudget
 
-  const model = resolveModel(resolved.ref)
+  const model = resolveModel(activeRef)
   const { session } = await createAgentSession({
     model,
     sessionManager,
@@ -737,25 +747,3 @@ function resolveRoleContext(
 export function getBundledSkillsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 }
-
-// Profile-fallback warning is fired once per (profile, ref) pair per process.
-// Without rate-limiting, every memory-logger spawn (~every idle event) would
-// emit a fresh warning when the user has only `default` configured — tens of
-// warnings per channel session is noise the operator will learn to ignore.
-// The pair includes `ref` so a config reload that changes `default` re-warns.
-const profileFallbackWarned = new Set<string>()
-
-function warnProfileFallbackOnce(profile: string, ref: string): void {
-  const key = `${profile}\x00${ref}`
-  if (profileFallbackWarned.has(key)) return
-  profileFallbackWarned.add(key)
-  console.warn(
-    `[agent] unknown model profile "${profile}"; falling back to "default" (${ref}). Add it under \`models\` in typeclaw.json to remove this warning. (further occurrences suppressed)`,
-  )
-}
-
-// Test-only: clear the rate-limit cache so a test can assert the warning fires
-// once after rate-limit reset.
-export function __resetProfileFallbackWarningsForTesting(): void {
-  profileFallbackWarned.clear()
-}

package/src/agent/model-fallback.ts

@@ -0,0 +1,127 @@
+import { resolveProfile } from '@/config'
+import type { Models } from '@/config/config'
+import type { KnownModelRef } from '@/config/providers'
+
+import type { AgentSession } from './index'
+import { subscribeProviderErrors } from './provider-error'
+
+// Result of a single fallback-aware prompt run.
+// - `refUsed` is the ref whose session ultimately handled the turn.
+// - `attempts` lists every ref that was tried, in order, with the failure
+//   reason for each attempt that didn't make it through. `attempts.length`
+//   is always >= 1; the last entry succeeded iff `success: true`.
+// - `session` / `dispose` are the session that handled the turn (or attempted
+//   the final entry, on full-chain failure). Callers that need to keep using
+//   the session for subsequent turns store these in their state; callers that
+//   tear down per-turn (cron) just call `dispose()` and discard.
+export type FallbackPromptResult = {
+  success: boolean
+  refUsed: KnownModelRef
+  attempts: FallbackAttempt[]
+  session: AgentSession
+  dispose: () => Promise<void>
+  // When `success === false`, this is the error from the final attempt.
+  lastError?: Error
+}
+
+export type FallbackAttempt = {
+  ref: KnownModelRef
+  // 'hard' = session.prompt() threw. 'soft' = pi-coding-agent surfaced an
+  // upstream error via stopReason: 'error' on the final assistant message.
+  // 'success' = the turn finished cleanly.
+  outcome: 'hard' | 'soft' | 'success'
+  errorMessage?: string
+}
+
+// Build the ordered list of refs to attempt for a given profile. Single-ref
+// profiles produce a length-1 chain; the fallback path is then a no-op in
+// practice (the first attempt either succeeds or the error propagates).
+//
+// Exported so callers can introspect the chain (e.g. logs, telemetry) before
+// firing the prompt — useful for `[cron] ${jobId}: trying chain a → b → c`.
+export function resolveFallbackChain(models: Models, profile: string | undefined): KnownModelRef[] {
+  return resolveProfile(models, profile).refs
+}
+
+// Drives one `session.prompt(text)` call with full fallback semantics:
+//
+//   1. Create a session bound to `refs[0]` via `createSessionForRef`.
+//   2. Subscribe to provider-error events so soft errors (pi-coding-agent's
+//      `stopReason: 'error'` shape) trigger fallback in addition to throws.
+//   3. Await `session.prompt(text)`.
+//   4. If the prompt threw OR a soft error fired during the turn:
+//      - dispose the failed session
+//      - advance to `refs[i+1]` and retry (only if a fallback is available)
+//   5. Return the session that handled the turn (or the last-tried session
+//      on full-chain failure), the ref used, and the attempt log.
+//
+// The wrapper intentionally does NOT swallow the final failure: when every
+// ref in the chain has been exhausted, the returned `success: false` plus
+// `lastError` lets the caller surface the failure however it already does
+// (console.error in the server drain, channel reaction in the router,
+// cron-job status). This keeps the helper composable with the existing
+// error-handling code at each call site.
+export async function promptWithFallback(opts: {
+  refs: KnownModelRef[]
+  text: string
+  createSessionForRef: (ref: KnownModelRef) => Promise<{ session: AgentSession; dispose: () => Promise<void> }>
+  // Called after each non-final attempt so callers can log the per-attempt
+  // failure with their own context (sessionId, channel key, job id, ...).
+  onAttemptFailed?: (attempt: FallbackAttempt) => void
+}): Promise<FallbackPromptResult> {
+  if (opts.refs.length === 0) {
+    throw new Error('promptWithFallback: refs[] must be non-empty')
+  }
+  const attempts: FallbackAttempt[] = []
+  let lastError: Error | undefined
+  for (let i = 0; i < opts.refs.length; i++) {
+    const ref = opts.refs[i]!
+    const isLast = i === opts.refs.length - 1
+    const { session, dispose } = await opts.createSessionForRef(ref)
+    // Capture the first soft error per attempt. The `subscribeProviderErrors`
+    // listener fires synchronously off the `message_end` event, which lands
+    // BEFORE `session.prompt()` resolves — so by the time `await` returns,
+    // `softError` is populated if a soft error occurred.
+    let softError: Error | undefined
+    const unsub = subscribeProviderErrors(session, (err) => {
+      if (!softError) softError = new Error(err.message)
+    })
+    try {
+      try {
+        await session.prompt(opts.text)
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err))
+        const attempt: FallbackAttempt = { ref, outcome: 'hard', errorMessage: error.message }
+        attempts.push(attempt)
+        lastError = error
+        if (!isLast) opts.onAttemptFailed?.(attempt)
+        unsub()
+        await dispose()
+        if (isLast) {
+          return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
+        }
+        continue
+      }
+      if (softError !== undefined) {
+        const attempt: FallbackAttempt = { ref, outcome: 'soft', errorMessage: softError.message }
+        attempts.push(attempt)
+        lastError = softError
+        if (!isLast) opts.onAttemptFailed?.(attempt)
+        unsub()
+        await dispose()
+        if (isLast) {
+          return { success: false, refUsed: ref, attempts, session, dispose: async () => {}, lastError }
+        }
+        continue
+      }
+      attempts.push({ ref, outcome: 'success' })
+      unsub()
+      return { success: true, refUsed: ref, attempts, session, dispose }
+    } catch (err) {
+      unsub()
+      await dispose()
+      throw err
+    }
+  }
+  throw new Error('promptWithFallback: unreachable — loop terminated without returning')
+}

package/src/agent/session-meta.ts

@@ -8,7 +8,7 @@ export type SessionMetaPayload = {
 
 export type MinimalSessionOrigin =
   | { kind: 'tui' }
-  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }
   | { kind: 'channel'; adapter: string; workspace: string; chat: string; thread: string | null }
   | { kind: 'subagent'; subagent: string; parentSessionId: string }
 

package/src/agent/session-origin.ts

@@ -25,7 +25,7 @@ export type SessionOrigin =
   | {
       kind: 'cron'
       jobId: string
-      jobKind: 'prompt' | 'exec' | 'subagent'
+      jobKind: 'prompt' | 'exec' | 'subagent' | 'handler'
       scheduledByRole?: string
       scheduledByOrigin?: SessionOrigin | { kind: 'config-file' }
     }
@@ -78,6 +78,7 @@ type PlatformInfo = {
 const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
   'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id' },
   'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id' },
+  github: { displayName: 'GitHub', mentionMode: 'at-username' },
   'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username' },
   kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias' },
 }
@@ -150,7 +151,7 @@ function renderTuiOrigin(): string {
   ].join('\n')
 }
 
-function renderCronOrigin(origin: { jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }): string {
+function renderCronOrigin(origin: { jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' | 'handler' }): string {
   return [
     '## Session origin',
     '',