@llblab/pi-kit 0.38.4 → 0.39.0

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

@@ -7,14 +7,17 @@
 import type {
   ExtensionAPI,
   ExtensionContext,
+  SessionStartEvent,
   CustomMessageEntryDraft,
   TurnEndEvent,
   TurnEndEventResult,
 } from "@earendil-works/pi-coding-agent";
 
 import * as SessionEvidence from "./session-evidence.ts";
+import * as RunDelivery from "./run-delivery.ts";
 
-export type { ExtensionAPI, ExtensionContext, TurnEndEvent, TurnEndEventResult };
+export type { ExtensionAPI, ExtensionContext, SessionStartEvent, TurnEndEvent, TurnEndEventResult };
+export { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 
 export const RUN_COMPLETION_BATCH_CUSTOM_TYPE = "pi-actors-run-batch";
 export const RUN_STEER_CUSTOM_TYPE = "pi-actors-run-steer";
@@ -50,6 +53,7 @@ export function createNotificationSink(
 export function createRunCompletionBatchEntry(
   batchId: string,
   content: string,
+  presentation?: unknown,
 ): CustomMessageEntryDraft {
   return {
     type: "custom_message",
@@ -61,6 +65,7 @@ export function createRunCompletionBatchEntry(
         batch_id: batchId,
         kind: "completion_batch",
       },
+      ...(presentation === undefined ? {} : { pi_actors_presentation: presentation }),
     },
   };
 }
@@ -69,8 +74,9 @@ export function sendRunCompletionBatch(
   pi: ExtensionAPI,
   batchId: string,
   content: string,
+  presentation?: unknown,
 ): void {
-  const { type: _type, ...message } = createRunCompletionBatchEntry(batchId, content);
+  const { type: _type, ...message } = createRunCompletionBatchEntry(batchId, content, presentation);
   pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 }
 
@@ -95,9 +101,39 @@ export function sendRunSteer(
   });
 }
 
