typeclaw 0.14.0 → 0.15.1

package/src/sandbox/build.ts

@@ -0,0 +1,128 @@
+import { SandboxPolicyError } from './errors'
+import {
+  DEFAULT_SANDBOX_ENV,
+  type SandboxCommandFilter,
+  type SandboxEnvPolicy,
+  type SandboxMount,
+  type SandboxPolicy,
+} from './policy'
+import { formatCommand } from './quote'
+
+export type SandboxedCommand = {
+  argv: string[]
+  commandString: string
+}
+
+// Pure: no I/O, no bwrap availability probe (that is `ensureBwrapAvailable`'s
+// job). Given a bash command and a policy, returns the bwrap-wrapped argv plus
+// a shell-quoted rendering of it. Knows nothing about subagents, origins, or
+// the agent runtime — a consumer resolves a policy from whatever context it
+// has and calls this. Throws SandboxPolicyError only when the consumer opted
+// into the command-filter knobs and the command violates them.
+export function buildSandboxedCommand(command: string, policy: SandboxPolicy = {}): SandboxedCommand {
+  if (policy.commandFilter !== undefined) {
+    applyCommandFilter(command, policy.commandFilter)
+  }
+  const argv = buildArgv(command, policy)
+  return { argv, commandString: formatCommand(argv) }
+}
+
+function buildArgv(command: string, policy: SandboxPolicy): string[] {
+  const bwrap = policy.bwrapPath ?? 'bwrap'
+  const argv: string[] = [bwrap, '--unshare-all']
+
+  if (policy.network === 'inherit') {
+    // --unshare-all already unshared the net namespace; --share-net rejoins
+    // the outer container's network. Other namespaces (user/pid/mount/ipc/
+    // uts/cgroup) stay unshared. Default ('none' / undefined) leaves the net
+    // namespace isolated — prompt-injected bash cannot exfiltrate over the
+    // network without the consumer explicitly opting in.
+    argv.push('--share-net')
+  }
+
+  const proc = policy.process ?? {}
+  if (proc.newSession !== false) {
+    // Drops the controlling terminal so the contained process cannot push
+    // input back into the agent's tty via TIOCSTI. Mandated by
+    // docs/internals/sandbox.mdx. Harmless for a one-shot `bash -c`.
+    argv.push('--new-session')
+  }
+  if (proc.dieWithParent !== false) {
+    argv.push('--die-with-parent')
+  }
+
+  argv.push('--clearenv')
+  for (const [key, value] of Object.entries(resolveEnv(policy.env))) {
+    argv.push('--setenv', key, value)
+  }
+
+  argv.push('--ro-bind', '/usr', '/usr', '--ro-bind', '/etc', '/etc', '--dev', '/dev', '--tmpfs', '/tmp')
+
+  if ((policy.proc ?? 'tmpfs') === 'tmpfs') {
+    // --tmpfs /proc, never --proc /proc (OrbStack's kernel blocks
+    // mount("proc",...) from user namespaces) and never --dev-bind /proc /proc
+    // (leaks the outer container's /proc/N/environ — including
+    // FIREWORKS_API_KEY — into the sandbox). See sandbox.mdx.
+    argv.push('--tmpfs', '/proc')
+  }
+
+  for (const mount of policy.mounts ?? []) {
+    appendMount(argv, mount)
+  }
+
+  if (policy.cwd !== undefined) {
+    argv.push('--chdir', policy.cwd)
+  }
+
+  argv.push('bash', '-c', command)
+  return argv
+}
+
+function appendMount(argv: string[], mount: SandboxMount): void {
+  switch (mount.type) {
+    case 'ro-bind':
+      argv.push('--ro-bind', mount.source, mount.dest)
+      return
+    case 'bind':
+      argv.push('--bind', mount.source, mount.dest)
+      return
+    case 'tmpfs':
+      argv.push('--tmpfs', mount.dest)
+      return
+    case 'dev':
+      argv.push('--dev', mount.dest)
+      return
+  }
+}
+
+function resolveEnv(env: SandboxEnvPolicy | undefined): Record<string, string> {
+  const resolved: Record<string, string> = { ...DEFAULT_SANDBOX_ENV, ...env?.set }
+  for (const key of env?.passthrough ?? []) {
+    const value = process.env[key]
+    if (value !== undefined) resolved[key] = value
+  }
+  return resolved
+}
+
+// Token-boundary match: the normalized command must equal a prefix exactly or
+// start with `prefix + ' '`. Substring matching would let `git-evil ...` slip
+// past a `git` prefix; this does not.
+const ALLOWLIST_WHITESPACE = /\s+/g
+const FORBIDDEN_METACHARS = /[;&|`$()<>\\\n]/
+
+function applyCommandFilter(command: string, filter: SandboxCommandFilter): void {
+  if (filter.rejectShellMetacharacters === true && FORBIDDEN_METACHARS.test(command)) {
+    throw new SandboxPolicyError(
+      'command contains a forbidden shell metacharacter. This policy only permits simple commands without ; & | ` $ ( ) < > \\ or newlines.',
+    )
+  }
+  if (filter.allowPrefixes !== undefined) {
+    const normalized = command.trim().replace(ALLOWLIST_WHITESPACE, ' ')
+    const matched = filter.allowPrefixes.some((p) => normalized === p || normalized.startsWith(`${p} `))
+    if (!matched) {
+      throw new SandboxPolicyError(
+        `command does not match any allowed prefix. Allowed: ${filter.allowPrefixes.join(', ')}`,
+      )
+    }
+  }
+}

