@llblab/pi-actors 0.12.0

package/docs/template-recipes.md

@@ -0,0 +1,285 @@
+# Template Recipe Standard
+
+Template recipes are saved JSON definitions around the synchronous [Command Template Standard](./command-templates.md).
+
+**Meta-contract:** a recipe stores a command-template graph plus defaults and run mode. It does not create a second execution language.
+
+**Scope:** reusable JSON shape, recipe naming, file-backed recipes, co-located recipes, recipe-layer imports/references, call-time values, foreground execution, and the `async: true` handoff to the [Async Run Standard](./async-runs.md).
+
+---
+
+## Reading Model
+
+```text
+command template = execution graph
+recipe          = saved JSON definition
+run             = one execution instance
+async: true     = run through detached lifecycle
+```
+
+A recipe wraps one command-template tree. The wrapped `template` keeps the normal command-template semantics: argv splitting, placeholders, defaults, typed args, sequence, `parallel: true`, `when`, delay, retry, failure propagation, recover cleanup, and output selection.
+
+Layer boundary: `imports`, `{ "name": "alias" }` imported-recipe nodes, `{alias.defaults.key}` references, fallback expressions, and recipe-local ternaries are recipe-loading features. They resolve before the command-template graph runs and do not extend the portable Command Template Standard. Typed imports are recipe definitions: they expose the imported recipe's command-template-shaped metadata (`template`, `args`, `defaults`, flags, and `values`), while async-run launch fields such as `async` and `state_dir` remain lifecycle configuration for starting a run, not part of the imported execution graph.
+
+## Layer Ownership
+
+Template-recipe standard owns:
+
+- Saved JSON definitions around one command-template graph.
+- File-backed and co-located recipe shapes.
+- Recipe identity through `name` or filename.
+- Recipe defaults, values, imports, import references, and import-node expansion.
+- Ordered named artifact declarations through `artifacts`.
+- Foreground-vs-detached selection through `async: true` when invoked by a recipe-aware host.
+
+Template-recipe standard does not own:
+
+- How command-template nodes execute internally.
+- Async state files, logs, FIFO, status, cancellation, or observability.
+- Tool registry naming, button UX, package installation, or operator-specific policy.
+- Domain workflows such as swarm quorum, release policy, backlog parsing, or merge policy.
+
+A recipe can be synchronous or asynchronous:
+
+- Omitted or false `async`: a registered tool executes the recipe in the foreground and returns normal tool output.
+- `async: true`: a registered tool starts a detached async run and returns run metadata immediately.
+
+## Minimal Shape
+
+Synchronous recipe:
+
+```json
+{
+  "name": "check-docs",
+  "template": "npm run check:docs"
+}
+```
+
+Async recipe:
+
+```json
+{
+  "name": "review-docs",
+  "async": true,
+  "template": "review docs/spec.md"
+}
+```
+
+`name` names the saved definition when an explicit name is needed. File-backed recipes usually omit it because the filename is the canonical recipe id. `template` is the command-template tree. `async: true` selects detached run mode when the recipe is invoked through a registered tool.
+
+For object form, keep `template` last. Recipe metadata comes first; executable content stays last.
+
+## Named Artifacts
+
+Use recipe-level `artifacts` to declare stable artifact names and paths for the whole recipe, ordered from most important to least important:
+
+```json
+{
+  "name": "report-task",
+  "args": ["report_path:path"],
+  "defaults": { "report_path": "artifacts/report.md" },
+  "artifacts": {
+    "report": "{report_path}",
+    "summary": "artifacts/summary.json"
+  },
+  "template": "generate-report --out {report_path}"
+}
+```
+
+`output` and `artifacts` are intentionally different. `output` is the command-template primary result selector and defaults to stdout; it participates in sequence/stdin flow. `artifacts` is recipe metadata: an ordered named artifact manifest for humans, async completion events, and downstream tooling. `stdout` remains the default command result channel and is not renamed by `artifacts`.
+
+## Mailbox
+
+Use recipe-level `mailbox` to document the semantic messages a recipe actor accepts and emits:
+
+```json
+{
+  "mailbox": {
+    "accepts": ["control.continue", "control.revise", "control.approve", "control.stop"],
+    "emits": ["checkpoint.needs_scope", "branch.done", "run.done"]
+  }
+}
+```
+
+`mailbox` is contract metadata, not transport configuration. It should name semantic message types, not FIFO commands, file paths, or CLI fragments.
+
+## Actor Message Delivery
+
+Recipes do not declare a second event-delivery policy. A running actor emits addressed messages such as `command.done`, `run.done`, or `checkpoint.needs_input`; the coordinator/runtime decides whether a message stays diagnostic, becomes a notification, or re-enters the agent context. This keeps recipe metadata focused on the actor contract:
+
+```json
+{
+  "mailbox": {
+    "accepts": ["control.stop"],
+    "emits": ["command.done", "run.done", "run.failed"]
+  },
+  "template": "run-subtask {prompt}"
+}
+```
+
+## Command-Template Flags At Recipe Top Level
+
+Top-level command-template flags may sit beside `name` and `async`:
+
+```json
+{
+  "name": "review-docs",
+  "async": true,
+  "parallel": true,
+  "timeout": 300000,
+  "failure": "branch",
+  "template": ["review-a docs/spec.md", "review-b docs/spec.md"]
+}
+```
+
+Valid command-template flags include `args`, `defaults`, `parallel`, `when`, `label`, `timeout`, `delay`, `output`, `retry`, `failure`, `recover`, and `repeat`.
+
+Timeout is disabled by default. Set a positive `timeout` when a recipe should fail closed after a bounded runtime; omit it, or set `0`, for intentionally open-ended runs that will be stopped by async cancellation, such as background audio playback.
+
+## Valid Graph
+
+The valid chain is:
+
+```text
+tool → template reference → recipe → run → template
+```
+
+A recipe must define `template` directly. A recipe must not define `tool`, because recipes are saved command-template definitions, not tool indirection layers.
+
+A recipe may live in a file or be co-located inside a registered tool entry. Both are storage variants of the same graph.
+
+## File-Backed Recipes
+
+Reusable local recipes live in:
+
+```text
+~/.pi/agent/recipes/*.json
+```
+
+Bare recipe names resolve under that directory, so `file: "review-docs"` loads:
+
+```text
+~/.pi/agent/recipes/review-docs.json
+```
+
+Call-time params override file params. `values` are merged with file values; call-time values win. If a run id is omitted for an explicit async start, the explicit recipe `name` or file basename becomes the default run id.
+
+## Registered Recipe Tools
+
+A registered tool can point at an actor recipe by storing the recipe path or name in `template`:
+
+```json
+{
+  "shader_ring": {
+    "description": "Start the shader ring recipe",
+    "args": ["theme", "out_dir"],
+    "template": "shader-ring-8-parallel.json"
+  }
+}
+```
+
+If `shader-ring-8-parallel.json` contains `async: true`, calling `shader_ring` starts a detached run and returns metadata. If `async` is omitted or false, calling `shader_ring` executes the recipe foreground and returns normal tool output.
+
+A registered tool may also co-locate an actor recipe directly in `tools.json`:
+
+```json
+{
+  "review_docs": {
+    "description": "Start an async docs review",
+    "name": "review-docs",
+    "async": true,
+    "template": "review {scope}"
+  }
+}
+```
+
+The co-located entry must still own `template` directly and must not define `tool`.
+
+## Values And Public Args
+
+Recipe placeholders come from runtime values, recipe `defaults`, inline placeholder defaults, and registered-tool defaults.
+
+Recipe tools derive public arguments from the referenced or co-located command template when the recipe is available locally. Explicit `args` is still available when the public tool surface should be narrower than the recipe internals.
+
+Example: a recipe may expose a private `repo` default for an example script, while the registered public tool only asks for `file`, `volume`, and `player`.
+
+## Recipe Imports
+
+File-backed recipes may import other file-backed recipes at the recipe layer. Imports are resolved before the command-template graph is executed, so command-template core stays registry-free and synchronous.
+
+```json
+{
+  "name": "parent",
+  "imports": {
+    "prepare": "prepare-worktree.json",
+    "test": {
+      "from": "run-tests.json",
+      "values": { "suite": "unit" }
+    }
+  },
+  "template": [{ "name": "prepare" }, { "name": "test" }]
+}
+```
+
+An import binding may be either a string recipe path/name or an object with:
+
+- `from`: recipe path or bare name.
+- `defaults`: extra default values exposed through the import.
+- `values`: explicit values for embedding that imported recipe.
+
+A template node of `{ "name": "alias" }` is replaced with the imported recipe's command-template graph. Imported recipe defaults are merged with import `defaults`, import `values`, node `defaults`, and node `values`; later layers win. This lets a parent recipe embed a reusable recipe in a sequence or `parallel: true` branch without inventing a workflow language.
+
+Async composition stays explicit: importing a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
+
+```json
+{
+  "name": "parallel-review",
+  "async": true,
+  "imports": {
+    "review": "review-one.json"
+  },
+  "parallel": true,
+  "failure": "branch",
+  "template": [
+    { "name": "review", "values": { "scope": "README.md" } },
+    { "name": "review", "values": { "scope": "docs/template-recipes.md" } }
+  ]
+}
+```
+
+Recipes can also read imported metadata and value containers before command-template placeholder expansion. Each import alias acts like a recipe-local variable:
+
+```json
+{
+  "imports": {
+    "base": {
+      "from": "base.json",
+      "values": { "target": "docs" }
+    }
+  },
+  "defaults": {
+    "profile": "{base.defaults.profile=safe}",
+    "target": "{base.values.target}",
+    "label": "{base.name}:{base.values.target}",
+    "enabled_label": "{base.defaults.enabled?enabled:disabled}"
+  },
+  "template": "run {base.defaults.profile=safe} {base.values.target} {label}"
+}
+```
+
+Supported references are:
+
+- `{alias.name}`
+- `{alias.file}`
+- `{alias.defaults.key}`
+- `{alias.values.key}`
+- `{alias.defaults.key=fallback}` for a missing/null import value fallback.
+- `{alias.values.key?truthy:falsy}` for a small recipe-layer ternary.
+
+Nested object keys are dot-separated. Import references are resolved before normal command-template placeholders, so ordinary values such as `{label}` still flow through command-template defaults and call-time values. Ternaries use simple falsy checks for missing, null, false, zero, and empty string. Missing imports, missing values without fallback, and import cycles fail during recipe loading.
+
+## Recipe Shape
+
+Use `name` for an explicit recipe id, rely on the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` before relying on recipe launchers.
+
+If a proposed recipe needs a scheduler, queue daemon, `goto`, or custom workflow syntax, stop. Keep the recipe as saved command-template JSON and put policy in the registered tool, script, or caller.

package/docs/tool-registry.md

@@ -0,0 +1,142 @@
+# Tool Registry
+
+`pi-actors` stores registered command-template tools and template-recipe launchers in `~/.pi/agent/tools.json` and registers them automatically on session start.
+
+This document is the local adaptation of the portable [Command Template Standard](./command-templates.md).
+
+## Registering Tools
+
+`register_tool` is the interactive API for listing, creating, updating, or deleting persistent tools. Call it without arguments to list registered tools.
+
+```text
+register_tool name=transcribe_groq \
+  description="Transcribe audio files using Groq Whisper API" \
+  template="~/.pi/agent/skills/groq-stt/scripts/transcribe.mjs {file} {lang=ru} {model=whisper-large-v3-turbo}"
+```
+
+```text
+register_tool name=call_subagent \
+  description="Run pi as a non-interactive sub-agent" \
+  template="pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+```
+
+Use `update=true` to overwrite an existing tool. Omit `template` and co-located recipe fields during update to keep the previous execution binding.
+
+`template` may also be a standard command-template sequence for multi-step tools. Timeout is disabled by default; add explicit positive `timeout` values when individual steps should fail closed:
+
+```json
+[
+  "~/bin/tts --text {text} --out {mp3}",
+  { "timeout": 300000, "template": "ffmpeg -y -i {mp3} -c:a libopus {ogg}" }
+]
+```
+
+For reusable workflows, register a small tool whose `template` points to a template recipe instead of embedding a large parallel template in the tool itself:
+
+```text
+register_tool name=shader_ring \
+  description="Start the shader ring recipe" \
+  template="shader-ring-8-parallel.json" \
+  args="theme,out_dir"
+```
+
+This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/shader-ring-8-parallel.json` contains `async: true`, calling the tool starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+
+When co-location is clearer than a separate file, the registry entry may include recipe fields directly beside tool metadata:
+
+```json
+{
+  "review_docs": {
+    "description": "Start an async docs review",
+    "name": "review-docs",
+    "async": true,
+    "template": "pi -p --model openai-codex/gpt-5.5 --tools read,bash \"Review {scope}\""
+  }
+}
+```
+
+This is still not a cycle: `name` names the saved definition when it differs from the tool key, `async: true` selects detached run mode, and `template` remains the executable body. Co-located recipe entries must not define `tool`.
+
+Delete a tool with `template=null`:
+
+```text
+register_tool name=call_subagent template=null
+```
+
+## Stored Shape
+
+Tool names come from the top-level registry keys. Tool entries define `template`; it may be an inline command template, a template recipe JSON path/name, or the body of a co-located template recipe when `async` or entry-local `name` is present. Template entries keep `template` last, matching the command-template readability rule. The commands above persist entries like this:
+
+```json
+{
+  "transcribe_groq": {
+    "description": "Transcribe audio files using Groq Whisper API",
+    "template": "~/.pi/agent/skills/groq-stt/scripts/transcribe.mjs {file} {lang=ru} {model=whisper-large-v3-turbo}"
+  },
+  "call_subagent": {
+    "description": "Run pi as a non-interactive sub-agent",
+    "template": "pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+  },
+  "shader_ring": {
+    "description": "Start the shader ring recipe",
+    "args": ["theme", "out_dir"],
+    "template": "shader-ring-8-parallel.json"
+  }
+}
+```
+
+## Args and Defaults
+
+When `args` is omitted, `pi-actors` derives tool parameters from placeholders in `template`:
+
+```text
+template="~/bin/transcribe {file} {lang=ru} {model=whisper-large-v3-turbo}"
+```
+
+The optional `args` field is an explicit placeholder declaration, matching the command-template standard. Untyped declarations remain valid:
+
+```json
+{ "args": ["file", "lang"] }
+```
+
+Typed declarations are progressive and compact; they improve generated tool schemas and runtime validation without requiring authors to write JSON Schema. Types can be declared either in `args` or directly on template placeholders.
+
+Use the metadata-first style when the command line is long and readability benefits from keeping the executable string short:
+
+```json
+{
+  "args": [
+    "file:path",
+    "out_dir:path",
+    "request_timeout:int",
+    "speed:number",
+    "dry_run:bool",
+    "mode:enum(check,fix)"
+  ],
+  "defaults": {
+    "timeout": "60000",
+    "speed": "1.5",
+    "dry_run": "true",
+    "mode": "check"
+  },
+  "template": "tool --file {file} --out {out_dir} --timeout {request_timeout} --speed {speed} --dry-run {dry_run} --mode {mode}"
+}
+```
+
+Use the inline-first style when a compact tool is clearer as one self-contained template:
+
+```text
+template="tool --file {file:path} --out {out_dir:path} --timeout {request_timeout:int=60000} --speed {speed:number=1.5} --dry-run {dry_run:bool=true} --mode {mode:enum(check,fix)=check}"
+```
+
+Supported compact types are `string` (implicit), `path`, `int`, `number`, `bool`, and `enum(a,b)`. Defaults should be stored in `defaults`, written inline as `{name=default}`, or supplied through interactive shorthand. Shorthand such as `args="file,lang=ru"` and typed shorthand such as `request_timeout:int=60000` are normalized before persistence. When both `args` and template placeholders provide a type for the same name, explicit `args` wins.
+
+Defaults are applied before substitution, with resolution order runtime values → stored `defaults` → inline default → error. Missing required values are rejected before or during execution. Typed runtime values are normalized before substitution: `int` and `number` values become numeric strings, booleans become `true`/`false`, and enums must match one of the declared values.
+
+Template recipe tools derive public arguments from the referenced or co-located command template when the recipe is available locally. Explicit `args` is still available when the public tool surface should be narrower or defaulted differently, or when a file-backed recipe is not available during registration. Runtime values are passed as `values`; async recipe tools also accept optional `run_id` to override the generated run id.
+
+## File Argument Naming
+
+For tools that accept a local file path, use `file` as the canonical argument name.
+
+Avoid using `filename` for full paths. `filename` usually means a basename/display name, while `file` can represent a concrete local file path.

package/index.ts

@@ -0,0 +1,198 @@
+/**
+ * pi-actors — actor runtime and persistent local tool registry for pi.
+ * Zones: composition root, pi agent, actor runtime
+ *
+ * Wraps command templates as callable pi tools, stores their definitions in tools.json, and exposes actor orchestration across reloads and sessions.
+ */
+
+import { existsSync, readdirSync, watch, type FSWatcher } from "node:fs";
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import * as CommandTemplates from "./lib/command-templates.ts";
+import * as Observability from "./lib/observability.ts";
+import * as Paths from "./lib/paths.ts";
+import * as Prompts from "./lib/prompts.ts";
+import * as Runtime from "./lib/runtime.ts";
+import * as Temp from "./lib/temp.ts";
+import * as Tools from "./lib/tools.ts";
+
+const CONFIG_PATH = Paths.getConfigPath();
+const TEMP_DIR = Paths.getExtensionTmpDir();
+const RUN_STATE_ROOT = Paths.getRunStateRoot();
+const RESERVED_TOOL_NAMES = new Set([
+  "read",
+  "write",
+  "edit",
+  "bash",
+  "find",
+  "grep",
+  "ls",
+  "register_tool",
+  "message",
+  "spawn",
+  "inspect",
+]);
+
+export default function toolRegistryExtension(pi: ExtensionAPI) {
+  let runsAnimationInterval: NodeJS.Timeout | undefined;
+  let runsNotifyTimeout: NodeJS.Timeout | undefined;
+  let stateRootWatcher: FSWatcher | undefined;
+  const runDirWatchers = new Map<string, FSWatcher>();
+  const observedRuns = new Map<string, Observability.RunObservedStatus>();
+  const observedRunEventLines = new Map<string, number>();
+  let runStatusFrame = 0;
+  const getRunOwnerId = (ctx: ExtensionContext): string =>
+    ctx.sessionManager.getSessionId();
+  const updateRunUi = (ctx: ExtensionContext, notify = false): void => {
+    const ownerId = getRunOwnerId(ctx);
+    const summary = Observability.summarizeRuns(undefined, ownerId);
+    const status = Observability.renderRunStatus(summary, runStatusFrame++);
+    ctx.ui.setStatus(
+      "zz-pi-actors-runs",
+      status ? ctx.ui.theme.fg("dim", status) : undefined,
+    );
+    ctx.ui.setWidget("zz-pi-actors-runs", undefined);
+    const transitions = Observability.detectRunTransitions(
+      observedRuns,
+      summary,
+    );
+    const outboxEvents = Observability.detectRunOutboxEvents(
+      observedRunEventLines,
+      summary,
+    );
+    if (!notify) return;
+    for (const transition of transitions) {
+      if (!Observability.shouldNotifyRunTransition(transition)) continue;
+      const text = Observability.formatRunTransitionMessage(transition);
+      const notificationType =
+        Observability.getRunTransitionNotificationType(transition);
+      ctx.ui.notify(text, notificationType);
+      if (!Observability.shouldSendRunTransitionFollowUp(transition)) continue;
+      pi.sendMessage(
+        {
+          customType: "pi-actors-run",
+          content: text,
+          display: true,
+          details: transition,
+        },
+        { deliverAs: "followUp", triggerTurn: true },
+      );
+    }
+    for (const event of outboxEvents) {
+      if (!Observability.shouldNotifyRunOutboxEvent(event)) continue;
+      const text = Observability.formatRunOutboxMessage(event);
+      const notificationType =
+        Observability.getRunOutboxNotificationType(event);
+      ctx.ui.notify(text, notificationType);
+      if (!Observability.shouldSendRunOutboxFollowUp(event)) continue;
+      pi.sendMessage(
+        {
+          customType: "pi-actors-run-message",
+          content: text,
+          display: true,
+          details: event,
+        },
+        { deliverAs: "followUp", triggerTurn: true },
+      );
+    }
+  };
+  const closeRunWatchers = (): void => {
+    stateRootWatcher?.close();
+    stateRootWatcher = undefined;
+    for (const watcher of runDirWatchers.values()) watcher.close();
+    runDirWatchers.clear();
+    if (runsNotifyTimeout) clearTimeout(runsNotifyTimeout);
+    runsNotifyTimeout = undefined;
+  };
+  const scheduleRunEventUpdate = (ctx: ExtensionContext): void => {
+    if (runsNotifyTimeout) clearTimeout(runsNotifyTimeout);
+    runsNotifyTimeout = setTimeout(() => {
+      refreshRunWatchers(ctx);
+      updateRunUi(ctx, true);
+    }, 50);
+    runsNotifyTimeout.unref?.();
+  };
+  const watchRunDir = (ctx: ExtensionContext, stateDir: string): void => {
+    if (runDirWatchers.has(stateDir) || !existsSync(stateDir)) return;
+    try {
+      const watcher = watch(stateDir, () => scheduleRunEventUpdate(ctx));
+      watcher.on("error", () => {
+        watcher.close();
+        runDirWatchers.delete(stateDir);
+      });
+      runDirWatchers.set(stateDir, watcher);
+    } catch {
+      // Watching is best-effort; explicit inspect remains available.
+    }
+  };
+  function refreshRunWatchers(ctx: ExtensionContext): void {
+    if (!existsSync(RUN_STATE_ROOT)) return;
+    if (!stateRootWatcher) {
+      try {
+        stateRootWatcher = watch(RUN_STATE_ROOT, () => scheduleRunEventUpdate(ctx));
+        stateRootWatcher.on("error", () => {
+          stateRootWatcher?.close();
+          stateRootWatcher = undefined;
+        });
+      } catch {
+        // Watching is best-effort; explicit inspect remains available.
+      }
+    }
+    for (const entry of readdirSync(RUN_STATE_ROOT, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      watchRunDir(ctx, `${RUN_STATE_ROOT}/${entry.name}`);
+    }
+  }
+  const actorToolDefinitions = new Map<string, any>();
+  const runtime = Runtime.createAutoToolsRuntime({
+    configPath: CONFIG_PATH,
+    exec: CommandTemplates.execCommandTemplate,
+    getAllTools: () => pi.getAllTools(),
+    registerTool: (definition) => {
+      actorToolDefinitions.set(definition.name, definition);
+      pi.registerTool(definition);
+    },
+    reservedToolNames: RESERVED_TOOL_NAMES,
+  });
+  pi.on("session_start", async (_event, ctx) => {
+    await Temp.prepareExtensionTempDir(TEMP_DIR);
+    runtime.loadTools(ctx);
+    updateRunUi(ctx);
+    closeRunWatchers();
+    refreshRunWatchers(ctx);
+    if (runsAnimationInterval) clearInterval(runsAnimationInterval);
+    runsAnimationInterval = setInterval(() => updateRunUi(ctx, false), 1000);
+    runsAnimationInterval.unref?.();
+  });
+  pi.on("session_shutdown", async () => {
+    if (runsAnimationInterval) clearInterval(runsAnimationInterval);
+    runsAnimationInterval = undefined;
+    closeRunWatchers();
+  });
+  pi.on("before_agent_start", async (event) => ({
+    systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
+  }));
+  pi.registerTool(
+    Tools.createRegisterToolDefinition<ExtensionContext>({
+      configPath: CONFIG_PATH,
+      getActiveTools: () => pi.getActiveTools(),
+      getExternalToolConflict: runtime.getExternalToolConflict,
+      getTools: runtime.getTools,
+      notify: runtime.notify,
+      registerRuntimeTool: runtime.registerRuntimeTool,
+      reservedToolNames: RESERVED_TOOL_NAMES,
+      setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
+    }),
+  );
+  pi.registerTool(Tools.createSpawnToolDefinition<ExtensionContext>());
+  pi.registerTool(
+    Tools.createActorMessageToolDefinition<ExtensionContext>({
+      getTool: (name) => actorToolDefinitions.get(name),
+    }),
+  );
+  pi.registerTool(Tools.createInspectToolDefinition());
+}