+function hasCompletionFrontmatterPrefix(content: string): boolean {
+  const opening = /^\uFEFF?---[ \t]*(?:\r\n|\r|\n)/u.exec(content);
+  if (!opening) return false;
+  for (const line of content.slice(opening[0].length).split(/\r\n|\r|\n/u)) {
+    const field = line.trim();
+    if (field === "---") return false;
+    if (!field) continue;
+    if (/^(?:index|run|state|kind)[ \t]*:/iu.test(field) ||
+      ["index", "run", "state", "kind"].some(key => key.startsWith(field.toLowerCase()))) return true;
+    // Continue through plausible metadata, not arbitrary thematic-break prose.
+    if (!/^[a-z_][a-z0-9_-]*[ \t]*:/iu.test(field)) return false;
+  }
+  return false;
+}
+
+function unheaderedCompletionId(content: string): string | { malformed: true } | undefined {
+  // Preserve the existing legacy RegExp coercion before inspecting compiler-owned record framing.
+  const legacyId = /^Batch: `([^`]{1,128})`$/mu.exec(content)?.[1];
+  if (typeof content === "string") {
+    const core = RunDelivery.readCompletionYamlCarrier(content);
+    if (core.state === "available") return core.packet.batchId;
+    // Initial compiler headers only: never recover identity by scanning authored bodies.
+    if (/^(?:index: (?:\d+|"\?")\nrun: [^\n]*\nstate:|_completion:\n  (?:codec|batch_id):)/u.test(content)) return { malformed: true };
+  }
+  if (typeof content === "string" && (hasCompletionFrontmatterPrefix(content) || /^(?:#|Run #|— Новый поток|- run:|- #0:\n|- result: omitted \(model byte limit\)\n|- omitted_results:)/u.test(content))) {
+    return RunDelivery.readRunCompletionRecordMarker(content)?.batchId ?? { malformed: true };
+  }
+  return legacyId;
+}
+
 function completionBatchMessage(
   message: unknown,
-): { batchId: string; content: string } | undefined {
+): { batchId: string; content: string } | { malformed: true } | undefined {
   if (!message || typeof message !== "object" || Array.isArray(message)) return undefined;
   const record = message as Record<string, unknown>;
   if (
@@ -115,9 +151,14 @@ function completionBatchMessage(
     typeof envelope.batch_id === "string"
     ? envelope.batch_id
     : undefined;
-  const contentId = /^Batch: `([^`]{1,128})`$/mu.exec(record.content)?.[1];
-  const batchId = detailedId ?? contentId;
-  if (!batchId || batchId.length > 128) return undefined;
+  // Retained headers or the new closed footer identify delivery; authored labels never override either.
+  const contentId = record.content.startsWith("- completion:")
+    ? /^- completion: ([^\r\n\u2028\u2029]{1,128})\n- presentation: ax_records\n/u.exec(record.content)?.[1]
+    : record.content.startsWith("- completions:")
+      ? /^- completions: [1-9]\d{0,2}\n- batch: ([^\r\n\u2028\u2029]{1,128})\n/u.exec(record.content)?.[1]
+      : unheaderedCompletionId(record.content);
+  const batchId = detailedId ?? (typeof contentId === "string" ? contentId : undefined);
+  if (!batchId || batchId.length > 128) return contentId && typeof contentId === "object" ? contentId : undefined;
   return { batchId, content: record.content };
 }
 
@@ -131,7 +172,7 @@ export function dedupeRunCompletionBatchContext(messages: unknown[]): {
   const conflicts = new Set<string>();
   for (const message of messages) {
     const batch = completionBatchMessage(message);
-    if (!batch) continue;
+    if (!batch || "malformed" in batch) continue;
     const existing = batches.get(batch.batchId);
     if (existing !== undefined && existing !== batch.content) {
       conflicts.add(batch.batchId);
@@ -142,7 +183,7 @@ export function dedupeRunCompletionBatchContext(messages: unknown[]): {
   const retained = new Set<string>();
   const filtered = messages.filter((message) => {
     const batch = completionBatchMessage(message);
-    if (!batch) return true;
+    if (!batch || "malformed" in batch) return true;
     if (conflicts.has(batch.batchId) || retained.has(batch.batchId)) return false;
     retained.add(batch.batchId);
     return true;
@@ -155,8 +196,10 @@ export function removeRunCompletionBatchFromContext(
   messages: unknown[],
   batchId: string,
 ): unknown[] {
-  return messages.filter((message) =>
-    completionBatchMessage(message)?.batchId !== batchId);
+  return messages.filter((message) => {
+    const batch = completionBatchMessage(message);
+    return !batch || "malformed" in batch || batch.batchId !== batchId;
+  });
 }
 
 function steerMessage(
@@ -232,15 +275,20 @@ export function inspectRunCompletionBatchSessionEvidence(
   ctx: ExtensionContext,
   input: { batchId: string; content: string },
 ): SessionEvidence.ActiveSessionEntryEvidence {
-  return SessionEvidence.inspectBoundedActiveSessionEntries({
+  let unidentifiedRecord = false;
+  const evidence = SessionEvidence.inspectBoundedActiveSessionEntries({
     getEntry: (id) => ctx.sessionManager.getEntry(id),
     leaf: ctx.sessionManager.getLeafEntry(),
     match: (entry) => {
       const batch = completionBatchMessage(entry);
+      if (batch && "malformed" in batch) { unidentifiedRecord = true; return undefined; }
       if (!batch || batch.batchId !== input.batchId) return undefined;
       return batch.content === input.content ? "present" : "conflict";
     },
   });
+  // An unidentified new record may be this pending epoch; it cannot prove absence or permit replay.
+  return evidence.status === "absent" && unidentifiedRecord
+    ? { ...evidence, status: "unknown", reason: "completion record correlation is unavailable" } : evidence;
 }
 
 export function inspectRunSteerSessionEvidence(

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

@@ -0,0 +1,232 @@
+/**
+ * Captured Recipe evidence projection.
+ * Owns: shared Recipe/launch privacy normalization, known runtime-origin scrubbing and pure captured-secret/reference comparison policy.
+ * Excludes: filesystem reads, identity admission, live Recipe resolution, export writes and native authority.
+ */
+import { isAbsolute, win32 } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { redactSessionEvidenceValue } from "./session-evidence.ts";
+
+function privateOriginScrubber(meta: Record<string, unknown>): (value: string) => string {
+  const origins = new Set<string>();
+  const collect = (value: unknown, actorContext = false): void => {
+    if (Array.isArray(value)) { value.forEach(item => collect(item)); return; }
+    if (!value || typeof value !== "object") return;
+    for (const [key, item] of Object.entries(value)) {
+      if ((["recipe_file", "source_file", "recipe_dir", "skill_dir"].includes(key) || (actorContext && key === "file")) &&
+        typeof item === "string" && item && (isAbsolute(item) || win32.isAbsolute(item))) origins.add(item);
+      collect(item, key === "actorRecipeContext");
+    }
+  };
+  collect({ recipe_file: meta.recipe_file, contexts: meta.recipe_context_records, values: meta.values,
+    template: meta.template, singleton_values: meta.singleton_values });
+  const longestFirst = [...origins].sort((a, b) => b.length - a.length);
+  // A directory suffix in a logical reference is not an absolute runtime-origin token.
+  return value => longestFirst.reduce((text, origin) => text.replaceAll(origin, (match, offset: number) =>
+    /[\p{L}\p{N}_.-]$/u.test(text.slice(0, offset)) ? match : "[PRIVATE_RECIPE_ORIGIN]"), value);
+}
+
+/** Pure Recipe-provenance privacy for captured evidence; this callback grants no runtime authority. */
+export function createRunRecipeEvidenceRedactor(meta: Record<string, unknown>, maxTextChars?: number): (value: unknown) => unknown {
+  const scrubOrigin = privateOriginScrubber(meta);
+  const stripPrivateOrigins = (value: unknown): unknown => {
+    if (typeof value === "string") return scrubOrigin(value);
+    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]) => [
+          scrubOrigin(key),
+          key === "actorRecipeContext" && entry && typeof entry === "object"
+            ? stripPrivateOrigins(
+                Object.fromEntries(
+                  Object.entries(entry as Record<string, unknown>).filter(
+                    ([contextKey]) => contextKey !== "file",
+                  ),
+                ),
+              )
+            : stripPrivateOrigins(entry),
+        ]),
+    );
+  };
+  return value => redactSessionEvidenceValue(stripPrivateOrigins(value), maxTextChars);
+}
+
+function capturedSecretLiterals(meta: Record<string, unknown>): string[] {
+  const literals = new Set<string>();
+  const collect = (value: unknown, sensitive = false): void => {
+    if (typeof value === "string") { if (sensitive && value) literals.add(value); return; }
+    if (!value || typeof value !== "object") return;
+    for (const [key, child] of Object.entries(value)) {
+      const privateKey = (redactSessionEvidenceValue({ [key]: "" }) as Record<string, unknown>)[key] === "[REDACTED]";
+      collect(child, sensitive || privateKey);
+    }
+  };
+  collect(meta);
+  return [...literals].sort((a, b) => b.length - a.length);
+}
+
+/** Literal sensitive-key privacy from captured data; does not admit metadata, references or producers. */
+export function capturedSecretMask(meta: Record<string, unknown>, replacement = "[REDACTED]"): (text: string) => string {
+  const escaped = capturedSecretLiterals(meta).map(value => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const secrets = escaped.length ? new RegExp(escaped.join("|"), "gu") : undefined;
+  return text => secrets ? text.replace(secrets, () => replacement) : text;
+}
+
+function capturedBodyPolicy(meta: Record<string, unknown>) {
+  const project = createRunRecipeEvidenceRedactor(meta, Number.MAX_SAFE_INTEGER), mask = capturedSecretMask(meta), literals = capturedSecretLiterals(meta);
+  const encoded = (value: string): string | undefined => {
+    const bom = value.startsWith("\uFEFF"); let parsed: unknown;
+    try { parsed = JSON.parse(bom ? value.slice(1) : value); } catch { return undefined; }
+    const present = literals.filter(literal => value.includes(literal));
+    if (present.length) {
+      // Probe only: never emit masked JSON or use its altered keys for sensitive-key decisions.
+      if (present.some(literal => JSON.stringify(literal).slice(1, -1) !== literal)) return "[REDACTED]";
+      try { const masked = mask(value); JSON.parse(bom ? masked.slice(1) : masked); } catch { return "[REDACTED]"; }
+    }
+    // Decode structured text before generic masking can alter its syntax; nested encoded content follows the same policy.
+    const projected = full(parsed);
+    return JSON.stringify(projected) === JSON.stringify(parsed) ? value : (bom ? "\uFEFF" : "") + JSON.stringify(projected);
+  };
+  const prepare = (value: unknown): unknown => {
+    if (typeof value === "string") return encoded(value) ?? value;
+    if (Array.isArray(value)) return value.map(prepare);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, prepare(item)]));
+    return value;
+  };
+  const scrub = (value: unknown): unknown => {
+    if (typeof value === "string") return mask(value);
+    if (Array.isArray(value)) return value.map(scrub);
+    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [mask(key), scrub(item)]));
+    return value;
+  };
+  const full = (value: unknown): unknown => scrub(project(prepare(value)));
+  return { full, encoded };
+}
+
+/** Original-publication body policy for already-admitted data; defaults elsewhere remain per-call origin/generic privacy. */
+export function createRunRecipeBodyRedactor(meta: Record<string, unknown>, maxTextChars?: number): (value: unknown) => unknown {
+  const { full } = capturedBodyPolicy(meta);
+  // All recorded content privacy precedes the existing display limit; no identity/source permission is minted.
+  return value => redactSessionEvidenceValue(full(value), maxTextChars);
+}
+
+/** Complete source text keeps public JSON spelling/BOM; never project its serialized protected JSON a second time. */
+export function createRunRecipeTextRedactor(meta: Record<string, unknown>): (text: string) => string {
+  const { full, encoded } = capturedBodyPolicy(meta);
+  return text => {
+    const projected = encoded(text) ?? full(text);
+    if (typeof projected !== "string") throw new Error("Run captured text privacy must return text.");
+    return projected;
+  };
+}
+
+/** Pure comparison for already-admitted closed reference data, never identity/source/body authority. */
+export function createContextIdentityPrivacyCheck(original: Record<string, unknown>): (identity: object) => boolean {
+  const redact = createRunRecipeEvidenceRedactor(original, Number.MAX_SAFE_INTEGER), withoutSecrets = capturedSecretMask(original, "");
+  // Removal detects presence even when an original credential literally equals the display replacement token.
+  return identity => isDeepStrictEqual(redact(identity), identity) && Object.values(identity).every(value => typeof value !== "string" || withoutSecrets(value) === value);
+}
+
+export interface RunRecipeView {
+  composition: Array<Record<string, unknown>>;
+  definition?: Record<string, unknown>;
+  diagnostics: string[];
+  identity: Record<string, unknown>;
+  launch: Record<string, unknown>;
+}
+
+export function projectRunRecipe(meta: Record<string, unknown>, diagnostics: readonly string[] = [],
+  redactEvidence: (value: unknown) => unknown = createRunRecipeEvidenceRedactor(meta)): RunRecipeView {
+  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 redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
+    redactEvidence(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: diagnostics.map(value => redactEvidence(value) as string),
+    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/recipes-context.ts

@@ -7,6 +7,7 @@
 import { createHash } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
 import * as RecipesReferences from "./recipes-references.ts";
@@ -64,8 +65,12 @@ function commandName(command: string): string {
   return basename(command).toLowerCase();
 }
 
-function isPiCommand(command: string): boolean {
-  return commandName(command) === "pi";
+const PI_NODE_CLI_PATHS = new Set(["./bundle/cli.js", "./cli.js"].map(path =>
+  fileURLToPath(new URL(path, import.meta.resolve("@earendil-works/pi-coding-agent")))));
+
+function isPiCommand(command: string, args: string[]): boolean {
+  const name = commandName(command);
+  return name === "pi" || ((name === "node" || name === "node.exe") && PI_NODE_CLI_PATHS.has(args[0]));
 }
 
 const PI_PRINT_FLAGS = new Set(["-p", "--print"]);
@@ -136,6 +141,21 @@ export function findPiPrintPromptIndex(args: string[]): number | undefined {
   return findPiPrintPromptIndexes(args).at(-1);
 }
 
+/** Pi text-print stdout (direct or resolved SDK CLI via Node) is the reply; JSON/RPC/interactive output is not. */
+export function piPrintResponseMode(command: string, args: string[]): "text" | "unsupported" | undefined {
+  if (!isPiCommand(command, args)) return undefined;
+  let print = false, mode = "text";
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]!;
+    if (arg === "--") break;
+    if (isPiPrintFlag(arg)) print = true;
+    else if (arg === "--mode") mode = args[++index] ?? "";
+    else if (arg.startsWith("--mode=")) mode = arg.slice(7);
+    else if (piOptionConsumesNextArg(arg)) index++;
+  }
+  return print && mode === "text" ? "text" : "unsupported";
+}
+
 function matchesActorContext(
   record: TemplateRecipeContextRecord,
   context: CommandTemplateActorRecipeContext | undefined,
@@ -202,7 +222,7 @@ export function appendRecipeContextToPiArgs(
   records: TemplateRecipeContextRecord[] | undefined,
   context?: CommandTemplateActorRecipeContext,
 ): string[] {
-  if (!records || records.length === 0 || !isPiCommand(command)) return args;
+  if (!records || records.length === 0 || !isPiCommand(command, args)) return args;
   const promptIndex = findPiPrintPromptIndex(args);
   if (promptIndex === undefined) return args;
   const block = buildRecipeContextPromptBlock(records, context);
@@ -230,11 +250,12 @@ export function attachPiSessionDir(
   args: string[],
   sessionDir: string,
 ): ManagedPiSessionArgs {
-  if (!isPiCommand(command) || findPiPrintPromptIndex(args) === undefined) {
+  if (!isPiCommand(command, args) || findPiPrintPromptIndex(args) === undefined) {
     return { args };
   }
   if (args.some((arg) => PI_SESSION_POLICY_FLAGS.has(arg))) return { args };
-  return { args: ["--session-dir", sessionDir, ...args], sessionDir };
+  const prefix = commandName(command) === "pi" ? 0 : 1;
+  return { args: [...args.slice(0, prefix), "--session-dir", sessionDir, ...args.slice(prefix)], sessionDir };
 }
 
 export interface MaterializedPiPrintPromptArgs {
@@ -248,7 +269,7 @@ export function materializePiPrintPromptArg(
   args: string[],
   promptFile: string | (() => string),
 ): MaterializedPiPrintPromptArgs {
-  if (!isPiCommand(command)) return { args };
+  if (!isPiCommand(command, args)) return { args };
   const promptIndexes = findPiPrintPromptIndexes(args);
   if (promptIndexes.length === 0) return { args };
   const prompt = promptIndexes.map((index) => args[index]).join(" ");