@llblab/pi-actors 0.32.0 → 0.34.0

package/lib/tools-local.ts

@@ -0,0 +1,234 @@
+/**
+ * Local tool definition behavior
+ * Zones: user recipe tools, generated schemas, async recipe launch
+ * Owns wrapping saved local capabilities as executable pi tools
+ */
+
+import * as Rooms from "./rooms.ts";
+import * as AsyncRuns from "./async-runs.ts";
+import * as CommandTemplates from "./command-templates.ts";
+import type { RegisteredTool } from "./config.ts";
+import * as Execution from "./execution.ts";
+import * as Prompts from "./prompts.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import * as RecipesUsage from "./recipes-usage.ts";
+import * as Schema from "./schema.ts";
+import * as ToolsResponse from "./tools-response.ts";
+
+type JsonSchema = Schema.JsonSchema;
+
+export interface RuntimeToolContext {
+  cwd: string;
+  sessionManager?: { getSessionId?: () => string };
+}
+
+function getRunOwnerId(ctx: RuntimeToolContext): string | undefined {
+  return ctx.sessionManager?.getSessionId?.();
+}
+
+function typedArgSchema(
+  arg: string,
+  type: Schema.ToolArgType | undefined,
+): JsonSchema {
+  const description =
+    !type || type.kind === "string"
+      ? `Argument: ${arg}`
+      : type.kind === "path"
+        ? `Path argument: ${arg}`
+        : `${type.kind[0].toUpperCase()}${type.kind.slice(1)} argument: ${arg}`;
+  return Schema.typedArgSchema(description, type);
+}
+
+function sampleValueForArg(
+  arg: string,
+  type: Schema.ToolArgType | undefined,
+  defaults: Record<string, unknown>,
+): unknown {
+  if (Object.hasOwn(defaults, arg)) return defaults[arg];
+  if (!type || type.kind === "string") return `<${arg}>`;
+  if (type.kind === "path") return `./${arg}`;
+  if (type.kind === "int") return 1;
+  if (type.kind === "number") return 1.5;
+  if (type.kind === "bool") return true;
+  if (type.kind === "array") return [`<${arg}>`];
+  return type.values[0] ?? `<${arg}>`;
+}
+
+function shouldAddRuntimeToolUsageHint(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    /^Argument \S+ must /.test(message) || /^Missing .* value: /.test(message)
+  );
+}
+
+function formatRuntimeToolUsageHint(
+  cfg: RegisteredTool,
+  required: string[],
+  includeRunId: boolean,
+): string {
+  const optional = cfg.args.filter((arg) => !required.includes(arg));
+  const example: Record<string, unknown> = {};
+  for (const arg of required)
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+  for (const arg of optional)
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+  if (includeRunId) example.run_id = `${cfg.name}-1`;
+  const lines = [
+    `Expected call shape for ${cfg.name}:`,
+    `${cfg.name}(${JSON.stringify(example, null, 2)})`,
+  ];
+  if (required.length) lines.push(`Required: ${required.join(", ")}`);
+  if (optional.length || includeRunId)
+    lines.push(
+      `Optional: ${[...optional, ...(includeRunId ? ["run_id"] : [])].join(", ")}`,
+    );
+  return lines.join("\n");
+}
+
+function formatRuntimeToolArgumentError(
+  cfg: RegisteredTool,
+  error: unknown,
+  required: string[],
+  includeRunId: boolean,
+): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  if (!shouldAddRuntimeToolUsageHint(error))
+    return error instanceof Error ? error : new Error(message);
+  return new Error(
+    `Invalid arguments for tool "${cfg.name}": ${message}\n\n${formatRuntimeToolUsageHint(
+      cfg,
+      required,
+      includeRunId,
+    )}`,
+  );
+}
+
+export function createRuntimeToolDefinition(
+  cfg: RegisteredTool,
+  exec: Execution.RegisteredToolExec,
+): any {
+  const paramSchema: Record<string, JsonSchema> = {};
+  const required: string[] = [];
+  const isRecipe = RecipesReferences.isRecipeTool(cfg.template, cfg.recipe);
+  const isAsyncRecipe =
+    cfg.recipe?.async === true ||
+    RecipesReferences.isAsyncRecipeReference(cfg.template);
+  const recipeTemplate =
+    cfg.recipe?.template ?? RecipesReferences.getRecipeTemplate(cfg.template);
+  const requiredTemplate = recipeTemplate ?? cfg.template!;
+  const requiredTemplateConfig: CommandTemplates.CommandTemplateConfig =
+    typeof requiredTemplate === "object" && !Array.isArray(requiredTemplate)
+      ? {
+          ...requiredTemplate,
+          args: cfg.args,
+          defaults: { ...(requiredTemplate.defaults ?? {}), ...cfg.defaults },
+        }
+      : {
+          args: cfg.args,
+          defaults: cfg.defaults,
+          template: requiredTemplate,
+        };
+  const requiredArgs =
+    isRecipe && cfg.storedArgs !== undefined
+      ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+      : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
+        ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+        : Schema.getRequiredToolArgNames(requiredTemplateConfig);
+  for (const arg of cfg.args) {
+    paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
+    if (requiredArgs.has(arg)) required.push(arg);
+  }
+  if (isAsyncRecipe)
+    paramSchema.run_id = Schema.stringSchema(
+      "Optional run id override for this async template recipe invocation.",
+    );
+  return {
+    name: cfg.name,
+    label: cfg.name,
+    description: cfg.description,
+    parameters: Schema.objectSchema(paramSchema, required),
+    promptSnippet: isRecipe
+      ? Prompts.formatRecipeToolPromptSnippet(
+          cfg.recipe?.name ?? String(cfg.template),
+          isAsyncRecipe,
+        )
+      : Prompts.formatRegisteredToolPromptSnippet(cfg.template),
+    async execute(
+      _toolCallId: string,
+      params: unknown,
+      signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: RuntimeToolContext,
+    ) {
+      try {
+        if (cfg.sourcePath)
+          RecipesUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
+        if (isAsyncRecipe) {
+          const input = params as Record<string, unknown>;
+          const { run_id, ...values } = input;
+          const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
+          const runId =
+            typeof run_id === "string" && run_id.trim()
+              ? run_id.trim()
+              : `${cfg.name}-${Date.now()}`;
+          const meta = AsyncRuns.startRun(
+            {
+              ...base,
+              launch_source: "tool",
+              ownerId: getRunOwnerId(ctx),
+              run_id: runId,
+              tool: cfg.name,
+              values: Schema.normalizeRuntimeValues(
+                { ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values },
+                cfg.argTypes,
+              ),
+            },
+            ctx.cwd,
+          );
+          Rooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
+          Rooms.writeCommunicationSnapshot(meta.state_dir, String(meta.run));
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: ToolsResponse.compactAsyncRunStatus(meta),
+              },
+            ],
+            details: meta,
+          };
+        }
+        if (isRecipe && recipeTemplate) {
+          const paramsWithDefaults = {
+            ...(cfg.recipe?.values ?? {}),
+            ...cfg.defaults,
+            ...(params as Record<string, unknown>),
+          };
+          return await Execution.executeRegisteredTool(
+            { ...cfg, template: recipeTemplate },
+            Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes),
+            exec,
+            ctx.cwd,
+            signal,
+          );
+        }
+        return await Execution.executeRegisteredTool(
+          cfg,
+          Schema.normalizeRuntimeValues(
+            params as Record<string, unknown>,
+            cfg.argTypes,
+          ),
+          exec,
+          ctx.cwd,
+          signal,
+        );
+      } catch (error) {
+        throw formatRuntimeToolArgumentError(
+          cfg,
+          error,
+          required,
+          isAsyncRecipe,
+        );
+      }
+    },
+  };
+}

