@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/lib/tools-local.ts

@@ -0,0 +1,303 @@
+/**
+ * Local tool definition behavior
+ * Zones: user recipe tools, generated schemas, async recipe launch
+ * Owns wrapping saved local capabilities as executable pi tools
+ */
+
+import * as AsyncRuns from "./async-runs.ts";
+import * as CommandTemplates from "./command-templates.ts";
+import * as ModelContext from "./model-context.ts";
+import type { RegisteredTool } from "./config.ts";
+import * as Execution from "./execution.ts";
+import * as Prompts from "./prompts.ts";
+import type * as RecipeResolution from "./recipes-context.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 extends ModelContext.CurrentModelContext {
+  recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
+  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) =>
+      !RecipesReferences.isRuntimeOwnedRecipeInput(arg) &&
+      !required.includes(arg),
+  );
+  const exampleDefaults = {
+    ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+    ...cfg.defaults,
+    ...(cfg.recipe?.values ?? {}),
+  };
+  const example: Record<string, unknown> = {};
+  for (const arg of required)
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
+  for (const arg of optional)
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
+  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 resolveRecipeToolValues(
+  cfg: RegisteredTool,
+  callerValues: Record<string, unknown>,
+  ctx: RuntimeToolContext,
+): Record<string, unknown> {
+  const recipeRuntimeValues = {
+    ...(cfg.recipe?.recipe_dir
+      ? { recipe_dir: cfg.recipe.recipe_dir }
+      : {}),
+    ...(cfg.recipe?.skill_dir ? { skill_dir: cfg.recipe.skill_dir } : {}),
+  };
+  return Schema.normalizeRuntimeValues(
+    ModelContext.withCurrentModelValues(
+      {
+        ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+        ...cfg.defaults,
+        ...(cfg.recipe?.values ?? {}),
+        ...callerValues,
+        ...recipeRuntimeValues,
+      },
+      ctx,
+    ),
+    cfg.argTypes,
+  );
+}
+
+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
+    ? cfg.recipe.async === true
+    : RecipesReferences.isAsyncRecipeReference(cfg.template);
+  const isSingletonRecipe = cfg.recipe?.singleton === true;
+  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 recipeInlineDefaults = Schema.getExplicitToolArgDefaults(
+    cfg.recipe?.args,
+  );
+  const requiredArgs =
+    isRecipe && cfg.storedArgs !== undefined
+      ? new Set(
+          cfg.args.filter(
+            (arg) =>
+              !Object.hasOwn(cfg.defaults, arg) &&
+              !Object.hasOwn(recipeInlineDefaults, arg),
+          ),
+        )
+      : !cfg.recipe && 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) {
+    if (RecipesReferences.isRuntimeOwnedRecipeInput(arg)) continue;
+    paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
+    if (requiredArgs.has(arg)) required.push(arg);
+  }
+  if (isAsyncRecipe && !isSingletonRecipe)
+    paramSchema.run_id = Schema.stringSchema(
+      "Optional run id override for this async template recipe invocation.",
+    );
+  if (isAsyncRecipe) {
+    paramSchema.transport_context = Schema.looseObjectSchema(
+      "Optional originating transport route preserved for detached terminal follow-up.",
+    );
+  }
+  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")
+        ) {
+          throw new Error(
+            `Recipe launch rejected because its source changed during activation: ${cfg.sourcePath}. Reload recipe tools and retry.`,
+          );
+        }
+        if (isAsyncRecipe) {
+          const input = params as Record<string, unknown>;
+          const { run_id, transport_context, ...values } = input;
+          const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
+          const runId = isSingletonRecipe
+            ? undefined
+            : typeof run_id === "string" && run_id.trim()
+              ? run_id.trim()
+              : `${cfg.name}-${Date.now()}`;
+          const meta = AsyncRuns.startRun(
+            {
+              ...base,
+              launch_source: "tool",
+              launch_correlation: { tool_call_id: toolCallId },
+              ...(transport_context &&
+              typeof transport_context === "object" &&
+              !Array.isArray(transport_context)
+                ? {
+                    transport_context: transport_context as Record<string, unknown>,
+                  } : {}),
+              ownerId: getRunOwnerId(ctx),
+              run_id: runId,
+              tool: cfg.name,
+              policy_values: ModelContext.withCurrentModelValues(
+                { ...(cfg.recipe?.values ?? {}), ...values },
+                ctx,
+              ),
+              values: resolveRecipeToolValues(cfg, values, ctx),
+            },
+            ctx.cwd,
+            { skillContext: ctx.recipeResolutionContext?.activeSkills },
+          );
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: ToolsResponse.compactAsyncRunStatus(meta),
+              },
+            ],
+            details: meta,
+          };
+        }
+        if (isRecipe && recipeTemplate) {
+          return await Execution.executeRegisteredTool(
+            { ...cfg, template: recipeTemplate },
+            resolveRecipeToolValues(
+              cfg,
+              params as Record<string, unknown>,
+              ctx,
+            ),
+            exec,
+            ctx.cwd,
+            signal,
+          );
+        }
+        return await Execution.executeRegisteredTool(
+          cfg,
+          Schema.normalizeRuntimeValues(
+            ModelContext.withCurrentModelValues(
+              params as Record<string, unknown>,
+              ctx,
+            ),
+            cfg.argTypes,
+          ),
+          exec,
+          ctx.cwd,
+          signal,
+        );
+      } catch (error) {
+        throw formatRuntimeToolArgumentError(
+          cfg,
+          error,
+          required,
+          isAsyncRecipe && !isSingletonRecipe,
+        );
+      }
+    },
+  };
+}

