typeclaw 0.34.1 → 0.35.1

package/src/config/config.ts

@@ -1,6 +1,6 @@
 import { accessSync, constants as fsConstants, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { isAbsolute, join, resolve } from 'node:path'
+import { isAbsolute, join, posix, resolve } from 'node:path'
 
 import type { Model } from '@mariozechner/pi-ai'
 import { z } from 'zod'
@@ -361,11 +361,98 @@ export type NetworkConfig = z.infer<typeof networkSchema>
 // mount actually works (bare-metal Linux, Docker Desktop — NOT OrbStack, which
 // rejects the mount even with the cap; there the runtime falls back to
 // 'proc-bind' regardless). The cost is the CAP_SYS_ADMIN grant on the container.
+
+// `sandbox.writablePaths` re-exposes operator-chosen subtrees of the agent
+// folder as WRITABLE inside the per-tool bwrap sandbox, on top of the built-in
+// free-write zones (workspace, public, mounts, .git). It exists for tools that
+// insist on writing a fixed config dir a low-trust role would otherwise hit
+// EROFS on (e.g. a CLI that rewrites `<agentDir>/.foo-cli/config.json`).
+//
+// Each entry is AGENT-ROOT-RELATIVE — it resolves under /agent and may not
+// escape it. Absolute container paths are rejected at parse time: a blanket RW
+// bind outside /agent would punch a hole through the agent trust boundary that
+// the rest of the sandbox model assumes can't happen. `..` segments and
+// null bytes are rejected for the same reason. Targets that don't exist, aren't
+// directories, are symlinks, or land on a security-sensitive path
+// (.git, .env, secrets.json, sessions, memory, .typeclaw, node_modules, the
+// agent root itself) are dropped at resolve time, NOT parse time — existence is
+// a runtime property and the drop keeps a stale config from aborting the
+// sandbox. See resolveWritableZones in src/sandbox/writable-zones.ts.
+export const relativeAgentPathSchema = z
+  .string()
+  .min(1)
+  .refine((value) => !isAbsolute(value), 'must be relative to the agent root, not an absolute path')
+  .refine((value) => !value.includes('\0'), 'must not contain a null byte')
+  .refine((value) => !value.split(/[/\\]+/).includes('..'), "must not contain a '..' segment")
+
+// `sandbox.symlinks` is the one-entry abstraction for the common case of a CLI
+// that reads its config from a fixed path the sandbox can't write: it (1) creates
+// the symlink `from -> /agent/<to>` and (2) makes `<to>` a writable zone (same
+// machinery as `writablePaths` — every `to` is folded into the writable set).
+//
+// `from` is the symlink LOCATION and is fully configurable: an absolute container
+// path (e.g. `/root/.metabase-cli`) or a `~/`-prefixed path expanded against the
+// stage's HOME. Two stages create it: the entrypoint shim creates it at the real
+// container HOME (/root) for trusted/owner roles whose bash runs UNSANDBOXED, and
+// the per-tool bwrap sandbox emits a `--symlink` at the sandbox HOME (/tmp) for
+// low-trust roles — because `$HOME` differs between the two stages, a `~/` from
+// resolves to a different absolute path in each, which is exactly what each
+// consumer needs. The entrypoint refuses to clobber an existing non-symlink.
+//
+// `from` SECURITY: it must not contain a null byte, must not be the root `/`, and
+// must not point INTO /agent (a self-referential loop). Kernel/virtual paths
+// (/proc, /sys, /dev, /run) are rejected — symlinking over them is never a real
+// config need and risks masking the runtime's view of them. `/etc/...` is allowed
+// (a legitimate use case) because the entrypoint's no-clobber guard already stops
+// it from overwriting an existing system file. `to` reuses relativeAgentPathSchema.
+//
+// `..` is rejected OUTRIGHT, before the /agent and kernel-root bans run. Those
+// bans previously inspected the RAW string, which both consumers later normalize
+// against $HOME — so a `~/../agent/workspace/.foo` (→ /agent/...) or
+// `~/../proc/x` (→ /proc/...) slipped past a startsWith('/agent') /
+// startsWith('/proc') check on the un-normalized text. A traversal segment is the
+// ONLY way the post-$HOME effective path can re-enter a banned root, so banning
+// `..` makes the raw-string bans equivalent to checking the effective path —
+// stage-independent, no need to expand $HOME at parse time. The bans then run on
+// the POSIX-normalized form so an absolute `from` like `/var/../proc` is caught
+// even though it has no leading `/proc` literal.
+const FORBIDDEN_SYMLINK_FROM_ROOTS = ['/proc', '/sys', '/dev', '/run'] as const
+function normalizedSymlinkFrom(value: string): string {
+  // The `~/` prefix is not a real path component; normalize only the remainder
+  // so a `~/a/b` stays `~/a/b` while `/var/../proc` collapses to `/proc`.
+  if (value.startsWith('~/')) return `~/${posix.normalize(value.slice(2))}`
+  return posix.normalize(value)
+}
+export const symlinkFromSchema = z
+  .string()
+  .min(1)
+  .refine((value) => !value.includes('\0'), 'must not contain a null byte')
+  .refine((value) => value.startsWith('~/') || isAbsolute(value), 'must be an absolute path or start with ~/')
+  .refine((value) => !value.split(/[/\\]+/).includes('..'), "must not contain a '..' segment")
+  .refine((value) => normalizedSymlinkFrom(value) !== '/', 'must not be the filesystem root')
+  .refine((value) => {
+    const normalized = normalizedSymlinkFrom(value)
+    return !normalized.startsWith('/agent/') && normalized !== '/agent'
+  }, 'must not point into /agent (the symlink would loop back into the agent folder)')
+  .refine((value) => {
+    const normalized = normalizedSymlinkFrom(value)
+    return !FORBIDDEN_SYMLINK_FROM_ROOTS.some((root) => normalized === root || normalized.startsWith(`${root}/`))
+  }, 'must not point at a kernel/virtual path (/proc, /sys, /dev, /run)')
+
+export const symlinkSchema = z.object({
+  from: symlinkFromSchema,
+  to: relativeAgentPathSchema,
+})
+
+export type SandboxSymlink = z.infer<typeof symlinkSchema>
+
 export const sandboxSchema = z
   .object({
     realProc: z.boolean().default(false),
+    writablePaths: z.array(relativeAgentPathSchema).default([]),
+    symlinks: z.array(symlinkSchema).default([]),
   })
-  .default({ realProc: false })
+  .default({ realProc: false, writablePaths: [], symlinks: [] })
 
 export type SandboxConfig = z.infer<typeof sandboxSchema>
 
@@ -592,6 +679,15 @@ export function expandMountPath(input: string, cwd: string): string {
   return isAbsolute(input) ? input : resolve(cwd, input)
 }
 
+// The full set of agent-relative dirs the sandbox should make writable: the
+// explicit `sandbox.writablePaths` plus every `sandbox.symlinks[].to` (so an
+// operator declaring a symlink doesn't also have to list its target). Order is
+// stable (writablePaths first) and duplicates are harmless — resolveWritableZones
+// dedupes after resolving each to an absolute path.
+export function getSandboxWritablePathSpecs(cfg: Pick<Config, 'sandbox'>): string[] {
+  return [...cfg.sandbox.writablePaths, ...cfg.sandbox.symlinks.map((link) => link.to)]
+}
+
 // Loaded eagerly from process.cwd()/typeclaw.json at module-import time so
 // citty arg defaults (e.g. config.port in src/cli/*.ts) see real values, not
 // hardcoded fallbacks. Missing file → schema defaults; malformed file → ALSO

package/src/container/start.ts

@@ -533,6 +533,18 @@ export async function planStart({
     runArgs.push('--cap-add=SYS_ADMIN')
   }
 
+  // sandbox.symlinks: the entrypoint shim creates `from -> /agent/<to>` at the
+  // real container HOME for the UNSANDBOXED (trusted/owner) bash path. The
+  // low-trust path is handled separately by the per-tool bwrap --symlink op
+  // (src/sandbox/build.ts). Passed as base64-encoded JSON because `from`/`to`
+  // are arbitrary operator strings — base64 sidesteps every shell-metachar and
+  // env-quoting hazard; the shim decodes + JSON-parses it with bun. Omitted when
+  // empty so the common case adds no env clutter and the shim's loop never runs.
+  if (cfg.sandbox.symlinks.length > 0) {
+    const encoded = Buffer.from(JSON.stringify(cfg.sandbox.symlinks), 'utf8').toString('base64')
+    runArgs.push('-e', `TYPECLAW_SANDBOX_SYMLINKS=${encoded}`)
+  }
+
   if (hostdControl) {
     runArgs.push('--add-host', HOST_GATEWAY_ALIAS)
   }

package/src/init/dockerfile.ts

@@ -385,6 +385,68 @@ link_persistent_home_files() {
   ln -sfn "$persist_root/${CLAUDE_CREDENTIALS_RELATIVE_PATH}" "$claude_config_dir/${CLAUDE_CREDENTIALS_FILE_NAME}"
 }
 
+# link_configured_symlinks creates the operator's \`sandbox.symlinks\` at the real
+# container $HOME for the UNSANDBOXED (trusted/owner) bash path; low-trust bash
+# gets an equivalent in-jail symlink from the per-tool bwrap builder instead
+# (src/sandbox/build.ts). TYPECLAW_SANDBOX_SYMLINKS is base64-encoded JSON of
+# [{from,to}] (set by start.ts only when non-empty). The whole job is done in
+# \`bun -e\` rather than POSIX shell because \`from\`/\`to\` are arbitrary operator
+# strings: a real JSON parser + Node fs API sidesteps every word-splitting,
+# glob, and metachar hazard that shell string-handling of untrusted paths
+# carries. Contract enforced here (belt to the config-parse validation in
+# config.ts): \`from\` is expanded against $HOME for a leading \`~/\`, \`to\` resolves
+# under /agent and may not escape it, and an existing NON-symlink at \`from\` is
+# refused (never clobbered) — a dangling/symlink \`from\` is replaced idempotently
+# with \`ln -sfn\` semantics (force + no-deref). Failures are logged and skipped
+# per-entry so one bad symlink never blocks container boot.
+#
+# TYPECLAW_AGENT_DIR defaults to /agent (the bind-mount path) and is overridable
+# only by the shim's behavioral tests, which point it at a tmpdir — same escape
+# hatch as TYPECLAW_PERSIST_HOME_ROOT in link_persistent_home_files. Production
+# never sets it.
+link_configured_symlinks() {
+  [ -n "\${TYPECLAW_SANDBOX_SYMLINKS:-}" ] || return 0
+  TYPECLAW_SANDBOX_SYMLINKS="$TYPECLAW_SANDBOX_SYMLINKS" HOME="$HOME" \\
+    TYPECLAW_AGENT_DIR="\${TYPECLAW_AGENT_DIR:-/agent}" bun -e '
+    import { lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+    import { dirname, join, normalize, resolve } from "node:path";
+    const home = process.env.HOME || "/root";
+    const agentDir = process.env.TYPECLAW_AGENT_DIR || "/agent";
+    let specs;
+    try {
+      specs = JSON.parse(Buffer.from(process.env.TYPECLAW_SANDBOX_SYMLINKS, "base64").toString("utf8"));
+    } catch (e) {
+      console.error("typeclaw-entrypoint: could not parse TYPECLAW_SANDBOX_SYMLINKS:", String(e));
+      process.exit(0);
+    }
+    for (const spec of Array.isArray(specs) ? specs : []) {
+      const from = String(spec?.from ?? "");
+      const to = String(spec?.to ?? "");
+      if (from === "" || to === "") continue;
+      const fromAbs = from.startsWith("~/") ? join(home, from.slice(2)) : normalize(from);
+      const target = resolve(agentDir, to);
+      if (target !== agentDir && !target.startsWith(agentDir + "/")) {
+        console.error("typeclaw-entrypoint: skip symlink, target escapes /agent:", to);
+        continue;
+      }
+      try {
+        mkdirSync(target, { recursive: true });
+        mkdirSync(dirname(fromAbs), { recursive: true });
+        let existing;
+        try { existing = lstatSync(fromAbs); } catch { existing = undefined; }
+        if (existing && !existing.isSymbolicLink()) {
+          console.error("typeclaw-entrypoint: refusing to clobber existing non-symlink at", fromAbs);
+          continue;
+        }
+        if (existing) rmSync(fromAbs);
+        symlinkSync(target, fromAbs);
+      } catch (e) {
+        console.error("typeclaw-entrypoint: failed to create symlink", fromAbs, "->", target, ":", String(e));
+      }
+    }
+  ' || true
+}
+
 start_xvfb() {
   if ! command -v Xvfb >/dev/null 2>&1; then
     return 0
@@ -419,6 +481,7 @@ start_xvfb() {
 
 if [ "\${TYPECLAW_NETWORK_BLOCK_INTERNAL:-0}" != "1" ]; then
   link_persistent_home_files
+  link_configured_symlinks
   start_xvfb
   exec bun run typeclaw "$@"
 fi
@@ -465,6 +528,7 @@ ip6tables -A OUTPUT -o lo -j ACCEPT
 ${ipv6Rules.join('\n')}
 
 link_persistent_home_files
+link_configured_symlinks
 start_xvfb
 exec setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin -- bun run typeclaw "$@"
 `

package/src/init/line-auth.ts

@@ -7,7 +7,7 @@ import { SecretsLineCredentialStore } from '@/secrets/line-store'
 export type LineBootstrapStatus = { ok: true } | { ok: false; reason: string }
 
 export type LineLoginCallbacks = {
-  onQRUrl?: (url: string) => void
+  onQRUrl?: (url: string) => void | Promise<void>
   onPincode: (pin: string) => void
 }
 
@@ -33,7 +33,10 @@ export type LineLoginInput =
 // Structural subset of the upstream LineClient the bootstrap drives. Declared
 // here so tests can inject a fake without standing up the real LOCO client.
 export type LineLoginClient = {
-  loginWithQR(options: { onQRUrl: (url: string) => void; onPincode: (pin: string) => void }): Promise<LineLoginResult>
+  loginWithQR(options: {
+    onQRUrl: (url: string) => void | Promise<void>
+    onPincode: (pin: string) => void
+  }): Promise<LineLoginResult>
   loginWithEmail(options: {
     email: string
     password: string
@@ -58,7 +61,9 @@ export async function runLineBootstrap(input: LineLoginInput): Promise<LineBoots
     const result =
       input.method === 'qr'
         ? await client.loginWithQR({
-            onQRUrl: (url) => input.callbacks.onQRUrl?.(url),
+            onQRUrl: async (url) => {
+              await input.callbacks.onQRUrl?.(url)
+            },
             onPincode: input.callbacks.onPincode,
           })
         : await client.loginWithEmail({

package/src/inspect/live.ts

@@ -11,9 +11,15 @@ export type StreamLiveOptions = {
   onSubscribed?: (live: boolean) => void
   onError?: (message: string) => void
   connectTimeoutMs?: number
+  heartbeatIntervalMs?: number
+  pongTimeoutMs?: number
+  bufferedAmountCeiling?: number
 }
 
 const DEFAULT_CONNECT_TIMEOUT_MS = 5_000
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000
+const DEFAULT_PONG_TIMEOUT_MS = 30_000
+const DEFAULT_BUFFERED_AMOUNT_CEILING = 1_048_576
 
 export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<InspectEvent> {
   const WS = opts.WebSocketImpl ?? WebSocket
@@ -26,6 +32,17 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   const accumulators = new Map<string, string>()
   const thinkingAccumulators = new Map<string, string>()
 
+  let heartbeat: ReturnType<typeof setInterval> | null = null
+  let awaitingPongSince: number | null = null
+  let supportsPing = false
+
+  const stopHeartbeat = (): void => {
+    if (heartbeat !== null) {
+      clearInterval(heartbeat)
+      heartbeat = null
+    }
+  }
+
   const wake = (): void => {
     if (resolveNext !== null) {
       const fn = resolveNext
@@ -43,13 +60,19 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
       return
     }
     if (msg.type === 'subscribed') {
+      supportsPing = msg.supportsPing === true
       opts.onSubscribed?.(msg.sessionLive)
       return
     }
+    if (msg.type === 'pong') {
+      awaitingPongSince = null
+      return
+    }
     if (msg.type === 'error') {
       opts.onError?.(msg.message)
       pendingError = msg.message
       closed = true
+      stopHeartbeat()
       try {
         ws.close()
       } catch {
@@ -84,6 +107,7 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   })
   ws.addEventListener('close', () => {
     closed = true
+    stopHeartbeat()
     wake()
   })
 
@@ -99,6 +123,7 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
         'abort',
         () => {
           closed = true
+          stopHeartbeat()
           try {
             ws.close()
           } catch {
@@ -134,25 +159,115 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   }
   ws.send(JSON.stringify(subscribe))
 
-  while (true) {
-    if (buffer.length > 0) {
-      const next = buffer.shift()!
-      yield next
-      continue
+  startHeartbeat({
+    ws,
+    intervalMs: opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+    pongTimeoutMs: opts.pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT_MS,
+    bufferedAmountCeiling: opts.bufferedAmountCeiling ?? DEFAULT_BUFFERED_AMOUNT_CEILING,
+    supportsPing: () => supportsPing,
+    isAwaitingPongSince: () => awaitingPongSince,
+    setAwaitingPongSince: (at) => {
+      awaitingPongSince = at
+    },
+    setTimer: (timer) => {
+      heartbeat = timer
+    },
+    onDead: () => {
+      closed = true
+      stopHeartbeat()
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+      wake()
+    },
+  })
+
+  try {
+    while (true) {
+      if (buffer.length > 0) {
+        const next = buffer.shift()!
+        yield next
+        continue
+      }
+      if (closed) {
+        if (pendingError !== null) throw new Error(pendingError)
+        return
+      }
+      const { event, done } = await new Promise<{ event: InspectEvent | null; done: boolean }>((resolve) => {
+        resolveNext = resolve
+      })
+      if (event !== null) yield event
+      if (done) {
+        if (pendingError !== null) throw new Error(pendingError)
+        return
+      }
+    }
+  } finally {
+    // Also fired when the consumer abandons the generator (break from a
+    // `for await` calls .return()): close the socket so it can't outlive the
+    // viewer, not just the heartbeat timer.
+    stopHeartbeat()
+    closed = true
+    try {
+      ws.close()
+    } catch {
+      /* ignore */
     }
-    if (closed) {
-      if (pendingError !== null) throw new Error(pendingError)
+  }
+}
+
+type HeartbeatOptions = {
+  ws: WebSocket
+  intervalMs: number
+  pongTimeoutMs: number
+  bufferedAmountCeiling: number
+  // Read live: the `subscribed` reply that sets it arrives after the timer is
+  // armed, so a snapshot taken at startHeartbeat time would always be false.
+  supportsPing: () => boolean
+  isAwaitingPongSince: () => number | null
+  setAwaitingPongSince: (at: number | null) => void
+  setTimer: (timer: ReturnType<typeof setInterval>) => void
+  onDead: () => void
+}
+
+// Steady-state liveness watchdog. The connect gate only bounds the OPENING
+// phase; once subscribed, a wedged socket (send queue not draining, no
+// 'close'/'error') would park the read loop forever. The interval fires on the
+// event-loop timer queue independent of the dead socket, so it always runs.
+// Two death signals, both treated as a clean close (return, never throw) so the
+// viewer recovers to the picker:
+//   1. bufferedAmount past a ceiling — our writes are not draining. Always on:
+//      it needs no server cooperation, so it works against any server version.
+//   2. a ping with no pong within the deadline — round-trip liveness lost,
+//      which also covers idle tails (a quiet-but-healthy tail still pongs). Only
+//      armed when the server advertised supportsPing; a pre-heartbeat server
+//      answers an unknown ping with error+close, so probing it would kill the
+//      tail. Such a server degrades to bufferedAmount-only detection.
+function startHeartbeat(opts: HeartbeatOptions): void {
+  let pingId = 0
+  const tick = (): void => {
+    if (opts.ws.bufferedAmount >= opts.bufferedAmountCeiling) {
+      opts.onDead()
       return
     }
-    const { event, done } = await new Promise<{ event: InspectEvent | null; done: boolean }>((resolve) => {
-      resolveNext = resolve
-    })
-    if (event !== null) yield event
-    if (done) {
-      if (pendingError !== null) throw new Error(pendingError)
+    if (!opts.supportsPing()) return
+    const awaiting = opts.isAwaitingPongSince()
+    if (awaiting !== null) {
+      if (Date.now() - awaiting >= opts.pongTimeoutMs) opts.onDead()
       return
     }
+    pingId += 1
+    const ping: InspectClientMessage = { type: 'ping', id: pingId }
+    try {
+      opts.ws.send(JSON.stringify(ping))
+      opts.setAwaitingPongSince(Date.now())
+    } catch {
+      opts.onDead()
+    }
   }
+  opts.setTimer(setInterval(tick, opts.intervalMs))
 }
 
 function frameToEvent(

package/src/plugin/context.ts

@@ -13,6 +13,7 @@ export type CreatePluginContextOptions<TConfig> = {
   logger: PluginLogger
   permissions: PermissionService
   resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
+  hasGithubAppTokenResolver?: () => boolean
   spawnSubagent: SpawnSubagentFn
   isBooted: () => boolean
 }
@@ -30,7 +31,10 @@ export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TC
     config: opts.config,
     logger: opts.logger,
     permissions: opts.permissions,
-    github: { resolveTokenForRepo: opts.resolveGithubTokenForRepo ?? githubTokenUnavailable },
+    github: {
+      resolveTokenForRepo: opts.resolveGithubTokenForRepo ?? githubTokenUnavailable,
+      hasAppTokenResolver: opts.hasGithubAppTokenResolver ?? (() => false),
+    },
     spawnSubagent: async (name: string, payload?: unknown, options?: SpawnSubagentOptions) => {
       if (!opts.isBooted()) {
         throw new Error(

package/src/plugin/manager.ts

@@ -22,6 +22,7 @@ export type LoadPluginsOptions = {
   loadEntry?: LoadPluginEntryFn
   roles?: RolesConfig
   resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
+  hasGithubAppTokenResolver?: () => boolean
   // Bundled plugins resolved by the runtime (not from typeclaw.json). Loaded
   // before user-declared `entries` so a config block named after a bundled
   // plugin (e.g. "memory") is consumed by the bundled plugin, and so plugin-
@@ -104,6 +105,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
       logger,
       permissions,
       resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
+      hasGithubAppTokenResolver: opts.hasGithubAppTokenResolver,
       spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
       isBooted: () => booted,
     })

package/src/plugin/types.ts

@@ -280,6 +280,7 @@ export type PluginContext<TConfig = never> = {
 
 export type PluginGithubServices = {
   resolveTokenForRepo: ResolveGithubTokenForRepo
+  hasAppTokenResolver: () => boolean
 }
 
 export type PluginExports = {

package/src/run/index.ts

@@ -167,6 +167,7 @@ export async function startAgent({
     configsByName: pluginConfigsByName,
     bundled: BUNDLED_PLUGINS,
     resolveGithubTokenForRepo: githubTokenBridge.resolveTokenForRepo,
+    hasGithubAppTokenResolver: githubTokenBridge.hasAppTokenResolver,
     ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })