@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,20 @@
+/**
+ * Actor Inspector evidence readers.
+ * Zones: owned actor-instance inventory and captured Recipe projection
+ * Owns actor-instance TUI evidence; Trace, Control, and execution parsing stay in their domains.
+ */
+export interface ActorInspectorRunItem {
+    run: string;
+    runInstanceId?: string;
+    status: string;
+    updatedAt?: string;
+}
+export declare function readActorInspectorRuns(stateRoot: string, ownerId: string): ActorInspectorRunItem[];
+export interface ActorInspectorRecipeView {
+    composition: Array<Record<string, unknown>>;
+    definition?: Record<string, unknown>;
+    diagnostics: string[];
+    identity: Record<string, unknown>;
+    launch: Record<string, unknown>;
+}
+export declare function readActorInspectorRecipe(stateDir: string): ActorInspectorRecipeView;

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * Shared output, preview, and Control envelope limits.
+ * Zones: output governance, Trace previews, Inspect defaults, Control portability
+ */
+export declare const DEFAULT_INSPECT_LINES = 40;
+export declare const TOOL_OUTPUT_MAX_BYTES: number;
+export declare const TOOL_OUTPUT_MAX_LINES = 2000;
+export declare const COMPACT_PREVIEW_CHARS = 160;
+export declare const CONTROL_ACTION_MAX_LENGTH = 64;
+export declare const CONTROL_INPUT_MAX_BYTES = 380;
+export declare const CONTROL_WIRE_MAX_BYTES = 512;
+export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
+export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
+export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
+export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;
+export declare const TRACE_EVENT_MAX_BYTES: number;
+export declare const TRACE_EVENT_MAX_READ = 200;
+export declare const TRACE_JOURNAL_MAX_EVENTS = 2048;
+export declare const TRACE_JOURNAL_TARGET_EVENTS = 1536;
+export declare const TRACE_JOURNAL_MAX_BYTES: number;
+export declare const TRACE_JOURNAL_TARGET_BYTES: number;
+export declare const RUN_CONTROL_PENDING_LIMIT = 64;
+export declare const RUN_CONTROL_TERMINAL_LIMIT = 128;
+export declare const RUN_CONTROL_ERROR_MAX_BYTES: number;
+export declare const RUN_CONTROL_JOURNAL_MAX_BYTES: number;
+export declare const RUN_RETENTION_MAX_RECORDS = 256;
+export declare const RUN_RETENTION_MAX_BYTES: number;

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * Current model/thinking propagation helpers
+ * Zones: pi session context, recipe inheritance
+ * Owns current model/thinking extraction from Pi tool contexts and implicit command-template values.
+ */
+export interface CurrentModelContext {
+    currentThinking?: unknown;
+    getThinkingLevel?: () => unknown;
+    model?: {
+        id?: unknown;
+        modelId?: unknown;
+        provider?: unknown;
+    };
+    sessionManager?: {
+        getBranch?: () => unknown[];
+        getSessionId?: () => string;
+    };
+    thinkingLevel?: unknown;
+}
+export declare const CURRENT_MODEL_VALUE_KEY = "current_model";
+export declare const CURRENT_THINKING_VALUE_KEY = "current_thinking";
+export type CurrentPolicySource = "explicit" | "inherited" | "mixed" | "unresolved" | "unused";
+export interface CurrentPolicyAxisProvenance {
+    explicit_keys?: string[];
+    inherited_keys?: string[];
+    source: CurrentPolicySource;
+    unresolved_keys?: string[];
+    value?: string;
+}
+export interface CurrentPolicyProvenance {
+    model: CurrentPolicyAxisProvenance;
+    thinking: CurrentPolicyAxisProvenance;
+}
+export interface CurrentPolicyRecipeSummary {
+    model?: {
+        inherited_defaults?: string[];
+        public_args?: string[];
+    };
+    thinking?: {
+        inherited_defaults?: string[];
+        public_args?: string[];
+    };
+}
+export declare function getCurrentModelPattern(ctx: CurrentModelContext | undefined): string | undefined;
+export declare function getCurrentThinkingLevel(ctx: CurrentModelContext | undefined): string | undefined;
+export declare function withCurrentModelValues<T extends Record<string, unknown>>(values: T, ctx: CurrentModelContext | undefined): T & Record<string, unknown>;
+export declare function describeCurrentPolicyProvenance(input: {
+    defaults?: Record<string, unknown>;
+    template: unknown;
+    values?: Record<string, unknown>;
+}): CurrentPolicyProvenance;
+export declare function describeRecipeCurrentPolicy(input: {
+    args?: unknown;
+    defaults?: Record<string, unknown>;
+    template: unknown;
+}): CurrentPolicyRecipeSummary | undefined;

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

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

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