package/node_modules/@llblab/pi-actors/lib/tools-message.ts

@@ -0,0 +1,176 @@
+/**
+ * Public Control facade under the stable `message` tool name.
+ * Zones: Control request validation, Run/runtime dispatch, compact receipts
+ * Owns public Control execution; journaling, delivery, and lifecycle mutation stay in Run domains.
+ */
+
+import * as AsyncRuns from "./async-runs.ts";
+import * as Control from "./control.ts";
+import * as Schema from "./schema.ts";
+import * as ToolsAccess from "./tools-access.ts";
+import * as ToolsResponse from "./tools-response.ts";
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function compactControlResult(
+  request: Control.ControlRequest,
+  result: Record<string, unknown>,
+): string {
+  const tokens = [
+    `target=${request.target}`,
+    `action=${request.action}`,
+    `status=${String(result.delivery ?? result.status ?? (result.stopped === true ? "handled" : "accepted"))}`,
+  ];
+  if (result.control_id) tokens.push(`control=${String(result.control_id)}`);
+  if (result.reason) tokens.push(`reason=${String(result.reason).replaceAll(/\s+/g, "_")}`);
+  if (Array.isArray(result.next_actions) && result.next_actions.length > 0) {
+    tokens.push(
+      `next=${(result.next_actions as string[])
+        .map((action) => action.replaceAll(/\s+/g, "_"))
+        .join("|")}`,
+    );
+  }
+  return `\n${tokens.join(" ")}`;
+}
+
+function runNextActions(run: string, result: Record<string, unknown>): string[] {
+  if (result.delivery === "queued" || result.delivery === "delivered") {
+    return [`inspect target=run:${run} view=control`];
+  }
+  if (result.stopped === true) return [`inspect target=run:${run} view=control`];
+  return [];
+}
+
+export interface ControlToolDeps {
+  handleRuntimeControl?: (
+    action: string,
+    input: unknown,
+  ) => Record<string, unknown>;
+}
+
+export function createControlToolDefinition<TContext = unknown>(
+  deps: ControlToolDeps = {},
+): any {
+  return {
+    name: "message",
+    label: "Control",
+    description:
+      "Apply one Control action to an existing Run or the pi-actors runtime.",
+    parameters: Schema.objectSchema(
+      {
+        target: Schema.stringSchema("Run target run:<id>, or literal runtime."),
+        action: Schema.stringSchema("Lowercase ASCII Control action, at most 64 characters."),
+        input: Schema.unionSchema([
+          Schema.stringSchema("Optional Control input string; serialized JSON must fit 380 bytes."),
+          Schema.looseObjectSchema("Optional structured Control input; serialized JSON must fit 380 bytes."),
+          Schema.arraySchema("Optional structured Control input array; serialized JSON must fit 380 bytes."),
+        ]),
+        verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
+      },
+      ["target", "action"],
+    ),
+    async execute(
+      _toolCallId: string,
+      params: unknown,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: TContext,
+    ) {
+      const request = Control.normalizeControlRequest(params);
+      let result: Record<string, unknown>;
+      if (request.target === "runtime") {
+        if (request.action !== "review.retry" && request.action !== "review.reset") {
+          throw new Error(
+            `unsupported runtime Control action: ${request.action}; use review.retry or review.reset`,
+          );
+        }
+        if (!deps.handleRuntimeControl) {
+          throw new Error("runtime Control is unavailable");
+        }
+        result = deps.handleRuntimeControl(request.action, request.input);
+      } else {
+        const run = request.target.slice(4);
+        const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);
+        const runInstanceId =
+          typeof status.run_instance_id === "string"
+            ? status.run_instance_id
+            : undefined;
+        if (!runInstanceId) throw new Error(`Run generation unavailable: ${run}`);
+        if (request.action === "kill") {
+          result = AsyncRuns.killRun(run, {
+            ...(typeof status.ownerId === "string"
+              ? { ownerId: status.ownerId }
+              : {}),
+            runInstanceId,
+          });
+        } else if (request.action === "archive") {
+          result = AsyncRuns.archiveRun(run, {
+            ...(typeof status.ownerId === "string"
+              ? { ownerId: status.ownerId }
+              : {}),
+            runInstanceId,
+          });
+        } else if (request.action === "prune") {
+          const input = asRecord(request.input);
+          result = AsyncRuns.pruneRun(
+            run,
+            {
+              preserveArtifacts:
+                input.preserve_artifacts === true ||
+                input.preserveArtifacts === true,
+            },
+            {
+              ...(typeof status.ownerId === "string"
+                ? { ownerId: status.ownerId }
+                : {}),
+              runInstanceId,
+            },
+          );
+        } else {
+          const declared = Array.isArray(status.control)
+            ? status.control.filter(
+                (action): action is string => typeof action === "string",
+              )
+            : [];
+          if (!declared.includes(request.action)) {
+            throw new Error(
+              `undeclared Run Control action: ${request.action}; available=${declared.join(",") || "none"}`,
+            );
+          }
+          result = await AsyncRuns.sendRunControl(
+            run,
+            {
+              action: request.action,
+              ...(request.input !== undefined ? { input: request.input } : {}),
+              run_instance_id: runInstanceId,
+            },
+            {
+              ...(typeof status.ownerId === "string"
+                ? { ownerId: status.ownerId }
+                : {}),
+            },
+          );
+        }
+        const nextActions = runNextActions(run, result);
+        if (nextActions.length > 0) result = { ...result, next_actions: nextActions };
+      }
+      const response = { control: request, result };
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              request.verbose === true
+                ? ToolsResponse.jsonText(response)
+                : compactControlResult(request, result),
+          },
+        ],
+        details: response,
+      };
+    },
+  };
+}

