npm - typeclaw - Versions diffs - 0.34.1 → 0.35.0 - Mend

typeclaw 0.34.1 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/package.json +3 -1
package/src/agent/plugin-tools.ts +53 -5
package/src/agent/provider-error.ts +10 -0
package/src/agent/session-origin.ts +26 -0
package/src/agent/tools/channel-disengage.ts +13 -9
package/src/bundled-plugins/github-cli-auth/gh-command.ts +124 -6
package/src/bundled-plugins/github-cli-auth/git-command.ts +172 -26
package/src/bundled-plugins/github-cli-auth/index.ts +46 -7
package/src/bundled-plugins/github-cli-auth/token-class.ts +13 -0
package/src/bundled-plugins/security/policies/prompt-injection.ts +33 -2
package/src/channels/adapters/github/inbound.ts +41 -3
package/src/channels/adapters/slack-bot.ts +17 -9
package/src/channels/continuation-willingness.ts +331 -0
package/src/channels/github-review-claim.ts +105 -0
package/src/channels/github-token-bridge.ts +7 -0
package/src/channels/router.ts +103 -24
package/src/cli/channel.ts +102 -11
package/src/cli/qr.ts +130 -0
package/src/config/config.ts +98 -2
package/src/container/start.ts +12 -0
package/src/init/dockerfile.ts +64 -0
package/src/init/line-auth.ts +8 -3
package/src/plugin/context.ts +5 -1
package/src/plugin/manager.ts +2 -0
package/src/plugin/types.ts +1 -0
package/src/run/index.ts +1 -0
package/src/sandbox/build.ts +27 -0
package/src/sandbox/index.ts +6 -0
package/src/sandbox/package-install.ts +23 -0
package/src/sandbox/policy.ts +31 -0
package/src/sandbox/symlinks.ts +34 -0
package/src/sandbox/writable-zones.ts +164 -4
package/src/skills/typeclaw-channel-github/SKILL.md +4 -2
package/src/skills/typeclaw-github-contributing/SKILL.md +124 -0
package/typeclaw.schema.json +32 -1

package/src/cli/qr.ts ADDED Viewed

