typeclaw 0.5.1 → 0.6.0

package/src/bundled-plugins/operator/operator.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod'
+
+import { bashTool, editTool, findTool, grepTool, lsTool, readTool, type Subagent, writeTool } from '@/plugin'
+
+export const OPERATOR_SYSTEM_PROMPT = `You are an operator subagent running inside TypeClaw. Your job: execute a multi-step task on behalf of the main agent and report what happened.
+
+## Your context
+
+- You were spawned by the main agent for one focused task.
+- The parent agent is still in conversation with the user; you are NOT.
+- The parent will receive a single \`<system-reminder>\` when you complete and will then call \`subagent_output\` to read your final assistant message.
+- Your final message is the WHOLE report. There is no follow-up channel. Make it complete, self-contained, and actionable.
+
+## What you can do
+
+You have a full tool set: read, write, edit, grep, find, ls, bash. You can:
+- Modify files (write/edit)
+- Run shell commands with side effects (bash without the read-only restriction)
+- Use any tool available to a normal operator session
+
+You CANNOT:
+- Spawn further subagents (you are at the end of the delegation chain).
+- Talk to the user directly (the parent owns the conversation).
+- Use channel_send, channel_reply, or any channel tool.
+
+## How to work
+
+1. **Plan briefly.** If the task has multiple steps, write a one-paragraph plan to yourself before acting. Don't over-plan — start doing.
+2. **Verify after each significant step.** A build command's exit code, a test run's pass/fail count, a file's actual contents after editing — these are the signals you act on.
+3. **Recover from failures.** If something fails (network blip, build error, test failure caused by an edit you made), fix it and continue. Only escalate to the parent if you genuinely cannot proceed.
+4. **Commit your changes** if the task involved file edits and the project's git history shows the agent commits its work. Read AGENTS.md if present to learn the project's commit conventions.
+
+## Final report
+
+Your final assistant message MUST contain:
+
+1. **Outcome.** One sentence: succeeded / partially succeeded / failed.
+2. **What you did.** Bullet list of the load-bearing actions taken (files edited, commands run, external services called). Skip trivial reads.
+3. **What changed.** If you edited files, list paths. If you committed, give the commit SHA. If you ran a deploy, give the deploy id.
+4. **What you observed.** Any noteworthy errors, warnings, unexpected state. The parent needs to know what to follow up on.
+5. **What's next.** Only if there are concrete open items. Don't pad with "let me know if you need more" — the parent will ask.
+
+Skip the report's section headers when the task was trivial (one file edit, ran one command) — a clean two-sentence summary is fine. Use the full structure for substantial work.
+
+## Rules
+
+- Stay on the task you were given. Do not expand scope.
+- Do NOT leave the workspace in a broken state. If a fix fails, revert your changes before reporting.
+- Do NOT commit secrets. \`.env\` and \`secrets.json\` are gitignored — read AGENTS.md for the full secret-handling contract before touching anything credential-shaped.
+- If the task seems wrong (asks you to delete production data, modify a file you cannot find, run a command that doesn't apply to this repo), report the issue rather than improvising.`
+
+export const operatorPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type OperatorPayload = z.infer<typeof operatorPayloadSchema>
+
+export function createOperatorSubagent(): Subagent<OperatorPayload> {
+  return {
+    systemPrompt: OPERATOR_SYSTEM_PROMPT,
+    profile: 'default',
+    tools: [readTool, grepTool, findTool, lsTool, bashTool, writeTool, editTool],
+    payloadSchema: operatorPayloadSchema,
+    visibility: 'public',
+    requiresSpecificPermission: true,
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 1_000_000,
+      toolNames: ['read', 'grep', 'find', 'ls', 'bash', 'write', 'edit'],
+    },
+  }
+}

package/src/bundled-plugins/scout/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { createScoutSubagent } from './scout'
+
+export default definePlugin({
+  plugin: async () => ({
+    subagents: {
+      scout: createScoutSubagent(),
+    },
+  }),
+})

