@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,204 @@
+/**
+ * Actor Inspector evidence readers.
+ * Zones: owned actor-instance inventory and captured Recipe projection
+ * Owns actor-instance TUI evidence; Trace, Control, and execution parsing stay in their domains.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import * as SessionEvidence from "./session-evidence.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export interface ActorInspectorRunItem {
+  run: string;
+  runInstanceId?: string;
+  status: string;
+  updatedAt?: string;
+}
+
+function matchesOwner(stateDir: string, ownerId: string): boolean {
+  const meta = readJsonFileResilient<Record<string, unknown>>(
+    path.join(stateDir, "run.json"),
+    {},
+  ).value;
+  return meta.ownerId === ownerId;
+}
+
+export function readActorInspectorRuns(
+  stateRoot: string,
+  ownerId: string,
+): ActorInspectorRunItem[] {
+  try {
+    return fs
+      .readdirSync(stateRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .flatMap((entry) => {
+        const stateDir = path.join(stateRoot, entry.name);
+        if (!matchesOwner(stateDir, ownerId)) return [];
+        const runMeta = readJsonFileResilient<Record<string, unknown>>(
+          path.join(stateDir, "run.json"),
+          {},
+        ).value;
+        const progress = readJsonFileResilient<Record<string, unknown>>(
+          path.join(stateDir, "progress.json"),
+          {},
+        ).value;
+        const result = readJsonFileResilient<Record<string, unknown>>(
+          path.join(stateDir, "result.json"),
+          {},
+        ).value;
+        return [{
+          run: entry.name,
+          ...(typeof runMeta.run_instance_id === "string"
+            ? { runInstanceId: runMeta.run_instance_id }
+            : {}),
+          status: String(
+            progress.phase ??
+              (Object.keys(result).length ? "terminal" : "unknown"),
+          ),
+          ...(typeof progress.updatedAt === "string"
+            ? { updatedAt: progress.updatedAt }
+            : typeof result.completedAt === "string"
+              ? { updatedAt: result.completedAt }
+              : {}),
+        }];
+      })
+      .sort((left, right) =>
+        String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")) ||
+        right.run.localeCompare(left.run),
+      );
+  } catch {
+    return [];
+  }
+}
+
+export interface ActorInspectorRecipeView {
+  composition: Array<Record<string, unknown>>;
+  definition?: Record<string, unknown>;
+  diagnostics: string[];
+  identity: Record<string, unknown>;
+  launch: Record<string, unknown>;
+}
+
+export function readActorInspectorRecipe(
+  stateDir: string,
+): ActorInspectorRecipeView {
+  const result = readJsonFileResilient<Record<string, unknown>>(
+    path.join(stateDir, "run.json"),
+    {},
+  );
+  const meta = result.value;
+  const contexts = Array.isArray(meta.recipe_context_records)
+    ? meta.recipe_context_records.filter(
+        (entry): entry is Record<string, unknown> =>
+          Boolean(entry && typeof entry === "object" && !Array.isArray(entry)),
+      )
+    : [];
+  const primary = contexts.find((entry) => entry.depth === 0) ?? contexts[0];
+  const definition =
+    primary?.recipe &&
+    typeof primary.recipe === "object" &&
+    !Array.isArray(primary.recipe)
+      ? (primary.recipe as Record<string, unknown>)
+      : undefined;
+  const stripPrivateOrigins = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(stripPrivateOrigins);
+    if (!value || typeof value !== "object") return value;
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(
+          ([key, entry]) =>
+            entry !== undefined &&
+            key !== "recipe_dir" &&
+            key !== "skill_dir" &&
+            key !== "source_file",
+        )
+        .map(([key, entry]) => [
+          key,
+          key === "actorRecipeContext" && entry && typeof entry === "object"
+            ? stripPrivateOrigins(
+                Object.fromEntries(
+                  Object.entries(entry as Record<string, unknown>).filter(
+                    ([contextKey]) => contextKey !== "file",
+                  ),
+                ),
+              )
+            : stripPrivateOrigins(entry),
+        ]),
+    );
+  };
+  const redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
+    SessionEvidence.redactSessionEvidenceValue(
+      stripPrivateOrigins(value),
+    ) as Record<string, unknown>;
+  const primarySourceKind =
+    primary?.source_kind === "active_skill_component"
+      ? "active_skill_component"
+      : primary?.source_kind === "user_registry_capability" ||
+          meta.launch_source === "tool"
+        ? "user_registry_capability"
+        : "explicit_file_recipe";
+  const primaryLogicalReference =
+    typeof primary?.logical_reference === "string"
+      ? primary.logical_reference
+      : typeof primary?.name === "string"
+        ? primary.name
+        : typeof meta.recipe === "string"
+          ? meta.recipe
+          : "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({
+        ...(typeof entry.alias === "string" ? { alias: entry.alias } : {}),
+        depth: entry.depth,
+        import_path: entry.import_path,
+        logical_reference: entry.logical_reference ?? entry.name,
+        recipe_stem: entry.name,
+        role: entry.role,
+        ...(typeof entry.skill === "string" ? { skill: entry.skill } : {}),
+        source_kind:
+          entry.source_kind === "active_skill_component"
+            ? "active_skill_component"
+            : entry.source_kind === "user_registry_capability" ||
+                (entry.depth === 0 && meta.launch_source === "tool")
+              ? "user_registry_capability"
+              : "explicit_file_recipe",
+      }),
+    ),
+    ...(definition ? { definition: redactedRecord(definition) } : {}),
+    diagnostics: result.diagnostics.map((diagnostic) => diagnostic.message),
+    identity: redactedRecord({
+      run: meta.run,
+      recipe: meta.recipe,
+      recipe_stem: primary?.name ?? meta.recipe,
+      logical_reference: primaryLogicalReference,
+      ...(typeof primary?.skill === "string" ? { skill: primary.skill } : {}),
+      source_kind: primarySourceKind,
+      launch_kind: meta.launch_kind ?? meta.launch_source,
+      launch_source: meta.launch_source,
+      ...(meta.singleton === true
+        ? { singleton: true, singleton_recipe_id: meta.singleton_recipe_id }
+        : {}),
+    }),
+    launch: redactedRecord({
+      cwd: meta.cwd,
+      template: meta.template,
+      values: launchValues,
+      model_policy: meta.model_policy,
+      control: meta.control,
+      artifacts: meta.artifacts,
+      notification_policy: meta.notification_policy,
+      retire_when: meta.retire_when,
+      singleton_values: meta.singleton_values,
+    }),
+  };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Shared output, preview, and Control envelope limits.
+ * Zones: output governance, Trace previews, Inspect defaults, Control portability
+ */
+
+export const DEFAULT_INSPECT_LINES = 40;
+export const TOOL_OUTPUT_MAX_BYTES = 50 * 1024;
+export const TOOL_OUTPUT_MAX_LINES = 2_000;
+export const COMPACT_PREVIEW_CHARS = 160;
+export const CONTROL_ACTION_MAX_LENGTH = 64;
+export const CONTROL_INPUT_MAX_BYTES = 380;
+export const CONTROL_WIRE_MAX_BYTES = 512;
+export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
+export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export const SESSION_EVIDENCE_MAX_TURNS = 100;
+export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
+export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;
+export const TRACE_EVENT_MAX_BYTES = 64 * 1024;
+export const TRACE_EVENT_MAX_READ = 200;
+export const TRACE_JOURNAL_MAX_EVENTS = 2_048;
+export const TRACE_JOURNAL_TARGET_EVENTS = 1_536;
+export const TRACE_JOURNAL_MAX_BYTES = 4 * 1024 * 1024;
+export const TRACE_JOURNAL_TARGET_BYTES = 3 * 1024 * 1024;
+export const RUN_CONTROL_PENDING_LIMIT = 64;
+export const RUN_CONTROL_TERMINAL_LIMIT = 128;
+export const RUN_CONTROL_ERROR_MAX_BYTES = 4 * 1024;
+export const RUN_CONTROL_JOURNAL_MAX_BYTES = 1024 * 1024;
+export const RUN_RETENTION_MAX_RECORDS = 256;
+export const RUN_RETENTION_MAX_BYTES = 1024 * 1024;