@@ -0,0 +1,130 @@
+import { execFile } from 'node:child_process'
+import { writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import QRCode from 'qrcode'
+const execFileAsync = promisify(execFile)
+// The upstream LINE SDK's QR login hands back a raw auth URL
+// (https://line.me/R/au/q/...), which is not scannable on its own — the LINE
+// mobile app needs an actual QR image. This module renders that URL the way the
+// upstream `agent-line` CLI does: an HTML page opened in the browser plus, on a
+// TTY, an inline ASCII QR. Every external effect is best-effort so a non-TTY or
+// browserless host degrades to a machine-readable scan payload rather than
+// blocking login.
+export type QRPresentation = {
+  qrUrl: string
+  htmlPath: string | null
+  terminal: string | null
+  opened: boolean
+}
+export type DisplayQROptions = {
+  title: string
+  scanInstruction: string
+  brandColor?: string
+  isTty?: boolean
+  opener?: (filePath: string) => Promise<void>
+  tmpDir?: string
+  now?: () => number
+}
+export async function buildQRHtml(
+  url: string,
+  options: { title: string; scanInstruction: string; brandColor: string },
+): Promise<string> {
+  const svg = await QRCode.toString(url, { type: 'svg', margin: 2 })
+  const title = escapeHtml(options.title)
+  const instruction = escapeHtml(options.scanInstruction)
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>${title}</title>
+<style>body{display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:100vh;margin:0;font-family:-apple-system,system-ui,sans-serif;background:${options.brandColor}}
+.card{background:#fff;border-radius:16px;padding:40px;text-align:center;box-shadow:0 4px 24px rgba(0,0,0,.15)}
+h1{margin:0 0 8px;font-size:22px;color:#111}p{margin:0 0 24px;color:#666;font-size:14px}
+svg{width:280px;height:280px}</style></head>
+<body><div class="card"><h1>${title}</h1><p>${instruction}</p>${svg}</div></body></html>`
+}
+export async function renderTerminalQR(url: string): Promise<string> {
+  // 'L' error correction yields the fewest modules, so the QR stays small
+  // enough to scan from a terminal over SSH where screen real estate is the
+  // binding constraint. A short-lived auth URL doesn't need higher ECC.
+  return QRCode.toString(url, { type: 'terminal', small: true, errorCorrectionLevel: 'L' })
+}
+// Writes the QR HTML to a temp file and tries to open it in the default
+// browser, and (when on a TTY) renders an inline ASCII QR. Every external
+// effect is best-effort: a failure to write, open, or render degrades the
+// result rather than throwing, so login is never blocked by presentation.
+export async function displayQR(url: string, options: DisplayQROptions): Promise<QRPresentation> {
+  const brandColor = options.brandColor ?? '#06C755'
+  const isTty = options.isTty ?? process.stderr.isTTY === true
+  const now = options.now ?? Date.now
+  const dir = options.tmpDir ?? tmpdir()
+  const htmlPath = await writeQRHtmlFile(url, {
+    title: options.title,
+    scanInstruction: options.scanInstruction,
+    brandColor,
+    dir,
+    stamp: now(),
+  })
+  let opened = false
+  if (htmlPath !== null) {
+    const open = options.opener ?? openInBrowser
+    opened = await open(htmlPath).then(
+      () => true,
+      () => false,
+    )
+  }
+  const terminal = isTty ? await renderTerminalQR(url).catch(() => null) : null
+  return { qrUrl: url, htmlPath, terminal, opened }
+}
+async function writeQRHtmlFile(
+  url: string,
+  options: { title: string; scanInstruction: string; brandColor: string; dir: string; stamp: number },
+): Promise<string | null> {
+  try {
+    const html = await buildQRHtml(url, options)
+    const slug =
+      options.title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'qr'
+    const htmlPath = join(options.dir, `typeclaw-${slug}-${options.stamp}.html`)
+    await writeFile(htmlPath, html, { mode: 0o600 })
+    return htmlPath
+  } catch {
+    return null
+  }
+}
+async function openInBrowser(filePath: string): Promise<void> {
+  const platform = process.platform
+  if (platform === 'darwin') {
+    await execFileAsync('open', [filePath])
+    return
+  }
+  if (platform === 'win32') {
+    await execFileAsync('cmd', ['/c', 'start', '', filePath])
+    return
+  }
+  await execFileAsync('xdg-open', [filePath])
+}
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}

package/src/config/config.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/plugin/context.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/src/run/index.ts CHANGED Viewed

@@ -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 } : {}),
   })

package/src/sandbox/build.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { posix } from 'node:path'
 import { SandboxPolicyError } from './errors'
 import {
   DEFAULT_SANDBOX_ENV,
@@ -8,6 +10,8 @@ import {
 } from './policy'
 import { formatCommand } from './quote'
+const { dirname } = posix
 export type SandboxedCommand = {
   argv: string[]
   commandString: string
@@ -163,9 +167,11 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
     appendMount(argv, mount)
   }
+  appendWritableRoot(argv, policy)
   appendMasks(argv, policy)
   appendWritable(argv, policy)
   appendProtected(argv, policy)
+  appendSymlinks(argv, policy)
   if (policy.cwd !== undefined) {
     argv.push('--chdir', policy.cwd)
@@ -175,6 +181,15 @@ function buildArgv(command: string, policy: SandboxPolicy): string[] {
   return argv
 }
+// Renders BEFORE appendMasks so the broad RW root is overridden by the secret
+// masks and protected re-binds that follow (last-op-wins). See
+// SandboxWritableRootPolicy for the full ordering contract.
+function appendWritableRoot(argv: string[], policy: SandboxPolicy): void {
+  if (policy.writableRoot !== undefined) {
+    argv.push('--bind', policy.writableRoot.dir, policy.writableRoot.dir)
+  }
+}
 function appendMasks(argv: string[], policy: SandboxPolicy): void {
   for (const dir of policy.masks?.dirs ?? []) {
     argv.push('--tmpfs', dir)
@@ -202,6 +217,18 @@ function appendProtected(argv: string[], policy: SandboxPolicy): void {
   }
 }
+// Rendered after every bind (incl. the /tmp session bind in policy.mounts) so
+// last-op-wins keeps the symlink: a `/tmp/.foo` dest emitted before the /tmp
+// bind would be erased by it. `--dir` ensures the symlink's parent exists inside
+// the jail (the sandbox HOME dir may not be present after --clearenv tmpfs
+// scaffolding); `--symlink TARGET DEST` then creates `dest -> target`.
+function appendSymlinks(argv: string[], policy: SandboxPolicy): void {
+  for (const link of policy.symlinks ?? []) {
+    argv.push('--dir', dirname(link.dest))
+    argv.push('--symlink', link.target, link.dest)
+  }
+}
 function appendMount(argv: string[], mount: SandboxMount): void {
   switch (mount.type) {
     case 'ro-bind':

package/src/sandbox/index.ts CHANGED Viewed

@@ -11,12 +11,16 @@ export {
 } from './availability'
 export { resolveHiddenPaths, type HiddenPaths } from './hidden-paths'
 export {
+  resolvePackageInstallZones,
   resolveProtectedZones,
   resolveWritableZones,
   subtractMasked,
+  type PackageInstallZones,
   type ProtectedZones,
   type WritableZones,
 } from './writable-zones'
+export { resolveSandboxSymlinks, type SandboxSymlinkSpec } from './symlinks'
+export { isPackageInstallCommand } from './package-install'
 export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
 export { formatCommand, shellQuote } from './quote'
 export { SandboxPolicyError, SandboxUnavailableError } from './errors'
@@ -30,5 +34,7 @@ export {
   type SandboxProcessPolicy,
   type SandboxProcStrategy,
   type SandboxProtectedPolicy,
+  type SandboxSymlinkOp,
   type SandboxWritablePolicy,
+  type SandboxWritableRootPolicy,
 } from './policy'

package/src/sandbox/package-install.ts ADDED Viewed

@@ -0,0 +1,23 @@
+// Recognizes the narrow command class that earns the package-install sandbox
+// mode (RW project root). Deliberately conservative: a single standalone local
+// `bun add` / `bun install` / `bun i` with NO shell metacharacters, chaining,
+// redirects, or substitution. Anything fancier (`bun add x && rm -rf …`,
+// `bun add x; curl …`, a subshell, a pipe) falls back to the default ro-root
+// jail so the broad RW root can never be piggybacked onto an attacker-controlled
+// second command. Global installs (`-g` / `--global`) are excluded — the
+// bun-hygiene guard already blocks them and they write outside the jail anyway.
+const SHELL_METACHARACTERS = /[;&|`$()<>\\\n\r{}!*?[\]"']/
+const GLOBAL_FLAG = /^(-g|--global)$/
+export function isPackageInstallCommand(command: string): boolean {
+  if (SHELL_METACHARACTERS.test(command)) return false
+  const words = command.trim().split(/\s+/)
+  if (words[0] !== 'bun') return false
+  const subcommand = words[1]
+  if (subcommand !== 'add' && subcommand !== 'install' && subcommand !== 'i') return false
+  return !words.some((word) => GLOBAL_FLAG.test(word))
+}

package/src/sandbox/policy.ts CHANGED Viewed

@@ -83,6 +83,35 @@ export type SandboxProtectedPolicy = {
   files?: string[]
 }
+// Symlinks recreated INSIDE the jail so a CLI that reads a fixed path (e.g.
+// `$HOME/.metabase-cli`) resolves to a writable target under /agent. `dest` is
+// the symlink location resolved against the SANDBOX HOME (/tmp), `target` is the
+// absolute /agent path it points at. Rendered last (after the /tmp bind and all
+// writable binds) so last-op-wins keeps the symlink — a `/tmp/...` dest emitted
+// before the /tmp bind would be erased by it.
+export type SandboxSymlinkOp = {
+  target: string
+  dest: string
+}
+// A single RW bind of the project root, used ONLY by the package-install path
+// (recognized standalone `bun add`/`bun install` commands). `bun add` writes
+// node_modules/ AND a temp lockfile (`bun.lock.NNN.tmp`, atomically renamed)
+// directly under the root, so a file-level RW bind of `bun.lock` alone is
+// insufficient — Bun needs DIRECTORY write to create its temp file. The default
+// ro-root + narrow carve-out model can't express that, so this widens the root
+// to RW for that command class only.
+//
+// CRITICAL ordering: unlike `writable` (rendered AFTER masks), `writableRoot`
+// renders BEFORE masks so the broad RW root does not re-expose secrets. With
+// last-op-wins the chain is: ro-bind root → writableRoot (RW root) → masks
+// (re-hide .env/secrets.json/private dirs) → protected (re-RO node_modules/typeclaw,
+// packages, .agents/skills, .git/hooks, .git/config). Everything stays hidden or
+// EROFS except the dirs a dependency install legitimately needs to write.
+export type SandboxWritableRootPolicy = {
+  dir: string
+}
 export type SandboxPolicy = {
   bwrapPath?: string
   cwd?: string
@@ -95,9 +124,11 @@ export type SandboxPolicy = {
   // the builder stays pure.
   procSelfExe?: string
   mounts?: SandboxMount[]
+  writableRoot?: SandboxWritableRootPolicy
   masks?: SandboxMaskPolicy
   writable?: SandboxWritablePolicy
   protected?: SandboxProtectedPolicy
+  symlinks?: SandboxSymlinkOp[]
   network?: SandboxNetwork
   env?: SandboxEnvPolicy
   commandFilter?: SandboxCommandFilter

package/src/sandbox/symlinks.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import { posix } from 'node:path'
+import type { SandboxSymlinkOp } from './policy'
+const { isAbsolute, join, normalize } = posix
+export type SandboxSymlinkSpec = {
+  from: string
+  to: string
+}
+// Resolves config `sandbox.symlinks` into the in-jail `--symlink` ops the bwrap
+// builder consumes. `from` is the symlink LOCATION: a `~/`-prefixed `from` is
+// expanded against the SANDBOX HOME (`/tmp`, where the per-session tmp dir is
+// bound), NOT the container's real `/root` — inside the jail a CLI reading
+// `$HOME/.foo` looks under `/tmp`, so the symlink must live there. An absolute
+// `from` is used verbatim. `to` is resolved to the absolute /agent path the
+// symlink points at. Container paths are always POSIX, so this uses posix path
+// ops regardless of the dev-stage host OS.
+export function resolveSandboxSymlinks(
+  agentDir: string,
+  specs: readonly SandboxSymlinkSpec[],
+  sandboxHome: string,
+): SandboxSymlinkOp[] {
+  return specs.map((spec) => ({
+    target: join(agentDir, spec.to),
+    dest: resolveSymlinkDest(spec.from, sandboxHome),
+  }))
+}
+function resolveSymlinkDest(from: string, home: string): string {
+  if (from.startsWith('~/')) return join(home, from.slice(2))
+  return isAbsolute(from) ? normalize(from) : join(home, from)
+}