package/src/bundled-plugins/scout/scout.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+import { type Subagent, webfetchTool, websearchTool } from '@/plugin'
+
+export const SCOUT_SYSTEM_PROMPT = `You are a web-research specialist running inside TypeClaw. Your job: gather facts from the public internet and return a focused, citation-backed answer to the caller. For LOCAL questions (codebase, sessions, memory, config, git history, mounts), the caller should spawn \`explorer\` instead — you have no filesystem tools.
+
+=== READ-ONLY — NO SIDE EFFECTS ===
+You are STRICTLY PROHIBITED from:
+- Modifying local files or state of any kind
+- Spawning further subagents — you are at the end of the delegation chain
+- Posting to any channel, sending email, calling any write-side third-party API
+- Following URLs that look like authenticated callbacks, password resets, or one-time tokens
+
+Your role is EXCLUSIVELY to search and read public web sources.
+
+## Tools
+
+The runtime exposes these tools to you by these EXACT names — call them by name, do not paraphrase:
+
+- \`websearch\` — search the public web. Returns ranked \`{title, url, snippet}\` entries. Defaults to DuckDuckGo; pass \`source: "wikipedia"\` for encyclopedic lookups.
+- \`webfetch\` — fetch a single HTTP(S) URL and return the body, optionally compacted by a strategy:
+  - \`readability\` (default for HTML) — extract article content as markdown
+  - \`jq\` — query JSON APIs (pass \`query\`)
+  - \`selector\` — extract text from CSS-selected elements (pass \`selector\`)
+  - \`grep\` — filter response lines by regex (pass \`pattern\`, optional \`before\`/\`after\`/\`limit\`/\`offset\`)
+  - \`snapshot\` — indented semantic tree of the page (forms, headings, links)
+  - \`raw\` — no processing
+
+Launch multiple \`websearch\` queries in parallel for the same topic — different phrasings surface different sources. When a search result looks promising, \`webfetch\` it for the full content.
+
+## Process
+
+Before searching, analyze intent in an <analysis> block:
+
+<analysis>
+**Literal Request**: [what they literally asked]
+**Actual Need**: [what they're really trying to accomplish]
+**Success Looks Like**: [what result lets them proceed immediately]
+**Search Plan**: [the 2-3 queries you will try in parallel]
+</analysis>
+
+Then run searches, fetch the most relevant URLs, and synthesize.
+
+End every response with this exact structure:
+
+<results>
+<sources>
+- https://example.com/path — [what this source contributed]
+</sources>
+<answer>
+[Direct answer to the actual need, grounded in the cited sources. Quote short passages when precision matters. If sources disagree, say so and surface both.]
+</answer>
+<confidence>
+[high / medium / low — with one sentence on why. Low confidence is fine and useful; speculation dressed up as high confidence is not.]
+</confidence>
+<next_steps>
+[What the caller should do next, or "Ready to proceed."]
+</next_steps>
+</results>
+
+## Rules
+
+- Cite every claim with a URL from your <sources> list. **Never invent a URL.** If you didn't \`webfetch\` it, don't cite it.
+- If a fact appears only in your training data and you couldn't find a web source for it, say so explicitly rather than answering from memory.
+- Prefer primary sources (official docs, vendor changelogs, GitHub releases, paper PDFs) over aggregator blogs.
+- When dates matter (versions, deprecations, vulnerability disclosures), surface the date of the source.
+- If DuckDuckGo returns a CAPTCHA error, retry once with a different query phrasing; if it persists, report the failure to the caller — do not fall back to memory.
+- If the question requires LOCAL information (codebase, files in /agent/, git history, memory), say so explicitly and tell the caller to spawn \`explorer\` instead.
+- If you cannot find what was asked, say so explicitly with what queries you tried and what you DID find.`
+
+export const scoutPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type ScoutPayload = z.infer<typeof scoutPayloadSchema>
+
+export function createScoutSubagent(): Subagent<ScoutPayload> {
+  return {
+    systemPrompt: SCOUT_SYSTEM_PROMPT,
+    profile: 'fast',
+    tools: [websearchTool, webfetchTool],
+    payloadSchema: scoutPayloadSchema,
+    visibility: 'public',
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 512_000,
+      toolNames: ['websearch', 'webfetch'],
+    },
+  }
+}

