@llblab/pi-actors 0.44.0 → 0.45.1

package/dist/scripts/locker.mjs

@@ -65,7 +65,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
   mkdirSync(stateDir, { recursive: true });
-
   function readJson(path, fallback) {
     if (!existsSync(path)) return fallback;
     try {
@@ -74,11 +73,9 @@ async function runLocker(argv = process.argv.slice(2)) {
       return fallback;
     }
   }
-
   function writeJson(path, value) {
     writeJsonAtomic(path, value);
   }
-
   function getControlEndpoint() {
     if (process.platform !== "win32") return { path: controlPath, type: "fifo" };
     const hash = createHash("sha256")
@@ -87,7 +84,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       .slice(0, 20);
     return { path: `\\\\.\\pipe\\pi-actors-locker-${hash}`, type: "named-pipe" };
   }
-
   function writeControlEndpoint(endpoint) {
     if (!runInstanceId) throw new Error("Run generation unavailable for Control endpoint");
     writeJson(join(stateDir, "control-endpoint.json"), {
@@ -96,7 +92,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       run_instance_id: runInstanceId,
     });
   }
-
   function journal(event, data = {}) {
     const release = acquireFileMutationLock(journalPath);
     try {
@@ -111,11 +106,9 @@ async function runLocker(argv = process.argv.slice(2)) {
       writeTextAtomic(journalPath, content);
     } finally { release(); }
   }
-
   function encodeJournal(records) {
     return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
   }
-
   function emitTrace(kind, summary, data = {}, level = "info") {
     appendRunTraceEvent(stateDir, {
       attention: "followup",
@@ -125,11 +118,9 @@ async function runLocker(argv = process.argv.slice(2)) {
       summary,
     });
   }
-
   function now() {
     return Date.now();
   }
-
   function cleanExpiredLocks(locks) {
     const current = now();
     const kept = {};
@@ -139,7 +130,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
     return kept;
   }
-
   function normalizeControl(line) {
     const trimmed = line.trim();
     if (!trimmed) return undefined;
@@ -160,8 +150,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       );
     }
   }
-
-
   function tailJournal(count) {
     if (!existsSync(journalPath)) return [];
     return readFileSync(journalPath, "utf8")
@@ -177,7 +165,6 @@ async function runLocker(argv = process.argv.slice(2)) {
         }
       });
   }
-
   function printSnapshot() {
     const locks = cleanExpiredLocks(readJson(locksPath, {}));
     writeJson(locksPath, locks);
@@ -195,7 +182,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       ),
     );
   }
-
   function nextTask(queue, locks) {
     const items = Array.isArray(queue.items) ? queue.items : [];
     const index = items.findIndex((item) => {
@@ -205,7 +191,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     if (index < 0) return undefined;
     return items.splice(index, 1)[0];
   }
-
   function handle(control) {
     const action = control.action;
     const body =
@@ -333,18 +318,15 @@ async function runLocker(argv = process.argv.slice(2)) {
     journal("lock.unknown", { action, input: body });
     emitTrace("lock.unknown", `Unknown Control ${action}`, { action, input: body }, "warning");
   }
-
   if (mode === "snapshot") {
     printSnapshot();
     process.exit(0);
   }
-
   const startupRun = readJson(join(stateDir, "run.json"), undefined);
   if (!startupRun || typeof startupRun.run_instance_id !== "string") {
     throw new Error("Run generation unavailable for Control service");
   }
   runInstanceId = startupRun.run_instance_id;
-
   function handleLine(line) {
     const control = normalizeControl(line);
     if (!control) return false;
@@ -376,7 +358,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       return false;
     }
   }
-
   async function serveFifo(endpoint) {
     if (!existsSync(endpoint.path)) {
       const result = spawnSync("mkfifo", [endpoint.path]);
@@ -403,7 +384,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       fs.closeSync(fd);
     }
   }
-
   async function serveNamedPipe(endpoint) {
     let resolveStopped;
     const stopped = new Promise((resolve) => {
@@ -428,7 +408,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     });
     await stopped;
   }
-
   const endpoint = getControlEndpoint();
   writeJson(queuePath, readJson(queuePath, { items: [] }));
   writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));

package/dist/scripts/recipe-utils.mjs

@@ -369,7 +369,6 @@ if (!command) {
   usage();
   process.exit(1);
 }
-
 if (command === "run-summary")
   runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
 else if (command === "run-ops-snapshot")

package/dist/scripts/release-gates.mjs

