@llblab/pi-actors 0.45.0 → 0.46.0

package/docs/template-recipes.md

@@ -10,7 +10,7 @@ A Recipe stores a reusable command-template definition as JSON or Markdown.
   "description": "Create a repository health artifact",
   "args": ["repo:path", "artifact_path:path", "model:string"],
   "defaults": { "artifact_path": "{state_dir}/health.md" },
-  "imports": { "review": "subagent-review.json" },
+  "imports": { "review": "swarm/quorum-review" },
   "artifacts": { "report": "{artifact_path}" },
   "template": {
     "name": "review",
@@ -39,11 +39,13 @@ summarize {file}
 
 Fences marked `template`, `command-template`, `json`, or `recipe` can define execution. Frontmatter supports Recipe metadata and command-template flags.
 
+Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; both JSON and Markdown fail with migration guidance when that removed field is present. `SKILL.md` `name` remains Pi host metadata and matches the Skill directory; pi-actors introduces no additional Skill identity field. The `name` field on a command-template node still selects an imported alias and is not Recipe self-identity.
+
 ## Fields
 
 Common Recipe fields:
 
-- `name`, `description`, `disabled`;
+- `description`, `disabled`;
 - `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
 - `imports` with optional binding defaults/values;
 - `template`;
@@ -58,25 +60,39 @@ Common Recipe fields:
 ```json
 {
   "imports": {
-    "review": "subagent-review.json",
-    "verify": {
-      "from": "subagent-verify.json",
+    "review": "swarm/quorum-review",
+    "report": {
+      "from": "../shared/report.md",
       "defaults": { "thinking": "medium" }
     }
   },
   "template": [
     { "name": "review", "values": { "input": "{input}" } },
-    { "name": "verify", "values": { "input": "Use prior output" } }
+    { "name": "report", "values": { "input": "Use prior output" } }
   ]
 }
 ```
 
 Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Effective values follow `caller > node/import/Recipe values > defaults > inline arg default > missing-value error`, then the selected value is checked against its declared type or enum.
 
-Bare references preserve user → adjacent → packaged resolution. `std:<name>` selects a packaged Recipe exactly. `skill:<skill-name>/<recipe-path>` selects a component under the `recipes/` tree of a Skill currently active through Pi resource discovery. Skill Recipes never become tools merely by existing, and duplicate active Skill names fail as ambiguous rather than shadowing silently.
+Imports accept exactly `<skill>/<recipe>` or an explicit `.json` / `.md` file path. A Skill reference selects one direct filename stem under the exact Skill currently active through Pi resource discovery; duplicate active Skill identities and JSON/Markdown stem collisions fail closed. Explicit paths may be relative (`./local-review.json`, `../shared/report.md`) or absolute (`/absolute/path/to/recipe.json`). An entry file path resolves from invocation `cwd`; a relative import resolves from the importing Recipe's directory. No bare or ambient lookup remains.
 
 Direct delegation can use another Recipe as the entire template. The delegated Recipe remains the source of truth while the wrapper may narrow args/defaults or override selected lifecycle metadata.
 
+A launched Run captures each entry/import role, filename-derived stem, logical reference, Skill identity when owned, and import alias ancestry. Private physical source paths remain execution provenance; Inspector and child-agent context expose logical identities rather than machine-local Skill locations.
+
+## Migration from pre-0.46 references
+
+```text
+std:foo              -> owning-skill/foo
+skill:foo/bar        -> foo/bar
+root packaged foo    -> owning-skill/new-file-stem
+Recipe name field    -> delete; filename is identity
+nested skill path    -> flatten filename or use explicit file path
+```
+
+Removed `std:` and `skill:` forms fail with migration guidance; they are not aliases. Root packaged Recipes no longer exist. Flatten a maintained Skill component to a direct filename, or reference a nested/local file explicitly when it is intentionally outside the Skill component namespace.
+
 ## Control
 
 Only a process that consumes actor-local input declares actions:
@@ -85,7 +101,7 @@ Only a process that consumes actor-local input declares actions:
 {
   "async": true,
   "control": ["pause", "resume", "stop"],
-  "template": "{repo}/scripts/service.mjs --state-dir {state_dir}"
+  "template": "{skill_dir}/scripts/service.mjs --state-dir {state_dir}"
 }
 ```
 
@@ -110,7 +126,7 @@ Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an ac
 
 ## Context and Provenance
 
-File-backed Runs capture Recipe context records for the entry and imports, including qualified `std:` or `skill:` identity when applicable. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
+File-backed Runs capture Recipe context records for the entry and imports. File identity is the filename stem; a direct Recipe under an active Skill has the logical identity `<skill>/<stem>`. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
 
 Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
 
@@ -129,18 +145,18 @@ Defaults can inherit current Pi policy:
 
 Resolution fails before launch when required current policy is unavailable. The Run persists whether values were inherited or explicit.
 
-## Resolution and Shadowing
+## Resolution Context
 
-User Recipes under `~/.pi/agent/recipes` take priority over adjacent and packaged Recipes for compatible bare lookup. Exact `std:` and `skill:` references bypass that ambiguous space. The active Skill namespace converges from Pi's loaded Skill metadata on startup/reload; pi-actors does not scan ambient Skill roots independently. An invalid active file blocks fallback and reports both paths. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives an immutable active-Skill resolution context from Pi's loaded Skill metadata; pi-actors does not scan ambient Skill roots independently or keep a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
 
 ## Validation
 
 ```bash
-node scripts/validate-recipe.mjs recipes/example.json --qa
-node scripts/validate-recipe.mjs recipes --all --qa --summary
+node skills/actors/scripts/validate-recipe.mjs path/to/recipe.json --qa
+node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary
 ```
 
-Validation checks JSON/Markdown compilation, imports, Control, artifacts, helper paths, and platform notes. Files exceed 1 MiB or import depth 32 fail closed.
+Skill validation recursively inventories every direct `<skill>/recipes/*.json|*.md` component, rejects nested files and duplicate stems, and checks filename identity, JSON/Markdown compilation, origins, imports, Control, artifacts, portable paths, helper targets, and platform notes. Files exceeding 1 MiB or import depth 32 fail closed.
 
 ## Related
 

package/docs/tool-registry.md

@@ -22,7 +22,7 @@ Promote an immutable captured draft only with its draft path and explicit target
 
 ## Resolution
 
-User Recipes take priority over packaged Recipes. Active invalid or disabled shadowing blocks fallback and reports both paths. Runtime reload watches the Recipe root and converges after atomic changes; stale watcher generations cannot replace current registration state.
+User Recipes are the only file-discovered tool source. Invalid or disabled user entries fail closed. Active Skill Recipes remain exact components outside tool discovery. Runtime reload watches the user Recipe root and converges after atomic changes; stale watcher generations cannot replace current registration state.
 
 Inspect registry state with:
 
@@ -61,7 +61,7 @@ Usage and lineage live in locked metadata ledgers rather than authored Recipe fi
 
 ## Wrapping Existing Recipes
 
-Prefer a small user-root wrapper that imports a maintained Recipe by exact `std:<recipe>` or `skill:<skill>/<recipe-path>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
+Prefer a small user-root wrapper that imports a maintained Recipe by exact `<skill>/<recipe>` identity and delegates by alias. Skill Recipes remain components and are never exposed merely because their Skill is active. Do not duplicate executable templates, defaults, Control declarations, artifacts, or runtime-owned `{recipe_dir}`/`{skill_dir}`. Install only specific capabilities; internal automatic-review Recipes must not become user-callable tools.
 
 ## Safety
 

package/fixtures/protocol/recipe-summary.json

@@ -1,6 +1,6 @@
 {
   "id": "music-player",
-  "path": "recipes/music-player.json",
+  "path": "skills/media/recipes/player.json",
   "location": "packaged",
   "active": true,
   "args": ["repo", "command", "source", "loop", "volume", "player", "state_dir"],

package/index.ts

@@ -1,124 +1,30 @@
 /**
  * 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 durable user tools as recipe files, and exposes actor orchestration across reloads and sessions.
+ * Owns extension composition and Pi event registration, not domain behavior.
  */
 
-import * as AutomaticReviewRuntime from "./lib/automatic-review-runtime.ts";
-import * as CommandTemplates from "./lib/command-templates.ts";
+import * as ExtensionRuntime from "./lib/extension-runtime.ts";
 import * as InspectorCommand from "./lib/inspector-command.ts";
-import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
-import * as Prompts from "./lib/prompts.ts";
-import * as RecipesReferences from "./lib/recipes-references.ts";
-import * as RunUiRuntime from "./lib/run-ui-runtime.ts";
-import * as Runtime from "./lib/runtime.ts";
-import * as Temp from "./lib/temp.ts";
-import * as Tools from "./lib/tools.ts";
-import * as ToolsResponse from "./lib/tools-response.ts";
 
 export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
-  let activeRunContext: Pi.ExtensionContext | undefined;
-  const getRunOwnerId = Pi.getSessionId;
-  const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
-    getActiveContext: () => activeRunContext,
-    getRunOwnerId,
-    getThinkingLevel: () => pi.getThinkingLevel(),
-  });
-  const runUiRuntime = RunUiRuntime.createRunUiRuntime({
-    getActiveContext: () => activeRunContext,
-    getRunOwnerId,
-    onRunEvent: automaticReview.schedule,
-    pi,
-  });
-  const actorToolDefinitions = new Map<string, Tools.ActorToolDefinition>();
-  const withCurrentThinkingContext = <T extends Tools.ActorToolDefinition>(
-    definition: T,
-  ): T => {
-    if (typeof definition.execute !== "function") return definition;
-    const execute = definition.execute as (...args: unknown[]) => unknown;
-    return {
-      ...definition,
-      execute: async (...args: unknown[]) => {
-        const nextArgs = [...args];
-        const ctx = nextArgs[4];
-        if (ctx && typeof ctx === "object") {
-          nextArgs[4] = {
-            ...(ctx as Record<string, unknown>),
-            getThinkingLevel: () => pi.getThinkingLevel(),
-          };
-        }
-        try {
-          return ToolsResponse.spaceToolResult(await execute(...nextArgs));
-        } catch (error) {
-          throw ToolsResponse.spaceToolError(error);
-        }
-      },
-    } as T;
-  };
-  const runtime = Runtime.createAutoToolsRuntime({
-    configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
-    exec: CommandTemplates.execCommandTemplate,
-    getActiveTools: () => pi.getActiveTools(),
-    registerTool: (definition) => {
-      const wrapped = withCurrentThinkingContext(definition);
-      actorToolDefinitions.set(wrapped.name, wrapped);
-      pi.registerTool(wrapped);
-    },
-    reservedToolNames: Tools.RESERVED_TOOL_NAMES,
-    setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
-  });
-  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
-  pi.on("resources_discover", async () => {
-    const skillPaths = Paths.getExistingExtensionSkillPaths(import.meta.url);
-    if (skillPaths.length === 0) return;
-    return { skillPaths };
-  });
-  pi.on("session_start", async (_event, ctx) => {
-    // Clear the pre-overlay widget after hot reloads from older pi-actors builds.
-    ctx.ui.setWidget("zz-pi-actors-comms", undefined);
-    activeRunContext = ctx;
-    runUiRuntime.close();
-    automaticReview.close();
-    recipeReload.close();
-    await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
-    if (activeRunContext !== ctx) return;
-    automaticReview.start(ctx);
-    runtime.loadTools(ctx);
-    runUiRuntime.start(ctx);
-    recipeReload.watch(ctx);
-  });
-  pi.on("agent_end", async (_event, ctx) => {
-    if (activeRunContext === ctx) automaticReview.schedule();
-  });
-  pi.on("session_shutdown", async (event, ctx) => {
-    activeRunContext = undefined;
-    automaticReview.close();
-    recipeReload.close();
-    runUiRuntime.shutdown(event.reason, ctx);
-  });
-  InspectorCommand.registerActorInspectorCommand(pi, getRunOwnerId);
-  pi.on("before_agent_start", async (event) => {
-    RecipesReferences.setActiveSkillRecipeSources(
+  const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
+  pi.on("resources_discover", async () =>
+    runtime.discoverResources(import.meta.url),
+  );
+  pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
+  pi.on("agent_end", async (_event, ctx) => runtime.onAgentEnd(ctx));
+  pi.on("session_shutdown", async (event, ctx) =>
+    runtime.onSessionShutdown(event.reason, ctx),
+  );
+  pi.on("before_agent_start", async (event, ctx) =>
+    runtime.beforeAgentStart(
+      event.systemPrompt,
       event.systemPromptOptions.skills ?? [],
-    );
-    return {
-      systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
-    };
-  });
-  Pi.registerToolDefinitions(
-    pi,
-    Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
-      configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
-      getActiveTools: () => pi.getActiveTools(),
-      getRuntimeTool: (name) =>
-        Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) =>
-          actorToolDefinitions.get(activeName),
-        ),
-      handleRuntimeControl: automaticReview.handleControl,
-      registryRuntime: runtime,
-      setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
-    }).map(withCurrentThinkingContext),
+      ctx,
+    ),
   );
+  InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);
+  runtime.registerCoreTools();
 }

package/lib/async-runs.ts

@@ -259,11 +259,23 @@ function assertNoActiveRunState(stateDir: string): void {
   RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
 
-function resolveRecipeFile(file: string): string {
-  return (
-    RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
-    RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
-    RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot())
+export interface AsyncRunStartOptions {
+  skillContext?: RecipesReferences.ActiveSkillRecipeContext;
+}
+
+function resolveRecipeFile(
+  file: string,
+  cwd: string,
+  options: AsyncRunStartOptions,
+): string {
+  const path = RecipesReferences.resolveRecipeReferencePath(
+    file,
+    cwd,
+    options.skillContext,
+  );
+  if (path) return path;
+  throw new Error(
+    `Recipe reference not found. Use <skill>/<recipe> or an explicit .json/.md file path: ${file}`,
   );
 }
 
@@ -274,13 +286,18 @@ function isMutableUsageRecipeFile(file: string): boolean {
   return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
 }
 
-function readRecipeFile(file: string): AsyncRunStartParams {
-  const path = resolveRecipeFile(file);
+function readRecipeFile(
+  file: string,
+  cwd: string,
+  options: AsyncRunStartOptions,
+): AsyncRunStartParams {
+  const path = resolveRecipeFile(file, cwd, options);
   const raw = RecipesReferences.readRawRecipeConfig(path);
   const includeActorRecipeContext =
     raw?.actor_context !== false && raw?.actor_context !== "off";
   const config = RecipesReferences.readResolvedRecipeConfig(path, [], {
     includeActorRecipeContext,
+    skillContext: options.skillContext,
   });
   if (!config) {
     throw new Error(`Template recipe must define template: ${path}`);
@@ -301,9 +318,13 @@ function getRunIdFromFile(file: string | undefined): string | undefined {
   return name || undefined;
 }
 
-function resolveStartParams(params: AsyncRunStartParams): AsyncRunStartParams {
+function resolveStartParams(
+  params: AsyncRunStartParams,
+  cwd: string,
+  options: AsyncRunStartOptions,
+): AsyncRunStartParams {
   if (!params.file) return params;
-  const fileParams = readRecipeFile(params.file);
+  const fileParams = readRecipeFile(params.file, cwd, options);
   return {
     ...fileParams,
     ...params,
@@ -468,25 +489,15 @@ function prepareStateDirForStart(stateDir: string): void {
 export function startRun(
   params: AsyncRunStartParams,
   cwd: string,
+  options: AsyncRunStartOptions = {},
 ): AsyncRunMeta {
-  const startParams = resolveStartParams(params);
+  const startParams = resolveStartParams(params, cwd, options);
   const resolved = resolveRunTemplate(startParams);
   const run = safeRunId(startParams.run_id);
   const stateDir = resolveStateDir(startParams, run);
   const recipeFile = startParams.file
-    ? resolveRecipeFile(startParams.file)
+    ? resolveRecipeFile(startParams.file, cwd, options)
     : undefined;
-  const packagedRecipeRoot = resolve(Paths.getPackagedRecipeRoot());
-  const recipeRelation = recipeFile
-    ? relative(packagedRecipeRoot, recipeFile)
-    : undefined;
-  const packagedRepo =
-    startParams.defaults?.repo === "~/.pi/agent/extensions/pi-actors" &&
-    recipeRelation &&
-    !recipeRelation.startsWith("..") &&
-    !isAbsolute(recipeRelation)
-      ? dirname(packagedRecipeRoot)
-      : undefined;
   const argSpec = Schema.parseToolArgDeclarationList(startParams.args ?? []);
   if (argSpec.error) throw new Error(argSpec.error);
   const declaredArgs = new Set(argSpec.args);
@@ -498,7 +509,6 @@ export function startRun(
     {
       ...argSpec.defaults,
       ...(startParams.defaults || {}),
-      ...(packagedRepo ? { repo: packagedRepo } : {}),
       ...(startParams.values || {}),
       run_id: run,
       state_dir: stateDir,
@@ -546,7 +556,20 @@ export function startRun(
       startParams.actor_context !== "off";
     const recipeContextRecords =
       recipeFile && includeActorRecipeContext
-        ? RecipesReferences.buildRecipeContextRecords(recipeFile)
+        ? RecipesReferences.buildRecipeContextRecords(
+            recipeFile,
+            options.skillContext,
+          ).map((record, index) =>
+            index === 0 &&
+            startParams.launch_source === "tool" &&
+            record.source_kind === "explicit_file_recipe"
+              ? {
+                  ...record,
+                  logical_reference: record.name,
+                  source_kind: "user_registry_capability" as const,
+                }
+              : record,
+          )
         : undefined;
     if (
       recipeFile &&

package/lib/automatic-review-runtime.ts

@@ -4,13 +4,14 @@
  * Owns automatic-review lifecycle wiring without owning review decisions or filesystem transactions.
  */
 
-import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as DraftSleep from "./draft-sleep.ts";
 import * as ModelContext from "./model-context.ts";
 import * as Paths from "./paths.ts";
 import type * as Pi from "./pi.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import * as ReviewControl from "./review-control.ts";
 import * as ToolReviewScheduler from "./tool-review-scheduler.ts";
 
@@ -27,6 +28,16 @@ export interface AutomaticReviewRuntimeDeps {
   getThinkingLevel(): unknown;
 }
 
+export const PACKAGE_RECIPE_MEMORY_CONTEXT =
+  RecipesReferences.createActiveSkillRecipeContext([
+    {
+      name: "recipe-memory",
+      filePath: fileURLToPath(
+        new URL("../skills/recipe-memory/SKILL.md", import.meta.url),
+      ),
+    },
+  ]);
+
 export function createAutomaticReviewRuntime(
   deps: AutomaticReviewRuntimeDeps,
 ): AutomaticReviewRuntime {
@@ -88,7 +99,7 @@ export function createAutomaticReviewRuntime(
           }
           return AsyncRuns.startRun(
             {
-              file: join(Paths.getPackagedRecipeRoot(), "draft-review.json"),
+              file: "recipe-memory/draft-review",
               launch_source: "tool",
               notification_policy: "silent",
               ownerId: deps.getRunOwnerId(ctx),
@@ -97,6 +108,7 @@ export function createAutomaticReviewRuntime(
               values: { input_path: batch.reviewerInputPath },
             },
             ctx.cwd,
+            { skillContext: PACKAGE_RECIPE_MEMORY_CONTEXT },
           );
         },
         process: (state) =>
@@ -113,7 +125,7 @@ export function createAutomaticReviewRuntime(
           }
           return AsyncRuns.startRun(
             {
-              file: join(Paths.getPackagedRecipeRoot(), "tool-review.json"),
+              file: "recipe-memory/tool-review",
               launch_source: "tool",
               notification_policy: "silent",
               ownerId: deps.getRunOwnerId(ctx),
@@ -122,6 +134,7 @@ export function createAutomaticReviewRuntime(
               values: { input_path: batch.reviewerInputPath },
             },
             ctx.cwd,
+            { skillContext: PACKAGE_RECIPE_MEMORY_CONTEXT },
           );
         },
         process: (state) =>

package/lib/draft-sleep.ts

@@ -96,7 +96,6 @@ function readState(path: string): DraftSleepState | undefined {
 function defaultActiveTools(recipeRoot: string): DraftReviewActiveTool[] {
   const discovered = RecipesDiscovery.discoverRecipeSources([
     { root: recipeRoot, defaultTool: true, mutableUsage: true },
-    { root: Paths.getPackagedRecipeRoot() },
   ]);
   return [...discovered.active.values()]
     .filter((entry) => existsSync(entry.path))

package/lib/extension-runtime.ts

@@ -0,0 +1,158 @@
+/**
+ * Pi actor extension runtime coordinator.
+ * Zones: extension session lifecycle, host tool adaptation, runtime service composition
+ * Owns low-level Pi lifecycle effects and tool wrapping without owning event registration.
+ */
+
+import * as AutomaticReviewRuntime from "./automatic-review-runtime.ts";
+import * as CommandTemplates from "./command-templates.ts";
+import * as Paths from "./paths.ts";
+import * as Pi from "./pi.ts";
+import * as Prompts from "./prompts.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import * as RunUiRuntime from "./run-ui-runtime.ts";
+import * as Runtime from "./runtime.ts";
+import * as Temp from "./temp.ts";
+import * as Tools from "./tools.ts";
+import * as ToolsResponse from "./tools-response.ts";
+
+export interface ActorExtensionRuntime {
+  beforeAgentStart(
+    systemPrompt: string,
+    skills: RecipesReferences.ActiveSkillRecipeSource[],
+    ctx: Pi.ExtensionContext,
+  ): { systemPrompt: string };
+  discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
+  getRunOwnerId(ctx: Pi.ExtensionContext): string;
+  onAgentEnd(ctx: Pi.ExtensionContext): void;
+  onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
+  onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
+  registerCoreTools(): void;
+}
+
+export function createActorExtensionRuntime(
+  pi: Pi.ExtensionAPI,
+): ActorExtensionRuntime {
+  let activeRunContext: Pi.ExtensionContext | undefined;
+  const skillContextsBySession = new Map<
+    string,
+    RecipesReferences.ActiveSkillRecipeContext
+  >();
+  const getRunOwnerId = Pi.getSessionId;
+  const getSkillContext = (ctx: Pi.ExtensionContext) =>
+    skillContextsBySession.get(getRunOwnerId(ctx)) ??
+    RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+  const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
+    getActiveContext: () => activeRunContext,
+    getRunOwnerId,
+    getThinkingLevel: () => pi.getThinkingLevel(),
+  });
+  const runUiRuntime = RunUiRuntime.createRunUiRuntime({
+    getActiveContext: () => activeRunContext,
+    getRunOwnerId,
+    onRunEvent: automaticReview.schedule,
+    pi,
+  });
+  const actorToolDefinitions = new Map<string, Tools.ActorToolDefinition>();
+  const withCurrentThinkingContext = <T extends Tools.ActorToolDefinition>(
+    definition: T,
+  ): T => {
+    if (typeof definition.execute !== "function") return definition;
+    const execute = definition.execute as (...args: unknown[]) => unknown;
+    return {
+      ...definition,
+      execute: async (...args: unknown[]) => {
+        const nextArgs = [...args];
+        const ctx = nextArgs[4];
+        if (ctx && typeof ctx === "object") {
+          nextArgs[4] = {
+            ...(ctx as Record<string, unknown>),
+            activeSkillRecipeContext: getSkillContext(
+              ctx as Pi.ExtensionContext,
+            ),
+            getThinkingLevel: () => pi.getThinkingLevel(),
+          };
+        }
+        try {
+          return ToolsResponse.spaceToolResult(await execute(...nextArgs));
+        } catch (error) {
+          throw ToolsResponse.spaceToolError(error);
+        }
+      },
+    } as T;
+  };
+  const runtime = Runtime.createAutoToolsRuntime({
+    configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
+    exec: CommandTemplates.execCommandTemplate,
+    getActiveTools: () => pi.getActiveTools(),
+    registerTool: (definition) => {
+      const wrapped = withCurrentThinkingContext(definition);
+      actorToolDefinitions.set(wrapped.name, wrapped);
+      pi.registerTool(wrapped);
+    },
+    reservedToolNames: Tools.RESERVED_TOOL_NAMES,
+    setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
+  });
+  const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
+  return {
+    beforeAgentStart(systemPrompt, skills, ctx) {
+      skillContextsBySession.set(
+        getRunOwnerId(ctx),
+        RecipesReferences.createActiveSkillRecipeContext(skills),
+      );
+      return {
+        systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
+      };
+    },
+    discoverResources(metaUrl) {
+      const skillPaths = Paths.getExistingExtensionSkillPaths(metaUrl);
+      return skillPaths.length > 0 ? { skillPaths } : undefined;
+    },
+    getRunOwnerId,
+    onAgentEnd(ctx) {
+      if (activeRunContext === ctx) automaticReview.schedule();
+    },
+    onSessionShutdown(reason, ctx) {
+      skillContextsBySession.delete(getRunOwnerId(ctx));
+      activeRunContext = undefined;
+      automaticReview.close();
+      recipeReload.close();
+      runUiRuntime.shutdown(reason, ctx);
+    },
+    async onSessionStart(ctx) {
+      skillContextsBySession.set(
+        getRunOwnerId(ctx),
+        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT,
+      );
+      ctx.ui.setWidget("zz-pi-actors-comms", undefined);
+      activeRunContext = ctx;
+      runUiRuntime.close();
+      automaticReview.close();
+      recipeReload.close();
+      await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
+      if (activeRunContext !== ctx) return;
+      automaticReview.start(ctx);
+      runtime.loadTools(ctx);
+      runUiRuntime.start(ctx);
+      recipeReload.watch(ctx);
+    },
+    registerCoreTools() {
+      Pi.registerToolDefinitions(
+        pi,
+        Tools.createCoreActorToolDefinitions<Pi.ExtensionContext>({
+          configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
+          getActiveTools: () => pi.getActiveTools(),
+          getRuntimeTool: (name) =>
+            Tools.resolveActiveRuntimeTool(
+              name,
+              runtime.getTools(),
+              (activeName) => actorToolDefinitions.get(activeName),
+            ),
+          handleRuntimeControl: automaticReview.handleControl,
+          registryRuntime: runtime,
+          setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
+        }).map(withCurrentThinkingContext),
+      );
+    },
+  };
+}