package/node_modules/@llblab/pi-actors/lib/model-context.ts

@@ -0,0 +1,359 @@
+/**
+ * Current model/thinking propagation helpers
+ * Zones: pi session context, recipe inheritance
+ * Owns current model/thinking extraction from Pi tool contexts and implicit command-template values.
+ */
+
+export interface CurrentModelContext {
+  currentThinking?: unknown;
+  getThinkingLevel?: () => unknown;
+  model?: {
+    id?: unknown;
+    modelId?: unknown;
+    provider?: unknown;
+  };
+  sessionManager?: {
+    getBranch?: () => unknown[];
+    getSessionId?: () => string;
+  };
+  thinkingLevel?: unknown;
+}
+
+export const CURRENT_MODEL_VALUE_KEY = "current_model";
+export const CURRENT_THINKING_VALUE_KEY = "current_thinking";
+
+export type CurrentPolicySource =
+  | "explicit"
+  | "inherited"
+  | "mixed"
+  | "unresolved"
+  | "unused";
+
+export interface CurrentPolicyAxisProvenance {
+  explicit_keys?: string[];
+  inherited_keys?: string[];
+  source: CurrentPolicySource;
+  unresolved_keys?: string[];
+  value?: string;
+}
+
+export interface CurrentPolicyProvenance {
+  model: CurrentPolicyAxisProvenance;
+  thinking: CurrentPolicyAxisProvenance;
+}
+
+export interface CurrentPolicyRecipeSummary {
+  model?: {
+    inherited_defaults?: string[];
+    public_args?: string[];
+  };
+  thinking?: {
+    inherited_defaults?: string[];
+    public_args?: string[];
+  };
+}
+
+export function getCurrentModelPattern(
+  ctx: CurrentModelContext | undefined,
+): string | undefined {
+  const provider = ctx?.model?.provider;
+  const id = ctx?.model?.id ?? ctx?.model?.modelId;
+  if (typeof provider !== "string" || !provider.trim()) return undefined;
+  if (typeof id !== "string" || !id.trim()) return undefined;
+  return `${provider.trim()}/${id.trim()}`;
+}
+
+function normalizeThinkingLevel(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function getSessionThinkingLevel(
+  ctx: CurrentModelContext | undefined,
+): string | undefined {
+  const branch = ctx?.sessionManager?.getBranch?.();
+  if (!Array.isArray(branch)) return undefined;
+  for (const entry of [...branch].reverse()) {
+    if (!entry || typeof entry !== "object") continue;
+    const record = entry as Record<string, unknown>;
+    if (record.type !== "thinking_level_change") continue;
+    const level = normalizeThinkingLevel(record.thinkingLevel);
+    if (level) return level;
+  }
+  return undefined;
+}
+
+export function getCurrentThinkingLevel(
+  ctx: CurrentModelContext | undefined,
+): string | undefined {
+  return (
+    normalizeThinkingLevel(ctx?.currentThinking) ??
+    normalizeThinkingLevel(ctx?.thinkingLevel) ??
+    normalizeThinkingLevel(ctx?.getThinkingLevel?.()) ??
+    getSessionThinkingLevel(ctx)
+  );
+}
+
+export function withCurrentModelValues<T extends Record<string, unknown>>(
+  values: T,
+  ctx: CurrentModelContext | undefined,
+): T & Record<string, unknown> {
+  const currentModel = getCurrentModelPattern(ctx);
+  const currentThinking = getCurrentThinkingLevel(ctx);
+  if (!currentModel && !currentThinking) return values;
+  return {
+    ...values,
+    ...(currentModel ? { [CURRENT_MODEL_VALUE_KEY]: currentModel } : {}),
+    ...(currentThinking
+      ? { [CURRENT_THINKING_VALUE_KEY]: currentThinking }
+      : {}),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function stringReferencesPlaceholder(
+  value: string,
+  placeholder: string,
+): boolean {
+  return new RegExp(`\\{\\s*${placeholder}\\s*\\}`).test(value);
+}
+
+function modelPolicyKeyMatches(key: string): boolean {
+  return /(^|_)models?$/.test(key);
+}
+
+function thinkingPolicyKeyMatches(key: string): boolean {
+  return /(^|_)(thinking|thinking_level)$/.test(key);
+}
+
+function argName(token: unknown): string | undefined {
+  if (typeof token !== "string") return undefined;
+  return token.split(":")[0]?.trim() || undefined;
+}
+
+function collectPolicyDefaults(
+  value: unknown,
+  placeholder: string,
+  path = "template",
+  keys = new Set<string>(),
+): Set<string> {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      collectPolicyDefaults(item, placeholder, `${path}[${index}]`, keys),
+    );
+    return keys;
+  }
+  if (!isRecord(value)) return keys;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "defaults" && isRecord(child)) {
+      for (const [defaultKey, defaultValue] of Object.entries(child)) {
+        if (
+          typeof defaultValue === "string" &&
+          stringReferencesPlaceholder(defaultValue, placeholder)
+        ) {
+          keys.add(defaultKey);
+        }
+      }
+      continue;
+    }
+    collectPolicyDefaults(child, placeholder, `${path}.${key}`, keys);
+  }
+  return keys;
+}
+
+function collectPolicyDirectRefs(
+  value: unknown,
+  placeholder: string,
+  path = "template",
+  refs = new Set<string>(),
+): Set<string> {
+  if (typeof value === "string") {
+    if (stringReferencesPlaceholder(value, placeholder)) refs.add(path);
+    return refs;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      collectPolicyDirectRefs(item, placeholder, `${path}[${index}]`, refs),
+    );
+    return refs;
+  }
+  if (!isRecord(value)) return refs;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "defaults") continue;
+    collectPolicyDirectRefs(child, placeholder, `${path}.${key}`, refs);
+  }
+  return refs;
+}
+
+function summarizePolicyAxis(input: {
+  currentValue?: string;
+  directRefKey: string;
+  explicitKeyMatches: (key: string) => boolean;
+  explicitValues: Record<string, unknown>;
+  inheritedDefaultKeys: Set<string>;
+  directRefs: Set<string>;
+}): CurrentPolicyAxisProvenance {
+  const explicitKeys = Object.keys(input.explicitValues)
+    .filter(
+      (key) =>
+        key !== CURRENT_MODEL_VALUE_KEY &&
+        key !== CURRENT_THINKING_VALUE_KEY &&
+        input.explicitKeyMatches(key),
+    )
+    .sort();
+  const inheritedKeys = [...input.inheritedDefaultKeys]
+    .filter((key) => !Object.hasOwn(input.explicitValues, key))
+    .sort();
+  const directRefs = [...input.directRefs].length > 0 ? [input.directRefKey] : [];
+  const inheritedOrDirect = [...new Set([...inheritedKeys, ...directRefs])].sort();
+  const unresolvedKeys = input.currentValue ? [] : inheritedOrDirect;
+  const inheritedResolvedKeys = input.currentValue ? inheritedOrDirect : [];
+  const hasExplicit = explicitKeys.length > 0;
+  const hasInherited = inheritedResolvedKeys.length > 0;
+  const source: CurrentPolicySource = unresolvedKeys.length
+    ? "unresolved"
+    : hasExplicit && hasInherited
+      ? "mixed"
+      : hasExplicit
+        ? "explicit"
+        : hasInherited
+          ? "inherited"
+          : "unused";
+  const explicitValue = explicitKeys
+    .map((key) => input.explicitValues[key])
+    .find((value) => typeof value === "string" && value.trim());
+  const value = hasInherited
+    ? input.currentValue
+    : typeof explicitValue === "string"
+      ? explicitValue
+      : undefined;
+  return {
+    ...(explicitKeys.length ? { explicit_keys: explicitKeys } : {}),
+    ...(inheritedResolvedKeys.length
+      ? { inherited_keys: inheritedResolvedKeys }
+      : {}),
+    source,
+    ...(unresolvedKeys.length ? { unresolved_keys: unresolvedKeys } : {}),
+    ...(value ? { value } : {}),
+  };
+}
+
+function collectPolicyDefaultsAcross(
+  items: unknown[],
+  placeholder: string,
+): Set<string> {
+  return items.reduce<Set<string>>(
+    (keys, item) => collectPolicyDefaults(item, placeholder, "template", keys),
+    new Set<string>(),
+  );
+}
+
+function collectPolicyDirectRefsAcross(
+  items: unknown[],
+  placeholder: string,
+): Set<string> {
+  return items.reduce<Set<string>>(
+    (refs, item) => collectPolicyDirectRefs(item, placeholder, "template", refs),
+    new Set<string>(),
+  );
+}
+
+export function describeCurrentPolicyProvenance(input: {
+  defaults?: Record<string, unknown>;
+  template: unknown;
+  values?: Record<string, unknown>;
+}): CurrentPolicyProvenance {
+  const explicitValues = input.values ?? {};
+  const defaultsEnvelope = input.defaults ? { defaults: input.defaults } : {};
+  const templateAndDefaults = [defaultsEnvelope, input.template];
+  return {
+    model: summarizePolicyAxis({
+      currentValue:
+        typeof explicitValues[CURRENT_MODEL_VALUE_KEY] === "string"
+          ? String(explicitValues[CURRENT_MODEL_VALUE_KEY])
+          : undefined,
+      directRefKey: CURRENT_MODEL_VALUE_KEY,
+      directRefs: collectPolicyDirectRefsAcross(
+        templateAndDefaults,
+        "current_model",
+      ),
+      explicitKeyMatches: modelPolicyKeyMatches,
+      explicitValues,
+      inheritedDefaultKeys: collectPolicyDefaultsAcross(
+        templateAndDefaults,
+        "current_model",
+      ),
+    }),
+    thinking: summarizePolicyAxis({
+      currentValue:
+        typeof explicitValues[CURRENT_THINKING_VALUE_KEY] === "string"
+          ? String(explicitValues[CURRENT_THINKING_VALUE_KEY])
+          : undefined,
+      directRefKey: CURRENT_THINKING_VALUE_KEY,
+      directRefs: collectPolicyDirectRefsAcross(
+        templateAndDefaults,
+        "current_thinking",
+      ),
+      explicitKeyMatches: thinkingPolicyKeyMatches,
+      explicitValues,
+      inheritedDefaultKeys: collectPolicyDefaultsAcross(
+        templateAndDefaults,
+        "current_thinking",
+      ),
+    }),
+  };
+}
+
+function publicPolicyArgs(
+  args: unknown,
+  matches: (key: string) => boolean,
+): string[] {
+  return Array.isArray(args)
+    ? args
+        .map(argName)
+        .filter((key): key is string => Boolean(key && matches(key)))
+        .sort()
+    : [];
+}
+
+function nonEmptyAxisRecipeSummary(
+  inheritedDefaults: string[],
+  publicArgs: string[],
+): { inherited_defaults?: string[]; public_args?: string[] } | undefined {
+  if (inheritedDefaults.length === 0 && publicArgs.length === 0)
+    return undefined;
+  return {
+    ...(inheritedDefaults.length
+      ? { inherited_defaults: inheritedDefaults }
+      : {}),
+    ...(publicArgs.length ? { public_args: publicArgs } : {}),
+  };
+}
+
+export function describeRecipeCurrentPolicy(input: {
+  args?: unknown;
+  defaults?: Record<string, unknown>;
+  template: unknown;
+}): CurrentPolicyRecipeSummary | undefined {
+  const templateAndDefaults = [
+    input.defaults ? { defaults: input.defaults } : {},
+    input.template,
+  ];
+  const model = nonEmptyAxisRecipeSummary(
+    [...collectPolicyDefaultsAcross(templateAndDefaults, "current_model")].sort(),
+    publicPolicyArgs(input.args, modelPolicyKeyMatches),
+  );
+  const thinking = nonEmptyAxisRecipeSummary(
+    [
+      ...collectPolicyDefaultsAcross(templateAndDefaults, "current_thinking"),
+    ].sort(),
+    publicPolicyArgs(input.args, thinkingPolicyKeyMatches),
+  );
+  if (!model && !thinking) return undefined;
+  return {
+    ...(model ? { model } : {}),
+    ...(thinking ? { thinking } : {}),
+  };
+}