@llblab/pi-actors 0.44.0 → 0.45.1

package/lib/extension-runtime.ts

@@ -0,0 +1,139 @@
+/**
+ * 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[],
+  ): { 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 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);
+  return {
+    beforeAgentStart(systemPrompt, skills) {
+      RecipesReferences.setActiveSkillRecipeSources(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) {
+      activeRunContext = undefined;
+      automaticReview.close();
+      recipeReload.close();
+      runUiRuntime.shutdown(reason, ctx);
+    },
+    async onSessionStart(ctx) {
+      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),
+      );
+    },
+  };
+}

package/lib/inspector.ts

@@ -105,9 +105,22 @@ export function readActorInspectorRecipe(
   const redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
     SessionEvidence.redactSessionEvidenceValue(
       Object.fromEntries(
-        Object.entries(value).filter(([, entry]) => entry !== undefined),
+        Object.entries(value).filter(
+          ([key, entry]) =>
+            entry !== undefined &&
+            key !== "recipe_dir" &&
+            key !== "skill_dir",
+        ),
       ),
     ) as Record<string, unknown>;
+  const launchValues =
+    meta.values && typeof meta.values === "object" && !Array.isArray(meta.values)
+      ? Object.fromEntries(
+          Object.entries(meta.values as Record<string, unknown>).filter(
+            ([key]) => key !== "recipe_dir" && key !== "skill_dir",
+          ),
+        )
+      : meta.values;
   return {
     composition: contexts.map((entry) =>
       redactedRecord({
@@ -116,6 +129,7 @@ export function readActorInspectorRecipe(
         file: entry.file,
         import_path: entry.import_path,
         name: entry.name,
+        qualified_name: entry.qualified_name,
       }),
     ),
     ...(definition ? { definition: redactedRecord(definition) } : {}),
@@ -129,7 +143,7 @@ export function readActorInspectorRecipe(
     launch: redactedRecord({
       cwd: meta.cwd,
       template: meta.template,
-      values: meta.values,
+      values: launchValues,
       model_policy: meta.model_policy,
       control: meta.control,
       artifacts: meta.artifacts,

package/lib/recipes-discovery.ts

@@ -122,6 +122,25 @@ function getRecipeCommandTemplateConfig(
     : config) as CommandTemplates.CommandTemplateConfig;
 }
 
+function getRecipeDiagnosticTemplateConfig(
+  config: TemplateRecipeConfig,
+): CommandTemplates.CommandTemplateObjectConfig {
+  const templateConfig = getRecipeCommandTemplateConfig(config);
+  return typeof templateConfig === "object" && !Array.isArray(templateConfig)
+    ? {
+        ...templateConfig,
+        defaults: {
+          ...(templateConfig.defaults ?? {}),
+          ...(config.defaults ?? {}),
+          ...(config.values ?? {}),
+        },
+      }
+    : {
+        defaults: { ...(config.defaults ?? {}), ...(config.values ?? {}) },
+        template: templateConfig,
+      };
+}
+
 function getRecipeConfigDiagnostics(
   file: string,
   config: TemplateRecipeConfig | undefined,
@@ -131,7 +150,7 @@ function getRecipeConfigDiagnostics(
     return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
   }
   return CommandTemplates.getCommandTemplateWarnings(
-    getRecipeCommandTemplateConfig(config),
+    getRecipeDiagnosticTemplateConfig(config),
   ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
@@ -141,7 +160,7 @@ function getRecipeRiskLabels(
   if (!config) return [];
   const labels = new Set(
     CommandTemplates.getCommandTemplateRiskLabels(
-      getRecipeCommandTemplateConfig(config),
+      getRecipeDiagnosticTemplateConfig(config),
     ),
   );
   if (config.async === true) labels.add("risk.long_running");
@@ -846,9 +865,10 @@ export function toRegisteredTool(
   assertToolSafeRepeatConfig(
     argTemplateConfig,
     explicitArgTypes,
-    cfg.defaults ?? {},
+    { ...(cfg.defaults ?? {}), ...(cfg.values ?? {}) },
   );
   const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  Schema.assertCompatibleToolArgTypes(explicitArgTypes, argTypes);
   return {
     name: entry.id,
     description,

package/lib/recipes-references.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, extname, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
 
 import type {
   CommandTemplateConfig,
@@ -15,6 +15,7 @@ import type {
 import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
 import * as RecipeControl from "./recipe-control.ts";
+import * as Schema from "./schema.ts";
 
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
@@ -57,6 +58,8 @@ export interface TemplateRecipeDefinition {
 
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
   async?: boolean;
+  recipe_dir?: string;
+  skill_dir?: string;
 }
 
 interface ImportedRecipe {
@@ -74,6 +77,7 @@ export interface TemplateRecipeContextRecord {
   file: string;
   import_path: string[];
   name: string;
+  qualified_name?: string;
   recipe: Record<string, unknown>;
   role: "entry" | "import";
 }
@@ -82,10 +86,120 @@ export interface ReadResolvedRecipeConfigOptions {
   includeActorRecipeContext?: boolean;
 }
 
+const RUNTIME_RECIPE_VALUE_NAMES = new Set(["recipe_dir", "skill_dir"]);
+const activeSkillRecipeRoots = new Map<string, Set<string>>();
+
+export interface ActiveSkillRecipeSource {
+  name: string;
+  filePath?: string;
+  baseDir?: string;
+}
+
+export function setActiveSkillRecipeSources(
+  skills: ActiveSkillRecipeSource[],
+): void {
+  activeSkillRecipeRoots.clear();
+  for (const skill of skills) {
+    const name = skill.name.trim();
+    const skillDir = skill.baseDir
+      ? resolve(skill.baseDir)
+      : skill.filePath
+        ? dirname(resolve(skill.filePath))
+        : undefined;
+    if (!name || !skillDir) continue;
+    const roots = activeSkillRecipeRoots.get(name) ?? new Set<string>();
+    roots.add(resolve(skillDir, "recipes"));
+    activeSkillRecipeRoots.set(name, roots);
+  }
+}
+
+export function getActiveSkillRecipeNamespaces(): Record<string, string[]> {
+  return Object.fromEntries(
+    [...activeSkillRecipeRoots.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, roots]) => [name, [...roots].sort()]),
+  );
+}
+
+function qualifiedRecipeNameForFile(file: string): string | undefined {
+  const path = resolve(file);
+  const stdRelation = relative(Paths.getPackagedRecipeRoot(), path);
+  if (
+    stdRelation &&
+    !stdRelation.startsWith("..") &&
+    !isAbsolute(stdRelation)
+  ) {
+    return `std:${stdRelation.replace(/\.(?:json|md)$/u, "")}`;
+  }
+  for (const [skillName, roots] of activeSkillRecipeRoots) {
+    if (roots.size !== 1) continue;
+    const root = [...roots][0];
+    const relation = relative(root, path);
+    if (relation && !relation.startsWith("..") && !isAbsolute(relation))
+      return `skill:${skillName}/${relation.replaceAll("\\", "/").replace(/\.(?:json|md)$/u, "")}`;
+  }
+  return undefined;
+}
+
+function qualifiedRecipeCandidates(value: string): string[] | undefined {
+  if (value.startsWith("std:")) {
+    return recipeNameFiles(value.slice(4)).map((file) =>
+      resolve(Paths.getPackagedRecipeRoot(), file),
+    );
+  }
+  if (!value.startsWith("skill:")) return undefined;
+  const qualified = value.slice(6);
+  const separator = qualified.indexOf("/");
+  if (separator <= 0 || separator === qualified.length - 1)
+    throw new Error(`Invalid Skill Recipe reference: ${value}`);
+  const skillName = qualified.slice(0, separator);
+  const recipeName = qualified.slice(separator + 1);
+  const roots = [...(activeSkillRecipeRoots.get(skillName) ?? [])];
+  if (roots.length === 0)
+    throw new Error(`Active Skill Recipe namespace not found: ${skillName}`);
+  if (roots.length > 1)
+    throw new Error(
+      `Ambiguous active Skill Recipe namespace ${skillName}: ${roots.join(", ")}`,
+    );
+  const root = roots[0];
+  return recipeNameFiles(recipeName).map((file) => {
+    const candidate = resolve(root, file);
+    const relation = relative(root, candidate);
+    if (!relation || relation.startsWith("..") || isAbsolute(relation))
+      throw new Error(`Skill Recipe reference escapes its recipes root: ${value}`);
+    return candidate;
+  });
+}
+
 function hasWhitespace(value: string): boolean {
   return /\s/.test(value);
 }
 
+function findOwningSkillDir(recipeFile: string): string | undefined {
+  let current = dirname(recipeFile);
+  while (true) {
+    if (existsSync(resolve(current, "SKILL.md"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function assertRuntimeRecipeValuesNotDeclared(raw: Record<string, unknown>): void {
+  const args = Array.isArray(raw.args)
+    ? Schema.getExplicitToolArgNames(raw.args.map(String))
+    : [];
+  for (const name of RUNTIME_RECIPE_VALUE_NAMES) {
+    if (
+      args.includes(name) ||
+      (isRecord(raw.defaults) && Object.hasOwn(raw.defaults, name)) ||
+      (isRecord(raw.values) && Object.hasOwn(raw.values, name))
+    ) {
+      throw new Error(`Recipe runtime value is reserved: ${name}`);
+    }
+  }
+}
+
 export function resolveRecipePath(
   value: string,
   recipeRoot = Paths.getRecipeRoot(),
@@ -125,6 +239,8 @@ function recipeCandidatePaths(
   value: string,
   currentRecipeRoot: string,
 ): string[] {
+  const qualified = qualifiedRecipeCandidates(value.trim());
+  if (qualified) return qualified;
   if (!isBareRecipeName(value))
     return [resolveRecipePath(value, currentRecipeRoot)];
   const roots = [
@@ -646,6 +762,63 @@ function mergeDefaults(
   return Object.keys(merged).length > 0 ? merged : undefined;
 }
 
+function assertRecipeDefaultsDeclared(
+  args: string[] | undefined,
+  defaults: Record<string, unknown> | undefined,
+  label: string,
+): void {
+  const spec = Schema.parseToolArgDeclarationList(args ?? []);
+  if (spec.error) throw new Error(spec.error);
+  if (spec.args.length === 0) return;
+  const declared = new Set(spec.args);
+  for (const key of Object.keys(defaults ?? {})) {
+    if (!declared.has(key)) throw new Error(`Unknown ${label} argument: ${key}`);
+  }
+}
+
+function assertRecipeArgumentContract(
+  config: Pick<
+    TemplateRecipeDefinition,
+    "args" | "defaults" | "values" | "template"
+  >,
+  label = "Recipe default",
+): void {
+  assertRecipeDefaultsDeclared(config.args, config.defaults, label);
+  const spec = Schema.parseToolArgDeclarationList(config.args ?? []);
+  if (spec.error) throw new Error(spec.error);
+  Schema.assertCompatibleToolArgTypes(
+    spec.argTypes,
+    Schema.getTemplateArgTypes({ template: config.template }),
+  );
+  const staticValues = Object.fromEntries(
+    Object.entries({ ...config.defaults, ...config.values }).filter(
+      ([, value]) =>
+        typeof value !== "string" || !/\{[^{}]+\}/.test(value),
+    ),
+  );
+  Schema.normalizeRuntimeValues(staticValues, spec.argTypes);
+}
+
+function resolveRecipeValueLayers(
+  args: string[] | undefined,
+  ...layers: Array<Record<string, unknown> | undefined>
+): Record<string, unknown> | undefined {
+  const spec = Schema.parseToolArgDeclarationList(args ?? []);
+  if (spec.error) throw new Error(spec.error);
+  const merged = mergeDefaults(spec.defaults, ...layers);
+  if (!merged) return undefined;
+  const staticValues = Object.fromEntries(
+    Object.entries(merged).filter(
+      ([, value]) =>
+        typeof value !== "string" || !/\{[^{}]+\}/.test(value),
+    ),
+  );
+  return {
+    ...merged,
+    ...Schema.normalizeRuntimeValues(staticValues, spec.argTypes),
+  };
+}
+
 function applyDefaultsToTemplate(
   template: CommandTemplateValue,
   defaults: Record<string, unknown> | undefined,
@@ -655,6 +828,7 @@ function applyDefaultsToTemplate(
   delete cleanOverrides.name;
   delete cleanOverrides.template;
   delete cleanOverrides.values;
+  delete cleanOverrides.defaults;
   if (typeof template === "object" && !Array.isArray(template)) {
     return {
       ...template,
@@ -716,11 +890,22 @@ function applyDelegatedRecipeToNode(
   delegated: TemplateRecipeConfig,
   overrides: Record<string, unknown> = {},
 ): CommandTemplateValue {
-  return applyDefaultsToTemplate(
-    delegated.template,
+  const nodeDefaults = isRecord(overrides.defaults)
+    ? overrides.defaults
+    : undefined;
+  const nodeValues = isRecord(overrides.values) ? overrides.values : undefined;
+  const values = resolveRecipeValueLayers(
+    delegated.args,
+    delegated.defaults,
     delegated.values,
-    overrides,
+    nodeDefaults,
+    nodeValues,
+    {
+      ...(delegated.recipe_dir ? { recipe_dir: delegated.recipe_dir } : {}),
+      ...(delegated.skill_dir ? { skill_dir: delegated.skill_dir } : {}),
+    },
   );
+  return applyDefaultsToTemplate(delegated.template, values, overrides);
 }
 
 function expandRecipeDelegations(
@@ -830,7 +1015,8 @@ function expandImportNodes(
       ? record.defaults
       : undefined;
     const nodeValues = isRecord(record.values) ? record.values : undefined;
-    const defaults = mergeDefaults(
+    const defaults = resolveRecipeValueLayers(
+      imported.config.args,
       imported.defaults,
       imported.values,
       nodeDefaults,
@@ -897,6 +1083,8 @@ export function readResolvedRecipeConfig(
   const raw = readRawRecipeConfig(path);
   if (!raw || !Object.hasOwn(raw, "template")) return undefined;
   RecipeControl.assertRecipeHasNoMailbox(raw);
+  assertRuntimeRecipeValuesNotDeclared(raw);
+  assertRecipeArgumentContract(raw as unknown as TemplateRecipeDefinition);
   const imports: Record<string, ImportedRecipe> = {};
   for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
     const importPath = resolveRecipeImportPath(
@@ -913,13 +1101,22 @@ export function readResolvedRecipeConfig(
       typeof binding === "string" ? undefined : binding.defaults;
     const bindingValues =
       typeof binding === "string" ? undefined : binding.values;
+    assertRecipeDefaultsDeclared(
+      config.args,
+      bindingDefaults,
+      `Recipe import ${alias} default`,
+    );
     imports[alias] = {
       alias,
       file: importPath,
       name: config.name ?? alias,
       config,
       defaults: { ...(config.defaults ?? {}), ...(bindingDefaults ?? {}) },
-      values: { ...(bindingValues ?? {}) },
+      values: {
+        ...(bindingValues ?? {}),
+        ...(config.recipe_dir ? { recipe_dir: config.recipe_dir } : {}),
+        ...(config.skill_dir ? { skill_dir: config.skill_dir } : {}),
+      },
     };
   }
   const substituted = substituteImportRefs(raw, imports) as Record<
@@ -945,6 +1142,21 @@ export function readResolvedRecipeConfig(
       )
     : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
   const recipeName = getRecipeIdFromPath(path);
+  const recipeDir = dirname(path);
+  const skillDir = findOwningSkillDir(path);
+  if (
+    !skillDir &&
+    JSON.stringify({
+      artifacts: substituted.artifacts,
+      defaults: substituted.defaults,
+      template: substituted.template,
+      values: substituted.values,
+    }).includes("{skill_dir}")
+  ) {
+    throw new Error(
+      `Recipe uses {skill_dir} outside an owning Skill directory: ${path}`,
+    );
+  }
   const templateWithContext = options.includeActorRecipeContext
     ? withActorRecipeContext(expandedTemplate, {
         file: path,
@@ -967,6 +1179,8 @@ export function readResolvedRecipeConfig(
   );
   return {
     name: recipeName,
+    recipe_dir: recipeDir,
+    ...(skillDir ? { skill_dir: skillDir } : {}),
     ...(typeof substituted.description === "string" &&
     substituted.description.trim()
       ? { description: substituted.description.trim() }
@@ -1059,7 +1273,11 @@ export function readResolvedRecipeConfig(
     ...(typeof substituted.repeat === "number"
       ? { repeat: substituted.repeat }
       : {}),
-    ...(isRecord(substituted.values) ? { values: substituted.values } : {}),
+    values: {
+      ...(isRecord(substituted.values) ? substituted.values : {}),
+      recipe_dir: recipeDir,
+      ...(skillDir ? { skill_dir: skillDir } : {}),
+    },
     ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
   };
 }
@@ -1084,12 +1302,14 @@ function collectRecipeContextRecords(
   }
   const raw = readRawRecipeConfig(path);
   if (!raw || !Object.hasOwn(raw, "template")) return [];
+  const qualifiedName = qualifiedRecipeNameForFile(path);
   const record: TemplateRecipeContextRecord = {
     ...(alias ? { alias } : {}),
     depth: stack.length,
     file: path,
     import_path: importPath,
     name: getRecipeIdFromPath(path),
+    ...(qualifiedName ? { qualified_name: qualifiedName } : {}),
     recipe: raw,
     role: stack.length === 0 ? "entry" : "import",
   };

package/lib/schema.ts

@@ -185,7 +185,11 @@ function isValidDefault(type: ToolArgType, value: string): boolean {
 }
 
 export function parseToolArgDeclarations(value: string): ToolArgSpec {
-  const source = splitArgDeclarations(value);
+  return parseToolArgDeclarationList(splitArgDeclarations(value));
+}
+
+export function parseToolArgDeclarationList(value: unknown[]): ToolArgSpec {
+  const source = value.map(String);
   const seen = new Set<string>();
   const duplicates = new Set<string>();
   const args: string[] = [];
@@ -324,6 +328,7 @@ function collectCommandTemplateConfigDeclarations(
     collectTemplatePlaceholderDeclarations(config, declarations);
     return;
   }
+  if (!config || typeof config !== "object") return;
   if (Array.isArray(config)) {
     for (const step of config)
       collectCommandTemplateConfigDeclarations(step, declarations);
@@ -356,11 +361,42 @@ export function getTemplatePlaceholderNames(
   );
 }
 
+function toolArgTypesEqual(left: ToolArgType, right: ToolArgType): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function assertCompatibleToolArgTypes(
+  ...sources: Array<Record<string, ToolArgType> | undefined>
+): void {
+  const seen: Record<string, ToolArgType> = {};
+  for (const source of sources) {
+    for (const [name, type] of Object.entries(source ?? {})) {
+      const previous = seen[name];
+      if (previous && !toolArgTypesEqual(previous, type)) {
+        throw new Error(
+          `Conflicting argument type for ${name}: ${canonicalArgDeclaration(name, previous)} vs ${canonicalArgDeclaration(name, type)}`,
+        );
+      }
+      seen[name] = type;
+    }
+  }
+}
+
 export function getTemplateArgTypes(
   config: CommandTemplates.CommandTemplateConfig,
 ): Record<string, ToolArgType> {
   const argTypes: Record<string, ToolArgType> = {};
   for (const declaration of getTemplatePlaceholderDeclarations(config)) {
+    const previous = argTypes[declaration.arg];
+    if (
+      previous &&
+      declaration.type.kind !== "string" &&
+      !toolArgTypesEqual(previous, declaration.type)
+    ) {
+      throw new Error(
+        `Conflicting argument type for ${declaration.arg}: ${canonicalArgDeclaration(declaration.arg, previous)} vs ${declaration.declaration}`,
+      );
+    }
     if (declaration.type.kind !== "string")
       argTypes[declaration.arg] = declaration.type;
   }
@@ -373,6 +409,22 @@ export function getExplicitToolArgNames(args: string[] | undefined): string[] {
   );
 }
 
+export function getExplicitToolArgDefaults(
+  args: string[] | string | undefined,
+): Record<string, string> {
+  const declarations =
+    typeof args === "string" ? splitArgDeclarations(args) : (args ?? []);
+  return Object.fromEntries(
+    declarations
+      .map((item) => parseToolArgToken(String(item)))
+      .filter(
+        (item): item is ParsedToolArgToken & { defaultValue: string } =>
+          item.defaultValue !== undefined,
+      )
+      .map((item) => [item.arg, item.defaultValue]),
+  );
+}
+
 export function getToolArgNames(
   config: CommandTemplates.CommandTemplateConfig,
 ): string[] {