package/lib/tools-mailbox.ts

@@ -0,0 +1,56 @@
+/**
+ * Public tool mailbox contract helpers
+ * Zones: accepted/emitted message type declarations, contract normalization, compact type extraction
+ * Owns mailbox metadata normalization for public message and inspect tool paths
+ */
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function normalizeMailboxEntry(
+  value: unknown,
+): Record<string, unknown> | undefined {
+  if (typeof value === "string") return { type: value };
+  const record = asRecord(value);
+  if (typeof record.type !== "string" || !record.type.trim()) return undefined;
+  return {
+    type: record.type.trim(),
+    ...(record.body_schema !== undefined
+      ? { body_schema: record.body_schema }
+      : {}),
+    ...(record.ack !== undefined ? { ack: record.ack } : {}),
+    ...(typeof record.idempotency === "string"
+      ? { idempotency: record.idempotency }
+      : {}),
+    ...(typeof record.level === "string" ? { level: record.level } : {}),
+    ...(record.requires_response === true ? { requires_response: true } : {}),
+    ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
+  };
+}
+
+export function normalizeMailboxContracts(
+  mailbox: Record<string, unknown>,
+): Record<string, unknown[]> {
+  const accepts = Array.isArray(mailbox.accepts)
+    ? mailbox.accepts
+        .map(normalizeMailboxEntry)
+        .filter((entry): entry is Record<string, unknown> => Boolean(entry))
+    : [];
+  const emits = Array.isArray(mailbox.emits)
+    ? mailbox.emits
+        .map(normalizeMailboxEntry)
+        .filter((entry): entry is Record<string, unknown> => Boolean(entry))
+    : [];
+  return { accepts, emits };
+}
+
+export function mailboxTypes(entries: unknown[]): string[] {
+  return entries.flatMap((entry) =>
+    typeof asRecord(entry).type === "string"
+      ? [String(asRecord(entry).type)]
+      : [],
+  );
+}