typeclaw 0.18.0 → 0.20.0

package/src/cli/ui.ts

@@ -152,6 +152,12 @@ export const SLACK_APP_MANIFEST = {
     // so a misconfigured (non-Socket-Mode) deployment fails fast rather
     // than silently routing real slash invocations to a third-party URL.
     slash_commands: [
+      {
+        command: '/help',
+        description: 'List available commands',
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
       {
         command: '/stop',
         description: 'Abort the current turn in this channel',

package/src/commands/index.ts

@@ -1,8 +1,27 @@
-export type CommandHandler<Context> = (context: Context, command: ParsedCommand) => Promise<void> | void
+// Returning nothing keeps the void contract — the dispatch layer then falls
+// back to its static per-result-kind reply. A `reply` lets dynamic commands
+// (/help) surface text the dispatcher could not have known statically.
+export type CommandHandlerResult = void | { reply?: string }
+
+export type CommandHandler<Context> = (
+  context: Context,
+  command: ParsedCommand,
+) => Promise<CommandHandlerResult> | CommandHandlerResult
+
+// `permission` and `requiresLiveSession` are command-level policy the dispatch
+// layer (the channel router) enforces. They live on the command, not the
+// dispatcher, so a new command declares its own requirements in one place:
+// 'session.control' + requiresLiveSession:true is the control-command default
+// (/stop); 'none' + requiresLiveSession:false is the informational default
+// (/help). Both are optional so plain registries (tests, TUI) need not care.
+export type CommandPermission = 'none' | 'session.control'
 
 export type Command<Context> = {
   name: string
   aliases?: readonly string[]
+  description: string
+  permission?: CommandPermission
+  requiresLiveSession?: boolean
   handler: CommandHandler<Context>
 }
 
@@ -11,14 +30,27 @@ export type ParsedCommand = {
   args: string
 }
 
+// Read-only view of a registered command, used to generate help text from the
+// registry so the listing can never drift from the actual command set. Aliases
+// are folded into the canonical entry rather than listed as separate commands.
+export type CommandInfo = {
+  name: string
+  aliases: readonly string[]
+  description: string
+  permission: CommandPermission
+  requiresLiveSession: boolean
+}
+
 export type CommandResult =
   | { kind: 'not-command' }
   | { kind: 'unknown-command'; name: string }
-  | { kind: 'handled'; name: string }
+  | { kind: 'handled'; name: string; reply?: string }
 
 export type CommandRegistry<Context> = {
   parse: (text: string) => ParsedCommand | null
   has: (name: string) => boolean
+  get: (name: string) => CommandInfo | undefined
+  list: () => readonly CommandInfo[]
   execute: (text: string, context: Context) => Promise<CommandResult>
 }
 
@@ -33,16 +65,34 @@ export function createCommandRegistry<Context>(commands: readonly Command<Contex
     }
   }
 
+  const info = (command: Command<Context>): CommandInfo => ({
+    name: command.name,
+    aliases: command.aliases ?? [],
+    description: command.description,
+    permission: command.permission ?? 'session.control',
+    requiresLiveSession: command.requiresLiveSession ?? true,
+  })
+
   return {
     parse: parseCommand,
     has: (name) => byName.has(name.toLowerCase()),
+    get: (name) => {
+      const command = byName.get(name.toLowerCase())
+      return command ? info(command) : undefined
+    },
+    // Canonical commands only, in declaration order. Aliases resolve to the
+    // same Command object, so de-dupe by identity to avoid duplicate rows.
+    list: () => commands.map(info),
     execute: async (text, context) => {
       const parsed = parseCommand(text)
       if (parsed === null) return { kind: 'not-command' }
       const command = byName.get(parsed.name)
       if (!command) return { kind: 'unknown-command', name: parsed.name }
-      await command.handler(context, parsed)
-      return { kind: 'handled', name: command.name }
+      const result = await command.handler(context, parsed)
+      const reply = result?.reply
+      return reply !== undefined
+        ? { kind: 'handled', name: command.name, reply }
+        : { kind: 'handled', name: command.name }
     },
   }
 }

package/src/init/dockerfile.ts

@@ -50,6 +50,16 @@ export type BuildDockerfileOptions = {
 // flag the seccomp default profile blocks `unshare(CLONE_NEWUSER)` and bwrap
 // fails at startup. The two changes are load-bearing together — do not drop
 // one without the other.
+//
+// `jq` is in baseline (not behind a toggle) so it is available to the
+// per-tool bwrap sandbox that wraps agent bash calls. The sandbox only
+// `--ro-bind`s `/usr` + `/bin` from the container (see `src/sandbox/build.ts`),
+// so a binary that is not in the base image is invisible inside the sandbox —
+// there is no per-call install path. JSON munging in one-shot read-only
+// pipelines (`curl ... | jq`, `cat foo.json | jq`) is a baseline expectation
+// for the explorer/reviewer/scout subagents, whose prompts already advertise
+// `jq` as an available pipeline tool, so it ships unconditionally rather than
+// as an opt-in toggle.
 const BASELINE_APT_PACKAGES = [
   'git',
   'ca-certificates',
@@ -58,6 +68,7 @@ const BASELINE_APT_PACKAGES = [
   'iptables',
   'util-linux',
   'bubblewrap',
+  'jq',
 ] as const
 
 // curl-impersonate is the only currently-working way to query DuckDuckGo from
@@ -87,6 +98,33 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
+// yq is the YAML/JSON/XML processor the `explorer` and `reviewer` subagent
+// prompts advertise alongside `jq` as a sanctioned one-shot read-only
+// pipeline tool (`... | yq`). Like `jq` (shipped in baseline), a binary that
+// is not in the container base image is invisible inside the per-tool bwrap
+// sandbox that wraps agent bash calls — the sandbox only `--ro-bind`s `/usr`
+// + `/bin` from the container, and there is no per-call install path. So `yq`
+// ships unconditionally, same rationale as `jq`/`bubblewrap`/`util-linux`.
+//
+// This is Mike Farah's Go `yq` (https://github.com/mikefarah/yq), NOT the
+// Python jq-wrapper of the same name in Debian's `yq` apt package. The
+// prompts pair `yq` with `jq` for jq-style expression pipelines, which is
+// Farah's syntax — the Python tool's CLI is incompatible. Distributed as a
+// per-arch static binary (no apt package on trixie for the Go variant), so
+// it follows the pinned-version + per-arch SHA256 + `sha256sum -c` pattern of
+// curl-impersonate and cloudflared rather than the apt baseline list.
+//
+// To bump: pick a release from https://github.com/mikefarah/yq/releases,
+// then for each arch download yq_linux_<arch> and `shasum -a 256` it (or read
+// the SHA-256 column from the release's `checksums` file, cross-indexed via
+// `checksums_hashes_order`). Update all three constants in the same commit;
+// the build fails loudly at `sha256sum -c` on a mismatch. Version literal is
+// the release tag exactly as it appears on GitHub (with `v` prefix).
+export const YQ_VERSION = 'v4.53.2'
+export const YQ_SHA256_AMD64 = 'd56bf5c6819e8e696340c312bd70f849dc1678a7cda9c2ad63eebd906371d56b'
+export const YQ_SHA256_ARM64 = '03061b2a50c7a498de2bbb92d7cb078ce433011f085a4994117c2726be4106ea'
+export const YQ_RELEASE_URL_BASE = 'https://github.com/mikefarah/yq/releases/download'
+
 // cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
 // SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
 // all three constants in the same commit, and the build fails loudly at
@@ -1177,6 +1215,8 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
+${LAYER_2_6_YQ}
+
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1256,6 +1296,8 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
+${LAYER_2_6_YQ}
+
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1310,6 +1352,24 @@ RUN ARCH_TARBALL="$(if [ "$TARGETARCH" = "arm64" ]; then echo aarch64-linux-gnu;
  && rm curl-impersonate.tar.gz \\
  && /usr/local/bin/curl_${CURL_IMPERSONATE_PROFILE} --version > /dev/null`
 
+// Layer 2.6: install pinned Mike Farah `yq` (Go) so the explorer/reviewer
+// subagents' advertised `... | yq` pipelines resolve inside the bwrap
+// sandbox. Unconditional like the apt baseline (jq, git): a missing binary
+// is invisible to sandboxed bash, so this is not behind a toggle. Placed
+// after curl-impersonate (curl + ca-certificates from baseline guaranteed
+// present) and before agent-browser so an agent-browser bump doesn't
+// invalidate this layer. See the YQ_* constants above for the bump recipe
+// and the Go-vs-Python `yq` rationale.
+const LAYER_2_6_YQ = `# Layer 2.6 (stable): pinned Mike Farah yq for sandbox-visible YAML pipelines.
+RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \\
+ && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${YQ_SHA256_ARM64}; else echo ${YQ_SHA256_AMD64}; fi)" \\
+ && cd /tmp \\
+ && curl -fsSL -o yq "${YQ_RELEASE_URL_BASE}/${YQ_VERSION}/yq_linux_\${ARCH_BIN}" \\
+ && echo "\${ARCH_SHA}  yq" | sha256sum -c - \\
+ && chmod +x yq \\
+ && mv yq /usr/local/bin/yq \\
+ && /usr/local/bin/yq --version > /dev/null`
+
 const LAYER_3_AGENT_BROWSER_ARM64_CONFIG = `# Layer 3 (stable, arm64 only): point agent-browser at the apt-installed
 # chromium. Independent of the npm install below so it stays cached across
 # agent-browser version bumps.

package/src/init/validate-api-key.ts

@@ -1,3 +1,4 @@
+import { effectiveBaseUrl } from '@/agent/model-overrides'
 import { KNOWN_PROVIDERS, type KnownProviderId } from '@/config/providers'
 
 const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader: 'bearer' | 'x-api-key' }>> = {
@@ -8,6 +9,19 @@ const PROVIDER_PROBE: Partial<Record<KnownProviderId, { url: string; authHeader:
   'zai-coding': { url: 'https://api.z.ai/api/coding/paas/v4/models', authHeader: 'bearer' },
 }
 
+// When a base-URL override (ANTHROPIC_BASE_URL / OPENAI_BASE_URL) points at a
+// proxy, probe THAT endpoint — validating against the public API would test the
+// wrong gateway (and may reject a proxy-only credential). The path suffix is
+// whatever the hardcoded default probe URL adds on top of the provider's
+// default baseUrl, so providers with different version-segment conventions
+// (anthropic baseUrl omits `/v1`, openai includes it) each keep their own path.
+function probeUrlFor(providerId: KnownProviderId, defaultUrl: string): string {
+  const defaultBase = KNOWN_PROVIDERS[providerId].baseUrl
+  const base = effectiveBaseUrl(providerId, defaultBase)
+  if (base === undefined) return defaultUrl
+  return `${base}${defaultUrl.slice(defaultBase.length)}`
+}
+
 export type KeyValidationResult =
   | { kind: 'ok' }
   | { kind: 'skipped'; reason: 'no-probe' | 'network-error'; detail?: string }
@@ -36,7 +50,7 @@ export async function validateApiKey(
   }
 
   try {
-    const res = await fetchImpl(probe.url, {
+    const res = await fetchImpl(probeUrlFor(providerId, probe.url), {
       method: 'GET',
       headers,
       signal: AbortSignal.timeout(TIMEOUT_MS),

package/src/inspect/loop.ts

@@ -2,6 +2,12 @@ import { runInspect, type RunInspectOptions, type RunInspectResult } from './ind
 
 export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
   newEscSignal: () => AbortSignal
+  // Runs after every runInspect attempt settles. The caller disarms the raw-mode
+  // ESC listener here so the live tail releases stdin before clack re-opens the
+  // picker: an ESC-aborted tail leaves the listener armed (raw mode on, 'data'
+  // handler attached), and handing clack that flowing stream freezes the picker
+  // on SSH/Bun pseudo-TTYs.
+  afterEscStream?: () => void
 }
 
 export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunInspectResult> {
@@ -23,7 +29,12 @@ export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunIn
     if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
     else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
 
-    const result = await runInspect(callOpts)
+    let result: RunInspectResult
+    try {
+      result = await runInspect(callOpts)
+    } finally {
+      opts.afterEscStream?.()
+    }
     if (!result.ok) return result
     if (result.escToPicker !== true) return result
     sessionArg = undefined

package/src/permissions/permissions.ts

@@ -9,6 +9,12 @@ export type PermissionService = {
   has(origin: SessionOrigin | undefined, permission: string): boolean
   resolveRole(origin: SessionOrigin | undefined): string
   describe(origin: SessionOrigin | undefined): { role: string; permissions: readonly string[] }
+  // Orders two role names on the severity tower so callers can cap an
+  // action to the requester's role (a guest turn must not read the output
+  // of a member-spawned subagent). `undefined` means an unknown role on
+  // either side and MUST be treated as deny, never allow — mistreating it
+  // as allow reopens the privilege-escalation hole this gate closes.
+  compareRoleSeverity(a: string, b: string): -1 | 0 | 1 | undefined
   // Rebuilds the resolved role table from the given roles config, preserving
   // the same plugin-permission set captured at construction time. Used by
   // the config reloadable so role match-rule edits (typeclaw role claim,
@@ -25,6 +31,7 @@ export type UnknownPermissionWarning = {
 export const noopPermissionService: PermissionService = {
   has: () => false,
   resolveRole: () => 'guest',
+  compareRoleSeverity: () => undefined,
   describe: () => ({ role: 'guest', permissions: [] }),
   replaceRoles: () => {},
 }
@@ -139,6 +146,15 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
     return 'guest'
   }
 
+  function roleSeverity(name: string): number | undefined {
+    if (name === 'owner') return 4
+    if (name === 'trusted') return 3
+    if (name === 'member') return 1
+    if (name === 'guest') return 0
+    if (byName.has(name)) return 2
+    return undefined
+  }
+
   return {
     has(origin, permission) {
       // Fail-safe floor: an undefined origin holds nothing, regardless of
@@ -156,6 +172,14 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
       return role.permissions.includes(permission)
     },
     resolveRole,
+    compareRoleSeverity(a, b) {
+      const aRank = roleSeverity(a)
+      const bRank = roleSeverity(b)
+      if (aRank === undefined || bRank === undefined) return undefined
+      if (aRank < bRank) return -1
+      if (aRank > bRank) return 1
+      return 0
+    },
     describe(origin) {
       const name = resolveRole(origin)
       const role = byName.get(name)

package/src/plugin/context.ts

@@ -1,3 +1,4 @@
+import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
 import type { PermissionService } from '@/permissions'
 
 import type { PluginContext, PluginLogger, SpawnSubagentOptions } from './types'
@@ -11,10 +12,16 @@ export type CreatePluginContextOptions<TConfig> = {
   config: TConfig
   logger: PluginLogger
   permissions: PermissionService
+  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
   spawnSubagent: SpawnSubagentFn
   isBooted: () => boolean
 }
 
+const githubTokenUnavailable: ResolveGithubTokenForRepo = async () => ({
+  kind: 'unavailable',
+  reason: 'GitHub token resolution is not wired in this context.',
+})
+
 export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TConfig>): PluginContext<TConfig> {
   return Object.freeze({
     name: opts.name,
@@ -23,6 +30,7 @@ export function createPluginContext<TConfig>(opts: CreatePluginContextOptions<TC
     config: opts.config,
     logger: opts.logger,
     permissions: opts.permissions,
+    github: { resolveTokenForRepo: opts.resolveGithubTokenForRepo ?? githubTokenUnavailable },
     spawnSubagent: async (name: string, payload?: unknown, options?: SpawnSubagentOptions) => {
       if (!opts.isBooted()) {
         throw new Error(

package/src/plugin/manager.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 
+import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
 import type { CronJob } from '@/cron'
 import {
   createPermissionService,
@@ -20,6 +21,7 @@ export type LoadPluginsOptions = {
   configsByName: Record<string, unknown>
   loadEntry?: LoadPluginEntryFn
   roles?: RolesConfig
+  resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
   // 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-
@@ -101,6 +103,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
       config: validatedConfig as never,
       logger,
       permissions,
+      resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
       spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
       isBooted: () => booted,
     })

package/src/plugin/types.ts

@@ -2,6 +2,7 @@ import type { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { SubagentShared } from '@/agent/subagents'
+import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
 import type { PermissionService } from '@/permissions'
 
 export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
@@ -273,9 +274,14 @@ export type PluginContext<TConfig = never> = {
   readonly config: TConfig
   readonly logger: PluginLogger
   readonly permissions: PermissionService
+  readonly github: PluginGithubServices
   spawnSubagent: (name: string, payload?: unknown, options?: SpawnSubagentOptions) => Promise<void>
 }
 
+export type PluginGithubServices = {
+  resolveTokenForRepo: ResolveGithubTokenForRepo
+}
+
 export type PluginExports = {
   tools?: Record<string, Tool<any>>
   subagents?: Record<string, Subagent<any>>

package/src/run/bundled-plugins.ts

@@ -1,6 +1,7 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
 import explorerPlugin from '@/bundled-plugins/explorer'
+import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import operatorPlugin from '@/bundled-plugins/operator'
@@ -28,6 +29,13 @@ import type { ResolvedPlugin } from '@/plugin'
 // Reversing this order would make guard advise on the full oversized payload
 // and then tool-result-cap would clobber the advice text along with the rest.
 //
+// `github-cli-auth` is registered AFTER `security` so security's `tool.before`
+// runs its exfil/secret scanners on the bash command first. github-cli-auth
+// injects the minted token via an env overlay (TYPECLAW_INTERNAL_BASH_ENV), not
+// by rewriting the command string, so the token never enters argv or logs — but
+// ordering security first still matters so a blocked command never reaches the
+// mint path at all.
+//
 // `memory` is registered before `backup` so memory's dreaming commits always
 // land in the same git index window before backup's commit-and-push cycle.
 // They commit disjoint paths today (memory/ vs sessions/ + agent changes),
@@ -37,6 +45,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
   { name: 'tool-result-cap', version: undefined, source: '<bundled>', defined: toolResultCapPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
+  { name: 'github-cli-auth', version: undefined, source: '<bundled>', defined: githubCliAuthPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
   { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },

package/src/run/index.ts

@@ -19,6 +19,7 @@ import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import {
   createChannelManager,
   createChannelsReloadable,
+  createGithubTokenBridge,
   createSubagentCompletionBridge,
   type ChannelManager,
   type SubagentCompletionBridge,
@@ -138,11 +139,13 @@ export async function startAgent({
 
   const pluginConfigsByName = loadPluginConfigsSync(cwd)
   const cwdConfig = loadConfigSync(cwd)
+  const githubTokenBridge = createGithubTokenBridge()
   const pluginsLoaded = await loadPlugins({
     entries: cwdConfig.plugins,
     agentDir: cwd,
     configsByName: pluginConfigsByName,
     bundled: BUNDLED_PLUGINS,
+    resolveGithubTokenForRepo: githubTokenBridge.resolveTokenForRepo,
     ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })
 
@@ -255,6 +258,7 @@ export async function startAgent({
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
+    githubTokenBridge,
     stream,
   })