@@ -7,6 +7,8 @@ import { dirname, extname, join, normalize, relative, resolve } from "node:path"
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { executableBlockBlankLines } from "./executable-block-style.mjs";
+
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const temp = mkdtempSync(join(tmpdir(), "pi-actors-release-index-"));
 const indexPath = join(temp, "index");
@@ -71,7 +73,6 @@ try {
     .filter(Boolean);
   const fileSet = new Set(files);
   console.log(`[release] exact temporary index: ${files.length} files`);
-
   const secretPatterns = [
     [/-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]{80,}?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/u, "private-key block"],
     [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/u, "AWS access key"],
@@ -92,7 +93,17 @@ try {
     }
   }
   console.log("[release] bounded secret and public-path hygiene checked");
-
+  const executableSources = files.filter((path) =>
+    /\.(?:[cm]?js|ts)$/u.test(path) && !path.startsWith("dist/"),
+  );
+  for (const path of executableSources) {
+    const blankLines = executableBlockBlankLines(stagedText(path) ?? "");
+    check(
+      blankLines.length === 0,
+      `blank lines inside executable blocks: ${path}:${blankLines.join(",")}`,
+    );
+  }
+  console.log("[release] executable blocks contain no blank lines");
   const removedPaths = [
     "lib/messages.ts",
     "lib/rooms.ts",
@@ -113,7 +124,6 @@ try {
     "lib/run-inspector-overlay.ts",
   ];
   for (const path of removedPaths) check(!fileSet.has(path), `removed surface returned: ${path}`);
-
   const currentSurface = /^(?:lib\/|scripts\/|recipes\/|fixtures\/|skills\/|docs\/|README\.md|AGENTS\.md)/u;
   const forbiddenPatterns = [
     [/room:</u, "room address"],
@@ -144,7 +154,6 @@ try {
     }
   }
   console.log("[release] removed-surface and legacy-fallback allowlists checked");
-
   const directTraceWrite = /(?:appendFileSync|writeFileSync|writeText(?:Atomic)?)\s*\(\s*[A-Za-z0-9_.]*?(?:trace|event)(?:Path|File)/iu;
   for (const path of files.filter((candidate) =>
     (candidate.startsWith("lib/") && candidate.endsWith(".ts")) ||
@@ -172,7 +181,6 @@ try {
     );
   }
   console.log("[release] canonical Trace and Control writer residue checked");
-
   // owner | class | lock | record bound | byte bound | recovery
   const appendOnlyOwners = new Set([
     "lib/runs-trace.ts", // canonical Run evidence | token lock | 2048 | 4 MiB | compact valid suffix
@@ -189,7 +197,6 @@ try {
       check(appendOnlyOwners.has(path), `unregistered shipped append-only writer: ${path}`);
   for (const path of appendOnlyOwners) check(fileSet.has(path), `stale append-only owner inventory: ${path}`);
   console.log(`[release] append-only owner inventory checked: ${appendOnlyOwners.size} source owners`);
-
   check(
     (stagedText("scripts/validate-recipe.mjs") ?? "").includes(
       "qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0",
@@ -197,15 +204,13 @@ try {
     "Recipe QA warnings are not release-blocking",
   );
   console.log("[release] zero-warning Recipe QA gate checked");
-
-  const maximumShippedLines = 29_598;
+  const maximumShippedLines = 32_000;
   const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
   const shippedLines = files
     .filter((path) => shippedPath.test(path))
     .reduce((total, path) => total + (((stagedText(path) ?? "").match(/\n/gu) ?? []).length + 1), 0);
   check(shippedLines <= maximumShippedLines, `shipped lines ${shippedLines} exceed release maximum ${maximumShippedLines}`);
   console.log(`[release] shipped lines ${shippedLines} <= release maximum ${maximumShippedLines}`);
-
   const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
   const sourceSet = new Set(sources);
   const graph = new Map();
@@ -240,7 +245,6 @@ try {
   }
   for (const path of sources) visit(path);
   console.log(`[release] strict Domain DAG: ${sources.length} sources, acyclic`);
-
   for (const path of ["README.md", "AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
     check(fileSet.has(path), `missing ABCd root/context file: ${path}`);
   }
@@ -263,7 +267,6 @@ try {
     check(docsIndex.includes(relative("docs", path).replaceAll("\\", "/")), `docs/README.md omits ${path}`);
   }
   console.log("[release] ABCd context roots, routing, and Markdown links checked");
-
   if (failures.length > 0) {
     for (const failure of failures) console.error(`[FAIL] ${failure}`);
     process.exitCode = 1;

package/dist/scripts/validate-recipe.mjs

@@ -187,7 +187,6 @@ export function validateRecipes(argv) {
   if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
     return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
   }
-
   const files = recipeFiles(expandPath(targetArg), all);
   const results = files.map((file) => validateFile(file, qa));
   const failed = results.filter((result) => !result.ok).length;

package/dist/skills/actors/SKILL.md

@@ -25,11 +25,11 @@ A Run target exposes exactly three inspect views: `recipe`, `trace`, and `contro
 
 ## Recipe
 
-A Recipe defines execution. It may declare args, defaults, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
+A Recipe defines execution. It may declare named typed args, inline fallbacks, configuration `defaults`, composition `values`, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
 
 Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Prefer maintained packaged Recipes over ad hoc wrappers. Use `std:<recipe>` for exact packaged lookup and `skill:<skill>/<recipe-path>` for a component bundled with a Pi-active Skill. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
 ## Trace
 

package/docs/command-templates.md

@@ -53,7 +53,7 @@ Common object fields:
 - `concurrency`: Optional positive integer cap for a `parallel: true` node. Omit it to launch all children at once.
 - `min_successful`: Optional non-negative integer evidence threshold for a `parallel: true` node. Usable branches are successful branches with non-empty stdout; joins include a `parallel_status` header when this is set.
 - `when`: Optional node guard. A false guard skips the node; strings may be `flag`, `!flag`, or `{flag?yes:no}` style expressions.
-- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. Defaults belong in `defaults` or inline placeholder defaults; hosts may normalize interactive shorthand such as `request_timeout:int=60000` before persistence.
+- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `request_timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. `name:type=value` is an optional argument with an inline fallback. Hosts reject duplicate names and conflicting declared/placeholder types rather than selecting one silently.
 - `defaults`: Placeholder default values by name.
 - `timeout`: Optional execution timeout in milliseconds. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely. Numeric control fields may be literal numbers or placeholders such as `"{timeout_ms}"`.
 - `delay`: Optional wait in milliseconds before starting this node. Default is no delay. It may be a literal number or placeholder.
@@ -104,7 +104,7 @@ With runtime values `{ "text": "hello" }`, argv is:
 ["--text", "hello", "--lang", "ru", "--rate", "+30%"]
 ```
 
-Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
+Use `defaults` for visible fallback configuration, `values` for composition binding, and inline defaults for compact local literals. Named resolution uses caller values before composition values, explicit defaults, and inline defaults; the final selected value is type/enum validated. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
 
 Use `{env??dev}` for fallback values and `{all?--all:}` to map boolean args to optional text.
 

package/docs/recipe-library.md

@@ -45,6 +45,8 @@ Subagent components provide reusable command-template cells for normalization, p
 
 Imports compose these definitions inside one parent Run. They are not independently addressable peers. Parent template flags control sequencing, parallelism, retries, failure scope, recovery, and repeated execution.
 
+Packaged components can be selected exactly as `std:<recipe-name>`. Recipes bundled under a Pi-active Skill are selected as `skill:<skill-name>/<recipe-path>` and receive runtime-owned `{skill_dir}` plus `{recipe_dir}`. Active Skill components are namespaced library entries, never automatic tools; expose one intentionally through a user Recipe wrapper when a direct tool is desired.
+
 ## Utility Recipes
 
 Utilities wrap deterministic local capabilities such as:

package/docs/template-recipes.md

@@ -44,7 +44,7 @@ Fences marked `template`, `command-template`, `json`, or `recipe` can define exe
 Common Recipe fields:
 
 - `name`, `description`, `disabled`;
-- `args`, typed arg declarations, and `defaults`;
+- `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
 - `imports` with optional binding defaults/values;
 - `template`;
 - `async`;
@@ -71,7 +71,9 @@ Common Recipe fields:
 }
 ```
 
-Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Resolution enforces Recipe-root priority, file-size/depth bounds, and cycle rejection.
+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.
 
 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.
 
@@ -102,9 +104,13 @@ Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters
 
 Artifact paths resolve under containment policy and appear in Run inspection. Recipes should write declared artifacts deterministically and fail when the requested write policy cannot be honored.
 
+## File Origins
+
+Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an active Skill also receives `{skill_dir}`, resolved to the directory containing that Skill's `SKILL.md`; using `{skill_dir}` elsewhere fails clearly. These runtime values cannot be declared in `args`, `defaults`, or `values`, and caller input cannot override them. They expand in templates, recursive defaults/values, imports, and artifacts while existing `./` executable behavior remains relative to invocation `cwd`.
+
 ## Context and Provenance
 
-File-backed Runs capture Recipe context records for the entry and imports. The captured bundle explains composition identity and remains generation-local evidence. It does not override the authored task prompt.
+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.
 
 Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
 
@@ -125,7 +131,7 @@ Resolution fails before launch when required current policy is unavailable. The
 
 ## Resolution and Shadowing
 
-User Recipes under `~/.pi/agent/recipes` take priority over packaged Recipes. 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` 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.
 
 ## Validation
 

package/docs/tool-registry.md

@@ -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 packaged or skill-owned Recipe by path and delegates by alias. Do not duplicate its executable template, defaults, Control declaration, or artifacts. 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 `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.
 
 ## Safety
 

package/index.ts

@@ -1,118 +1,29 @@
 /**
  * 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 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) => ({
-    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),
+  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) =>
+    runtime.beforeAgentStart(
+      event.systemPrompt,
+      event.systemPromptOptions.skills ?? [],
+    ),
+  );
+  InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);
+  runtime.registerCoreTools();
 }

package/lib/async-runs.ts

@@ -33,6 +33,7 @@ import {
 import * as Paths from "./paths.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
+import * as Schema from "./schema.ts";
 import {
   resolveArtifactManifest,
   resolveArtifactPaths,
@@ -128,6 +129,8 @@ export interface AsyncRunStartParams {
   template?: CommandTemplateValue;
   args?: string[];
   defaults?: Record<string, unknown>;
+  recipe_dir?: string;
+  skill_dir?: string;
   parallel?: boolean;
   concurrency?: number | string;
   min_successful?: number | string;
@@ -309,7 +312,14 @@ function resolveStartParams(params: AsyncRunStartParams): AsyncRunStartParams {
       fileParams.run_id ||
       fileParams.name ||
       getRunIdFromFile(fileParams.file),
-    values: { ...(fileParams.values ?? {}), ...(params.values ?? {}) },
+    values: {
+      ...(fileParams.values ?? {}),
+      ...(params.values ?? {}),
+      ...(fileParams.recipe_dir
+        ? { recipe_dir: fileParams.recipe_dir }
+        : {}),
+      ...(fileParams.skill_dir ? { skill_dir: fileParams.skill_dir } : {}),
+    },
   };
 }
 
@@ -477,13 +487,37 @@ export function startRun(
     !isAbsolute(recipeRelation)
       ? dirname(packagedRecipeRoot)
       : undefined;
-  const values = {
-    ...(packagedRepo ? { repo: packagedRepo } : {}),
-    ...(startParams.values || {}),
-    run_id: run,
-    state_dir: stateDir,
-    trace_file: join(stateDir, "trace.jsonl"),
-  };
+  const argSpec = Schema.parseToolArgDeclarationList(startParams.args ?? []);
+  if (argSpec.error) throw new Error(argSpec.error);
+  const declaredArgs = new Set(argSpec.args);
+  for (const key of Object.keys(startParams.defaults ?? {})) {
+    if (declaredArgs.size > 0 && !declaredArgs.has(key))
+      throw new Error(`Unknown Recipe default argument: ${key}`);
+  }
+  const values = Schema.normalizeRuntimeValues(
+    {
+      ...argSpec.defaults,
+      ...(startParams.defaults || {}),
+      ...(packagedRepo ? { repo: packagedRepo } : {}),
+      ...(startParams.values || {}),
+      run_id: run,
+      state_dir: stateDir,
+      trace_file: join(stateDir, "trace.jsonl"),
+    },
+    argSpec.argTypes,
+  );
+  const runtimeTemplate =
+    resolved.template &&
+    typeof resolved.template === "object" &&
+    !Array.isArray(resolved.template)
+      ? {
+          ...resolved.template,
+          defaults: {
+            ...(resolved.template.defaults ?? {}),
+            ...values,
+          },
+        }
+      : resolved.template;
   const modelPolicy = describeCurrentPolicyProvenance({
     defaults: startParams.defaults,
     template: resolved.template,
@@ -557,7 +591,7 @@ export function startRun(
       state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
       status: "running",
       ...(startParams.tool ? { tool: startParams.tool } : {}),
-      template: resolved.template,
+      template: runtimeTemplate,
       values,
       model_policy: modelPolicy,
       ...(artifacts ? { artifacts } : {}),

package/lib/config.ts

@@ -188,6 +188,10 @@ export function normalizeStoredTool(
           template: argTemplate,
         };
   const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  Schema.assertCompatibleToolArgTypes(
+    inferredArgTypes,
+    declarations.argTypes,
+  );
   const argTypes = { ...inferredArgTypes, ...declarations.argTypes };
   const cfg = {
     name,