@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/lib/config.ts

@@ -0,0 +1,261 @@
+/**
+ * Persistent tool registry config helpers
+ * Zones: registry config, persistence, normalization
+ * Owns registered-tool config loading, normalization, unsupported-shape rejection, and serialization
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import type { CommandTemplateValue } from "./command-templates.ts";
+import * as CommandTemplates from "./command-templates.ts";
+import { writeJsonAtomic } from "./file-state.ts";
+import { normalizeToolName } from "./identity.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import * as Schema from "./schema.ts";
+
+export interface RegisteredTool {
+  name: string;
+  description: string;
+  args: string[];
+  defaults: Record<string, string>;
+  argTypes?: Record<string, Schema.ToolArgType>;
+  recipe?: RecipesReferences.TemplateRecipeConfig;
+  template?: CommandTemplateValue;
+  storedArgs?: string[];
+  storedDefaults?: Record<string, string>;
+  sourcePath?: string;
+}
+
+export interface LoadConfigResult {
+  tools: Map<string, RegisteredTool>;
+  warnings: string[];
+  changed: boolean;
+}
+
+export function serializeTools(
+  source: Map<string, RegisteredTool>,
+): Record<string, unknown> {
+  const entries = [...source.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const result: Record<string, unknown> = {};
+  for (const [name, cfg] of entries) {
+    const entry: Record<string, unknown> = {
+      description: cfg.description,
+    };
+    if (cfg.storedArgs && cfg.storedArgs.length > 0)
+      entry.args = cfg.storedArgs;
+    if (cfg.storedDefaults && Object.keys(cfg.storedDefaults).length > 0)
+      entry.defaults = cfg.storedDefaults;
+    if (cfg.recipe?.name) entry.name = cfg.recipe.name;
+    if (cfg.recipe?.async !== undefined) entry.async = cfg.recipe.async;
+    if (cfg.recipe?.values) entry.values = cfg.recipe.values;
+    if (cfg.template) entry.template = cfg.template;
+    result[name] = entry;
+  }
+  return result;
+}
+
+export function saveTools(
+  path: string,
+  source: Map<string, RegisteredTool>,
+): string | undefined {
+  try {
+    writeJsonAtomic(path, serializeTools(source));
+    return undefined;
+  } catch (error) {
+    return getErrorMessage(error);
+  }
+}
+
+export function getStoredEntries(
+  raw: unknown,
+): Array<[string | undefined, unknown]> {
+  if (Array.isArray(raw)) return raw.map((value) => [undefined, value]);
+  if (raw && typeof raw === "object") {
+    return Object.entries(raw as Record<string, unknown>);
+  }
+  return [];
+}
+
+function getStoredTemplate(value: unknown): CommandTemplateValue | undefined {
+  if (typeof value === "string") return value.trim() || undefined;
+  if (!Array.isArray(value)) return undefined;
+  const template = value as CommandTemplates.CommandTemplateConfig[];
+  return CommandTemplates.expandCommandTemplateConfigs({ template }).length > 0
+    ? template
+    : undefined;
+}
+
+function formatTemplateForDescription(template: CommandTemplateValue): string {
+  return typeof template === "string" ? template : JSON.stringify(template);
+}
+
+export function normalizeStoredTool(
+  key: string | undefined,
+  value: unknown,
+  reservedToolNames: Set<string>,
+): { cfg?: RegisteredTool; changed: boolean; warning?: string } {
+  if (!value || typeof value !== "object") {
+    return {
+      changed: true,
+      warning: `Invalid tool entry: ${key ?? "<array item>"}`,
+    };
+  }
+  const record = value as Record<string, unknown>;
+  const rawName = key ?? (typeof record.name === "string" ? record.name : "");
+  const name = normalizeToolName(rawName);
+  if (!name) {
+    return {
+      changed: true,
+      warning: `Invalid tool name: ${rawName || key || "<empty>"}`,
+    };
+  }
+  if (reservedToolNames.has(name)) {
+    return { changed: true, warning: `Reserved tool name skipped: ${name}` };
+  }
+  const template = getStoredTemplate(record.template);
+  if (!template && typeof record.script === "string") {
+    return {
+      changed: false,
+      warning: `Tool "${name}" uses unsupported script config. Use template because pi-actors cannot load script entries.`,
+    };
+  }
+  if (record.job !== undefined || record.recipe !== undefined) {
+    return {
+      changed: false,
+      warning: `Tool "${name}" uses unsupported job/recipe config. Use template with optional name and async fields.`,
+    };
+  }
+  const keyedRecipeName =
+    key !== undefined && typeof record.name === "string" && record.name.trim()
+      ? record.name.trim()
+      : undefined;
+  if ((keyedRecipeName || typeof record.async === "boolean") && !template) {
+    return {
+      changed: false,
+      warning: `Tool "${name}" uses recipe config without template. Add template to make it a co-located template recipe.`,
+    };
+  }
+  if (!template) {
+    return { changed: true, warning: `Tool "${name}" has no template` };
+  }
+  const recipeName =
+    keyedRecipeName ?? (typeof record.async === "boolean" ? name : undefined);
+  const recipe: RecipesReferences.TemplateRecipeConfig | undefined = recipeName
+    ? {
+        name: recipeName,
+        ...(typeof record.async === "boolean" ? { async: record.async } : {}),
+        template,
+        ...(record.values &&
+        typeof record.values === "object" &&
+        !Array.isArray(record.values)
+          ? { values: record.values as Record<string, unknown> }
+          : {}),
+      }
+    : undefined;
+  const isRecipe = RecipesReferences.isRecipeTool(template, recipe);
+  const recipeTemplate = RecipesReferences.getRecipeTemplate(template);
+  const argTemplate = recipeTemplate ?? template;
+  const description =
+    typeof record.description === "string" && record.description.trim()
+      ? record.description.trim()
+      : isRecipe
+        ? `${recipe?.async === true || RecipesReferences.isAsyncRecipeReference(template) ? "Start async" : "Execute"} template recipe: ${recipe?.name ?? formatTemplateForDescription(template)}`
+        : `Execute command template: ${formatTemplateForDescription(template)}`;
+  const declarations = Schema.normalizeStoredToolArgDeclarations(
+    record.args,
+    record.defaults,
+  );
+  const storedArgs = declarations.provided
+    ? declarations.declarations
+    : undefined;
+  const storedDefaults =
+    declarations.provided && Object.keys(declarations.defaults).length > 0
+      ? declarations.defaults
+      : undefined;
+  const argTemplateConfig: CommandTemplates.CommandTemplateConfig =
+    typeof argTemplate === "object" && !Array.isArray(argTemplate)
+      ? {
+          ...argTemplate,
+          ...(storedArgs !== undefined ? { args: storedArgs } : {}),
+          defaults: {
+            ...(argTemplate.defaults ?? {}),
+            ...declarations.defaults,
+          },
+        }
+      : {
+          args: storedArgs,
+          defaults: declarations.defaults,
+          template: argTemplate,
+        };
+  const inferredArgTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  Schema.assertCompatibleToolArgTypes(
+    inferredArgTypes,
+    declarations.argTypes,
+  );
+  const argTypes = { ...inferredArgTypes, ...declarations.argTypes };
+  const cfg = {
+    name,
+    description,
+    args:
+      isRecipe && storedArgs !== undefined
+        ? Schema.getExplicitToolArgNames(storedArgs)
+        : RecipesReferences.isRecipeReference(template) && !recipeTemplate
+          ? Schema.getExplicitToolArgNames(storedArgs)
+          : Schema.getToolArgNames(argTemplateConfig),
+    defaults: declarations.defaults,
+    ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
+    ...(recipe ? { recipe } : {}),
+    template,
+    ...(storedArgs !== undefined ? { storedArgs } : {}),
+    ...(storedDefaults !== undefined ? { storedDefaults } : {}),
+  };
+  const changed =
+    (key === undefined && record.name !== undefined) ||
+    record.label !== undefined ||
+    JSON.stringify(record.template) !== JSON.stringify(template) ||
+    description !== record.description ||
+    declarations.changed;
+  return { cfg, changed };
+}
+
+export function loadToolConfig(
+  path: string,
+  reservedToolNames: Set<string>,
+): LoadConfigResult {
+  const warnings: string[] = [];
+  const tools = new Map<string, RegisteredTool>();
+  let changed = false;
+  if (!existsSync(path)) return { tools, warnings, changed };
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const entries = getStoredEntries(raw);
+    for (const [key, value] of entries) {
+      const result = normalizeStoredTool(key, value, reservedToolNames);
+      changed = changed || result.changed;
+      if (result.warning) warnings.push(result.warning);
+      if (!result.cfg) continue;
+      if (tools.has(result.cfg.name)) {
+        warnings.push(
+          `Duplicate tool kept from last entry: ${result.cfg.name}`,
+        );
+      }
+      if (tools.has(result.cfg.name)) changed = true;
+      tools.set(result.cfg.name, result.cfg);
+    }
+    if (entries.length === 0 && raw && typeof raw !== "object") {
+      warnings.push(`Invalid ${path} format`);
+    }
+    if (entries.length === 0 && raw && typeof raw !== "object") changed = true;
+    return { tools, warnings, changed };
+  } catch (error) {
+    return {
+      tools,
+      warnings: [`Failed to load ${path}: ${getErrorMessage(error)}`],
+      changed: false,
+    };
+  }
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/node_modules/@llblab/pi-actors/lib/control-projection.ts

@@ -0,0 +1,105 @@
+/**
+ * Model-facing Run Control projection.
+ * Zones: structured redaction, bounded Control input/error, decision-useful evidence
+ * Owns safe Control reads; durable journals and lifecycle transitions remain in runs-controls.
+ */
+
+import * as Limits from "./limits.ts";
+import type { RunControlRecord, RunControlStatus } from "./runs-controls.ts";
+import * as SessionEvidence from "./session-evidence.ts";
+
+export interface ProjectedRunControl {
+  action: string;
+  claimed_at?: string;
+  delivered_at?: string;
+  error?: string;
+  failed_at?: string;
+  handled_at?: string;
+  id: string;
+  input?: unknown;
+  queued_at: string;
+  run_instance_id: string;
+  status: RunControlStatus;
+}
+
+const OPTIONAL_TIMESTAMP_FIELDS = [
+  "claimed_at",
+  "delivered_at",
+  "failed_at",
+  "handled_at",
+] as const;
+type OptionalTimestampField = (typeof OPTIONAL_TIMESTAMP_FIELDS)[number];
+
+function boundedRedactedString(value: string, maxChars: number): string {
+  const redacted = SessionEvidence.redactSessionEvidenceValue(value, maxChars);
+  return typeof redacted === "string"
+    ? redacted
+    : String(redacted).slice(0, maxChars);
+}
+
+function boundedRedactedValue(value: unknown): unknown {
+  const redacted = SessionEvidence.redactSessionEvidenceValue(
+    value,
+    Limits.INSPECTOR_BODY_PREVIEW_CHARS,
+  );
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(redacted);
+  } catch {
+    return "[UNSERIALIZABLE]";
+  }
+  if (serialized === undefined) return "[UNSERIALIZABLE]";
+  if (serialized.length <= Limits.INSPECTOR_BODY_PREVIEW_CHARS) return redacted;
+  let preview = serialized.slice(0, Limits.INSPECTOR_BODY_PREVIEW_CHARS);
+  let bounded = { preview: `${preview}…`, truncated: true };
+  while (
+    preview &&
+    JSON.stringify(bounded).length > Limits.INSPECTOR_BODY_PREVIEW_CHARS
+  ) {
+    const excess = JSON.stringify(bounded).length - Limits.INSPECTOR_BODY_PREVIEW_CHARS;
+    preview = preview.slice(0, Math.max(0, preview.length - Math.max(1, excess)));
+    bounded = { preview: `${preview}…`, truncated: true };
+  }
+  return bounded;
+}
+
+export function projectRunControl(
+  control: RunControlRecord,
+): ProjectedRunControl {
+  const timestamps = Object.fromEntries(
+    OPTIONAL_TIMESTAMP_FIELDS.flatMap((field) => {
+      const value = control[field];
+      return typeof value === "string"
+        ? [[field, boundedRedactedString(value, Limits.COMPACT_PREVIEW_CHARS)] as const]
+        : [];
+    }),
+  ) as Partial<Pick<ProjectedRunControl, OptionalTimestampField>>;
+  return {
+    action: boundedRedactedString(control.action, Limits.COMPACT_PREVIEW_CHARS),
+    ...timestamps,
+    ...(typeof control.error === "string"
+      ? {
+          error: boundedRedactedString(
+            control.error,
+            Limits.INSPECTOR_BODY_PREVIEW_CHARS,
+          ),
+        }
+      : {}),
+    id: boundedRedactedString(control.id, Limits.COMPACT_PREVIEW_CHARS),
+    ...(control.input !== undefined
+      ? { input: boundedRedactedValue(control.input) }
+      : {}),
+    queued_at: boundedRedactedString(
+      control.queued_at,
+      Limits.COMPACT_PREVIEW_CHARS,
+    ),
+    run_instance_id: boundedRedactedString(
+      control.run_instance_id,
+      Limits.COMPACT_PREVIEW_CHARS,
+    ),
+    status: boundedRedactedString(
+      control.status,
+      Limits.COMPACT_PREVIEW_CHARS,
+    ) as RunControlStatus,
+  };
+}