@@ -0,0 +1,186 @@
+/**
+ * Async run observability helpers
+ * Zones: async runtime, ambient UI, diagnostics
+ * Owns ambient summaries, terminal events, and Trace-attention delivery for detached Runs
+ */
+import { type FSWatcher } from "node:fs";
+import * as AsyncRuns from "./async-runs.ts";
+export type RunObservedStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
+export type RunTraceAttention = "log" | "notify" | "followup";
+export type RunTraceLevel = "info" | "warning" | "error";
+export interface RunObservation {
+    activeSubagents?: number;
+    completed?: number;
+    descendantSubagents?: number;
+    failures?: number;
+    ownerId?: string;
+    artifacts?: Record<string, string>;
+    launchCorrelation?: Record<string, string>;
+    launchSource?: AsyncRuns.AsyncRunLaunchSource;
+    modelPolicy?: Record<string, unknown>;
+    notificationPolicy?: "normal" | "silent";
+    recipeFile?: string;
+    terminalHandled?: boolean;
+    retireWhen?: string;
+    run: string;
+    semanticResult?: RunTerminalSemanticResult;
+    tool?: string;
+    stateDir?: string;
+    status: RunObservedStatus;
+    updatedAt?: string;
+}
+export interface RunSummary {
+    cancelled: number;
+    done: number;
+    exited: number;
+    failed: number;
+    killed: number;
+    running: number;
+    runningSubagents: number;
+    runs: RunObservation[];
+    total: number;
+}
+export interface RunUiObservationState {
+    attentionEventIds: Map<string, Set<string>>;
+    legacyEventLines: Map<string, number>;
+    frame: number;
+    observed: Map<string, RunObservedStatus>;
+}
+export interface RunUiSnapshot {
+    attentionEvents: RunAttentionEvent[];
+    status: string | undefined;
+    summary: RunSummary;
+    transitions: RunTransition[];
+}
+export interface RunUiNotificationSink {
+    notify(message: string, level: "info" | "warning" | "error"): void;
+    sendFollowUp(message: {
+        customType: string;
+        content: string;
+        display: false;
+        details: unknown;
+    }): void;
+}
+export declare function createRunUiObservationState(): RunUiObservationState;
+export declare function primeRunAttentionState(state: RunUiObservationState, ownerId: string, stateRoot?: string): void;
+export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string, options?: {
+    includeAttention?: boolean;
+    stateRoot?: string;
+}): RunUiSnapshot;
+export declare function pruneRunUiObservationState(state: RunUiObservationState, snapshot: Pick<RunUiSnapshot, "summary" | "transitions">): void;
+export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink, inFlight?: Set<string>): void;
+export declare function reconcileRunTerminalNotifications(input: {
+    inFlight?: Set<string>;
+    ownerId: string;
+    sink: RunUiNotificationSink;
+    state: RunUiObservationState;
+    stateRoot?: string;
+    includeAttention?: boolean;
+}): RunUiSnapshot;
+export declare function deliverRunAttentionNotifications(events: RunAttentionEvent[], sink: RunUiNotificationSink): void;
+export interface RunRetirementCandidate {
+    activeSubagents: number;
+    childRuns: number;
+    descendantSubagents: number;
+    run: string;
+    stateDir: string;
+    terminalChildRuns: number;
+}
+export interface RunRetirementExecution {
+    action: "stop" | "cancel" | "skip" | "failed";
+    error?: string;
+    run: string;
+    stateDir: string;
+}
+export type RunStateWatcherDiagnosticCode = "attach_failed" | "error" | "removed" | "rearmed";
+export interface RunStateWatcherDiagnostic {
+    code: RunStateWatcherDiagnosticCode;
+    id: number;
+    message: string;
+    path: string;
+    scope: "root" | "run";
+    ts: string;
+}
+export interface RunStateWatcher {
+    close(): void;
+    getDiagnostics(): RunStateWatcherDiagnostic[];
+    refresh(): void;
+}
+export declare function createRunStateWatcher(input: {
+    exists?: (path: string) => boolean;
+    listDirectories?: (path: string) => string[];
+    onChange: () => void;
+    stateRoot?: string;
+    watchPath?: (path: string, onChange: () => void) => FSWatcher;
+}): RunStateWatcher;
+export interface RunTerminalReconciliationLoop {
+    close(): void;
+    reconcileNow(): void;
+    start(): void;
+}
+export declare function createRunTerminalReconciliationLoop(input: {
+    intervalMs?: number;
+    onError?: (error: unknown) => void;
+    reconcile: () => void;
+    refreshWatcher: () => void;
+}): RunTerminalReconciliationLoop;
+export interface RunRetirementExecutorOptions {
+    attempted?: Set<string>;
+    cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;
+    notify?: (message: string, level: "info" | "warning" | "error") => void;
+    sendStop: (candidate: RunRetirementCandidate) => Promise<unknown>;
+}
+export interface RunTransition {
+    from: RunObservedStatus;
+    run: string;
+    stateDir?: string;
+    artifacts?: Record<string, string>;
+    launchCorrelation?: Record<string, string>;
+    launchSource?: AsyncRuns.AsyncRunLaunchSource;
+    modelPolicy?: Record<string, unknown>;
+    recipeFile?: string;
+    terminalHandled?: boolean;
+    to: RunObservedStatus;
+    tool?: string;
+    semanticResult?: RunTerminalSemanticResult;
+}
+export interface RunTerminalSemanticResult {
+    body?: string;
+    correlationId?: string;
+    metadata: Record<string, unknown>;
+    summary: string;
+    synthesized: boolean;
+    type: string;
+}
+export interface RunAttentionEvent {
+    body?: unknown;
+    data?: unknown;
+    attention: RunTraceAttention;
+    id: string;
+    kind: string;
+    level: RunTraceLevel;
+    metadata?: Record<string, unknown>;
+    run: string;
+    stateDir: string;
+    summary: string;
+    ts: string;
+}
+export type RunTransitionNotificationType = "info" | "warning" | "error";
+export declare function summarizeRuns(stateRoot?: string, ownerId?: string): RunSummary;
+export declare function countRunningSubagentsByRun(stateRoot?: string, ownerId?: string): Map<string, number>;
+export declare function countRunningSubagents(stateRoot?: string, ownerId?: string): number;
+export declare function renderSubagentStatus(count: number, frame?: number): string | undefined;
+export declare function renderRunStatus(summary: RunSummary, frame?: number): string | undefined;
+export declare function findRunRetirementCandidates(summary: RunSummary): RunRetirementCandidate[];
+export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
+export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
+export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>, seenEventIds?: Map<string, Set<string>>): void;
+export declare function detectRunAttentionEvents(legacyLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>, prime?: boolean): RunAttentionEvent[];
+export declare function getRunAttentionNotificationType(event: RunAttentionEvent): RunTransitionNotificationType;
+export declare function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean;
+export declare function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean;
+export declare function formatRunAttentionMessage(event: RunAttentionEvent): string;
+export declare function getRunTransitionNotificationType(transition: RunTransition): RunTransitionNotificationType;
+export declare function shouldNotifyRunTransition(transition: RunTransition): boolean;
+export declare function shouldSendRunTransitionFollowUp(transition: RunTransition): boolean;
+export declare function formatRunTransitionMessage(transition: RunTransition): string;