package/node_modules/@llblab/pi-actors/lib/tools-register.ts

@@ -0,0 +1,63 @@
+/**
+ * Public register_tool behavior
+ * Zones: runtime tool registration, tool registry mutation, register_tool schema
+ * Owns the public register_tool definition that persists local agent capabilities
+ */
+
+import * as Prompts from "./prompts.ts";
+import * as Registry from "./registry.ts";
+import * as Schema from "./schema.ts";
+
+export type RegisterToolInput = Registry.RegisterToolInput;
+export type RegisterToolRuntimeDeps<TContext> =
+  Registry.RegisterToolRuntimeDeps<TContext>;
+
+const stringSchema = Schema.stringSchema;
+const booleanSchema = Schema.booleanSchema;
+const nullSchema = Schema.nullSchema;
+const arraySchema = Schema.arraySchema;
+const unionSchema = Schema.unionSchema;
+const objectSchema = Schema.objectSchema;
+const looseObjectSchema = Schema.looseObjectSchema;
+
+export function createRegisterToolDefinition<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+) {
+  return {
+    name: "register_tool",
+    label: "Register Tool",
+    description: Prompts.REGISTER_TOOL_DESCRIPTION,
+    promptSnippet: Prompts.REGISTER_TOOL_PROMPT_SNIPPET,
+    promptGuidelines: Prompts.REGISTER_TOOL_GUIDELINES,
+    parameters: objectSchema(
+      {
+        args: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.args),
+        async: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.async),
+        description: stringSchema(
+          Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.description,
+        ),
+        defaults: looseObjectSchema(
+          Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.defaults,
+        ),
+        draft: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.draft),
+        from: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.from),
+        name: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.name),
+        template: unionSchema([
+          stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
+          looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
+          arraySchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateArray),
+          nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
+        ]),
+        update: booleanSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.update),
+      },
+      [],
+    ),
+    execute: async (
+      _toolCallId: string,
+      params: unknown,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: TContext,
+    ) => Registry.executeRegisterTool(params, ctx, deps),
+  };
+}