package/src/sandbox/errors.ts

@@ -0,0 +1,20 @@
+export class SandboxUnavailableError extends Error {
+  override readonly name = 'SandboxUnavailableError'
+  constructor() {
+    super(
+      'sandbox unavailable: bwrap binary not found on PATH. Refusing to run a command that requires sandboxing without the kernel boundary in place.',
+    )
+  }
+}
+
+// Raised by the optional command-filter knobs (allowPrefixes,
+// rejectShellMetacharacters). These are consumer-opt-in restrictions layered
+// ABOVE the always-on kernel containment, so a rejection here is a policy
+// decision the consumer asked for — not a failure of the sandbox itself. The
+// message is phrased for the model to read and self-correct from.
+export class SandboxPolicyError extends Error {
+  override readonly name = 'SandboxPolicyError'
+  constructor(reason: string) {
+    super(`sandbox policy rejected command: ${reason}`)
+  }
+}

package/src/sandbox/index.ts

@@ -0,0 +1,14 @@
+export { buildSandboxedCommand, type SandboxedCommand } from './build'
+export { ensureBwrapAvailable } from './availability'
+export { formatCommand, shellQuote } from './quote'
+export { SandboxPolicyError, SandboxUnavailableError } from './errors'
+export {
+  DEFAULT_SANDBOX_ENV,
+  type SandboxCommandFilter,
+  type SandboxEnvPolicy,
+  type SandboxMount,
+  type SandboxNetwork,
+  type SandboxPolicy,
+  type SandboxProcessPolicy,
+  type SandboxProcStrategy,
+} from './policy'

package/src/sandbox/policy.ts

