typeclaw 0.5.1 → 0.6.0

package/README.md

@@ -140,6 +140,10 @@ bun run format
 
 See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy.
 
+## Website
+
+The landing page and documentation site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/). It's a Next.js + Fumadocs app — see [`docs/README.md`](./docs/README.md) for layout and the contributor workflow.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -25,12 +25,14 @@ import type { Stream } from '@/stream'
 import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
+import type { LiveSubagentRegistry } from './live-subagents'
 import { lookAtTool } from './multimodal'
 import { resolveBuiltinToolRefs, wrapPluginTool, wrapSystemAgentTool, wrapSystemTool } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
 import { loadSelf } from './self'
 import { SESSION_META_CUSTOM_TYPE, sessionMetaPayload } from './session-meta'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
+import type { CreateSessionForSubagent, SubagentRegistry } from './subagents'
 import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
 import {
   createBudgetState,
@@ -43,7 +45,10 @@ import { createChannelHistoryTool } from './tools/channel-history'
 import { createChannelReplyTool } from './tools/channel-reply'
 import { createChannelSendTool } from './tools/channel-send'
 import { createRestartTool } from './tools/restart'
+import { createSpawnSubagentTool } from './tools/spawn-subagent'
 import { createStreamSnapshotTool } from './tools/stream-snapshot'
+import { createSubagentCancelTool } from './tools/subagent-cancel'
+import { createSubagentOutputTool } from './tools/subagent-output'
 import { webfetchTool } from './tools/webfetch'
 import { websearchTool } from './tools/websearch'
 
@@ -153,6 +158,16 @@ export type CreateSessionOptions = {
   // already seen") provide their own here. See `ToolResultBudget` for the
   // shared shape.
   toolResultBudgetMessage?: ToolResultBudget['exhaustedMessage']
+  // Orchestration wiring. When all three of `liveSubagentRegistry`,
+  // `subagentRegistry`, and `createSessionForSubagent` are present (AND
+  // `pluginSubagent` is unset), the session exposes the spawn_subagent,
+  // subagent_output, and subagent_cancel tools. Subagent-origin sessions
+  // get an empty tool set via the `pluginSubagent` branch; the gate here
+  // (omitting these for subagent sessions) is what prevents recursive
+  // spawning.
+  liveSubagentRegistry?: LiveSubagentRegistry
+  subagentRegistry?: SubagentRegistry
+  createSessionForSubagent?: CreateSessionForSubagent
 }
 
 export type CreateSessionResult = {
@@ -205,9 +220,16 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
   const getOrigin: () => SessionOrigin | undefined =
     options.originRef !== undefined ? () => options.originRef!.current : () => options.origin
 
-  const subagentBuiltinTools = options.pluginSubagent?.toolRefs
+  // Subagent built-in tool refs are dual-routed (see BUILTIN_TOOL_DEFINITION
+  // dual-map in plugin-tools.ts): pi-side coding tools go to `tools:` so they
+  // become the strict base set, typeclaw-side web tools go to `customTools:`.
+  // The two `tools:` fields below (effective `options.tools` and the resolved
+  // subagent pi-side builtins) are mutually exclusive — `options.tools` is only
+  // passed by non-subagent callers like multimodal look-at; subagent sessions
+  // never set both.
+  const resolvedSubagentBuiltins = options.pluginSubagent?.toolRefs
     ? resolveBuiltinToolRefs(options.pluginSubagent.toolRefs)
-    : undefined
+    : { agentTools: [], toolDefinitions: [] }
   const pluginCustomTools = options.pluginSubagent
     ? wrapSubagentCustomTools(options.pluginSubagent, options.plugins, getOrigin)
     : wrapRegistryTools(options.plugins, getOrigin)
@@ -224,11 +246,9 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     : undefined
   const sessionBudgetState = sessionBudget ? createBudgetState() : undefined
 
-  const hookWrappedTools = wrapSystemAgentTools(
-    options.tools ?? (subagentBuiltinTools as AgentSessionTools | undefined),
-    options.plugins,
-    getOrigin,
-  )
+  const effectiveTools =
+    options.tools ?? (options.pluginSubagent ? (resolvedSubagentBuiltins.agentTools as AgentSessionTools) : undefined)
+  const hookWrappedTools = wrapSystemAgentTools(effectiveTools, options.plugins, getOrigin)
   const tools =
     sessionBudget && sessionBudgetState && hookWrappedTools
       ? (hookWrappedTools.map((t) =>
@@ -265,7 +285,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     options.customTools !== undefined
       ? options.customTools
       : options.pluginSubagent
-        ? []
+        ? resolvedSubagentBuiltins.toolDefinitions
         : [
             websearchTool,
             webfetchTool,
@@ -282,6 +302,16 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
                   }),
                 ]
               : []),
+            ...buildSubagentOrchestrationTools({
+              liveRegistry: options.liveSubagentRegistry,
+              registry: options.subagentRegistry,
+              createSessionForSubagent: options.createSessionForSubagent,
+              agentDir: options.plugins?.agentDir,
+              parentSessionId: sessionManager.getSessionId(),
+              getOrigin,
+              permissions: options.permissions,
+              stream: options.stream,
+            }),
           ]
   const customToolsPreBudget = [...wrapSystemTools(customSystemTools, options.plugins, getOrigin), ...pluginCustomTools]
   const customTools =
