@llblab/pi-actors 0.12.0

package/lib/registry.ts

@@ -0,0 +1,302 @@
+/**
+ * Registry mutation use-cases
+ * Zones: registry mutations, persistence, runtime activation
+ * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
+ */
+
+import * as Config from "./config.ts";
+import * as Identity from "./identity.ts";
+import * as Output from "./output.ts";
+import * as CommandTemplates from "./command-templates.ts";
+import * as RecipeReferences from "./recipe-references.ts";
+import * as Schema from "./schema.ts";
+
+export interface RegisterToolInput {
+  name?: string;
+  description?: string;
+  async?: boolean;
+  state_dir?: string;
+  template?: CommandTemplates.CommandTemplateValue | null;
+  args?: string;
+  update?: boolean;
+  values?: Record<string, unknown>;
+}
+
+export interface RegisterToolResultDetails {
+  args?: string[];
+  async?: boolean;
+  config?: string;
+  defaults?: Record<string, string>;
+  recipeName?: string;
+  state_dir?: string;
+  template?: CommandTemplates.CommandTemplateValue;
+  templateWarnings?: string[];
+  tool: string;
+}
+
+export interface RegisterToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: RegisterToolResultDetails;
+}
+
+export interface RegisterToolRuntimeDeps<TContext> {
+  configPath: string;
+  getExternalToolConflict: (name: string) => string | undefined;
+  getTools: () => Map<string, Config.RegisteredTool>;
+  getActiveTools: () => string[];
+  notify: (
+    ctx: TContext,
+    message: string,
+    type: "info" | "warning" | "error",
+  ) => void;
+  registerRuntimeTool: (cfg: Config.RegisteredTool) => void;
+  reservedToolNames: Set<string>;
+  setActiveTools: (toolNames: string[]) => void;
+}
+
+function textContent(text: string) {
+  return { type: "text" as const, text };
+}
+
+function listTools<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  const names = [...deps.getTools().keys()].sort();
+  return {
+    content: [
+      textContent(
+        Output.formatToolText(
+          names.length > 0
+            ? `Registered tools:\n${names.map((name) => `- ${name}`).join("\n")}`
+            : "No registered tools.",
+        ),
+      ),
+    ],
+    details: { tool: "register_tool" },
+  };
+}
+
+function deleteTool<TContext>(
+  name: string,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): RegisterToolResult {
+  const tools = deps.getTools();
+  if (!tools.has(name)) {
+    return {
+      content: [
+        textContent(Output.formatToolText(`Tool "${name}" not found.`)),
+      ],
+      details: { tool: name },
+    };
+  }
+  const nextTools = new Map(tools);
+  nextTools.delete(name);
+  const saveError = Config.saveTools(deps.configPath, nextTools);
+  if (saveError) {
+    throw new Error(
+      Output.formatToolText(`Failed to persist tool deletion: ${saveError}`),
+    );
+  }
+  tools.delete(name);
+  deps.setActiveTools(
+    deps.getActiveTools().filter((toolName) => toolName !== name),
+  );
+  deps.notify(ctx, `Deleted tool: ${name}`, "info");
+  return {
+    content: [
+      textContent(
+        Output.formatToolText(
+          `Deleted tool "${name}". Reload to remove it from the complete registry.`,
+        ),
+      ),
+    ],
+    details: { config: deps.configPath, tool: name },
+  };
+}
+
+function getInputTemplate(
+  value: CommandTemplates.CommandTemplateValue | null | undefined,
+): CommandTemplates.CommandTemplateValue | null | undefined {
+  if (typeof value === "string") return value.trim();
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) {
+    const steps = CommandTemplates.expandCommandTemplateConfigs({
+      template: value,
+    });
+    if (steps.length === 0)
+      throw new Error(
+        Output.formatToolText("Tool template sequence is empty."),
+      );
+    return value;
+  }
+  throw new Error(
+    Output.formatToolText("Tool template must be a string or sequence."),
+  );
+}
+
+function buildConfig(
+  name: string,
+  input: RegisterToolInput,
+  existing: Config.RegisteredTool | undefined,
+): Config.RegisteredTool {
+  const explicitArgs =
+    input.args === undefined
+      ? undefined
+      : Schema.parseToolArgDeclarations(input.args);
+  if (explicitArgs?.error)
+    throw new Error(Output.formatToolText(explicitArgs.error));
+  const description = (input.description ?? existing?.description ?? "").trim();
+  if (!description) {
+    throw new Error(
+      Output.formatToolText("Tool description is required unless deleting."),
+    );
+  }
+  const template = getInputTemplate(input.template);
+  if (template === null) {
+    throw new Error(
+      Output.formatToolText("Tool template cannot be null here."),
+    );
+  }
+  const finalTemplate =
+    template === undefined || template === "" ? existing?.template : template;
+  if (!finalTemplate) {
+    throw new Error(Output.formatToolText("Tool template is required."));
+  }
+  const inputRecipe = typeof input.async === "boolean" ? name : undefined;
+  const recipe: RecipeReferences.TemplateRecipeConfig | undefined = inputRecipe
+    ? {
+        name: inputRecipe,
+        ...(typeof input.async === "boolean" ? { async: input.async } : {}),
+        ...(typeof input.state_dir === "string" && input.state_dir.trim()
+          ? { state_dir: input.state_dir.trim() }
+          : {}),
+        template: finalTemplate,
+        ...(input.values && typeof input.values === "object"
+          ? { values: input.values }
+          : {}),
+      }
+    : template === undefined
+      ? existing?.recipe
+      : undefined;
+  const defaults = explicitArgs?.defaults ?? existing?.storedDefaults ?? {};
+  const storedArgs = explicitArgs
+    ? explicitArgs.declarations
+    : existing?.storedArgs;
+  const storedDefaults =
+    Object.keys(defaults).length > 0 ? defaults : undefined;
+  const recipeTemplate = RecipeReferences.getRecipeTemplate(finalTemplate);
+  const argTemplate = recipeTemplate ?? finalTemplate;
+  const argTemplateConfig: CommandTemplates.CommandTemplateConfig =
+    typeof argTemplate === "object" && !Array.isArray(argTemplate)
+      ? {
+          ...argTemplate,
+          ...(storedArgs !== undefined ? { args: storedArgs } : {}),
+          defaults: { ...(argTemplate.defaults ?? {}), ...defaults },
+        }
+      : {
+          args: storedArgs,
+          defaults,
+          template: argTemplate,
+        };
+  const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  const argTypes = {
+    ...inferredArgTypes,
+    ...(existing?.argTypes ?? {}),
+    ...(explicitArgs?.argTypes ?? {}),
+  };
+  return {
+    name,
+    description,
+    template: finalTemplate,
+    ...(recipe ? { recipe } : {}),
+    args:
+      RecipeReferences.isRecipeTool(finalTemplate, recipe) &&
+      storedArgs !== undefined
+        ? Schema.getExplicitToolArgNames(storedArgs)
+        : RecipeReferences.isRecipeReference(finalTemplate) && !recipeTemplate
+          ? Schema.getExplicitToolArgNames(storedArgs)
+          : Schema.getToolArgNames(argTemplateConfig),
+    defaults,
+    ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
+    ...(storedArgs !== undefined ? { storedArgs } : {}),
+    ...(storedDefaults !== undefined ? { storedDefaults } : {}),
+  };
+}
+
+export async function executeRegisterTool<TContext>(
+  params: unknown,
+  ctx: TContext,
+  deps: RegisterToolRuntimeDeps<TContext>,
+): Promise<RegisterToolResult> {
+  const input = params as RegisterToolInput;
+  if (!input.name) return listTools(deps);
+  const name = Identity.normalizeToolName(input.name);
+  if (!name) throw new Error(Output.formatToolText("Invalid tool name."));
+  if (deps.reservedToolNames.has(name)) {
+    throw new Error(Output.formatToolText(`Reserved tool name: ${name}`));
+  }
+  const templateProvided = Object.hasOwn(input, "template");
+  const template = getInputTemplate(input.template);
+  if (templateProvided && (template === null || template === ""))
+    return deleteTool(name, ctx, deps);
+  const tools = deps.getTools();
+  const existing = tools.get(name);
+  const conflict = deps.getExternalToolConflict(name);
+  if (conflict) throw new Error(Output.formatToolText(conflict));
+  if (existing && !input.update) {
+    throw new Error(
+      Output.formatToolText(
+        `Tool "${name}" already registered. Use update=true to overwrite.`,
+      ),
+    );
+  }
+  if (template === undefined && !existing) {
+    throw new Error(
+      Output.formatToolText("Tool template is required for new registrations."),
+    );
+  }
+  const cfg = buildConfig(name, input, existing);
+  const nextTools = new Map(tools);
+  nextTools.set(name, cfg);
+  const saveError = Config.saveTools(deps.configPath, nextTools);
+  if (saveError) {
+    throw new Error(
+      Output.formatToolText(
+        `Failed to persist tool registration: ${saveError}`,
+      ),
+    );
+  }
+  tools.set(name, cfg);
+  deps.registerRuntimeTool(cfg);
+  deps.notify(ctx, `Tool persisted: ${name}`, "info");
+  const templateWarnings = CommandTemplates.getCommandTemplateWarnings(
+    typeof cfg.template === "object" && !Array.isArray(cfg.template)
+      ? cfg.template
+      : { template: cfg.template! },
+  );
+  const warningText =
+    templateWarnings.length > 0
+      ? `\nWarnings:\n${templateWarnings.map((warning) => `- ${warning}`).join("\n")}`
+      : "";
+  return {
+    content: [
+      textContent(
+        Output.formatToolText(
+          `${existing ? "Updated" : "Registered"} tool "${name}" (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`,
+        ),
+      ),
+    ],
+    details: {
+      args: cfg.args,
+      config: deps.configPath,
+      defaults: cfg.defaults,
+      ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
+      ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),
+      ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
+      ...(cfg.template ? { template: cfg.template } : {}),
+      ...(templateWarnings.length > 0 ? { templateWarnings } : {}),
+      tool: name,
+    },
+  };
+}