@@ -0,0 +1,47 @@
+export type SandboxMount =
+  | { type: 'ro-bind'; source: string; dest: string }
+  | { type: 'bind'; source: string; dest: string }
+  | { type: 'tmpfs'; dest: string }
+  | { type: 'dev'; dest: string }
+
+export type SandboxNetwork = 'none' | 'inherit'
+
+export type SandboxProcStrategy = 'tmpfs' | 'none'
+
+export type SandboxEnvPolicy = {
+  set?: Record<string, string>
+  passthrough?: string[]
+}
+
+export type SandboxCommandFilter = {
+  allowPrefixes?: string[]
+  rejectShellMetacharacters?: boolean
+}
+
+export type SandboxProcessPolicy = {
+  newSession?: boolean
+  dieWithParent?: boolean
+}
+
+export type SandboxPolicy = {
+  bwrapPath?: string
+  cwd?: string
+  mounts?: SandboxMount[]
+  network?: SandboxNetwork
+  env?: SandboxEnvPolicy
+  commandFilter?: SandboxCommandFilter
+  process?: SandboxProcessPolicy
+  proc?: SandboxProcStrategy
+}
+
+// The env the sandbox always re-introduces after `--clearenv`. Anything not
+// listed here (or explicitly named in `env.set` / `env.passthrough` by the
+// consumer) is invisible inside the sandbox. This is the load-bearing leak
+// guard: the container env holds FIREWORKS_API_KEY and GH_TOKEN, and env
+// inheritance is the single highest-risk exfil path for prompt-injected bash.
+// HOME points at /tmp because the sandbox mounts /tmp as a fresh tmpfs.
+export const DEFAULT_SANDBOX_ENV: Record<string, string> = {
+  PATH: '/usr/local/bin:/usr/bin:/bin',
+  HOME: '/tmp',
+  LANG: 'C.UTF-8',
+}

package/src/sandbox/quote.ts

@@ -0,0 +1,18 @@
+// POSIX shell quoting for rendering a bwrap argv array into a single
+// `bash -c`-safe string. Today's bash tool accepts a string `command` slot
+// (`mutableArgs.command`), so the sandbox primitive renders its canonical
+// argv into a quoted string the agent runtime can drop in unchanged.
+//
+// This is a local copy of the same helper in `src/update/index.ts`. It is
+// deliberately not promoted to a shared module yet: two call sites do not
+// justify the coupling, and this primitive is meant to stand alone with zero
+// imports from the rest of the tree. Promote to `src/shared/shell.ts` only
+// when a third independent consumer appears.
+export function shellQuote(arg: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg)) return arg
+  return `'${arg.replaceAll("'", "'\\''")}'`
+}
+
+export function formatCommand(argv: readonly string[]): string {
+  return argv.map(shellQuote).join(' ')
+}

package/src/server/index.ts

