@llblab/pi-actors 0.33.0 → 0.34.1

package/dist/lib/command-templates.d.ts

@@ -1,7 +1,7 @@
 /**
- * Command-template standard helpers
- * Zones: shared utils, local process execution, automation standard
- * Owns shell-free command-template splitting, placeholder defaults, composition expansion, executable path expansion, and direct execution
+ * Command-template execution standard.
+ * Zones: shell-free command parsing, placeholder expansion, local process execution, composition semantics
+ * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 export interface CommandTemplateActorRecipeContext {

package/dist/lib/command-templates.js

@@ -1,7 +1,7 @@
 /**
- * Command-template standard helpers
- * Zones: shared utils, local process execution, automation standard
- * Owns shell-free command-template splitting, placeholder defaults, composition expansion, executable path expansion, and direct execution
+ * Command-template execution standard.
+ * Zones: shell-free command parsing, placeholder expansion, local process execution, composition semantics
+ * Owns portable command-template parsing, expansion, risk checks, retries, timeouts, and direct execution.
  */
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";

package/dist/lib/config.d.ts

@@ -4,7 +4,7 @@
  * Owns registered-tool config loading, normalization, unsupported-shape rejection, and serialization
  */
 import type { CommandTemplateValue } from "./command-templates.ts";
-import * as RecipeReferences from "./recipe-references.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import * as Schema from "./schema.ts";
 export interface RegisteredTool {
     name: string;
@@ -12,7 +12,7 @@ export interface RegisteredTool {
     args: string[];
     defaults: Record<string, string>;
     argTypes?: Record<string, Schema.ToolArgType>;
-    recipe?: RecipeReferences.TemplateRecipeConfig;
+    recipe?: RecipesReferences.TemplateRecipeConfig;
     template?: CommandTemplateValue;
     storedArgs?: string[];
     storedDefaults?: Record<string, string>;

package/dist/lib/config.js

@@ -7,7 +7,7 @@ import { existsSync, readFileSync } from "node:fs";
 import * as CommandTemplates from "./command-templates.js";
 import { writeJsonAtomic } from "./file-state.js";
 import { normalizeToolName } from "./identity.js";
-import * as RecipeReferences from "./recipe-references.js";
+import * as RecipesReferences from "./recipes-references.js";
 import * as Schema from "./schema.js";
 export function serializeTools(source) {
     const entries = [...source.entries()].sort(([a], [b]) => a.localeCompare(b));
@@ -124,13 +124,13 @@ export function normalizeStoredTool(key, value, reservedToolNames) {
                 : {}),
         }
         : undefined;
-    const isRecipe = RecipeReferences.isRecipeTool(template, recipe);
-    const recipeTemplate = RecipeReferences.getRecipeTemplate(template);
+    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 || RecipeReferences.isAsyncRecipeReference(template) ? "Start async" : "Execute"} template recipe: ${recipe?.name ?? formatTemplateForDescription(template)}`
+            ? `${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
@@ -160,7 +160,7 @@ export function normalizeStoredTool(key, value, reservedToolNames) {
         description,
         args: isRecipe && storedArgs !== undefined
             ? Schema.getExplicitToolArgNames(storedArgs)
-            : RecipeReferences.isRecipeReference(template) && !recipeTemplate
+            : RecipesReferences.isRecipeReference(template) && !recipeTemplate
                 ? Schema.getExplicitToolArgNames(storedArgs)
                 : Schema.getToolArgNames(argTemplateConfig),
         defaults: declarations.defaults,

package/dist/lib/{output.d.ts → execution-output.d.ts}

@@ -1,7 +1,7 @@
 /**
- * Tool output formatting helpers
- * Zones: tool execution, output formatting, temp artifacts
- * Owns stdout/stderr failure formatting, tail truncation, and full-output temp-file persistence
+ * Registered tool execution output.
+ * Zones: command execution results, bounded output formatting, temp artifacts
+ * Owns stdout/stderr failure formatting, tail truncation, and full-output temp-file persistence.
  */
 export interface FormattedOutput {
     text: string;

package/dist/lib/{output.js → execution-output.js}

@@ -1,7 +1,7 @@
 /**
- * Tool output formatting helpers
- * Zones: tool execution, output formatting, temp artifacts
- * Owns stdout/stderr failure formatting, tail truncation, and full-output temp-file persistence
+ * Registered tool execution output.
+ * Zones: command execution results, bounded output formatting, temp artifacts
+ * Owns stdout/stderr failure formatting, tail truncation, and full-output temp-file persistence.
  */
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { join } from "node:path";

package/dist/lib/execution.js

@@ -4,7 +4,7 @@
  * Owns command-template invocation execution and pi tool-result payload formatting
  */
 import * as CommandTemplates from "./command-templates.js";
-import { formatFailureOutput, formatOutput, formatToolText } from "./output.js";
+import { formatFailureOutput, formatOutput, formatToolText, } from "./execution-output.js";
 import * as Schema from "./schema.js";
 const DEFAULT_MAX_PARALLEL_BRANCHES = 64;
 function textContent(text) {

package/dist/lib/{actor-inspector-tui.d.ts → inspector.d.ts}

@@ -1,6 +1,7 @@
 /**
- * Actor inspector TUI previews.
- * Zones: terminal actor inspection, room/direct message previews, no-dependency UI formatting
+ * Inspector preview rendering.
+ * Zones: terminal run inspection, room/direct message previews, no-dependency UI formatting
+ * Owns read-only previews and TUI-ready summaries; actor routing stays outside.
  */
 export interface ActorInspectorPreview {
     body_preview?: string;

package/dist/lib/{actor-inspector-tui.js → inspector.js}

@@ -1,6 +1,7 @@
 /**
- * Actor inspector TUI previews.
- * Zones: terminal actor inspection, room/direct message previews, no-dependency UI formatting
+ * Inspector preview rendering.
+ * Zones: terminal run inspection, room/direct message previews, no-dependency UI formatting
+ * Owns read-only previews and TUI-ready summaries; actor routing stays outside.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";

package/dist/lib/mailbox-loop.d.ts

@@ -1,9 +1,9 @@
 /**
- * Minimal mailbox loop helpers.
+ * Mailbox worker loop primitives.
  * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
- * Owns small reusable primitives for recipe authors; scheduling and task policy stay outside.
+ * Owns reusable claim/handle/drain behavior across run and branch inboxes; scheduling and task policy stay outside.
  */
-import { type BranchInboxRecord } from "./actor-rooms.ts";
+import { type BranchInboxRecord } from "./rooms.ts";
 import { type RunInboxMessage } from "./async-runs.ts";
 export type MailboxLoopMessage = RunInboxMessage | BranchInboxRecord;
 export type MailboxLoopTarget = {

package/dist/lib/mailbox-loop.js

@@ -1,9 +1,9 @@
 /**
- * Minimal mailbox loop helpers.
+ * Mailbox worker loop primitives.
  * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
- * Owns small reusable primitives for recipe authors; scheduling and task policy stay outside.
+ * Owns reusable claim/handle/drain behavior across run and branch inboxes; scheduling and task policy stay outside.
  */
-import { claimBranchInboxMessage, updateBranchInboxMessageStatus, } from "./actor-rooms.js";
+import { claimBranchInboxMessage, updateBranchInboxMessageStatus, } from "./rooms.js";
 import { claimRunInboxMessage, updateRunInboxMessageStatus, } from "./async-runs.js";
 export function isMailboxLoopStopMessage(message) {
     const type = message && typeof message === "object" && "type" in message

package/dist/lib/{actor-messages.d.ts → messages.d.ts}

@@ -1,7 +1,7 @@
 /**
- * Actor message protocol helpers.
- * Zones: 0.10 draft communication protocol, addressed messages, mailbox metadata
- * Owns pure validation/normalization for the semantic message envelope; transport routing stays in adapters.
+ * Actor message protocol.
+ * Zones: addressed envelopes, address parsing, route normalization
+ * Owns pure validation/normalization for semantic actor messages; transport routing stays in adapters.
  */
 export type ActorAddressKind = "branch" | "coordinator" | "room" | "run" | "session" | "tool";
 export interface ActorAddress {

package/dist/lib/{actor-messages.js → messages.js}

@@ -1,7 +1,7 @@
 /**
- * Actor message protocol helpers.
- * Zones: 0.10 draft communication protocol, addressed messages, mailbox metadata
- * Owns pure validation/normalization for the semantic message envelope; transport routing stays in adapters.
+ * Actor message protocol.
+ * Zones: addressed envelopes, address parsing, route normalization
+ * Owns pure validation/normalization for semantic actor messages; transport routing stays in adapters.
  */
 const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;

package/dist/lib/{actor-recipe-context.d.ts → recipes-context.d.ts}

@@ -1,9 +1,10 @@
 /**
- * Actor recipe context prompt helpers.
+ * Recipe context prompt assembly.
  * Zones: async runner prompt context, recipe provenance, LLM child launches
+ * Owns compact actor recipe context records appended to child-agent prompts.
  */
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
-import type { TemplateRecipeContextRecord } from "./recipe-references.ts";
+import type { TemplateRecipeContextRecord } from "./recipes-references.ts";
 export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
     you_are_here?: true;
     you_are_here_path?: string;

package/dist/lib/{actor-recipe-context.js → recipes-context.js}

@@ -1,6 +1,7 @@
 /**
- * Actor recipe context prompt helpers.
+ * Recipe context prompt assembly.
  * Zones: async runner prompt context, recipe provenance, LLM child launches
+ * Owns compact actor recipe context records appended to child-agent prompts.
  */
 import { basename } from "node:path";
 function commandName(command) {

package/dist/lib/{recipe-discovery.d.ts → recipes-discovery.d.ts}

@@ -4,7 +4,7 @@
  * Owns filename identity discovery across prioritized recipe roots
  */
 import type { RegisteredTool } from "./config.ts";
-import type { TemplateRecipeConfig } from "./recipe-references.ts";
+import type { TemplateRecipeConfig } from "./recipes-references.ts";
 export interface DiscoveredRecipe {
     id: string;
     path: string;
@@ -32,21 +32,21 @@ export interface RecipeIntegrityManifestEntry {
     disabled: boolean;
     shadowed: boolean;
 }
-export interface RecipeDiscoveryResult {
+export interface RecipesDiscoveryResult {
     active: Map<string, DiscoveredRecipe>;
     entries: DiscoveredRecipe[];
     diagnostics: string[];
 }
-export interface RecipeDiscoverySource {
+export interface RecipesDiscoverySource {
     root?: string;
     file?: string;
     defaultTool?: boolean;
     mutableUsage?: boolean;
 }
-export declare function discoverRecipeSources(sources: RecipeDiscoverySource[]): RecipeDiscoveryResult;
-export declare function discoverRecipes(roots: string[]): RecipeDiscoveryResult;
-export declare function createRecipeIntegrityManifest(result: RecipeDiscoveryResult): RecipeIntegrityManifestEntry[];
-export declare function getShadowedLaunchDiagnostic(result: RecipeDiscoveryResult, id: string): Record<string, unknown> | undefined;
+export declare function discoverRecipeSources(sources: RecipesDiscoverySource[]): RecipesDiscoveryResult;
+export declare function discoverRecipes(roots: string[]): RecipesDiscoveryResult;
+export declare function createRecipeIntegrityManifest(result: RecipesDiscoveryResult): RecipeIntegrityManifestEntry[];
+export declare function getShadowedLaunchDiagnostic(result: RecipesDiscoveryResult, id: string): Record<string, unknown> | undefined;
 export declare function listDraftRecipes(root: string): Array<Record<string, unknown>>;
-export declare function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown>;
+export declare function summarizeDiscovery(result: RecipesDiscoveryResult): Record<string, unknown>;
 export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/{recipe-discovery.js → recipes-discovery.js}

@@ -7,7 +7,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
-import * as RecipeReferences from "./recipe-references.js";
+import * as RecipesReferences from "./recipes-references.js";
 import * as Schema from "./schema.js";
 function assertToolSafeRepeatConfig(config, argTypes, defaults) {
     if (typeof config === "string" || config === undefined || config === null)
@@ -47,7 +47,7 @@ function listRecipeFiles(root) {
 }
 function getRecipeConfigDiagnostics(file, config) {
     if (!config) {
-        const reason = RecipeReferences.diagnoseRawRecipeConfigFailure(file);
+        const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
         return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
     }
     const commandTemplateConfig = typeof config.template === "object" && config.template !== null
@@ -56,9 +56,9 @@ function getRecipeConfigDiagnostics(file, config) {
     return CommandTemplates.getCommandTemplateWarnings(commandTemplateConfig).map((warning) => `Recipe ${file}: ${warning}`);
 }
 function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false) {
-    const id = RecipeReferences.getRecipeIdFromPath(file);
+    const id = RecipesReferences.getRecipeIdFromPath(file);
     try {
-        const config = RecipeReferences.readResolvedRecipeConfig(file);
+        const config = RecipesReferences.readResolvedRecipeConfig(file);
         const invalid = !config;
         const disabled = config?.disabled === true;
         return {
@@ -427,8 +427,8 @@ export function getShadowedLaunchDiagnostic(result, id) {
 }
 export function listDraftRecipes(root) {
     return listRecipeFiles(root).map((path) => {
-        const id = RecipeReferences.getRecipeIdFromPath(path);
-        const config = RecipeReferences.readRawRecipeConfig(path);
+        const id = RecipesReferences.getRecipeIdFromPath(path);
+        const config = RecipesReferences.readRawRecipeConfig(path);
         return {
             id,
             path,

package/dist/lib/registry.d.ts

@@ -3,8 +3,8 @@
  * Zones: registry mutations, persistence, runtime activation
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
-import * as Config from "./config.ts";
 import * as CommandTemplates from "./command-templates.ts";
+import * as Config from "./config.ts";
 export interface RegisterToolInput {
     name?: string;
     description?: string;

package/dist/lib/registry.js

@@ -5,12 +5,12 @@
  */
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
-import * as Identity from "./identity.js";
-import * as Output from "./output.js";
 import * as CommandTemplates from "./command-templates.js";
+import * as ExecutionOutput from "./execution-output.js";
 import { writeJsonAtomic } from "./file-state.js";
+import * as Identity from "./identity.js";
 import * as Paths from "./paths.js";
-import * as RecipeReferences from "./recipe-references.js";
+import * as RecipesReferences from "./recipes-references.js";
 import * as Schema from "./schema.js";
 function textContent(text) {
     return { type: "text", text };
@@ -19,7 +19,7 @@ function listTools(deps) {
     const names = [...deps.getTools().keys()].sort();
     return {
         content: [
-            textContent(Output.formatToolText(names.length > 0
+            textContent(ExecutionOutput.formatToolText(names.length > 0
                 ? `Registered tools:\n${names.map((name) => `- ${name}`).join("\n")}`
                 : "No registered tools.")),
         ],
@@ -51,7 +51,7 @@ function deleteTool(name, ctx, deps) {
     if (!tools.has(name)) {
         return {
             content: [
-                textContent(Output.formatToolText(`Tool "${name}" not found.`)),
+                textContent(ExecutionOutput.formatToolText(`Tool "${name}" not found.`)),
             ],
             details: { tool: name },
         };
@@ -64,7 +64,7 @@ function deleteTool(name, ctx, deps) {
     deps.notify(ctx, `Deleted tool: ${name}`, "info");
     return {
         content: [
-            textContent(Output.formatToolText(`Deleted tool "${name}". Reload to remove it from the complete registry.`)),
+            textContent(ExecutionOutput.formatToolText(`Deleted tool "${name}". Reload to remove it from the complete registry.`)),
         ],
         details: { config: recipePath, tool: name },
     };
@@ -79,32 +79,32 @@ function getInputTemplate(value) {
             template: value,
         });
         if (steps.length === 0)
-            throw new Error(Output.formatToolText("Tool template sequence is empty."));
+            throw new Error(ExecutionOutput.formatToolText("Tool template sequence is empty."));
         return value;
     }
     if (value && typeof value === "object") {
         CommandTemplates.expandCommandTemplateConfigs(value);
         return value;
     }
-    throw new Error(Output.formatToolText("Tool template must be a string, object, or sequence."));
+    throw new Error(ExecutionOutput.formatToolText("Tool template must be a string, object, or sequence."));
 }
 function buildConfig(name, input, existing) {
     const explicitArgs = input.args === undefined
         ? undefined
         : Schema.parseToolArgDeclarations(input.args);
     if (explicitArgs?.error)
-        throw new Error(Output.formatToolText(explicitArgs.error));
+        throw new Error(ExecutionOutput.formatToolText(explicitArgs.error));
     const description = (input.description ?? existing?.description ?? "").trim();
     if (!description) {
-        throw new Error(Output.formatToolText("Tool description is required unless deleting."));
+        throw new Error(ExecutionOutput.formatToolText("Tool description is required unless deleting."));
     }
     const template = getInputTemplate(input.template);
     if (template === null) {
-        throw new Error(Output.formatToolText("Tool template cannot be null here."));
+        throw new Error(ExecutionOutput.formatToolText("Tool template cannot be null here."));
     }
     const finalTemplate = template === undefined || template === "" ? existing?.template : template;
     if (!finalTemplate) {
-        throw new Error(Output.formatToolText("Tool template is required."));
+        throw new Error(ExecutionOutput.formatToolText("Tool template is required."));
     }
     const inputRecipe = typeof input.async === "boolean" ? name : undefined;
     const recipe = inputRecipe
@@ -127,7 +127,7 @@ function buildConfig(name, input, existing) {
         ? explicitArgs.declarations
         : existing?.storedArgs;
     const storedDefaults = Object.keys(defaults).length > 0 ? defaults : undefined;
-    const recipeTemplate = RecipeReferences.getRecipeTemplate(finalTemplate);
+    const recipeTemplate = RecipesReferences.getRecipeTemplate(finalTemplate);
     const argTemplate = recipeTemplate ?? finalTemplate;
     const argTemplateConfig = typeof argTemplate === "object" && !Array.isArray(argTemplate)
         ? {
@@ -151,10 +151,10 @@ function buildConfig(name, input, existing) {
         description,
         template: finalTemplate,
         ...(recipe ? { recipe } : {}),
-        args: RecipeReferences.isRecipeTool(finalTemplate, recipe) &&
+        args: RecipesReferences.isRecipeTool(finalTemplate, recipe) &&
             storedArgs !== undefined
             ? Schema.getExplicitToolArgNames(storedArgs)
-            : RecipeReferences.isRecipeReference(finalTemplate) && !recipeTemplate
+            : RecipesReferences.isRecipeReference(finalTemplate) && !recipeTemplate
                 ? Schema.getExplicitToolArgNames(storedArgs)
                 : Schema.getToolArgNames(argTemplateConfig),
         defaults,
@@ -169,9 +169,9 @@ export async function executeRegisterTool(params, ctx, deps) {
         return listTools(deps);
     const name = Identity.normalizeToolName(input.name);
     if (!name)
-        throw new Error(Output.formatToolText("Invalid tool name."));
+        throw new Error(ExecutionOutput.formatToolText("Invalid tool name."));
     if (deps.reservedToolNames.has(name)) {
-        throw new Error(Output.formatToolText(`Reserved tool name: ${name}`));
+        throw new Error(ExecutionOutput.formatToolText(`Reserved tool name: ${name}`));
     }
     const templateProvided = Object.hasOwn(input, "template");
     const template = getInputTemplate(input.template);
@@ -181,12 +181,12 @@ export async function executeRegisterTool(params, ctx, deps) {
     const existing = tools.get(name);
     const conflict = deps.getExternalToolConflict(name);
     if (conflict)
-        throw new Error(Output.formatToolText(conflict));
+        throw new Error(ExecutionOutput.formatToolText(conflict));
     if (existing && !input.update) {
-        throw new Error(Output.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
+        throw new Error(ExecutionOutput.formatToolText(`Tool "${name}" already registered. Use update=true to overwrite.`));
     }
     if (template === undefined && !existing) {
-        throw new Error(Output.formatToolText("Tool template is required for new registrations."));
+        throw new Error(ExecutionOutput.formatToolText("Tool template is required for new registrations."));
     }
     const cfg = buildConfig(name, input, existing);
     let recipePath;
@@ -194,7 +194,7 @@ export async function executeRegisterTool(params, ctx, deps) {
         recipePath = persistToolRecipe(deps, cfg);
     }
     catch (error) {
-        throw new Error(Output.formatToolText(`Failed to persist tool recipe: ${error instanceof Error ? error.message : String(error)}`));
+        throw new Error(ExecutionOutput.formatToolText(`Failed to persist tool recipe: ${error instanceof Error ? error.message : String(error)}`));
     }
     cfg.sourcePath = recipePath;
     tools.set(name, cfg);
@@ -208,7 +208,7 @@ export async function executeRegisterTool(params, ctx, deps) {
         : "";
     return {
         content: [
-            textContent(Output.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`)),
+            textContent(ExecutionOutput.formatToolText(`${existing ? "Updated" : "Registered"} tool "${name}" (args: ${Schema.formatToolArgs(cfg.args)}).${warningText}`)),
         ],
         details: {
             args: cfg.args,

package/dist/lib/{actor-rooms.d.ts → rooms.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Actor room persistence helpers.
- * Zones: room timelines, room rosters, cross-branch discovery state
- * Owns small file-backed room state; routing policy stays in tools/runtime adapters.
+ * Actor room persistence.
+ * Zones: room timelines, rosters, branch inboxes, cross-branch discovery state
+ * Owns file-backed room and branch-mailbox state; routing policy stays in tools/runtime adapters.
  */
-import type { ActorMessage } from "./actor-messages.ts";
+import type { ActorMessage } from "./messages.ts";
 export interface RoomMember {
     address: string;
     caps?: unknown;

package/dist/lib/{actor-rooms.js → rooms.js}

@@ -1,7 +1,7 @@
 /**
- * Actor room persistence helpers.
- * Zones: room timelines, room rosters, cross-branch discovery state
- * Owns small file-backed room state; routing policy stays in tools/runtime adapters.
+ * Actor room persistence.
+ * Zones: room timelines, rosters, branch inboxes, cross-branch discovery state
+ * Owns file-backed room and branch-mailbox state; routing policy stays in tools/runtime adapters.
  */
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";

package/dist/lib/runs-artifacts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ */
+export type RunArtifactDeclaration = string | {
+    path: string;
+    kind?: string;
+    media_type?: string;
+    required?: boolean;
+};
+export interface RunArtifactManifestEntry {
+    exists: boolean;
+    kind?: string;
+    media_type?: string;
+    path: string;
+    required?: boolean;
+    sha256?: string;
+    size?: number;
+}
+export declare function resolveArtifactPaths(artifacts: Record<string, RunArtifactDeclaration> | undefined, values: Record<string, unknown>): Record<string, RunArtifactDeclaration> | undefined;
+export declare function resolveArtifactManifest(artifacts: Record<string, RunArtifactDeclaration> | undefined): Record<string, RunArtifactManifestEntry> | undefined;

package/dist/lib/runs-artifacts.js

@@ -0,0 +1,68 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { substituteCommandTemplateToken } from "./command-templates.js";
+export function resolveArtifactPaths(artifacts, values) {
+    if (!artifacts)
+        return undefined;
+    const resolved = {};
+    for (const [key, value] of Object.entries(artifacts)) {
+        if (!key.trim())
+            continue;
+        if (typeof value === "string") {
+            resolved[key] = substituteCommandTemplateToken(value, values, `recipe artifacts.${key}`);
+        }
+        else if (value &&
+            typeof value === "object" &&
+            typeof value.path === "string") {
+            resolved[key] = {
+                ...value,
+                path: substituteCommandTemplateToken(value.path, values, `recipe artifacts.${key}.path`),
+            };
+        }
+    }
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+export function resolveArtifactManifest(artifacts) {
+    if (!artifacts)
+        return undefined;
+    const manifest = {};
+    for (const [name, artifact] of Object.entries(artifacts)) {
+        const declaration = typeof artifact === "string" ? { path: artifact } : artifact;
+        if (!declaration?.path)
+            continue;
+        try {
+            const content = readFileSync(declaration.path);
+            manifest[name] = {
+                exists: true,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+                sha256: createHash("sha256").update(content).digest("hex"),
+                size: content.byteLength,
+            };
+        }
+        catch {
+            manifest[name] = {
+                exists: false,
+                ...(declaration.kind ? { kind: declaration.kind } : {}),
+                ...(declaration.media_type
+                    ? { media_type: declaration.media_type }
+                    : {}),
+                path: declaration.path,
+                ...(declaration.required !== undefined
+                    ? { required: declaration.required }
+                    : {}),
+            };
+        }
+    }
+    return Object.keys(manifest).length > 0 ? manifest : undefined;
+}

package/dist/lib/runs-control.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Async run process control primitives.
+ * Owns platform signal planning, owned-process signalling, and terminal control markers.
+ */
+export interface RunProcessSignalPlan {
+    args?: string[];
+    command?: string;
+    signalTarget: "processGroup" | "process" | "processTree";
+}
+export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
+export declare function signalOwnedRunProcess(pid: number, signal: NodeJS.Signals): RunProcessSignalPlan;
+export declare function markTerminalHandled(stateDir: string, details: Record<string, unknown>): void;
+export declare function buildTerminalProgress(existing: Record<string, unknown> | undefined, phase: "cancelled" | "killed"): Record<string, unknown>;