@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,44 @@
+/**
+ * Public tool access and ownership checks
+ * Zones: session ownership, run visibility guards, tool authorization errors
+ * Owns consistent session-mismatch diagnostics for public tool execution paths
+ */
+import * as AsyncRuns from "./async-runs.js";
+export function getContextSessionId(ctx) {
+    return ctx?.sessionManager?.getSessionId?.();
+}
+export function requireContextSessionId(ctx, actor) {
+    const sessionId = getContextSessionId(ctx);
+    if (!sessionId) {
+        throw new Error(`${actor} requires a current coordinator session; use session:<id> or session:all for explicit session inventory.`);
+    }
+    return sessionId;
+}
+export function sessionMismatchError(input) {
+    const ownerSession = input.expectedSession ?? "none";
+    const currentSession = input.currentSession ?? "none";
+    const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
+    const hintTarget = input.expectedSession
+        ? `session:${input.expectedSession}`
+        : "session:all";
+    return Object.assign(new Error(`${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`), {
+        current_session: input.currentSession,
+        hint: `inspect target=${hintTarget} view=status`,
+        owner_session: input.expectedSession,
+        reason: "session_mismatch",
+        run: input.run,
+        target: input.target,
+    });
+}
+export function assertRunAccessibleToContext(runId, ctx) {
+    const status = AsyncRuns.getRunStatus(runId);
+    const sessionId = getContextSessionId(ctx);
+    if (sessionId && status.ownerId && status.ownerId !== sessionId) {
+        throw sessionMismatchError({
+            currentSession: sessionId,
+            expectedSession: String(status.ownerId),
+            run: runId,
+        });
+    }
+    return status;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Public inspect tool behavior.
+ * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
+ * Owns exact inspect target/view dispatch; source projection stays in domain modules.
+ */
+import * as Runtime from "./runtime.ts";
+export interface InspectToolDeps<TContext = unknown> {
+    getRunStatus?: (runOrDir: string) => Record<string, any>;
+    getTool?: (name: string) => any | undefined;
+    getToolStatus?: (name: string) => Record<string, unknown> | undefined;
+    listRuns?: () => Array<Record<string, any>>;
+    recipeRoot?: string;
+    registryStatus?: () => Runtime.RecipeRegistryStatus;
+}
+export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;

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

@@ -0,0 +1,532 @@
+/**
+ * Public inspect tool behavior.
+ * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
+ * Owns exact inspect target/view dispatch; source projection stays in domain modules.
+ */
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+import * as AsyncRuns from "./async-runs.js";
+import * as ControlProjection from "./control-projection.js";
+import * as Inspector from "./inspector.js";
+import * as Limits from "./limits.js";
+import { computeRunControlCapacity } from "./run-evidence-policy.js";
+import * as Paths from "./paths.js";
+import * as RecipesDiscovery from "./recipes-discovery.js";
+import * as RecipesReferences from "./recipes-references.js";
+import * as ReviewDiagnostics from "./review-diagnostics.js";
+import * as RunsControls from "./runs-controls.js";
+import * as RunControlDelivery from "./runs-control-delivery.js";
+import * as RunsTrace from "./runs-trace.js";
+import * as RuntimeIdentity from "./runtime-identity.js";
+import * as RuntimeTriage from "./runtime-triage.js";
+import * as Schema from "./schema.js";
+import * as ToolsAccess from "./tools-access.js";
+import * as ToolsResponse from "./tools-response.js";
+import * as TraceProjection from "./trace-projection.js";
+const asRecord = ToolsResponse.asRecord;
+const maybeJsonText = ToolsResponse.maybeJsonText;
+function runtimeStatus() {
+    return {
+        automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
+        run_root: Paths.getRunStateRoot(),
+        state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
+        version: RuntimeIdentity.getPackageVersion(),
+    };
+}
+function runtimeRuns(ctx, deps, status) {
+    const session = ToolsAccess.getContextSessionId(ctx);
+    const listed = deps.listRuns
+        ? deps.listRuns()
+        : AsyncRuns.listRuns(undefined, status);
+    const runs = listed
+        .map((run) => {
+        try {
+            return deps.getRunStatus
+                ? deps.getRunStatus(String(run.state_dir ?? run.run))
+                : AsyncRuns.getRunStatus(String(run.state_dir ?? run.run));
+        }
+        catch {
+            return run;
+        }
+    })
+        .filter((run) => !session || !run.ownerId || run.ownerId === session);
+    return { ...(session ? { owner_session: session } : {}), runs };
+}
+function runtimeTriage(ctx, deps) {
+    const inventory = runtimeRuns(ctx, deps, undefined);
+    const runs = inventory.runs;
+    const failed = runs.filter((run) => run.status === "failed");
+    const pendingControls = [];
+    const staleControls = [];
+    const backpressuredRuns = [];
+    const controlDiagnostics = [];
+    const traceDiagnostics = [];
+    const nowMs = Date.now();
+    for (const run of runs) {
+        const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
+        if (!stateDir)
+            continue;
+        const runId = String(run.run ?? "unknown");
+        const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+        const capacity = computeRunControlCapacity(journal.records);
+        controlDiagnostics.push(...journal.diagnostics.map((diagnostic) => ({
+            ...(diagnostic.line === undefined ? {} : { line: diagnostic.line }),
+            reason: diagnostic.line === undefined ? "unreadable_control_journal" : "invalid_control_json", run: runId,
+        })));
+        if (capacity.backpressured)
+            backpressuredRuns.push({
+                run: runId, pending: capacity.pending, pending_limit: capacity.limit,
+                journal_bytes: statSync(RunsControls.runControlsFile(stateDir)).size,
+            });
+        const traceSummary = RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(stateDir));
+        if (!traceSummary.history_complete)
+            traceDiagnostics.push({ run: runId, ...traceSummary });
+        for (const control of journal.records) {
+            const classified = RuntimeTriage.classifyRuntimeControl({
+                run: runId,
+                ...(typeof run.run_instance_id === "string"
+                    ? { runInstanceId: run.run_instance_id }
+                    : {}),
+                status: String(run.status ?? "unknown"),
+            }, control, nowMs);
+            if (classified.pending)
+                pendingControls.push(classified.pending);
+            if (classified.stale)
+                staleControls.push(classified.stale);
+            if (classified.diagnostic)
+                controlDiagnostics.push({ ...classified.diagnostic });
+        }
+    }
+    const attentionEvents = runs.flatMap((run) => {
+        const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
+        if (!stateDir)
+            return [];
+        return RunsTrace.readRunTraceEvents(stateDir)
+            .filter((event) => event.attention === "notify" || event.attention === "followup")
+            .map((event) => ({
+            run: run.run,
+            id: event.id,
+            kind: event.kind,
+            attention: event.attention,
+            summary: event.summary,
+            ts: event.ts,
+        }));
+    });
+    const boundedStaleControls = staleControls.slice(0, 40);
+    const staleKeys = new Set(boundedStaleControls.map((control) => `${control.run}\0${control.run_instance_id}\0${control.id}`));
+    const boundedPendingControls = [
+        ...boundedStaleControls,
+        ...pendingControls.filter((control) => !staleKeys.has(`${control.run}\0${control.run_instance_id}\0${control.id}`)),
+    ].slice(0, 40);
+    return {
+        ...inventory,
+        failed_runs: failed,
+        pending_control_count: pendingControls.length,
+        pending_controls: boundedPendingControls,
+        stale_control_count: staleControls.length,
+        stale_controls: boundedStaleControls,
+        backpressured_run_count: backpressuredRuns.length, backpressured_runs: backpressuredRuns.slice(0, 40),
+        control_diagnostic_count: controlDiagnostics.length, control_diagnostics: controlDiagnostics.slice(0, 40),
+        trace_diagnostic_count: traceDiagnostics.length, trace_diagnostics: traceDiagnostics.slice(0, 40),
+        attention_events: attentionEvents.slice(-40).reverse(),
+        next_actions: [
+            ...(failed.length ? ["inspect target=runtime view=runs status=failed"] : []),
+            ...new Set([...staleControls, ...backpressuredRuns].slice(0, 3).map((entry) => `inspect target=run:${entry.run} view=control`)),
+            ...(attentionEvents.length
+                ? attentionEvents.slice(-3).map((entry) => `inspect target=run:${String(entry.run)} view=trace source=runtime`)
+                : []),
+        ],
+    };
+}
+function compactRuntime(view, details) {
+    if (view === "runs") {
+        return `\nruntime runs=${details.runs?.length ?? 0}`;
+    }
+    if (view === "triage") {
+        return `\nruntime failed=${details.failed_runs?.length ?? 0} pending_controls=${Number(details.pending_control_count ?? 0)} stale_controls=${Number(details.stale_control_count ?? 0)} backpressured=${Number(details.backpressured_run_count ?? 0)} incomplete_trace=${Number(details.trace_diagnostic_count ?? 0)} attention=${details.attention_events?.length ?? 0}`;
+    }
+    return `\nruntime version=${String(details.version)} state_schema=${String(details.state_schema)} automatic_review=${String(details.automatic_review)}`;
+}
+function inspectRuntime(view, input, ctx, deps) {
+    if (view === "status")
+        return runtimeStatus();
+    if (view === "runs") {
+        return runtimeRuns(ctx, deps, typeof input.status === "string" ? input.status : undefined);
+    }
+    if (view === "triage")
+        return runtimeTriage(ctx, deps);
+    throw new Error("inspect runtime supports view=status, view=runs, or view=triage.");
+}
+function portableSkillRecipePath(file, skill, namespaces) {
+    const root = namespaces[skill]?.[0];
+    if (!root)
+        return `<active-skill:${skill}>`;
+    const relation = relative(root, file);
+    return !relation.startsWith("..") && !isAbsolute(relation)
+        ? `<active-skill:${skill}>/${relation.replaceAll("\\", "/")}`
+        : `<active-skill:${skill}>`;
+}
+function portableSkillRecipeDiagnosticReason(diagnostic, namespaces) {
+    let reason = diagnostic.reason;
+    if (diagnostic.file) {
+        reason = reason.replaceAll(diagnostic.file, portableSkillRecipePath(diagnostic.file, diagnostic.skill, namespaces));
+    }
+    for (const root of namespaces[diagnostic.skill] ?? []) {
+        reason = reason.replaceAll(root, `<active-skill:${diagnostic.skill}>`);
+    }
+    return reason;
+}
+function inspectRecipeIdentity(identity, resolutionContext, namespaces, inventory, registryStatus) {
+    const match = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\/([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/u.exec(identity);
+    const skill = match?.[1] ?? "";
+    const roots = skill ? namespaces[skill] ?? [] : [];
+    const skillActive = roots.length === 1;
+    const matchingComponent = inventory.components.find((component) => component.identity === identity);
+    const matchingRejection = inventory.rejected.find((diagnostic) => diagnostic.skill === skill &&
+        (diagnostic.stem === undefined || diagnostic.stem === match?.[2]));
+    let sourceLocation;
+    let rejectedReason;
+    let resolvable = false;
+    if (!match) {
+        rejectedReason =
+            "Identity must use canonical <skill>/<recipe> syntax.";
+    }
+    else if (roots.length === 0) {
+        rejectedReason = `Active Skill Recipe not found: ${identity}`;
+    }
+    else if (roots.length > 1) {
+        rejectedReason = matchingRejection
+            ? portableSkillRecipeDiagnosticReason(matchingRejection, namespaces)
+            : `Duplicate active Skill identity ${skill}`;
+    }
+    else if (matchingRejection) {
+        rejectedReason = portableSkillRecipeDiagnosticReason(matchingRejection, namespaces);
+        if (matchingRejection.file) {
+            sourceLocation = portableSkillRecipePath(matchingRejection.file, skill, namespaces);
+        }
+    }
+    else {
+        try {
+            const file = RecipesReferences.resolveRecipeReferencePath(identity, resolutionContext?.cwd, resolutionContext?.activeSkills);
+            if (!file || !existsSync(file)) {
+                rejectedReason = `Skill Recipe component not found: ${identity}`;
+            }
+            else {
+                sourceLocation = portableSkillRecipePath(file, skill, namespaces);
+                const recipe = RecipesReferences.readResolvedRecipeConfig(file, [], {
+                    skillContext: resolutionContext?.activeSkills,
+                });
+                if (recipe)
+                    resolvable = true;
+                else {
+                    rejectedReason =
+                        RecipesReferences.diagnoseRawRecipeConfigFailure(file) ??
+                            `Recipe could not be resolved: ${identity}`;
+                }
+            }
+        }
+        catch (error) {
+            rejectedReason = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const componentStatus = resolvable
+        ? "available"
+        : !match
+            ? "invalid_identity"
+            : roots.length === 0
+                ? "skill_inactive"
+                : roots.length > 1
+                    ? "ambiguous_skill"
+                    : matchingRejection
+                        ? "rejected"
+                        : matchingComponent
+                            ? "unresolvable"
+                            : "missing";
+    return {
+        identity,
+        skill_active: skillActive,
+        resolvable,
+        catalog_partial: inventory.partial,
+        component_status: componentStatus,
+        ...(sourceLocation ? { source_location: sourceLocation } : {}),
+        resolution_generation: resolutionContext?.generation ?? registryStatus?.resolution_generation ?? "unavailable",
+        ...(rejectedReason ? { rejected_reason: rejectedReason } : {}),
+        next_actions: resolvable
+            ? [
+                `spawn recipe=${identity}`,
+                `register_tool name=<tool-name> from=${identity}`,
+            ]
+            : roots.length === 0 && skill
+                ? [
+                    `activate Skill ${skill}`,
+                    `inspect target=recipes view=doctor identity=${identity}`,
+                ]
+                : ["inspect target=recipes view=imports verbose=true"],
+    };
+}
+function inspectRecipes(view, input, deps, context) {
+    if (view !== "status" &&
+        view !== "summary" &&
+        view !== "doctor" &&
+        view !== "imports" &&
+        view !== "reviews") {
+        throw new Error("inspect recipes supports view=status, view=summary, view=doctor, view=imports, or view=reviews.");
+    }
+    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    if (view === "reviews") {
+        return ReviewDiagnostics.readAutomaticReviewDiagnostics({ recipeRoot });
+    }
+    const discovered = RecipesDiscovery.discoverRecipeSources([
+        { root: recipeRoot, defaultTool: true, mutableUsage: true },
+    ]);
+    const resolutionContext = context && typeof context === "object" && "recipeResolutionContext" in context
+        ? context.recipeResolutionContext
+        : undefined;
+    const activeSkillContext = resolutionContext?.activeSkills ??
+        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+    const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces(activeSkillContext);
+    const skillInventory = RecipesReferences.inventoryActiveSkillRecipeComponents(activeSkillContext);
+    const registryStatus = deps.registryStatus?.();
+    const identity = typeof input.identity === "string" ? input.identity.trim() : "";
+    if (identity && view !== "doctor") {
+        throw new Error("inspect recipes identity is supported only with view=doctor.");
+    }
+    if (view === "doctor" && identity) {
+        return inspectRecipeIdentity(identity, resolutionContext, skillRecipeNamespaces, skillInventory, registryStatus);
+    }
+    const skillRecipeComponents = skillInventory.components.map((component) => ({
+        identity: component.identity,
+        source_kind: "active_skill_component",
+        skill: component.skill,
+        stem: component.stem,
+        imports: component.imports,
+    }));
+    const skillRecipeComponentDiagnostics = skillInventory.rejected.map((diagnostic) => ({
+        error: portableSkillRecipeDiagnosticReason(diagnostic, skillRecipeNamespaces),
+        ...(diagnostic.file
+            ? {
+                file: portableSkillRecipePath(diagnostic.file, diagnostic.skill, skillRecipeNamespaces),
+            }
+            : {}),
+        skill: diagnostic.skill,
+        ...(diagnostic.stem ? { stem: diagnostic.stem } : {}),
+    }));
+    const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
+    const summary = {
+        ...discoverySummary,
+        ...(registryStatus
+            ? {
+                ...registryStatus,
+                watched_root: "~/.pi/agent/recipes",
+            }
+            : {}),
+        active: Array.isArray(discoverySummary.active)
+            ? discoverySummary.active.map((entry) => ({
+                ...entry,
+                source_kind: "user_registry_capability",
+            }))
+            : discoverySummary.active,
+        skill_recipe_components: skillRecipeComponents,
+        skill_recipe_component_diagnostics: skillRecipeComponentDiagnostics,
+        skill_recipe_catalog_partial: skillInventory.partial,
+        active_skill_recipe_identities: Object.keys(skillRecipeNamespaces).sort(),
+        skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
+            .filter(([, roots]) => roots.length > 1)
+            .map(([name]) => ({
+            name,
+            error: `Ambiguous active Skill Recipe namespace ${name}`,
+        })),
+        drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
+    };
+    return {
+        ...summary,
+        next_actions: ToolsResponse.recipeRegistryNextActions(summary, view),
+    };
+}
+function parseRunTarget(target) {
+    if (!target.startsWith("run:"))
+        return undefined;
+    const run = target.slice(4);
+    return run && /^[A-Za-z0-9_.-]+$/.test(run) ? run : undefined;
+}
+function inspectRun(run, view, input, ctx, deps) {
+    if (view !== "recipe" && view !== "trace" && view !== "control") {
+        throw new Error("inspect run:<id> supports view=recipe, view=trace, or view=control.");
+    }
+    const status = deps.getRunStatus
+        ? deps.getRunStatus(run)
+        : ToolsAccess.assertRunAccessibleToContext(run, ctx);
+    const stateDir = String(status.state_dir);
+    if (view === "recipe") {
+        return Inspector.readActorInspectorRecipe(stateDir);
+    }
+    if (view === "trace") {
+        const source = typeof input.source === "string" ? input.source : "all";
+        if (source !== "all" &&
+            source !== "lifecycle" &&
+            source !== "control" &&
+            source !== "process" &&
+            source !== "agent" &&
+            source !== "artifact" &&
+            source !== "runtime") {
+            throw new Error(`unsupported Trace source: ${source}`);
+        }
+        return {
+            run, source,
+            summary: RunsTrace.summarizeRunTraceJournal(RunsTrace.readRunTraceJournal(stateDir)),
+            items: TraceProjection.projectRunTrace(stateDir, {
+                artifacts: status.artifacts,
+                limit: Number(input.lines || Limits.DEFAULT_INSPECT_LINES),
+                source,
+            }),
+        };
+    }
+    const runInstanceId = String(status.run_instance_id ?? "");
+    const journal = RunsControls.readRunControlJournalFromStateDir(stateDir);
+    const capacity = computeRunControlCapacity(journal.records);
+    const structuralDiagnostics = journal.records.flatMap((value) => {
+        const classified = RuntimeTriage.classifyRuntimeControl({ run,
+            runInstanceId: runInstanceId || undefined, status: String(status.status ?? "unknown") }, value, Date.now());
+        return classified.diagnostic ? [classified.diagnostic.reason] : [];
+    });
+    let journalBytes = 0;
+    try {
+        journalBytes = statSync(RunsControls.runControlsFile(stateDir)).size;
+    }
+    catch { }
+    const diagnostics = [...journal.diagnostics.map((item) => ({
+            ...(item.line === undefined ? {} : { line: item.line }),
+            reason: item.line === undefined ? "unreadable_control_journal" : "invalid_control_json",
+        })), ...structuralDiagnostics.map((reason) => ({ reason }))].slice(0, 40);
+    const nowMs = Date.now();
+    const stalePending = journal.records.reduce((count, control) => count + Number(Boolean(RuntimeTriage.classifyRuntimeControl({ run, runInstanceId: runInstanceId || undefined,
+        status: String(status.status ?? "unknown") }, control, nowMs).stale)), 0);
+    return {
+        run,
+        run_instance_id: runInstanceId,
+        status: status.status,
+        pending: capacity.pending, pending_limit: capacity.limit,
+        available: capacity.available, backpressured: capacity.backpressured,
+        journal_bytes: journalBytes, journal_limit: Limits.RUN_CONTROL_JOURNAL_MAX_BYTES,
+        ...(capacity.oldest_pending_at ? { oldest_pending_at: capacity.oldest_pending_at } : {}),
+        stale_pending: stalePending,
+        diagnostics,
+        actor_actions: Array.isArray(status.control) ? status.control : [],
+        runtime_actions: status.status === "running" ? ["kill"] : ["archive", "prune"],
+        endpoint: runInstanceId
+            ? RunControlDelivery.readRunControlEndpoint(stateDir, runInstanceId)
+            : undefined,
+        recent_controls: journal.records.slice(-Math.max(1, Number(input.lines || 20))).reverse()
+            .map((control) => ControlProjection.projectRunControl(control)),
+    };
+}
+function inspectTool(name, view, deps) {
+    if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+        throw new Error(`invalid tool target: tool:${name}`);
+    }
+    if (view !== "status" && view !== "schema") {
+        throw new Error("inspect tool:<name> supports view=status or view=schema.");
+    }
+    const tool = deps.getTool?.(name);
+    const status = deps.getToolStatus?.(name);
+    if (!tool && !status) {
+        throw new Error(`Registered tool not found: ${name}. Next: inspect target=recipes view=doctor; do not substitute spawn for tool invocation.`);
+    }
+    if (view === "schema" && !tool) {
+        throw new Error(`Tool "${name}" is registered but its callable schema is unavailable; callable_now=${String(status?.callable_now ?? false)}, activation_boundary=${String(status?.activation_boundary ?? "host_registration")}. Next: inspect target=tool:${name} view=status.`);
+    }
+    return {
+        name,
+        ...(view === "status" ? status : {}),
+        ...(tool
+            ? {
+                description: tool.description,
+                parameters: tool.parameters,
+                promptSnippet: tool.promptSnippet,
+            }
+            : {}),
+    };
+}
+function compactResult(target, view, details) {
+    if (target === "runtime")
+        return compactRuntime(view, details);
+    if (target === "recipes" && typeof details.identity === "string") {
+        const lines = [
+            `recipes doctor identity=${details.identity} skill_active=${String(details.skill_active)} resolvable=${String(details.resolvable)} catalog_partial=${String(details.catalog_partial)} component_status=${String(details.component_status)}`,
+            ...(details.source_location
+                ? [`source=${String(details.source_location)}`]
+                : []),
+            `resolution_generation=${String(details.resolution_generation)}`,
+            ...(details.rejected_reason
+                ? [`rejected_reason=${String(details.rejected_reason)}`]
+                : []),
+            ...(details.next_actions ?? []).map((action) => `next=${String(action)}`),
+        ];
+        return `\n${lines.join("\n")}`;
+    }
+    if (target === "recipes")
+        return ToolsResponse.compactRecipeRegistry(details);
+    if (target.startsWith("tool:") && view === "status") {
+        const required = Array.isArray(details.required_args)
+            ? details.required_args.map(String).join(",") || "none"
+            : "unknown";
+        const optional = Array.isArray(details.optional_args)
+            ? details.optional_args.map(String).join(",") || "none"
+            : "unknown";
+        const next = Array.isArray(details.next_actions) && details.next_actions.length > 0
+            ? String(details.next_actions[0])
+            : details.callable_now === true
+                ? `call tool ${target.slice(5)}`
+                : `register_tool name=${target.slice(5)} update=true`;
+        return `\ntool=${target.slice(5)} source=${String(details.source ?? "unknown")} callable_now=${String(details.callable_now ?? false)} activation_boundary=${String(details.activation_boundary ?? "unknown")} required=${required} optional=${optional} launch_kind=${String(details.launch_kind ?? "none")} spawn_calls=${Number(details.spawn_calls ?? 0)} tool_calls=${Number(details.tool_calls ?? 0)} next=${next}`;
+    }
+    if (target.startsWith("tool:"))
+        return `\ntool=${target.slice(5)} view=${view}`;
+    return `\nrun=${target.slice(4)} view=${view}`;
+}
+export function createInspectToolDefinition(deps = {}) {
+    return {
+        name: "inspect",
+        label: "Inspect",
+        description: "Inspect a Run's Recipe, Trace, or Control evidence, or runtime/recipe/tool diagnostics.",
+        parameters: Schema.objectSchema({
+            identity: Schema.stringSchema("Optional canonical <skill>/<recipe> identity for focused Recipe doctor diagnosis."),
+            lines: Schema.stringSchema("Bounded item count for Trace or recent Controls."),
+            source: Schema.stringSchema("Optional Trace source: all, lifecycle, control, process, agent, artifact, or runtime."),
+            status: Schema.stringSchema("Optional runtime Run status filter."),
+            target: Schema.stringSchema("Target: run:<id>, runtime, recipes, or tool:<name>."),
+            verbose: Schema.booleanSchema("Return full JSON instead of compact text."),
+            view: Schema.stringSchema("Run view recipe|trace|control, or target-specific management view."),
+        }, ["target", "view"]),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const input = asRecord(params);
+            const target = String(input.target ?? "");
+            const view = String(input.view ?? "");
+            let details;
+            if (target === "runtime") {
+                details = inspectRuntime(view, input, ctx, deps);
+            }
+            else if (target === "recipes") {
+                details = inspectRecipes(view, input, deps, ctx);
+            }
+            else {
+                const run = parseRunTarget(target);
+                if (run)
+                    details = inspectRun(run, view, input, ctx, deps);
+                else if (target.startsWith("tool:")) {
+                    details = inspectTool(target.slice(5), view, deps);
+                }
+                else {
+                    throw new Error(`unsupported inspect target: ${target}; use run:<id>, runtime, recipes, or tool:<name>`);
+                }
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: maybeJsonText(details, input.verbose === true || (target.startsWith("tool:") && view === "schema"), compactResult(target, view, details)),
+                    }],
+                details,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Local tool definition behavior
+ * Zones: user recipe tools, generated schemas, async recipe launch
+ * Owns wrapping saved local capabilities as executable pi tools
+ */
+import * as ModelContext from "./model-context.ts";
+import type { RegisteredTool } from "./config.ts";
+import * as Execution from "./execution.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
+export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
+    recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
+    cwd: string;
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+}
+export declare function createRuntimeToolDefinition(cfg: RegisteredTool, exec: Execution.RegisteredToolExec): any;