@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/tools-spawn.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public spawn tool behavior
+ * Zones: actor launch, draft recipe capture, launch diagnostics
+ * Owns the public spawn execution path for run-backed actors
+ */
+import * as ModelContext from "./model-context.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
+export interface SpawnToolContext extends ModelContext.CurrentModelContext {
+    recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
+    cwd: string;
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+}
+export declare function createSpawnToolDefinition<TContext extends SpawnToolContext>(): any;

package/node_modules/@llblab/pi-actors/dist/lib/tools-spawn.js

@@ -0,0 +1,133 @@
+/**
+ * Public spawn tool behavior
+ * Zones: actor launch, draft recipe capture, launch diagnostics
+ * Owns the public spawn execution path for run-backed actors
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as AsyncRuns from "./async-runs.js";
+import { withFileMutationLock } from "./file-state.js";
+import * as ModelContext from "./model-context.js";
+import * as Paths from "./paths.js";
+import * as RecipesUsage from "./recipes-usage.js";
+import * as Schema from "./schema.js";
+import * as ToolsResponse from "./tools-response.js";
+const asRecord = ToolsResponse.asRecord;
+const maybeJsonText = ToolsResponse.maybeJsonText;
+function getRunOwnerId(ctx) {
+    return ctx.sessionManager?.getSessionId?.();
+}
+function draftRecipeName(run) {
+    return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
+}
+function draftRecipeDefaults(values) {
+    const ignored = new Set(["run_id", "state_dir", "trace_file"]);
+    const defaults = Object.fromEntries(Object.entries(values).filter(([key]) => !ignored.has(key)));
+    return Object.keys(defaults).length > 0 ? defaults : undefined;
+}
+function writeSpawnDraftRecipe(input, meta) {
+    if (process.env.NODE_TEST_CONTEXT &&
+        process.env.PI_ACTORS_ENABLE_SPAWN_DRAFTS_IN_TEST !== "1")
+        return undefined;
+    if (input.template === undefined ||
+        input.file !== undefined ||
+        input.recipe !== undefined)
+        return undefined;
+    const root = Paths.getRecipeDraftRoot();
+    mkdirSync(root, { recursive: true });
+    const path = join(root, draftRecipeName(String(meta.run)));
+    const defaults = draftRecipeDefaults(meta.values);
+    const recipe = {
+        async: true,
+        description: `Draft recipe captured from spawn run ${String(meta.run)}`,
+        ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
+        ...(defaults ? { defaults } : {}),
+        template: input.template,
+    };
+    withFileMutationLock(root, () => withFileMutationLock(path, () => writeFileSync(path, `${JSON.stringify(recipe, null, 2)}\n`, { flag: "wx" })));
+    RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
+    return path;
+}
+function runIdFromTarget(target) {
+    if (!target)
+        return undefined;
+    if (!target.startsWith("run:")) {
+        throw new Error(`spawn.as accepts only run:<id>; received: ${target}`);
+    }
+    const run = target.slice(4);
+    if (!run || !/^[A-Za-z0-9_.-]+$/.test(run)) {
+        throw new Error(`invalid spawn Run target: ${target}`);
+    }
+    return run;
+}
+export function createSpawnToolDefinition() {
+    return {
+        name: "spawn",
+        label: "Spawn",
+        description: "Create one controllable Run from a Recipe file or inline command template.",
+        parameters: Schema.objectSchema({
+            artifacts: Schema.looseObjectSchema("Optional named artifact paths for the spawned Run."),
+            as: Schema.stringSchema("Optional Run identity in exact run:<id> form."),
+            file: Schema.stringSchema("Optional Recipe reference as <skill>/<recipe> or an explicit .json/.md file path."),
+            recipe: Schema.stringSchema("Alias for file."),
+            template: Schema.unionSchema([
+                Schema.stringSchema("Inline command template string"),
+                Schema.arraySchema("Inline command-template sequence or parallel tree"),
+                Schema.looseObjectSchema("Inline command-template object with flags such as parallel, repeat, retry, failure, and nested template."),
+            ]),
+            values: Schema.looseObjectSchema("Runtime placeholder values passed to the actor."),
+            transport_context: Schema.looseObjectSchema("Optional originating transport route preserved for detached terminal follow-up, e.g. Telegram chat_id and thread_id."),
+            verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
+        }, []),
+        async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+            const input = asRecord(params);
+            if (input.state_dir !== undefined) {
+                throw new Error("spawn.state_dir is not supported; run state is runtime-owned so run:<id> remains addressable and retention-safe.");
+            }
+            const runId = runIdFromTarget(typeof input.as === "string" ? input.as : undefined);
+            const recipe = typeof input.file === "string"
+                ? input.file
+                : typeof input.recipe === "string"
+                    ? input.recipe
+                    : undefined;
+            const meta = AsyncRuns.startRun({
+                file: recipe,
+                launch_source: "spawn",
+                launch_correlation: { tool_call_id: toolCallId },
+                ownerId: getRunOwnerId(ctx),
+                ...(input.transport_context
+                    ? { transport_context: asRecord(input.transport_context) } : {}),
+                run_id: runId,
+                ...(input.template !== undefined
+                    ? {
+                        template: input.template,
+                    }
+                    : {}),
+                values: ModelContext.withCurrentModelValues(asRecord(input.values), ctx),
+                ...(input.artifacts &&
+                    typeof input.artifacts === "object" &&
+                    !Array.isArray(input.artifacts)
+                    ? {
+                        artifacts: input.artifacts,
+                    }
+                    : {}),
+            }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
+            const draftRecipe = writeSpawnDraftRecipe(input, meta);
+            const nextActions = ToolsResponse.runNextActions(meta.run);
+            const details = {
+                ...meta,
+                ...(draftRecipe ? { draft_recipe: draftRecipe } : {}),
+                next_actions: nextActions,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: maybeJsonText(details, input.verbose === true, ToolsResponse.compactAsyncRunStatus(details)),
+                    },
+                ],
+                details,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Public tool family composition
+ * Zones: tool set, reserved tool names, pi-facing tool wiring
+ * Owns public tool-family composition without owning individual tool behavior
+ */
+import type { RuntimeToolContext } from "./tools-local.ts";
+import * as ToolsRegister from "./tools-register.ts";
+export type RegisterToolRuntimeDeps<TContext> = ToolsRegister.RegisterToolRuntimeDeps<TContext>;
+export interface ActorToolDefinition {
+    name: string;
+    execute?: (...args: never[]) => unknown;
+    [key: string]: unknown;
+}
+export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext> {
+    configPath: string;
+    getActiveTools: () => string[];
+    getRecipeResolutionContext: () => import("./recipes-context.ts").RecipeResolutionContext | undefined;
+    getRuntimeTool: (name: string) => unknown;
+    getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
+    handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;
+    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"> & {
+        getStatus(): import("./runtime.ts").RecipeRegistryStatus;
+    };
+    setActiveTools: (toolNames: string[]) => void;
+}
+export declare function resolveActiveRuntimeTool(name: string, activeTools: Pick<Map<string, unknown>, "has">, getDefinition: (name: string) => unknown): unknown;
+export declare const RESERVED_TOOL_NAMES: Set<string>;
+export declare function createCoreActorToolDefinitions<TContext extends RuntimeToolContext>(deps: CoreActorToolDefinitionDeps<TContext>): ActorToolDefinition[];