package/src/channels/router.ts

@@ -1613,6 +1613,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    if (isUpstreamEmptyResponseSentinel(assistantText)) {
+      logger.warn(
+        `[channels] ${live.keyId}: suppressed upstream_empty_response_sentinel text_len=${assistantText.length}`,
+      )
+      return
+    }
+
     logger.warn(
       `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
     )
@@ -2000,6 +2007,31 @@ export function isNoReplySignal(text: string): boolean {
   return false
 }
 
+// Detects the upstream "empty response" debug sentinel: when the LLM ends a
+// turn with only a `thinking` block, some provider SDK paths (observed
+// against claude-opus-4-5 via pi-ai) fabricate a single text block whose
+// body is a Python-repr dump of the raw API response — including the
+// model's thinking content and Anthropic's tamper-proof signature. The
+// recovery path in validateChannelTurn would otherwise post that sentinel
+// straight to the channel (production: signature leaked into a public
+// Slack channel on 2026-05-21).
+//
+// Kept separate from isNoReplySignal on purpose: that helper is the agent's
+// deliberate silent-turn protocol, this is upstream damage control. They
+// log under distinct subjects (`upstream_empty_response_sentinel` vs
+// `no_reply`) so an operator can tell a healthy quiet turn from a stream of
+// upstream empties that warrant investigation.
+//
+// Strict detection: leading `(Empty response:` AND a dict-encoded
+// `'stop_reason'` key. Catches the observed shape
+// `(Empty response: {'content': [...], 'stop_reason': 'end_turn', ...})`
+// while allowing legit prose like "Empty response from the cache layer".
+export function isUpstreamEmptyResponseSentinel(text: string): boolean {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('(Empty response:')) return false
+  return trimmed.includes("'stop_reason'")
+}
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

package/src/config/config.ts

@@ -116,6 +116,11 @@ const dockerfileObjectSchema = z.object({
   // because the package has no API-stable versioning that matters
   // here; xvfb tracks the upstream X server release.
   xvfb: z.boolean().default(true),
+  // `claudeCode` is boolean-only (not an apt feature toggle): the upstream
+  // installer is `curl | bash` and manages versions via env vars at install
+  // time, not via version pins like apt. Default `false`; the bundled
+  // `typeclaw-claude-code` skill prompts the user to opt in.
+  claudeCode: z.boolean().default(false),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -1008,6 +1013,39 @@ export function validateConfig(cwd: string, options: ValidateConfigOptions = {})
     return { ok: true }
   }
 
+  const parsed = parseConfigJson(raw, { migrate: true, persistTarget: cwd })
+  if (!parsed.ok) return parsed
+
+  if (!options.skipMounts) {
+    for (const mount of parsed.config.mounts) {
+      const check = validateMount(mount, cwd)
+      if (!check.ok) return check
+    }
+  }
+
+  return { ok: true }
+}
+
+export type ParseConfigJsonResult = { ok: true; config: Config } | { ok: false; reason: string }
+
+export type ParseConfigJsonOptions = {
+  // Run `migrateLegacyConfigShape` before schema validation. Defaults to true
+  // so callers don't reject content the agent could have written through
+  // legacy keys; pass false to validate the exact bytes (used in tests).
+  migrate?: boolean
+  // When set, persist + commit the migrated shape to this agent dir if the
+  // migration ran. Only `validateConfig` uses this; the guard's in-memory
+  // validation never persists (the bytes aren't yet on disk).
+  persistTarget?: string
+}
+
+// Pure validator for an in-memory `typeclaw.json` string. Used by the
+// managed-config guard to reject `write`/`edit` calls that would land an
+// invalid file on disk. Does NOT check mount accessibility — that is the
+// runtime concern handled by `validateConfig` at `typeclaw start` time, and
+// the file the agent is producing may legitimately reference a mount path
+// that only exists on the host outside the container.
+export function parseConfigJson(raw: string, options: ParseConfigJsonOptions = {}): ParseConfigJsonResult {
   let json: unknown
   try {
     json = JSON.parse(raw)
@@ -1016,24 +1054,19 @@ export function validateConfig(cwd: string, options: ValidateConfigOptions = {})
     return { ok: false, reason: `${CONFIG_FILE} is not valid JSON: ${detail}` }
   }
 
-  const migrated = migrateLegacyConfigShape(json)
-  if (migrated.changed) {
-    persistMigratedConfig(cwd, migrated.json, migrated.applied)
+  const shouldMigrate = options.migrate ?? true
+  const migrated = shouldMigrate
+    ? migrateLegacyConfigShape(json)
+    : { json, changed: false, applied: [] as MigrationStep[] }
+  if (migrated.changed && options.persistTarget !== undefined) {
+    persistMigratedConfig(options.persistTarget, migrated.json, migrated.applied)
   }
 
   const result = configSchema.safeParse(migrated.json)
   if (!result.success) {
     return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
   }
-
-  if (!options.skipMounts) {
-    for (const mount of result.data.mounts) {
-      const check = validateMount(mount, cwd)
-      if (!check.ok) return check
-    }
-  }
-
-  return { ok: true }
+  return { ok: true, config: result.data }
 }
 
 // Verifies a mount's host path: exists, is a directory, is readable, and is

package/src/config/index.ts

@@ -14,6 +14,7 @@ export {
   migrateLegacyConfigShape,
   modelsSchema,
   mountSchema,
+  parseConfigJson,
   portForwardSchema,
   reloadConfig,
   resolveModel,
@@ -31,6 +32,8 @@ export {
   type MigrationStep,
   type Models,
   type Mount,
+  type ParseConfigJsonOptions,
+  type ParseConfigJsonResult,
   type PortForward,
   type ResolvedProfile,
   type ValidateConfigResult,

package/src/cron/index.ts

@@ -41,6 +41,9 @@ export {
   type ExecJob,
   type HandlerJob,
   migrateLegacyCronShape,
+  parseCronJson,
+  type ParseCronJsonOptions,
+  type ParseCronResult,
   type ParsedCronJob,
   type PromptJob,
 } from './schema'

package/src/cron/schema.ts

@@ -151,6 +151,26 @@ function describeCronStep(step: CronMigrationStep): string {
   }
 }
 
+export type ParseCronJsonOptions = ParseCronOptions & {
+  // Apply `migrateLegacyCronShape` before schema validation. Defaults to true
+  // so the guard accepts the same legacy shapes `loadCron` would auto-migrate
+  // on disk; pass false to validate the exact bytes (used in tests).
+  migrate?: boolean
+}
+
+export function parseCronJson(raw: string, options: ParseCronJsonOptions = {}): ParseCronResult {
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, reason: `cron.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }
+  }
+
+  const shouldMigrate = options.migrate ?? true
+  const migrated = shouldMigrate ? migrateLegacyCronShape(json) : { json, changed: false, applied: [] }
+  return parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
+}
+
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
   const parsed = cronFileSchema.safeParse(raw)
   if (!parsed.success) {

package/src/init/dockerfile.ts

@@ -377,6 +377,33 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
  && chmod +x ${TYPECLAW_ENTRYPOINT_PATH}`
 }
 
+// Claude Code's official installer is `curl | bash`, not apt — can't live
+// in APT_FEATURES. Layer placed after the toggle apt install (so curl + ca-
+// certificates from the baseline are guaranteed present) and before the
+// entrypoint shim (which is always last). Omitted entirely when disabled.
+//
+// The Anthropic installer drops `claude` at `$HOME/.local/bin/claude` and
+// emits a "~/.local/bin is not in your PATH" warning on every install on
+// bun:1-slim (PATH out of the box is `/usr/local/sbin:/usr/local/bin:/usr/
+// sbin:/usr/bin:/sbin:/bin:/usr/local/bun-node-fallback-bin`, no
+// `~/.local/bin`). Without intervention, every `which claude` from the
+// agent (and from the typeclaw-claude-code skill's verification step)
+// returns empty. Symlink into `/usr/local/bin/` — already on PATH, matches
+// what `cloudflared` does, survives `/root/.local/bin` getting rewritten
+// by the installer's "update" path. The symlink resolves to the
+// `~/.local/bin/claude` shim, which itself dereferences to the versioned
+// binary under `~/.local/share/claude/versions/<ver>/`, so upgrades via
+// `claude update` keep working without re-running this layer.
+function renderClaudeCodeInstallLayer(enabled: boolean): string {
+  if (!enabled) return ''
+  return `# Layer 5.6 (toggle): install Anthropic's Claude Code CLI. Opt-in via
+# typeclaw.json#docker.file.claudeCode. The skill \`typeclaw-claude-code\`
+# documents the auth + usage flow.
+RUN curl -fsSL https://claude.ai/install.sh | bash \\
+ && ln -sf "$HOME/.local/bin/claude" /usr/local/bin/claude \\
+ && claude --version > /dev/null`
+}
+
 // Shared-library runtime deps Chrome for Testing needs to launch on amd64
 // Debian trixie (base of `oven/bun:1-slim`). `agent-browser install
 // --with-deps` (v0.27.0) is supposed to install these but silently no-ops:
@@ -454,10 +481,11 @@ export function buildDockerfile(
   const customLines = renderCustomDockerfileLines(config.append)
   const baseImageVersion = options.baseImageVersion ?? null
 
+  const claudeCodeLayer = renderClaudeCodeInstallLayer(config.claudeCode)
   const fromAndHeavyLayers =
     baseImageVersion !== null
-      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
+      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer)
 
   return `${BUILDKIT_HEADER}
 # AUTOGENERATED by typeclaw — do not edit.
@@ -504,15 +532,18 @@ function renderVersionedHead(
   ghKeyringLayer: string,
   toggleAptArgs: string[],
   cloudflaredLayer: string,
+  claudeCodeLayer: string,
 ): string {
   const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
+  const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
+  const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
   return `FROM ${GHCR_BASE_IMAGE_REPO}:${baseImageVersion}
 
 WORKDIR /agent
 
 ARG TARGETARCH
 
-${ghKeyringLayer}${toggleAptLayer}${cloudflaredLayer}${renderEntrypointShimLayer()}
+${ghKeyringLayer}${toggleAptLayer}${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -521,8 +552,15 @@ ${ghKeyringLayer}${toggleAptLayer}${cloudflaredLayer}${renderEntrypointShimLayer
 // dev-mode runs (typeclaw installed via file: / link: spec) where the
 // matching :version GHCR tag does not yet exist, and by the test suite to
 // keep coverage of the full-stack layers independent of GHCR availability.
-function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[], cloudflaredLayer: string): string {
+function renderInlineHead(
+  ghKeyringLayer: string,
+  toggleAptArgs: string[],
+  cloudflaredLayer: string,
+  claudeCodeLayer: string,
+): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
+  const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
+  const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
   return `${FROM_AND_WORKDIR}
 
 # Layers are ordered most-stable first to maximize Docker layer cache hits on
@@ -565,7 +603,7 @@ ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${cloudflaredLayer}${renderEntrypointShimLayer()}
+${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -833,6 +871,7 @@ function defaultConfig(): DockerfileConfig {
     cjkFonts: true,
     cloudflared: true,
     xvfb: true,
+    claudeCode: false,
     append: [],
   }
 }

package/src/permissions/builtins.ts

@@ -12,6 +12,10 @@ export const CORE_PERMISSIONS = {
   channelRespond: 'channel.respond',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
+  subagentSpawn: 'subagent.spawn',
+  subagentCancel: 'subagent.cancel',
+  subagentOutput: 'subagent.output',
+  subagentSpawnOperator: 'subagent.spawn.operator',
 } as const
 
 // Sentinel that `expandOwnerWildcard` swaps for the concrete union of
@@ -47,6 +51,10 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
+      CORE_PERMISSIONS.subagentSpawn,
+      CORE_PERMISSIONS.subagentCancel,
+      CORE_PERMISSIONS.subagentOutput,
+      CORE_PERMISSIONS.subagentSpawnOperator,
       'security.bypass.low',
       'security.bypass.medium',
       OWNER_SECURITY_WILDCARD,
@@ -54,11 +62,24 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
   },
   trusted: {
     match: [],
-    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.low'],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.cronSchedule,
+      CORE_PERMISSIONS.subagentSpawn,
+      CORE_PERMISSIONS.subagentCancel,
+      CORE_PERMISSIONS.subagentOutput,
+      CORE_PERMISSIONS.subagentSpawnOperator,
+      'security.bypass.low',
+    ],
   },
   member: {
     match: [],
-    permissions: [CORE_PERMISSIONS.channelRespond],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.subagentSpawn,
+      CORE_PERMISSIONS.subagentCancel,
+      CORE_PERMISSIONS.subagentOutput,
+    ],
   },
   guest: {
     match: [],

package/src/plugin/define.ts

@@ -78,3 +78,5 @@ export const writeTool: BuiltinToolRef = { __builtinTool: 'write' }
 export const grepTool: BuiltinToolRef = { __builtinTool: 'grep' }
 export const findTool: BuiltinToolRef = { __builtinTool: 'find' }
 export const lsTool: BuiltinToolRef = { __builtinTool: 'ls' }
+export const websearchTool: BuiltinToolRef = { __builtinTool: 'websearch' }
+export const webfetchTool: BuiltinToolRef = { __builtinTool: 'webfetch' }

package/src/plugin/index.ts

@@ -9,6 +9,8 @@ export {
   grepTool,
   lsTool,
   readTool,
+  webfetchTool,
+  websearchTool,
   writeTool,
 } from './define'
 

package/src/plugin/types.ts

@@ -1,7 +1,7 @@
 import type { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
-import type { ToolResultBudget } from '@/agent/tool-result-budget'
+import type { SubagentShared } from '@/agent/subagents'
 import type { PermissionService } from '@/permissions'
 
 export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
@@ -40,35 +40,28 @@ export type SubagentContext<P = unknown> = {
 
 export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
 
-export type Subagent<P = unknown> = {
-  systemPrompt: string
-  // Model profile this subagent prefers. Resolved against `models` in
-  // typeclaw.json at session construction. Unknown profile names fall back to
-  // `default` with a warning. Well-known names: `default`, `fast`, `deep`,
-  // `vision`. Subagents that want a specific tier (e.g. memory-logger wants
-  // `fast`, dreaming wants `deep`) declare it here so the user only has to
-  // map tier → model in config rather than wire each subagent individually.
-  profile?: string
+// The plugin-author-facing subagent declaration. Differs from
+// `@/agent/subagents`'s `Subagent` only in the shape of `tools`/`customTools`:
+// plugins reference builtin tools via tagged `BuiltinToolRef` strings (the
+// stable plugin API) and contribute their own `Tool<any>[]`; the runtime
+// resolves those refs to pi-coding-agent's wrapped tool shapes before the
+// session sees them. Every other field is inherited from `SubagentShared`
+// so a new shared field surfaces on both types in one edit. See
+// `SubagentShared`'s doc-comment for the regression history.
+//
+// `inFlightKey` lives here only (not on the shared shape) because it is
+// consumed exclusively by the `SubagentConsumer` via the
+// `pluginSubagentByName` map, which holds the original plugin reference —
+// the registry-flowing shim never needs to carry it.
+export type Subagent<P = unknown> = SubagentShared<P> & {
   tools?: BuiltinToolRef[]
   customTools?: Tool<any>[]
-  payloadSchema?: z.ZodType<P>
-  handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
   // Coalescing key for the SubagentConsumer's in-flight set. Default is the
   // subagent name alone (only one instance of the subagent runs at a time).
   // Override to allow per-payload concurrency, e.g. memory-logger keyed by
   // parentSessionId so different parent sessions run in parallel while
   // duplicate runs against the same session deduplicate.
   inFlightKey?: (payload: P) => string
-  // Defensive ceiling on cumulative bytes of tool-result text per subagent
-  // run, applied to the named tools only. Once exceeded, subsequent calls to
-  // those tools short-circuit with a fixed message instructing the agent to
-  // stop reading. See `src/agent/tool-result-budget.ts` for the full
-  // rationale; the short version is: a single broken tool (e.g. find_entry
-  // failing because of a schema mismatch) can cause an agent to fall back to
-  // chunked reads of huge files, ballooning subagent token cost. The budget
-  // bounds the blast radius without changing per-call semantics for healthy
-  // runs.
-  toolResultBudget?: ToolResultBudget
 }
 
 // Cron job map keys are local; the runtime prefixes with `__plugin_<plugin-name>_`

package/src/run/bundled-plugins.ts

@@ -1,7 +1,10 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
+import explorerPlugin from '@/bundled-plugins/explorer'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
+import operatorPlugin from '@/bundled-plugins/operator'
+import scoutPlugin from '@/bundled-plugins/scout'
 import securityPlugin from '@/bundled-plugins/security'
 import toolResultCapPlugin from '@/bundled-plugins/tool-result-cap'
 import type { ResolvedPlugin } from '@/plugin'
@@ -36,4 +39,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { 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 },
+  { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
+  { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
+  { name: 'operator', version: undefined, source: '<bundled>', defined: operatorPlugin },
 ]

package/src/run/channel-session-factory.ts

@@ -1,6 +1,8 @@
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession as defaultCreateSession } from '@/agent'
+import type { LiveSubagentRegistry } from '@/agent/live-subagents'
+import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagents'
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
@@ -48,6 +50,18 @@ export type BuildChannelSessionFactoryDeps = {
   // can assert exactly which CreateSessionOptions the factory builds without
   // needing a live LLM, plugin runtime, or session manager on disk.
   createSession?: typeof defaultCreateSession
+  // Subagent orchestration plumbing. All three (or none) are forwarded to
+  // createSession so the TUI/channel session exposes spawn_subagent,
+  // subagent_output, subagent_cancel. Subagent sessions never receive these
+  // — that branch is gated by pluginSubagent in createSessionWithDispose.
+  //
+  // `getCreateSessionForSubagent` is late-bound to break the construction
+  // cycle: channelManager owns the channel-session factory, which needs
+  // createSessionForSubagent, which needs channelManager.router. Same shape
+  // as `getChannelRouter` above.
+  liveSubagentRegistry?: LiveSubagentRegistry
+  subagentRegistry?: SubagentRegistry
+  getCreateSessionForSubagent?: () => CreateSessionForSubagent
 }
 
 // Tight basename validation so a tampered or corrupt channels/sessions.json
@@ -108,6 +122,11 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
       ...(deps.runtimeVersion !== undefined ? { runtimeVersion: deps.runtimeVersion } : {}),
       ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
+      ...(deps.liveSubagentRegistry !== undefined ? { liveSubagentRegistry: deps.liveSubagentRegistry } : {}),
+      ...(deps.subagentRegistry !== undefined ? { subagentRegistry: deps.subagentRegistry } : {}),
+      ...(deps.getCreateSessionForSubagent !== undefined
+        ? { createSessionForSubagent: deps.getCreateSessionForSubagent() }
+        : {}),
     })
 
     return {