@@ -1121,7 +1121,9 @@ function handleInspectMessage(
 
   if (stream !== undefined && typeof msg.sinceMs === 'number') {
     for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'broadcast' } })) {
-      sendInspect(ws, { type: 'frame', ts: event.ts, payload: broadcastEventToFrame(event) })
+      const payload = broadcastEventToFrame(event)
+      if (!isFrameForWatchedSession(payload, msg.sessionId)) continue
+      sendInspect(ws, { type: 'frame', ts: event.ts, payload })
     }
     for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'cron' } })) {
       sendInspect(ws, {
@@ -1143,7 +1145,9 @@ function handleInspectMessage(
 
   if (stream !== undefined) {
     ws.data.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (event) => {
-      sendInspect(ws, { type: 'frame', ts: event.ts, payload: broadcastEventToFrame(event) })
+      const payload = broadcastEventToFrame(event)
+      if (!isFrameForWatchedSession(payload, msg.sessionId)) return
+      sendInspect(ws, { type: 'frame', ts: event.ts, payload })
     })
     ws.data.unsubCron = stream.subscribe({ target: { kind: 'cron' } }, (event) => {
       sendInspect(ws, {
@@ -1171,6 +1175,15 @@ function broadcastEventToFrame(event: StreamMessage): InspectFramePayload {
   }
 }
 
+// Channel inbounds are published as global broadcasts, so every inspect client
+// receives every session's inbounds. Drop the ones that don't belong to the
+// session being watched. Non-inbound broadcasts (subagent completions, cron,
+// tunnels) stay global — they carry no session identity here.
+function isFrameForWatchedSession(payload: InspectFramePayload, watchedSessionId: string): boolean {
+  if (payload.kind !== 'channel_inbound') return true
+  return payload.sessionId === watchedSessionId
+}
+
 function readChannelInboundBroadcast(payload: unknown): InspectFramePayload | null {
   if (typeof payload !== 'object' || payload === null) return null
   const p = payload as Record<string, unknown>
@@ -1191,6 +1204,7 @@ function readChannelInboundBroadcast(payload: unknown): InspectFramePayload | nu
   if (decision !== 'engage' && decision !== 'observe' && decision !== 'denied' && decision !== 'claim') return null
   return {
     kind: 'channel_inbound',
+    ...(typeof p.sessionId === 'string' ? { sessionId: p.sessionId } : {}),
     adapter: p.adapter,
     workspace: p.workspace,
     chat: p.chat,

package/src/shared/index.ts

@@ -24,10 +24,4 @@ export {
   type TunnelSnapshot,
 } from './protocol'
 
-export {
-  formatLocalDate,
-  formatLocalDateTime,
-  formatLocalWeekday,
-  type LocalWeekday,
-  resolveLocalTimezoneName,
-} from './local-time'
+export { formatLocalDate, formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } from './local-time'

package/src/shared/local-time.ts

@@ -37,34 +37,26 @@ export function resolveLocalTimezoneName(): string {
   }
 }
 
-// English + Korean weekday name pair for a given Date. The per-turn time
-// anchor renders both so the model has the answer to "what day is it"
-// without computing weekday-from-ISO-date — a step LLMs get wrong often
-// enough to matter, especially when answering in a non-English language.
-// Pre-computing in both candidate reply languages removes the arithmetic
-// step entirely instead of trusting the model to do it correctly each
-// turn.
+// English weekday name for a given Date. The per-turn time anchor renders
+// it so the model has the answer to "what day is it" without computing
+// weekday-from-ISO-date — a step LLMs get wrong often enough to matter.
+// Pre-computing the weekday removes the arithmetic step entirely instead
+// of trusting the model to do it correctly each turn. English only:
+// TypeClaw's users are global, so a single canonical language keeps the
+// anchor compact and lets each agent's SOUL.md decide its reply language.
 //
-// Uses Intl.DateTimeFormat with explicit locales. No `timeZone` option:
+// Uses Intl.DateTimeFormat with an explicit locale. No `timeZone` option:
 // the container's local clock is already host-local (the entrypoint
 // propagates TZ via `-e TZ=<host-tz>`), so the runtime's default zone is
-// the one the user sees. Both locales fall back to the hand-rolled
-// 7-entry lookup if Intl throws (no-tzdata, locked-down sandbox) — the
-// fallback names stay readable and never make the prefix empty.
+// the one the user sees. Falls back to the hand-rolled 7-entry lookup if
+// Intl throws (no-tzdata, locked-down sandbox) — the fallback names stay
+// readable and never make the prefix empty.
 const WEEKDAYS_EN = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] as const
-const WEEKDAYS_KO = ['일요일', '월요일', '화요일', '수요일', '목요일', '금요일', '토요일'] as const
 
-export type LocalWeekday = { en: string; ko: string }
-
-export function formatLocalWeekday(date: Date = new Date()): LocalWeekday {
-  const dow = date.getDay()
-  const fallback: LocalWeekday = { en: WEEKDAYS_EN[dow]!, ko: WEEKDAYS_KO[dow]! }
+export function formatLocalWeekday(date: Date = new Date()): string {
   try {
-    return {
-      en: new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(date),
-      ko: new Intl.DateTimeFormat('ko-KR', { weekday: 'long' }).format(date),
-    }
+    return new Intl.DateTimeFormat('en-US', { weekday: 'long' }).format(date)
   } catch {
-    return fallback
+    return WEEKDAYS_EN[date.getDay()]!
   }
 }

package/src/shared/protocol.ts

@@ -101,6 +101,10 @@ export type InspectFramePayload =
   // text — no batching, no compose-prompt wrapping.
   | {
       kind: 'channel_inbound'
+      // Channel session this inbound belongs to. Absent for denied/claim
+      // intercepts that fire before a session exists. The inspect server drops
+      // frames whose sessionId does not match the watched session.
+      sessionId?: string
       adapter: string
       workspace: string
       chat: string

package/src/skills/typeclaw-channel-kakaotalk/SKILL.md

@@ -11,14 +11,16 @@ This means **you are messaging as a person, not as a bot.** Other participants s
 
 ## What KakaoTalk does NOT support
 
-If you produce any of the following, KakaoTalk will render it literally and the recipient will see the raw markup:
-
-- **Bold / italic / strikethrough** — `**bold**` shows as `**bold**`. Drop the asterisks; emphasize with word choice or capitalization (sparingly).
-- **Headings** — `# H1`, `## H2`, `### H3` all render as raw `#` characters.
-- **Tables** — pipe-delimited tables become a wall of `|` characters. Use bullet lists or short prose paragraphs instead.
-- **Code fences** — ``` blocks render as raw backticks. For short snippets, paste the code inline. For long snippets, summarize and offer to send it via another channel.
-- **Inline code** — `` `foo` `` renders as `` `foo` ``. Just write `foo`.
-- **Links with display text** — `[label](url)` becomes the literal string. Send the bare URL on its own; the KakaoTalk client will auto-link it.
+KakaoTalk renders messages as plain text — it has no rich-text formatting. **Write plain text from the start.** The adapter strips common markdown as a safety net before sending (so an accidental `**bold**` won't leak literal asterisks), but treat that as a last-resort guard, not a license to write markdown: the strip removes _markers_, it cannot make formatting-dependent layouts like tables readable. Compose for a plain-text surface and you control the result; lean on the stripper and you get whatever falls out.
+
+Specifically, do not rely on any of the following — write the plain-text equivalent yourself:
+
+- **Bold / italic / strikethrough** — emphasize with word choice or capitalization (sparingly), not `**asterisks**`.
+- **Headings** — `# H1`, `## H2`, `### H3` carry no visual weight here. Use a short label line or just lead with the point.
+- **Tables** — the stripper cannot rescue a pipe-delimited table; it would collapse into an unreadable line. Use bullet lists or short prose paragraphs instead.
+- **Code fences** — for short snippets, paste the code inline as plain text. For long snippets, summarize and offer to send it via another channel.
+- **Inline code** — just write `foo`, no backticks.
+- **Links with display text** — send the bare URL on its own line; the KakaoTalk client auto-links it. (A `[label](url)` that slips through is reduced to `label (url)`, but a bare URL reads cleaner.)
 - **Mentions** — there is no `@user` syntax that the protocol surfaces. Address people by name in the message body.
 - **Threads / replies-with-quote** — every message is a top-level chat post. There is no per-message reply UI.
 - **Outbound stickers / emoticons** — the KakaoTalk sticker store requires desktop-app purchase flows that the SDK does not replicate. Inbound stickers ARE surfaced (see below), but you cannot send one. If the user asks for a sticker, acknowledge the limit and offer text.
@@ -106,4 +108,4 @@ The adapter drops every inbound where `event.author_id` equals the logged-in acc
 
 ## When you cannot answer in KakaoTalk
 
-If the user asks you to do something the adapter cannot do (render markdown, post in a thread, send a sticker), say so plainly. Files are fine — those go through `attachments[]` as described above — but markdown rendering, threading, and stickers are real limits. Acknowledge the limit instead of silently dropping the request.
+If the user asks you to do something the adapter cannot do (post in a thread, send a sticker, render a real table), say so plainly. Files are fine — those go through `attachments[]` as described above — but threading, stickers, and rich formatting are real limits. Markdown markers you emit get stripped to plain text automatically, so a stray `**` won't leak; the limit is that nothing renders as formatting, not that it crashes. Acknowledge the limit instead of silently dropping the request.

package/typeclaw.schema.json

@@ -32,6 +32,7 @@
               "anthropic/claude-haiku-4-5",
               "anthropic/claude-sonnet-4-6",
               "anthropic/claude-opus-4-7",
+              "anthropic/claude-opus-4-8",
               "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
               "zai/glm-4.5-air",
               "zai/glm-4.6",
@@ -59,6 +60,7 @@
                 "anthropic/claude-haiku-4-5",
                 "anthropic/claude-sonnet-4-6",
                 "anthropic/claude-opus-4-7",
+                "anthropic/claude-opus-4-8",
                 "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
                 "zai/glm-4.5-air",
                 "zai/glm-4.6",