package/node_modules/@llblab/pi-actors/dist/lib/tools.js

@@ -0,0 +1,49 @@
+/**
+ * Public tool family composition
+ * Zones: tool set, reserved tool names, pi-facing tool wiring
+ * Owns public tool-family composition without owning individual tool behavior
+ */
+import * as ToolsInspect from "./tools-inspect.js";
+import * as ToolsMessage from "./tools-message.js";
+import * as ToolsRegister from "./tools-register.js";
+import * as ToolsSpawn from "./tools-spawn.js";
+export function resolveActiveRuntimeTool(name, activeTools, getDefinition) {
+    return activeTools.has(name) ? getDefinition(name) : undefined;
+}
+export const RESERVED_TOOL_NAMES = new Set([
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "find",
+    "grep",
+    "ls",
+    "register_tool",
+    "message",
+    "spawn",
+    "inspect",
+]);
+export function createCoreActorToolDefinitions(deps) {
+    return [
+        ToolsRegister.createRegisterToolDefinition({
+            configPath: deps.configPath,
+            getActiveTools: deps.getActiveTools,
+            getToolNameBlocker: deps.registryRuntime.getToolNameBlocker,
+            getTools: deps.registryRuntime.getTools,
+            getRecipeResolutionContext: deps.getRecipeResolutionContext,
+            notify: deps.registryRuntime.notify,
+            registerRuntimeTool: deps.registryRuntime.registerRuntimeTool,
+            reservedToolNames: RESERVED_TOOL_NAMES,
+            setActiveTools: deps.setActiveTools,
+        }),
+        ToolsSpawn.createSpawnToolDefinition(),
+        ToolsMessage.createControlToolDefinition({
+            handleRuntimeControl: deps.handleRuntimeControl,
+        }),
+        ToolsInspect.createInspectToolDefinition({
+            getTool: (name) => deps.getRuntimeTool(name),
+            getToolStatus: deps.getRuntimeToolStatus,
+            registryStatus: deps.registryRuntime.getStatus,
+        }),
+    ];
+}