@@ -430,6 +460,48 @@ export function buildChannelTools(
   return tools
 }
 
+export function buildSubagentOrchestrationTools(opts: {
+  liveRegistry: LiveSubagentRegistry | undefined
+  registry: SubagentRegistry | undefined
+  createSessionForSubagent: CreateSessionForSubagent | undefined
+  agentDir: string | undefined
+  parentSessionId: string
+  getOrigin: () => SessionOrigin | undefined
+  permissions: PermissionService | undefined
+  stream: Stream | undefined
+}): ToolDefinition[] {
+  if (
+    opts.liveRegistry === undefined ||
+    opts.registry === undefined ||
+    opts.createSessionForSubagent === undefined ||
+    opts.agentDir === undefined
+  ) {
+    return []
+  }
+  return [
+    createSpawnSubagentTool({
+      registry: opts.registry,
+      liveRegistry: opts.liveRegistry,
+      createSessionForSubagent: opts.createSessionForSubagent,
+      agentDir: opts.agentDir,
+      parentSessionId: opts.parentSessionId,
+      getOrigin: opts.getOrigin,
+      ...(opts.permissions ? { permissions: opts.permissions } : {}),
+      ...(opts.stream ? { stream: opts.stream } : {}),
+    }),
+    createSubagentOutputTool({
+      liveRegistry: opts.liveRegistry,
+      getOrigin: opts.getOrigin,
+      ...(opts.permissions ? { permissions: opts.permissions } : {}),
+    }),
+    createSubagentCancelTool({
+      liveRegistry: opts.liveRegistry,
+      getOrigin: opts.getOrigin,
+      ...(opts.permissions ? { permissions: opts.permissions } : {}),
+    }),
+  ]
+}
+
 function wrapRegistryTools(
   plugins: PluginSessionWiring | undefined,
   getOrigin: () => SessionOrigin | undefined,

package/src/agent/live-subagents.ts

@@ -0,0 +1,215 @@
+import type { AgentSession } from './index'
+
+export type SubagentProgressEvent =
+  | { kind: 'started'; ts: number }
+  | { kind: 'tool'; name: string; ok: boolean; ts: number }
+  | { kind: 'message'; preview: string; ts: number }
+
+export type SubagentStatus = 'running' | 'completed' | 'failed'
+
+export type SubagentCompletion = {
+  ok: boolean
+  finalMessage?: string
+  error?: string
+  durationMs: number
+}
+
+export type LiveSubagent = {
+  taskId: string
+  sessionId: string
+  subagentName: string
+  parentSessionId?: string
+  startedAt: number
+  status: SubagentStatus
+  completion?: SubagentCompletion
+  abort: () => Promise<void>
+  awaitCompletion: () => Promise<SubagentCompletion>
+}
+
+export const MAX_EVENTS_PER_SUBAGENT = 100
+export const MESSAGE_PREVIEW_CHARS = 200
+
+type AgentSessionEvent =
+  | { type: 'message_update'; assistantMessageEvent: { type: string; delta?: string } }
+  | { type: 'message_end'; message: unknown }
+  | { type: 'tool_execution_start'; toolCallId: string; toolName: string; args: unknown }
+  | { type: 'tool_execution_end'; toolCallId: string; toolName: string; result: unknown; isError: boolean }
+  | { type: string }
+
+export function coarsen(event: AgentSessionEvent, now: number): SubagentProgressEvent | null {
+  if (event.type === 'tool_execution_end') {
+    const ev = event as Extract<AgentSessionEvent, { type: 'tool_execution_end' }>
+    return { kind: 'tool', name: ev.toolName, ok: !ev.isError, ts: now }
+  }
+  if (event.type === 'message_end') {
+    const ev = event as Extract<AgentSessionEvent, { type: 'message_end' }>
+    const preview = extractMessagePreview(ev.message)
+    if (preview === null) return null
+    return { kind: 'message', preview, ts: now }
+  }
+  return null
+}
+
+function extractMessagePreview(message: unknown): string | null {
+  if (message === null || typeof message !== 'object') return null
+  const content = (message as { content?: unknown }).content
+  if (typeof content === 'string') {
+    const trimmed = content.trim()
+    return trimmed ? trimmed.slice(0, MESSAGE_PREVIEW_CHARS) : null
+  }
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      if (part && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
+        const text = (part as { text?: unknown }).text
+        if (typeof text === 'string') {
+          const trimmed = text.trim()
+          if (trimmed) return trimmed.slice(0, MESSAGE_PREVIEW_CHARS)
+        }
+      }
+    }
+  }
+  return null
+}
+
+export type StatusSnapshot = {
+  taskId: string
+  sessionId: string
+  subagentName: string
+  status: SubagentStatus
+  startedAt: number
+  elapsedMs: number
+  eventsCount: number
+  eventsRecent: SubagentProgressEvent[]
+  lastActivity: SubagentProgressEvent | null
+  statusSummary: string
+  completion?: SubagentCompletion
+}
+
+export class LiveSubagentRegistry {
+  private readonly entries = new Map<string, LiveSubagent>()
+  private readonly events = new Map<string, SubagentProgressEvent[]>()
+
+  register(live: LiveSubagent): void {
+    if (this.entries.has(live.taskId)) {
+      throw new Error(`task ${live.taskId} already registered`)
+    }
+    this.entries.set(live.taskId, live)
+    this.events.set(live.taskId, [{ kind: 'started', ts: live.startedAt }])
+  }
+
+  unregister(taskId: string): void {
+    this.entries.delete(taskId)
+    this.events.delete(taskId)
+  }
+
+  get(taskId: string): LiveSubagent | undefined {
+    return this.entries.get(taskId)
+  }
+
+  list(filter?: { parentSessionId?: string }): LiveSubagent[] {
+    const all = Array.from(this.entries.values())
+    if (filter?.parentSessionId === undefined) return all
+    return all.filter((e) => e.parentSessionId === filter.parentSessionId)
+  }
+
+  hasLiveForSession(sessionId: string): boolean {
+    for (const e of this.entries.values()) {
+      if (e.sessionId === sessionId && e.status === 'running') return true
+    }
+    return false
+  }
+
+  recordEvent(taskId: string, event: SubagentProgressEvent): void {
+    const ring = this.events.get(taskId)
+    if (ring === undefined) return
+    ring.push(event)
+    if (ring.length > MAX_EVENTS_PER_SUBAGENT) {
+      ring.splice(0, ring.length - MAX_EVENTS_PER_SUBAGENT)
+    }
+  }
+
+  recordCompletion(taskId: string, completion: SubagentCompletion): void {
+    const entry = this.entries.get(taskId)
+    if (entry === undefined) return
+    entry.completion = completion
+    entry.status = completion.ok ? 'completed' : 'failed'
+  }
+
+  snapshot(taskId: string, now: number = Date.now()): StatusSnapshot | undefined {
+    const entry = this.entries.get(taskId)
+    if (entry === undefined) return undefined
+    const events = this.events.get(taskId) ?? []
+    const eventsRecent = events.slice(-10)
+    const lastActivity: SubagentProgressEvent | null = events.length > 0 ? (events[events.length - 1] ?? null) : null
+    const elapsedMs = (entry.completion ? entry.startedAt + entry.completion.durationMs : now) - entry.startedAt
+    return {
+      taskId: entry.taskId,
+      sessionId: entry.sessionId,
+      subagentName: entry.subagentName,
+      status: entry.status,
+      startedAt: entry.startedAt,
+      elapsedMs,
+      eventsCount: events.length,
+      eventsRecent,
+      lastActivity,
+      statusSummary: renderStatusSummary(entry, events.length, lastActivity, elapsedMs),
+      ...(entry.completion ? { completion: entry.completion } : {}),
+    }
+  }
+
+  clear(): void {
+    this.entries.clear()
+    this.events.clear()
+  }
+}
+
+function renderStatusSummary(
+  entry: LiveSubagent,
+  eventsCount: number,
+  lastActivity: SubagentProgressEvent | null,
+  elapsedMs: number,
+): string {
+  const elapsed = formatElapsed(elapsedMs)
+  if (entry.status === 'completed') return `Completed in ${elapsed}.`
+  if (entry.status === 'failed') {
+    const err = entry.completion?.error ?? 'unknown error'
+    return `Failed after ${elapsed}: ${err}`
+  }
+  const last = describeLastActivity(lastActivity)
+  return `Running for ${elapsed}. ${eventsCount} event${eventsCount === 1 ? '' : 's'} so far${last ? `. Last: ${last}` : ''}.`
+}
+
+function describeLastActivity(event: SubagentProgressEvent | null): string | null {
+  if (event === null) return null
+  if (event.kind === 'tool') return `${event.ok ? '' : 'failed '}tool ${event.name}`
+  if (event.kind === 'message') {
+    const preview = event.preview.length > 60 ? `${event.preview.slice(0, 60)}…` : event.preview
+    return `message "${preview}"`
+  }
+  return null
+}
+
+function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const totalSec = Math.floor(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const min = Math.floor(totalSec / 60)
+  const sec = totalSec % 60
+  return `${min}m${sec}s`
+}
+
+export function attachProgressCapture(
+  registry: LiveSubagentRegistry,
+  taskId: string,
+  session: Pick<AgentSession, 'subscribe'>,
+): () => void {
+  const unsubscribe = session.subscribe((event: unknown) => {
+    const coarsened = coarsen(event as AgentSessionEvent, Date.now())
+    if (coarsened !== null) {
+      registry.recordEvent(taskId, coarsened)
+    }
+  })
+  return () => {
+    if (typeof unsubscribe === 'function') unsubscribe()
+  }
+}

