typeclaw 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -53,6 +53,7 @@
     "cron-parser": "^5.5.0",
     "jq-wasm": "^1.1.0-jq-1.8.1",
     "jsdom": "^29.0.2",
+    "qrcode": "^1.5.4",
     "turndown": "^7.2.4",
     "zod": "^4.3.6"
   },
@@ -61,6 +62,7 @@
     "@types/bun": "latest",
     "@types/jsdom": "^28.0.1",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/qrcode": "^1.5.6",
     "@types/sinonjs__fake-timers": "^15.0.1",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.18.1",

package/src/agent/plugin-tools.ts

@@ -23,7 +23,7 @@ import {
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
 } from '@/bundled-plugins/guard/policy'
-import { config } from '@/config/config'
+import { config, getSandboxWritablePathSpecs } from '@/config/config'
 import type { PermissionService } from '@/permissions/permissions'
 import type {
   BuiltinToolRef,
@@ -39,12 +39,16 @@ import {
   buildSandboxedCommand,
   canBindProcSafely,
   canMountRealProc,
+  DEFAULT_SANDBOX_ENV,
   ensureBwrapAvailable,
   ensureSessionTmpDir,
+  isPackageInstallCommand,
   mapVirtualTmpPath,
   resolveHiddenPaths,
+  resolvePackageInstallZones,
   resolveProcSelfExe,
   resolveProtectedZones,
+  resolveSandboxSymlinks,
   resolveWritableZones,
   type SandboxProcStrategy,
   subtractMasked,
@@ -590,7 +594,17 @@ async function applyBashSandbox(
   // (their masks are empty) and keep full unsandboxed access. subtractMasked
   // drops any writable zone masked for this role so an RW bind never re-exposes a
   // hidden path (e.g. a guest's masked workspace/).
-  const writable = subtractMasked(await resolveWritableZones(agentDir), { dirs, files })
+  // config.sandbox.* is read from the BOOT-TIME snapshot, not getConfig():
+  // sandbox is restart-required, so the writable surface AND the in-jail symlinks
+  // must stay coherent with the boot-time bwrap/capability decisions and with the
+  // entrypoint shim's symlink creation (same contract as resolveProcStrategy's
+  // read of config.sandbox.realProc below). getSandboxWritablePathSpecs folds
+  // every sandbox.symlinks[].to into the writable set so the symlink target is
+  // writable without the operator also listing it under writablePaths.
+  const writable = subtractMasked(await resolveWritableZones(agentDir, getSandboxWritablePathSpecs(config)), {
+    dirs,
+    files,
+  })
   // subtractMasked again on the protected set: a protected RO bind renders after
   // the masks (last-op-wins), so an unfiltered protected path nested under a
   // masked dir (e.g. a guest's workspace/ when core.hooksPath=workspace/hooks)
@@ -599,6 +613,31 @@ async function applyBashSandbox(
   const protectedZones = writable.dirs.includes(join(agentDir, '.git'))
     ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
     : { dirs: [], files: [] }
+  // A recognized standalone `bun add`/`bun install` needs DIRECTORY write at the
+  // root (node_modules/ + temp lockfile), which the narrow carve-out model can't
+  // grant. Widen to an RW root for that command class only, then re-hide secrets
+  // (masks) and re-RO the executable surfaces (resolvePackageInstallZones) on top
+  // — subtractMasked drops any protected path a mask already hides so the RW root
+  // never re-exposes it. The default jail's `writable`/`protected` are skipped
+  // here: writableRoot supersedes them for this command, and the same masks +
+  // package-install protected set cover the confidentiality and escalation
+  // boundaries.
+  const packageInstall = isPackageInstallCommand(command)
+    ? subtractMaskedProtected(await resolvePackageInstallZones(agentDir), { dirs, files })
+    : undefined
+
+  // Only emit an in-jail symlink for a target that actually survived as a
+  // writable dir: a symlink to a target that was dropped (missing, masked for
+  // this role, or filtered by the writable-zone guardrails) would dangle onto an
+  // EROFS/hidden path. Resolve `from` against the SANDBOX HOME (/tmp), where the
+  // per-session tmp dir is bound — NOT the container's real /root, which the jail
+  // never sees. The entrypoint shim handles the real-/root symlink for the
+  // unsandboxed (trusted/owner) path.
+  const writableDirSet = new Set(writable.dirs)
+  const sandboxHome = DEFAULT_SANDBOX_ENV.HOME ?? '/tmp'
+  const symlinks = resolveSandboxSymlinks(agentDir, config.sandbox.symlinks, sandboxHome).filter((op) =>
+    writableDirSet.has(op.target),
+  )
   // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
   // it would never reach the sandboxed process (the non-sandboxed spawnHook
   // path does not run when the command is rewritten to a bwrap invocation).
@@ -608,9 +647,10 @@ async function applyBashSandbox(
       { type: 'ro-bind', source: agentDir, dest: agentDir },
       { type: 'bind', source: sessionTmp, dest: '/tmp' },
     ],
-    masks: { dirs, files },
-    writable,
-    protected: protectedZones,
+    ...(packageInstall !== undefined
+      ? { writableRoot: { dir: packageInstall.root }, masks: { dirs, files }, protected: packageInstall.protected }
+      : { masks: { dirs, files }, writable, protected: protectedZones }),
+    symlinks,
     network: 'inherit',
     cwd: agentDir,
     proc,
@@ -620,6 +660,14 @@ async function applyBashSandbox(
   mutableArgs.command = commandString
 }
 
+function subtractMaskedProtected(
+  zones: { root: string; protected: { dirs: string[]; files: string[] } },
+  masked: { dirs: string[]; files: string[] },
+): { root: string; protected: { dirs: string[]; files: string[] } } {
+  const filtered = subtractMasked(zones.protected, masked)
+  return { root: zones.root, protected: filtered }
+}
+
 // Picks the /proc strategy for a sandboxed bash call. The branch order is:
 // 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
 // the kernel permits the mount (canMountRealProc) — it adds PID isolation but

package/src/agent/provider-error.ts

@@ -31,6 +31,16 @@ const GENERIC_SAFE_NOTICE = 'The upstream LLM provider failed. Operators can che
 // specific: a miss falls through to GENERIC_SAFE_NOTICE rather than echoing raw
 // text, so adding a new class is opt-in and never widens what we expose.
 const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
+  {
+    // Auth failure: the provider rejected our credentials (bad/expired/missing
+    // API key). Matched first because a 401 body can also mention "account",
+    // which would otherwise fall into the billing class below. The safe text
+    // names the operator action (check the API key) without echoing the raw
+    // error, whose body can carry a Bearer token.
+    match:
+      /\b(401|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|authentication failed|invalid bearer)\b/i,
+    safe: 'The upstream LLM provider rejected the request as unauthorized. Operators should check the provider API key configuration and `typeclaw logs`.',
+  },
   {
     match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
     safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',

package/src/agent/session-origin.ts

@@ -370,6 +370,17 @@ function renderChannelOrigin(
       'want to signal acknowledgment explicitly, use `channel_react({ emoji })`',
       '(it reacts, it does not comment) — never a text ack. Reserve `channel_reply`',
       'for the actual substantive answer.',
+      '',
+      '**A formal review verdict already IS the comment — never post it twice.**',
+      'When you submit a PR review (`APPROVE`, `REQUEST_CHANGES`, or `COMMENT`),',
+      'the review body renders on the PR as a comment, visually identical to a',
+      'plain comment. So put your entire verdict — the "approved", the praise,',
+      'the findings — in that review body. Do NOT then post the same (or',
+      'paraphrased) text again as a separate `channel_reply` / `gh pr comment`:',
+      'that is a visible duplicate, the exact same words landing twice seconds',
+      'apart. One verdict, one surface. If you have already submitted the review,',
+      'the PR has heard you — `skip_response({ reason: "verdict posted as review" })`',
+      'instead of echoing it as a comment.',
     )
   }
 
@@ -442,6 +453,21 @@ function renderChannelOrigin(
     '  natural terminal action for the turn. Pair it with `skip_response` when',
     '  you also want to stay silent this turn.',
     '',
+    '  **An explicit quiet command is a direct order to call this tool.** When',
+    '  someone tells you to stop — e.g. "disengage", "be quiet", "stop replying",',
+    '  "stop", "back off", "stay out of this", "shush", or "조용" / "조용히 해" /',
+    '  "그만" / "빠져" / "тихо" / "tais-toi" / "cállate" / "ruhig" / "黙って" /',
+    '  "安静" in any language — you MUST call `channel_disengage` that same turn.',
+    '  Posting a `channel_reply` like "ok, I\'ll be quiet" is NOT enough on its',
+    '  own: a reply alone re-grants the very stickiness they asked you to drop,',
+    '  so without the `channel_disengage` call you stay engaged and keep getting',
+    '  pulled back in — exactly what they told you to stop. The acknowledgement',
+    '  does not disengage you; the tool call does. If you ack, ack FIRST with',
+    '  `channel_reply`, THEN call `channel_disengage`; if you would rather go',
+    '  quiet without a word, call `channel_disengage` alone (optionally with',
+    '  `skip_response`). Match intent, not exact words: any clear request to',
+    '  stop participating counts, whatever the phrasing or language.',
+    '',
     '**Every user-facing sentence goes through `channel_reply`.** Narrating in',
     'plain text — "bumping to 16x now", "let me check that" — does NOT reach the',
     'user; it is invisible. If you want the user to see it, it is a',

package/src/agent/tools/channel-disengage.ts

@@ -34,15 +34,19 @@ export function createChannelDisengageTool({ router, origin }: CreateChannelDise
     name: 'channel_disengage',
     label: 'Channel Disengage',
     description:
-      'Stop auto-engaging on follow-up messages in THIS channel/thread. While engaged you ' +
-      "keep replying to a participant's next message without an @mention, and that " +
-      'engagement is renewed every time you reply — so in a group you can get stuck ' +
-      'answering turn after turn even after someone tells you to stop. Call this when a ' +
-      'human or peer bot asks you to be quiet / stop replying, or when you realize you are ' +
-      'in a redundant loop. After disengaging, you only re-engage in this conversation when ' +
-      'explicitly addressed again (mention, reply, or DM). This does not send any message ' +
-      'and does not affect other channels. Pair it with skip_response when you also want to ' +
-      'stay silent on the current turn.',
+      'Stop auto-engaging on follow-up messages in THIS channel/thread. Call this the moment ' +
+      'a human or peer bot tells you to stop — "disengage", "be quiet", "stop replying", ' +
+      '"stop", "back off", or the same in any language (e.g. "조용", "그만", "黙って", ' +
+      '"tais-toi", "cállate"). While engaged you keep replying to a participant\'s next ' +
+      'message without an @mention, and that engagement is renewed every time you reply — so ' +
+      'in a group you can get stuck answering turn after turn even after someone tells you to ' +
+      'stop. A reply like "ok, I will be quiet" does NOT disengage you; it re-grants the ' +
+      'stickiness they asked you to drop. Only THIS tool drops it. Also call it when you ' +
+      'notice you are in a redundant loop. After disengaging, you only re-engage in this ' +
+      'conversation when explicitly addressed again (mention, reply, or DM). This does not ' +
+      'send any message and does not affect other channels. If you want to acknowledge first, ' +
+      'send the channel_reply BEFORE this call. Pair it with skip_response when you also want ' +
+      'to stay silent on the current turn.',
     parameters: Type.Object({}),
 
     async execute() {

package/src/bundled-plugins/github-cli-auth/gh-command.ts

@@ -416,8 +416,7 @@ function stripRepoFlagFromCommand(command: string): string {
   while (i < command.length) {
     const ch = command[i] as string
     if (ch === '"' || ch === "'") {
-      const close = command.indexOf(ch, i + 1)
-      const endQuote = close === -1 ? command.length : close
+      const endQuote = findClosingQuote(command, i)
       out += command.slice(i, endQuote + 1)
       i = endQuote + 1
       continue
@@ -436,6 +435,24 @@ function stripRepoFlagFromCommand(command: string): string {
   return out
 }
 
+// Index of the quote that closes the one at `open`. Double quotes honor `\"` as
+// a literal (bash processes backslash escapes inside "..."), so a `-R o/r` buried
+// in a `-f body="{\"x\":\"-R o/r\"}"` value is not mistaken for an unquoted flag.
+// Single quotes take everything literally — no escapes — so the next `'` closes.
+// Unterminated quote returns the last index (strip nothing past it).
+function findClosingQuote(command: string, open: number): number {
+  const quote = command[open]
+  for (let i = open + 1; i < command.length; i++) {
+    const ch = command[i]
+    if (quote === '"' && ch === '\\') {
+      i += 1
+      continue
+    }
+    if (ch === quote) return i
+  }
+  return command.length - 1
+}
+
 // If `command` has an unquoted `-R`/`--repo` repo-flag token starting at `start`
 // (at a word boundary), returns the index just past the flag and its value;
 // otherwise null. Handles `-R o/r`, `--repo o/r`, `-R=o/r`, `--repo=o/r`.
@@ -447,10 +464,16 @@ function matchRepoFlagAt(command: string, start: number): number | null {
     if (!command.startsWith(flag, start)) continue
     let i = start + flag.length
     const sep = command[i]
+    // Both value forms validate the slug before stripping: the flag is only a
+    // repo flag if its value parses as owner/repo. Without this, the `=` form
+    // could strip a non-slug value the detection path would have rejected,
+    // diverging detection from rewrite.
     if (sep === '=') {
-      i += 1
-      while (i < command.length && command[i] !== ' ' && command[i] !== '\t') i += 1
-      return i
+      const valueStart = i + 1
+      let j = valueStart
+      while (j < command.length && command[j] !== ' ' && command[j] !== '\t') j += 1
+      if (!isRepoSlug(command.slice(valueStart, j))) return null
+      return j
     }
     if (sep === ' ' || sep === '\t') {
       let j = i
@@ -493,9 +516,20 @@ function classifyGhApiSegment(args: readonly string[]): GhSegmentDecision {
   const flagRepo = extractRepoFlag(args)
 
   if (pathRepos.length > 0) {
-    if (flagRepo !== null && !pathRepos.includes(flagRepo)) {
+    // Check EVERY repo flag, not just the first: the strip removes all of them,
+    // so a single non-redundant flag anywhere is a mint-for-X-hit-Y attempt and
+    // must block even when an earlier flag matches the path and would otherwise
+    // mask it.
+    const flagRepos = extractAllRepoFlags(args)
+    if (flagRepos.some((slug) => !pathRepos.includes(slug))) {
       return { kind: 'block', reason: API_REPO_CONFLICT_REASON }
     }
+    // Every `-R` here is redundant: it matches the repo already named in the
+    // literal path, which is authoritative. `gh api` rejects `-R` outright, so
+    // strip the flag rather than let `gh` fail with "unknown shorthand flag".
+    // Distinct from graphql (no path, -R IS the hint) — here the path mints the
+    // token and the flag is pure noise we remove for syntax.
+    if (flagRepos.length > 0) return { kind: 'inject', repoSlugs: pathRepos, stripRepoFlag: true }
     return { kind: 'inject', repoSlugs: pathRepos }
   }
 
@@ -519,6 +553,67 @@ function isGraphqlEndpoint(args: readonly string[]): boolean {
   return findApiEndpoint(args) === 'graphql'
 }
 
+export type GhAuthEnv = {
+  GH_TOKEN?: string | undefined
+  GITHUB_TOKEN?: string | undefined
+}
+
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/
+
+// The effective token `gh` would use for EACH `gh api` invocation that targets the
+// authenticated-user endpoint (`/user`, `user`, or a `/user/...` descendant). The
+// caller classifies each: an App installation token is not a user identity, so
+// GitHub rejects `/user` for it (token-CLASS mismatch, not an auth failure) — but a
+// PAT IS a user identity and works, so the guard must respect a command-local
+// `GH_TOKEN=…`/`GITHUB_TOKEN=…` override on that invocation, not just process env.
+// Precedence mirrors gh: local GH_TOKEN > process GH_TOKEN > local GITHUB_TOKEN >
+// process GITHUB_TOKEN. Narrow endpoint scope: `/users/{username}`, `/meta`,
+// `/rate_limit` are not user-identity endpoints and never match.
+export function effectiveGhTokensForAuthenticatedUserEndpoint(
+  command: string,
+  env: GhAuthEnv,
+): Array<string | undefined> {
+  const tokens = tokenize(command)
+  const ghStarts = findGhInvocations(tokens)
+  const result: Array<string | undefined> = []
+  for (let i = 0; i < ghStarts.length; i++) {
+    const start = ghStarts[i] as number
+    const end = ghStarts[i + 1] ?? tokens.length
+    if (!isAuthenticatedUserEndpointArgs(tokens.slice(start + 1, end))) continue
+    result.push(effectiveGhTokenForInvocation(tokens, start, env))
+  }
+  return result
+}
+
+export function usesGhApiAuthenticatedUserEndpoint(command: string): boolean {
+  return effectiveGhTokensForAuthenticatedUserEndpoint(command, {}).length > 0
+}
+
+function isAuthenticatedUserEndpointArgs(args: readonly string[]): boolean {
+  if (args[0] !== 'api') return false
+  const endpoint = findApiEndpoint(args)
+  if (endpoint === null) return false
+  const normalized = endpoint.startsWith('/') ? endpoint.slice(1) : endpoint
+  return normalized === 'user' || normalized.startsWith('user/')
+}
+
+// Walks the contiguous `VAR=val` assignments immediately before `gh` (the same
+// shape findGhInvocations skips) and applies gh's token precedence over env.
+function effectiveGhTokenForInvocation(tokens: readonly string[], ghStart: number, env: GhAuthEnv): string | undefined {
+  const local: GhAuthEnv = {}
+  for (let i = ghStart - 1; i >= 0 && ENV_ASSIGNMENT_RE.test(tokens[i] as string); i--) {
+    const token = tokens[i] as string
+    const name = token.slice(0, token.indexOf('='))
+    const value = token.slice(token.indexOf('=') + 1)
+    // Iterating right-to-left, so only record the first (leftmost wins on dup).
+    if (name === 'GH_TOKEN' && local.GH_TOKEN === undefined) local.GH_TOKEN = value
+    if (name === 'GITHUB_TOKEN' && local.GITHUB_TOKEN === undefined) local.GITHUB_TOKEN = value
+  }
+  const ghToken = local.GH_TOKEN ?? env.GH_TOKEN
+  if (ghToken !== undefined && ghToken !== '') return ghToken
+  return local.GITHUB_TOKEN ?? env.GITHUB_TOKEN
+}
+
 function findGhInvocations(tokens: readonly string[]): number[] {
   const starts: number[] = []
   for (let i = 0; i < tokens.length; i++) {
@@ -565,6 +660,29 @@ function extractRepoFlag(args: readonly string[]): string | null {
   return null
 }
 
+// Every valid `-R`/`--repo` slug in `args`, not just the first. The strip removes
+// ALL unquoted repo flags, so the conflict check must see ALL of them: a command
+// like `... -R path/repo -R victim/private` is a mint-for-X-hit-Y attempt where
+// the redundant first flag would otherwise mask the malicious second one.
+function extractAllRepoFlags(args: readonly string[]): string[] {
+  const slugs: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === undefined) continue
+    if (arg === '-R' || arg === '--repo') {
+      const value = args[i + 1]
+      if (value !== undefined && isRepoSlug(value)) slugs.push(value)
+    } else if (arg.startsWith('--repo=')) {
+      const value = arg.slice('--repo='.length)
+      if (isRepoSlug(value)) slugs.push(value)
+    } else if (arg.startsWith('-R=')) {
+      const value = arg.slice('-R='.length)
+      if (isRepoSlug(value)) slugs.push(value)
+    }
+  }
+  return slugs
+}
+
 // `gh api` flags that consume the FOLLOWING token as their value. The endpoint
 // is the first positional arg that is neither a flag nor a flag's value; only
 // THAT arg is parsed for owner/repo. Scanning every arg (as before) would let a

package/src/bundled-plugins/github-cli-auth/git-askpass.ts

@@ -0,0 +1,65 @@
+import { randomBytes } from 'node:crypto'
+import { chmod, mkdir, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+// A GIT_ASKPASS helper git invokes for username/password prompts. The token
+// rides in TYPECLAW_GIT_TOKEN (env, via the bash env overlay), NEVER in argv or
+// git config — so it cannot leak through process listings, logs, or .git/config.
+// The script contents are constant and secret-free; only the env value is secret.
+//
+// Host-scoped: git's prompt is `Username for 'https://github.com': ` etc. We
+// answer ONLY when the prompt names github.com; for any other host (e.g. one an
+// `insteadOf`/`pushurl` rewrite redirected to) we exit non-zero WITHOUT printing
+// the token, so a redirect can never exfiltrate it. The analyzer already blocks
+// the known redirect vectors; this is defense-in-depth at the credential edge.
+// The host match is on \`//github.com/\` and \`//github.com'\` (git wraps the URL
+// in quotes: \`Password for 'https://github.com': \`) so it cannot be fooled by
+// \`evil-github.com\` or \`github.com.evil/\`.
+const ASKPASS_SCRIPT = `#!/bin/sh
+case "$1" in
+  *//github.com/*|*//github.com\\'*) : ;;
+  *) exit 1 ;;
+esac
+case "$1" in
+  *Username*) printf '%s\\n' 'x-access-token' ;;
+  *) printf '%s\\n' "$TYPECLAW_GIT_TOKEN" ;;
+esac
+`
+
+// /usr is --ro-bind mounted into the per-tool bwrap sandbox (src/sandbox/build.ts),
+// so a helper here is readable by sandboxed bash; the per-session /tmp bind is not
+// a stable path. TYPECLAW_GIT_ASKPASS_PATH overrides it for tests/CI, which
+// cannot write under /usr.
+const DEFAULT_ASKPASS_PATH = '/usr/local/bin/typeclaw-git-askpass'
+
+function defaultPath(): string {
+  const override = process.env.TYPECLAW_GIT_ASKPASS_PATH
+  return override !== undefined && override !== '' ? override : DEFAULT_ASKPASS_PATH
+}
+
+let ensurePromise: Promise<string> | null = null
+
+export function resetGitAskPassHelperForTests(): void {
+  ensurePromise = null
+}
+
+// Writes the helper once per process (idempotent, race-safe via the shared
+// promise) and returns its absolute path. The temp name is unpredictable and
+// opened with `wx` (exclusive create, fails on an existing file/symlink) so a
+// planted symlink cannot redirect the write; then atomically renamed so a
+// concurrent reader never sees a partial file.
+export function ensureGitAskPassHelper(path: string = defaultPath()): Promise<string> {
+  if (ensurePromise !== null) return ensurePromise
+  ensurePromise = (async () => {
+    await mkdir(dirname(path), { recursive: true })
+    const tmp = join(dirname(path), `.typeclaw-git-askpass.${randomBytes(8).toString('hex')}.tmp`)
+    await writeFile(tmp, ASKPASS_SCRIPT, { mode: 0o755, flag: 'wx' })
+    await chmod(tmp, 0o755)
+    await rename(tmp, path)
+    return path
+  })().catch((err) => {
+    ensurePromise = null
+    throw err
+  })
+  return ensurePromise
+}