package/node_modules/@llblab/pi-actors/dist/lib/trace-projection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Unified bounded Run Trace projection.
+ * Zones: causal evidence merge, source filtering, redaction, deterministic ordering
+ * Owns public Trace items; source journals and session parsing remain in their domains.
+ */
+import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
+export type TraceSource = "lifecycle" | "control" | "process" | "agent" | "artifact" | "runtime";
+export type TraceSourceFilter = TraceSource | "all";
+export interface TraceItem {
+    id: string;
+    ts: string;
+    source: TraceSource;
+    kind: string;
+    summary: string;
+    level?: "info" | "warning" | "error";
+    detail: unknown;
+}
+export declare function projectRunTrace(stateDir: string, options?: {
+    artifacts?: Record<string, RunArtifactDeclaration>;
+    limit?: number;
+    source?: TraceSourceFilter;
+}): TraceItem[];

package/node_modules/@llblab/pi-actors/dist/lib/trace-projection.js

@@ -0,0 +1,231 @@
+/**
+ * Unified bounded Run Trace projection.
+ * Zones: causal evidence merge, source filtering, redaction, deterministic ordering
+ * Owns public Trace items; source journals and session parsing remain in their domains.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import * as ControlProjection from "./control-projection.js";
+import * as ExecutionSessions from "./execution-sessions.js";
+import * as Limits from "./limits.js";
+import { resolveArtifactManifest, } from "./runs-artifacts.js";
+import * as RunsControls from "./runs-controls.js";
+import { tailFile } from "./runs-status.js";
+import * as RunsTrace from "./runs-trace.js";
+import * as SessionEvidence from "./session-evidence.js";
+import { readJsonFileResilient, } from "./state-readers.js";
+const LIFECYCLE_PREFIXES = ["run.", "command."];
+const SOURCE_LIMIT = 100;
+const SOURCE_RANK = {
+    lifecycle: 6,
+    control: 5,
+    process: 4,
+    agent: 3,
+    artifact: 2,
+    runtime: 1,
+};
+function redact(value) {
+    return SessionEvidence.redactSessionEvidenceValue(value);
+}
+function sourceForEvent(event) {
+    return LIFECYCLE_PREFIXES.some((prefix) => event.kind.startsWith(prefix))
+        ? "lifecycle"
+        : "runtime";
+}
+function ordered(item, sourceKey, ordinal) {
+    return { item, ordinal, sourceKey };
+}
+function compareTraceItems(left, right) {
+    const timestamp = right.item.ts.localeCompare(left.item.ts);
+    if (timestamp)
+        return timestamp;
+    if (left.sourceKey === right.sourceKey) {
+        const ordinal = right.ordinal - left.ordinal;
+        if (ordinal)
+            return ordinal;
+    }
+    return SOURCE_RANK[right.item.source] - SOURCE_RANK[left.item.source] ||
+        right.item.id.localeCompare(left.item.id);
+}
+function latestControlTimestamp(control) {
+    return (control.failed_at ??
+        control.handled_at ??
+        control.claimed_at ??
+        control.delivered_at ??
+        control.queued_at);
+}
+function diagnosticItems(diagnostics) {
+    return diagnostics.slice(-SOURCE_LIMIT).map((diagnostic, index) => ({
+        id: `diagnostic:${diagnostic.path}:${diagnostic.line ?? 0}:${index}`,
+        ts: new Date(0).toISOString(),
+        source: "runtime",
+        kind: "state.read_error",
+        summary: "Malformed or unreadable Run evidence",
+        level: "warning",
+        detail: redact(diagnostic),
+    }));
+}
+function controlDiagnosticItems(diagnostics) {
+    return diagnostics.slice(-SOURCE_LIMIT).map((diagnostic, index) => ({
+        id: `control-diagnostic:${diagnostic.line ?? 0}:${index}`,
+        ts: new Date(0).toISOString(),
+        source: "runtime",
+        kind: "state.read_error",
+        summary: "Malformed or unreadable Control evidence",
+        level: "warning",
+        detail: {
+            ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+            reason: diagnostic.line === undefined
+                ? "unreadable_control_journal"
+                : "invalid_control_json",
+        },
+    }));
+}
+function traceEventItems(stateDir) {
+    const read = RunsTrace.readRunTraceJournal(stateDir);
+    const retained = read.events.slice(-SOURCE_LIMIT);
+    const projected = retained.map(({ event, ordinal }) => ordered({
+        id: event.id,
+        ts: event.ts,
+        source: sourceForEvent(event),
+        kind: event.kind,
+        summary: event.summary ?? event.kind,
+        ...(event.level ? { level: event.level } : {}),
+        detail: redact({
+            ...(event.attention ? { attention: event.attention } : {}),
+            ...(event.data !== undefined ? { data: event.data } : {}),
+        }),
+    }, "trace", ordinal));
+    const diagnostics = diagnosticItems(read.diagnostics).map((item, index) => ordered(item, "trace", read.events.length + index + 1));
+    const hasMarker = read.events.some(({ event }) => event.kind === "runtime.trace_compacted");
+    if (read.omittedPrefixBytes > 0 && !hasMarker) {
+        diagnostics.push(ordered({
+            id: "runtime:trace-history-incomplete",
+            ts: new Date(0).toISOString(),
+            source: "runtime",
+            kind: "runtime.trace_history_incomplete",
+            summary: "Trace history is incomplete",
+            level: "warning",
+            detail: {
+                omitted_prefix_bytes: read.omittedPrefixBytes,
+                read_bytes: read.readBytes,
+                retained_events: read.events.length,
+            },
+        }, "trace", 0));
+    }
+    return [...projected, ...diagnostics];
+}
+function controlItems(stateDir) {
+    const read = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    const start = Math.max(0, read.records.length - SOURCE_LIMIT);
+    const projected = read.records.slice(start).map((control, index) => {
+        const value = ControlProjection.projectRunControl(control);
+        return ordered({
+            id: `control:${value.id}`,
+            ts: latestControlTimestamp(value),
+            source: "control",
+            kind: `control.${value.status}`,
+            summary: `${value.action} ${value.status}`,
+            ...(value.status === "failed" ? { level: "error" } : {}),
+            detail: value,
+        }, "control", start + index + 1);
+    });
+    return [
+        ...projected,
+        ...controlDiagnosticItems(read.diagnostics).map((item, index) => ordered(item, "control", read.records.length + index + 1)),
+    ];
+}
+function agentItems(stateDir) {
+    return ExecutionSessions.readExecutionTurns(stateDir)
+        .slice(-SOURCE_LIMIT)
+        .map((turn) => {
+        const text = turn.assistantText ?? turn.userText ?? "Agent turn";
+        const summary = text.replaceAll(/\s+/g, " ").trim().slice(0, 160);
+        return ordered({
+            id: `agent:${turn.commandId}:${turn.sessionFile}:${turn.index}`,
+            ts: turn.timestamp ?? new Date(0).toISOString(),
+            source: "agent",
+            kind: "agent.turn",
+            summary: summary || "Agent turn",
+            ...(turn.error ? { level: "error" } : {}),
+            detail: redact(turn),
+        }, "agent", turn.index);
+    });
+}
+function processItems(stateDir) {
+    return ["stdout", "stderr"].flatMap((stream) => {
+        const path = join(stateDir, `${stream}.log`);
+        if (!existsSync(path))
+            return [];
+        const stat = statSync(path);
+        const tail = tailFile(path, Limits.DEFAULT_INSPECT_LINES);
+        if (!tail && stat.size === 0)
+            return [];
+        return [ordered({
+                id: `process:${stream}`,
+                ts: stat.mtime.toISOString(),
+                source: "process",
+                kind: `process.${stream}`,
+                summary: `${stream} (${stat.size} bytes)`,
+                ...(stream === "stderr" ? { level: "warning" } : {}),
+                detail: redact({ bytes: stat.size, path, tail }),
+            }, `process:${stream}`, 1)];
+    });
+}
+function resultItems(stateDir) {
+    const path = join(stateDir, "result.json");
+    const read = readJsonFileResilient(path, {});
+    if (Object.keys(read.value).length === 0) {
+        return diagnosticItems(read.diagnostics).map((item, index) => ordered(item, "process:result", index));
+    }
+    const stat = statSync(path);
+    const failed = Number(read.value.code ?? 0) !== 0;
+    return [ordered({
+            id: "process:result",
+            ts: typeof read.value.completedAt === "string"
+                ? read.value.completedAt
+                : stat.mtime.toISOString(),
+            source: "process",
+            kind: failed ? "process.failed" : "process.result",
+            summary: failed ? "Run process failed" : "Run process completed",
+            ...(failed ? { level: "error" } : {}),
+            detail: redact(read.value),
+        }, "process:result", 1), ...diagnosticItems(read.diagnostics).map((item, index) => ordered(item, "process:result", index + 2))];
+}
+function artifactItems(stateDir, declarations) {
+    const manifest = resolveArtifactManifest(declarations);
+    if (!manifest)
+        return [];
+    return Object.entries(manifest).slice(0, SOURCE_LIMIT).map(([name, artifact], index) => ordered({
+        id: `artifact:${name}`,
+        ts: artifact.exists && existsSync(artifact.path)
+            ? statSync(artifact.path).mtime.toISOString()
+            : new Date(0).toISOString(),
+        source: "artifact",
+        kind: artifact.exists ? "artifact.ready" : "artifact.missing",
+        summary: `${name}: ${artifact.exists ? "ready" : "missing"}`,
+        ...(artifact.required && !artifact.exists ? { level: "warning" } : {}),
+        detail: redact({
+            exists: artifact.exists,
+            path: relative(stateDir, artifact.path).replaceAll("\\", "/"),
+            required: artifact.required,
+            ...(artifact.size !== undefined ? { size: artifact.size } : {}),
+        }),
+    }, "artifact", index + 1));
+}
+export function projectRunTrace(stateDir, options = {}) {
+    const source = options.source ?? "all";
+    const items = [
+        ...traceEventItems(stateDir),
+        ...controlItems(stateDir),
+        ...agentItems(stateDir),
+        ...processItems(stateDir),
+        ...resultItems(stateDir),
+        ...artifactItems(stateDir, options.artifacts),
+    ]
+        .filter(({ item }) => source === "all" || item.source === source)
+        .sort(compareTraceItems);
+    return items
+        .slice(0, Math.max(1, Math.min(options.limit ?? 100, 200)))
+        .map(({ item }) => item);
+}

package/node_modules/@llblab/pi-actors/dist/pi-actors/index.js

@@ -0,0 +1 @@
+export { default } from "../index.js";