package/lib/runtime.ts

@@ -0,0 +1,101 @@
+/**
+ * Tool registry runtime coordinator
+ * Zones: runtime coordination, registry loading, pi tools
+ * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
+ */
+
+import * as Config from "./config.ts";
+import type { RegisteredToolExec } from "./execution.ts";
+import * as Tools from "./tools.ts";
+
+export interface RuntimeContext {
+  hasUI: boolean;
+  ui: {
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+  };
+}
+
+export interface ToolInfoLike {
+  name: string;
+}
+
+export interface ToolRegistryRuntimeDeps {
+  configPath: string;
+  exec: RegisteredToolExec;
+  getAllTools: () => ToolInfoLike[];
+  registerTool: (
+    definition: ReturnType<typeof Tools.createRuntimeToolDefinition>,
+  ) => void;
+  reservedToolNames: Set<string>;
+}
+
+export interface ToolRegistryRuntime {
+  getExternalToolConflict(name: string): string | undefined;
+  getTools(): Map<string, Config.RegisteredTool>;
+  loadTools(ctx: RuntimeContext): void;
+  notify(
+    ctx: RuntimeContext,
+    message: string,
+    type: "info" | "warning" | "error",
+  ): void;
+  registerRuntimeTool(cfg: Config.RegisteredTool): void;
+}
+
+export function createAutoToolsRuntime(
+  deps: ToolRegistryRuntimeDeps,
+): ToolRegistryRuntime {
+  const tools = new Map<string, Config.RegisteredTool>();
+  const runtimeTools = new Set<string>();
+  function notify(
+    ctx: RuntimeContext,
+    message: string,
+    type: "info" | "warning" | "error",
+  ) {
+    if (ctx.hasUI) ctx.ui.notify(message, type);
+  }
+  function getExternalToolConflict(name: string): string | undefined {
+    if (runtimeTools.has(name)) return undefined;
+    const existing = deps.getAllTools().find((tool) => tool.name === name);
+    return existing
+      ? `Tool "${name}" is already registered outside pi-actors.`
+      : undefined;
+  }
+  function registerRuntimeTool(cfg: Config.RegisteredTool) {
+    deps.registerTool(Tools.createRuntimeToolDefinition(cfg, deps.exec));
+    runtimeTools.add(cfg.name);
+  }
+  function loadTools(ctx: RuntimeContext) {
+    const loaded = Config.loadToolConfig(
+      deps.configPath,
+      deps.reservedToolNames,
+    );
+    tools.clear();
+    for (const [name, cfg] of loaded.tools) tools.set(name, cfg);
+    if (loaded.changed) {
+      const saveError = Config.saveTools(deps.configPath, tools);
+      if (saveError) {
+        loaded.warnings.push(
+          `Failed to normalize ${deps.configPath}: ${saveError}`,
+        );
+      }
+    }
+    for (const cfg of tools.values()) {
+      const conflict = getExternalToolConflict(cfg.name);
+      if (conflict) {
+        loaded.warnings.push(conflict);
+        continue;
+      }
+      registerRuntimeTool(cfg);
+    }
+    if (loaded.warnings.length > 0) {
+      notify(ctx, `Auto-tools: ${loaded.warnings.join("; ")}`, "warning");
+    }
+  }
+  return {
+    getExternalToolConflict,
+    getTools: () => tools,
+    loadTools,
+    notify,
+    registerRuntimeTool,
+  };
+}