package/src/agent/plugin-tools.ts

@@ -16,6 +16,7 @@ import { z } from 'zod'
 
 import {
   ACKNOWLEDGE_GUARDS,
+  checkManagedConfigGuard,
   checkNonWorkspaceWriteGuard,
   checkSkillAuthoringGuard,
 } from '@/bundled-plugins/guard/policy'
@@ -31,15 +32,8 @@ import type {
 } from '@/plugin'
 
 import type { SessionOrigin } from './session-origin'
-
-type AnyAgentTool =
-  | typeof piReadTool
-  | typeof piBashTool
-  | typeof piEditTool
-  | typeof piWriteTool
-  | typeof piGrepTool
-  | typeof piFindTool
-  | typeof piLsTool
+import { webfetchTool } from './tools/webfetch'
+import { websearchTool } from './tools/websearch'
 
 const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   Type.Object(
@@ -50,22 +44,64 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
   ),
 )
 
-const BUILTIN_TOOL_MAP: Record<string, AnyAgentTool> = {
+// `BuiltinToolRef.__builtinTool` strings are dual-routed when a plugin
+// subagent declares them: pi-coding-agent's own coding tools flow through
+// `createAgentSession({ tools: AgentTool[] })` (which pi treats as a strict
+// base-tool override — exactly the declared subset becomes active), and
+// typeclaw's own web tools flow through `customTools: ToolDefinition[]` (the
+// only path pi accepts for non-pi tool definitions). Routing typeclaw tools
+// through `tools:` silently drops them (pi's `tools` validator rejects shapes
+// it doesn't recognize); routing pi tools through `customTools:` would work
+// but ALSO auto-injects pi's default 4 base tools (read/bash/edit/write),
+// widening every plugin subagent's allowlist beyond what it declared. The
+// dual route is the only shape that gives "subagent gets exactly what it
+// asked for, nothing more." See `src/agent/index.ts` `createSessionWithDispose`
+// for the consumer that splits the resolved arrays into the two pi fields.
+type PiAgentToolName = 'read' | 'bash' | 'edit' | 'write' | 'grep' | 'find' | 'ls'
+type TypeclawToolName = 'websearch' | 'webfetch'
+
+const PI_AGENT_TOOL_MAP: Record<PiAgentToolName, AgentTool<any, any>> = {
+  read: piReadTool,
   bash: piBashTool,
   edit: piEditTool,
-  find: piFindTool,
+  write: piWriteTool,
   grep: piGrepTool,
+  find: piFindTool,
   ls: piLsTool,
-  read: piReadTool,
-  write: piWriteTool,
 }
 
-export function resolveBuiltinToolRefs(refs: BuiltinToolRef[]): AnyAgentTool[] {
-  return refs.map((ref) => {
-    const tool = BUILTIN_TOOL_MAP[ref.__builtinTool]
-    if (!tool) throw new Error(`unknown built-in tool ref: ${ref.__builtinTool}`)
-    return tool
-  })
+const TYPECLAW_TOOL_DEFINITION_MAP: Record<TypeclawToolName, ToolDefinition<any, any, any>> = {
+  websearch: websearchTool,
+  webfetch: webfetchTool,
+}
+
+function isPiAgentToolName(name: string): name is PiAgentToolName {
+  return name in PI_AGENT_TOOL_MAP
+}
+
+function isTypeclawToolName(name: string): name is TypeclawToolName {
+  return name in TYPECLAW_TOOL_DEFINITION_MAP
+}
+
+export type ResolvedBuiltinTools = {
+  agentTools: AgentTool<any, any>[]
+  toolDefinitions: ToolDefinition<any, any, any>[]
+}
+
+export function resolveBuiltinToolRefs(refs: BuiltinToolRef[]): ResolvedBuiltinTools {
+  const agentTools: AgentTool<any, any>[] = []
+  const toolDefinitions: ToolDefinition<any, any, any>[] = []
+  for (const ref of refs) {
+    const name = ref.__builtinTool
+    if (isPiAgentToolName(name)) {
+      agentTools.push(PI_AGENT_TOOL_MAP[name])
+    } else if (isTypeclawToolName(name)) {
+      toolDefinitions.push(TYPECLAW_TOOL_DEFINITION_MAP[name])
+    } else {
+      throw new Error(`unknown built-in tool ref: ${name}`)
+    }
+  }
+  return { agentTools, toolDefinitions }
 }
 
 export type WrapToolOptions = {
@@ -274,7 +310,11 @@ function errorResult(message: string) {
 }
 
 async function runFinalWriteGuards(options: { tool: string; args: Record<string, unknown>; agentDir: string }) {
-  return (await checkSkillAuthoringGuard(options)) ?? checkNonWorkspaceWriteGuard(options)
+  return (
+    (await checkManagedConfigGuard(options)) ??
+    (await checkSkillAuthoringGuard(options)) ??
+    checkNonWorkspaceWriteGuard(options)
+  )
 }
 
 function withGuardAcknowledgements<TParams extends TSchema>(toolName: string, parameters: TParams): TParams {

package/src/agent/session-origin.ts

@@ -226,6 +226,21 @@ function renderChannelOrigin(
     'reply, your entire final visible response must be exactly `NO_REPLY`.',
     'Any other visible text without a channel tool call is blocked.',
     '',
+    '**Default to ONE reply per inbound.** Send a second `channel_reply` only',
+    'when the user genuinely benefits from it:',
+    '',
+    '- the user asked multiple distinct things and each deserves its own',
+    '  scoped answer,',
+    '- your reply exceeds the platform message limit and must be chunked,',
+    '- you need to post an attachment AND commentary on it on Discord (on',
+    '  Slack, pass `text` and `attachments` in a single `channel_reply` call),',
+    '- you are emitting progress updates during a long-running task and the',
+    '  channel would otherwise sit silent.',
+    '',
+    'Do NOT send a second reply just to rephrase, restate, summarize, or',
+    '"confirm in plain language" something you already said. After the first',
+    'reply lands, end your turn — the user will respond if they want more.',
+    '',
     'To reply in this conversation, call `channel_reply({ text })`. Addressing',
     `is filled in from this session, including the thread${origin.thread !== null ? '' : ' (none here — this is a channel-root session)'}, so you don't`,
     'need to copy any of these fields:',