package/node_modules/@llblab/pi-actors/lib/control.ts

@@ -0,0 +1,117 @@
+/**
+ * Run Control request contract.
+ * Zones: public request validation, Run/runtime target normalization, input bounds
+ * Owns pure Control validation; journaling, delivery, and lifecycle mutation stay in adapters.
+ */
+
+import * as Limits from "./limits.ts";
+
+export interface ControlRequest {
+  target: `run:${string}` | "runtime";
+  action: string;
+  input?: unknown;
+  verbose?: boolean;
+}
+
+const RUN_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const ACTION_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+const CONTROL_FIELDS = new Set(["action", "input", "target", "verbose"]);
+const REMOVED_FIELDS = new Set([
+  "body",
+  "correlation_id",
+  "from",
+  "metadata",
+  "reply_to",
+  "summary",
+  "to",
+  "type",
+]);
+
+export function isControlAction(value: string): boolean {
+  return ACTION_PATTERN.test(value);
+}
+
+export function normalizeControlAction(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("control.action is required");
+  }
+  const action = value.trim();
+  if (!isControlAction(action)) {
+    throw new Error(`invalid control action: ${action}`);
+  }
+  if (action.length > Limits.CONTROL_ACTION_MAX_LENGTH) {
+    throw new Error(
+      `control.action exceeds ${Limits.CONTROL_ACTION_MAX_LENGTH} ASCII characters`,
+    );
+  }
+  return action;
+}
+
+export function normalizeControlInput(input: unknown): unknown {
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(input);
+  } catch {
+    throw new Error("control.input must be JSON-serializable");
+  }
+  if (serialized === undefined) {
+    throw new Error("control.input must be JSON-serializable");
+  }
+  const bytes = Buffer.byteLength(serialized);
+  if (bytes > Limits.CONTROL_INPUT_MAX_BYTES) {
+    throw new Error(
+      `control.input exceeds ${Limits.CONTROL_INPUT_MAX_BYTES} serialized bytes`,
+    );
+  }
+  return JSON.parse(serialized) as unknown;
+}
+
+function normalizeTarget(value: unknown): ControlRequest["target"] {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("control.target is required");
+  }
+  const target = value.trim();
+  if (target === "runtime") return target;
+  if (!target.startsWith("run:")) {
+    throw new Error(
+      `unsupported control target: ${target}; use run:<id> or runtime`,
+    );
+  }
+  const run = target.slice(4);
+  if (!RUN_ID_PATTERN.test(run)) {
+    throw new Error(`invalid control Run target: ${target}`);
+  }
+  return `run:${run}`;
+}
+
+export function normalizeControlRequest(input: unknown): ControlRequest {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("control request must be an object");
+  }
+  const record = input as Record<string, unknown>;
+  const fields = Object.keys(record);
+  const removed = fields.filter((field) => REMOVED_FIELDS.has(field));
+  if (removed.length > 0) {
+    throw new Error(
+      `actor-message fields are removed: ${removed.sort().join(", ")}; use target, action, input, verbose`,
+    );
+  }
+  const unknown = fields.filter((field) => !CONTROL_FIELDS.has(field));
+  if (unknown.length > 0) {
+    throw new Error(`unsupported control fields: ${unknown.sort().join(", ")}`);
+  }
+  const target = normalizeTarget(record.target);
+  const action = normalizeControlAction(record.action);
+  if (record.verbose !== undefined && typeof record.verbose !== "boolean") {
+    throw new Error("control.verbose must be a boolean");
+  }
+  const normalizedInput = record.input === undefined
+    ? undefined
+    : normalizeControlInput(record.input);
+  return {
+    target,
+    action,
+    ...(normalizedInput !== undefined ? { input: normalizedInput } : {}),
+    ...(record.verbose !== undefined ? { verbose: record.verbose } : {}),
+  };
+}