@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,491 @@
+/**
+ * Run Trace event journal.
+ * Zones: structured event validation, bounded atomic retention, resilient reads
+ * Owns canonical Run-local Trace persistence; lifecycle projection and owner attention delivery stay in adapters.
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, fstatSync, openSync, readSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { withFileMutationLock, writeTextAtomic } from "./file-state.js";
+import * as Limits from "./limits.js";
+import { accumulateTraceCompactionStatistics, selectNewestTraceSuffix, traceAppendFits, traceCompactionMarkerInput, TRACE_COMPACTION_KIND, TRACE_COMPACTION_VERSION, } from "./run-evidence-policy.js";
+const KIND_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+const TRACE_FIELDS = new Set([
+    "attention",
+    "data",
+    "id",
+    "kind",
+    "level",
+    "summary",
+    "ts",
+]);
+const TRACE_INPUT_FIELDS = new Set([
+    "attention",
+    "data",
+    "kind",
+    "level",
+    "summary",
+]);
+const FORBIDDEN_FIELDS = new Set([
+    "body",
+    "correlation_id",
+    "from",
+    "metadata",
+    "reply_to",
+    "to",
+    "type",
+]);
+const COMPACTION_DATA_FIELDS = new Set([
+    "compactions_total",
+    "dropped_bytes_total",
+    "dropped_event_count_exact",
+    "dropped_malformed_lines_total",
+    "dropped_valid_events_total",
+    "history_complete",
+    "retained_bytes",
+    "retained_events",
+    "version",
+]);
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+export function runTraceFile(stateDir) {
+    return join(stateDir, "trace.jsonl");
+}
+function hasExactFields(record, fields) {
+    const keys = Object.keys(record);
+    return keys.length === fields.size && keys.every((key) => fields.has(key));
+}
+function normalizeTraceEventInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Trace event must be an object");
+    }
+    const record = input;
+    const forbidden = Object.keys(record).filter((key) => FORBIDDEN_FIELDS.has(key));
+    if (forbidden.length > 0) {
+        throw new Error(`Trace event fields are removed: ${forbidden.sort().join(", ")}`);
+    }
+    const unknown = Object.keys(record).filter((key) => !TRACE_INPUT_FIELDS.has(key));
+    if (unknown.length > 0) {
+        throw new Error(`Unsupported Trace event fields: ${unknown.sort().join(", ")}`);
+    }
+    if (typeof record.kind !== "string" || !KIND_PATTERN.test(record.kind)) {
+        throw new Error("Trace event kind must be a lowercase semantic token");
+    }
+    if (record.kind === TRACE_COMPACTION_KIND) {
+        throw new Error(`Trace event kind is runtime-reserved: ${TRACE_COMPACTION_KIND}`);
+    }
+    if (record.summary !== undefined && typeof record.summary !== "string") {
+        throw new Error("Trace event summary must be a string");
+    }
+    if (record.level !== undefined &&
+        record.level !== "info" &&
+        record.level !== "warning" &&
+        record.level !== "error") {
+        throw new Error("Trace event level must be info, warning, or error");
+    }
+    if (record.attention !== undefined &&
+        record.attention !== "notify" &&
+        record.attention !== "followup") {
+        throw new Error("Trace event attention must be notify or followup");
+    }
+    return {
+        kind: record.kind,
+        ...(record.summary !== undefined
+            ? { summary: record.summary.slice(0, 1_000) }
+            : {}),
+        ...(record.data !== undefined ? { data: record.data } : {}),
+        ...(record.level !== undefined
+            ? { level: record.level }
+            : {}),
+        ...(record.attention !== undefined
+            ? { attention: record.attention }
+            : {}),
+    };
+}
+function encodeTraceEvent(event) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(event);
+    }
+    catch {
+        throw new Error("Trace event data must be JSON-serializable");
+    }
+    if (Buffer.byteLength(serialized) > Limits.TRACE_EVENT_MAX_BYTES) {
+        throw new Error(`Trace event exceeds ${Limits.TRACE_EVENT_MAX_BYTES} bytes`);
+    }
+    const encoded = `${serialized}\n`;
+    return { encoded, encodedBytes: Buffer.byteLength(encoded), event };
+}
+function createTraceEvent(input) {
+    return encodeTraceEvent({
+        id: randomUUID(),
+        ts: new Date().toISOString(),
+        ...normalizeTraceEventInput(input),
+    });
+}
+function readTraceWindow(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                content: Buffer.alloc(0),
+                fileBytes: 0,
+                leadingPartialLines: 0,
+                omittedPrefixBytes: 0,
+                readBytes: 0,
+            };
+        }
+        throw error;
+    }
+    try {
+        const fileBytes = fstatSync(fd).size;
+        if (!Number.isSafeInteger(fileBytes) || fileBytes < 0) {
+            throw new Error("Trace journal size is not safely representable");
+        }
+        const readBytes = Math.min(fileBytes, Limits.TRACE_JOURNAL_MAX_BYTES);
+        const offset = fileBytes - readBytes;
+        const buffer = Buffer.allocUnsafe(readBytes);
+        let consumed = 0;
+        while (consumed < readBytes) {
+            const count = readSync(fd, buffer, consumed, readBytes - consumed, offset + consumed);
+            if (count === 0)
+                throw new Error("Trace journal changed during bounded read");
+            consumed += count;
+        }
+        if (fstatSync(fd).size !== fileBytes) {
+            throw new Error("Trace journal changed during bounded read");
+        }
+        if (offset === 0) {
+            return {
+                content: buffer,
+                fileBytes,
+                leadingPartialLines: 0,
+                omittedPrefixBytes: 0,
+                readBytes,
+            };
+        }
+        const preceding = Buffer.allocUnsafe(1);
+        if (readSync(fd, preceding, 0, 1, offset - 1) !== 1) {
+            throw new Error("Trace journal changed during bounded read");
+        }
+        if (preceding[0] === 0x0a) {
+            return {
+                content: buffer,
+                fileBytes,
+                leadingPartialLines: 0,
+                omittedPrefixBytes: offset,
+                readBytes,
+            };
+        }
+        const newline = buffer.indexOf(0x0a);
+        const discarded = newline < 0 ? buffer.length : newline + 1;
+        return {
+            content: buffer.subarray(discarded),
+            fileBytes,
+            leadingPartialLines: 1,
+            omittedPrefixBytes: offset + discarded,
+            readBytes,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function isTraceEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    if (Object.keys(record).some((key) => !TRACE_FIELDS.has(key)))
+        return false;
+    if (typeof record.id !== "string" || !record.id ||
+        typeof record.ts !== "string" || !Number.isFinite(Date.parse(record.ts)) ||
+        typeof record.kind !== "string" || !KIND_PATTERN.test(record.kind))
+        return false;
+    if (record.summary !== undefined && typeof record.summary !== "string")
+        return false;
+    if (record.level !== undefined &&
+        record.level !== "info" &&
+        record.level !== "warning" &&
+        record.level !== "error")
+        return false;
+    return record.attention === undefined ||
+        record.attention === "notify" ||
+        record.attention === "followup";
+}
+function isCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function compactionData(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (!hasExactFields(record, COMPACTION_DATA_FIELDS))
+        return undefined;
+    if (record.version !== TRACE_COMPACTION_VERSION ||
+        !isCount(record.compactions_total) ||
+        !isCount(record.dropped_valid_events_total) ||
+        !isCount(record.dropped_malformed_lines_total) ||
+        !isCount(record.dropped_bytes_total) ||
+        typeof record.dropped_event_count_exact !== "boolean" ||
+        !isCount(record.retained_events) ||
+        !isCount(record.retained_bytes) ||
+        record.history_complete !== false)
+        return undefined;
+    return record;
+}
+function markerData(event) {
+    return event.kind === TRACE_COMPACTION_KIND &&
+        event.level === "warning" &&
+        event.summary === undefined &&
+        event.attention === undefined
+        ? compactionData(event.data)
+        : undefined;
+}
+function decodeTraceLine(line) {
+    if (line.length === 0 || line.length > Limits.TRACE_EVENT_MAX_BYTES) {
+        throw new Error("Trace journal line is empty or oversized");
+    }
+    const text = UTF8_DECODER.decode(line);
+    const event = JSON.parse(text);
+    if (!isTraceEvent(event) ||
+        (event.kind === TRACE_COMPACTION_KIND && !markerData(event))) {
+        throw new Error("Trace journal line is not a canonical event");
+    }
+    return { event, text };
+}
+function parseTraceJournal(window) {
+    let candidates = [];
+    let candidateHead = 0;
+    let candidateBytes = 0;
+    let droppedBytes = window.omittedPrefixBytes;
+    let droppedValidEvents = 0;
+    let malformedLines = window.leadingPartialLines;
+    let physicalEvents = 0;
+    let previousCompaction;
+    const dropOldestCandidate = () => {
+        const dropped = candidates[candidateHead++];
+        candidateBytes -= dropped.encodedBytes;
+        droppedBytes += dropped.encodedBytes;
+        droppedValidEvents += 1;
+        if (candidateHead > 2_048) {
+            candidates = candidates.slice(candidateHead);
+            candidateHead = 0;
+        }
+    };
+    const consume = (line, physicalBytes) => {
+        let decoded;
+        try {
+            decoded = decodeTraceLine(line);
+        }
+        catch {
+            malformedLines += 1;
+            droppedBytes += physicalBytes;
+            return;
+        }
+        const { event, text } = decoded;
+        physicalEvents += 1;
+        if (event.kind === TRACE_COMPACTION_KIND) {
+            previousCompaction = markerData(event);
+            return;
+        }
+        const encoded = `${text}\n`;
+        const candidate = {
+            encodedBytes: Buffer.byteLength(encoded),
+            value: { encoded, encodedBytes: Buffer.byteLength(encoded), event },
+        };
+        candidates.push(candidate);
+        candidateBytes += candidate.encodedBytes;
+        while (candidates.length - candidateHead > Limits.TRACE_JOURNAL_TARGET_EVENTS ||
+            candidateBytes > Limits.TRACE_JOURNAL_TARGET_BYTES)
+            dropOldestCandidate();
+    };
+    let start = 0;
+    while (start < window.content.length) {
+        const newline = window.content.indexOf(0x0a, start);
+        if (newline < 0) {
+            malformedLines += 1;
+            droppedBytes += window.content.length - start;
+            break;
+        }
+        consume(window.content.subarray(start, newline), newline - start + 1);
+        start = newline + 1;
+    }
+    candidates = candidates.slice(candidateHead);
+    return {
+        candidateBytes,
+        candidates,
+        droppedBytes,
+        droppedValidEvents,
+        malformedLines,
+        physicalEvents,
+        ...(previousCompaction ? { previousCompaction } : {}),
+    };
+}
+function markerReserveBytes(id, ts) {
+    const maximum = Number.MAX_SAFE_INTEGER;
+    return encodeTraceEvent({
+        id,
+        ts,
+        ...traceCompactionMarkerInput({
+            version: TRACE_COMPACTION_VERSION,
+            compactions_total: maximum,
+            dropped_valid_events_total: maximum,
+            dropped_malformed_lines_total: maximum,
+            dropped_bytes_total: maximum,
+            dropped_event_count_exact: false,
+            retained_events: maximum,
+            retained_bytes: maximum,
+            history_complete: false,
+        }),
+    }).encodedBytes;
+}
+function createCompactionMarker(id, ts, previous, delta, retainedWithoutMarkerBytes) {
+    let markerBytes = 0;
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const data = accumulateTraceCompactionStatistics(previous, {
+            ...delta,
+            retained_bytes: retainedWithoutMarkerBytes + markerBytes,
+        });
+        const marker = encodeTraceEvent({
+            id,
+            ts,
+            ...traceCompactionMarkerInput(data),
+        });
+        if (marker.encodedBytes === markerBytes)
+            return marker;
+        markerBytes = marker.encodedBytes;
+    }
+    throw new Error("Trace compaction marker size did not converge");
+}
+function compactTraceJournal(path, window, parsed, appended) {
+    const markerId = randomUUID();
+    const markerTs = new Date().toISOString();
+    const reserveBytes = markerReserveBytes(markerId, markerTs);
+    const selection = selectNewestTraceSuffix(parsed.candidates, {
+        bytes: appended.encodedBytes + reserveBytes,
+        events: 2,
+    });
+    const marker = createCompactionMarker(markerId, markerTs, parsed.previousCompaction, {
+        dropped_valid_events: parsed.droppedValidEvents + selection.droppedEvents,
+        dropped_malformed_lines: parsed.malformedLines,
+        dropped_bytes: parsed.droppedBytes + parsed.candidateBytes - selection.retainedBytes,
+        dropped_event_count_exact: window.omittedPrefixBytes === 0,
+        retained_events: selection.retainedEvents + 2,
+    }, selection.retainedBytes + appended.encodedBytes);
+    if (marker.encodedBytes > reserveBytes) {
+        throw new Error("Trace compaction marker exceeded its reserved bound");
+    }
+    const content = [
+        ...selection.retained.map(({ value }) => value.encoded),
+        appended.encoded,
+        marker.encoded,
+    ].join("");
+    const bytes = Buffer.byteLength(content);
+    const events = selection.retainedEvents + 2;
+    if (bytes > Limits.TRACE_JOURNAL_TARGET_BYTES ||
+        events > Limits.TRACE_JOURNAL_TARGET_EVENTS ||
+        bytes > Limits.TRACE_JOURNAL_MAX_BYTES ||
+        events > Limits.TRACE_JOURNAL_MAX_EVENTS) {
+        throw new Error("Trace compaction could not satisfy journal bounds");
+    }
+    writeTextAtomic(path, content);
+}
+export function appendRunTraceEvent(stateDir, input) {
+    const appended = createTraceEvent(input);
+    const path = runTraceFile(stateDir);
+    return withFileMutationLock(path, () => {
+        const window = readTraceWindow(path);
+        const parsed = parseTraceJournal(window);
+        const completeJournal = window.omittedPrefixBytes === 0 && parsed.malformedLines === 0;
+        if (completeJournal &&
+            traceAppendFits({ bytes: window.fileBytes, events: parsed.physicalEvents }, appended.encodedBytes)) {
+            writeFileSync(path, appended.encoded, { flag: "a" });
+        }
+        else {
+            compactTraceJournal(path, window, parsed, appended);
+        }
+        return appended.event;
+    });
+}
+export function readRunTraceJournal(stateDir) {
+    const path = runTraceFile(stateDir);
+    let window;
+    try {
+        window = readTraceWindow(path);
+    }
+    catch (error) {
+        return {
+            diagnostics: [{
+                    message: error instanceof Error ? error.message : String(error),
+                    path,
+                }],
+            events: [],
+            fileBytes: 0,
+            omittedPrefixBytes: 0,
+            readBytes: 0,
+        };
+    }
+    const diagnostics = [];
+    let events = [];
+    let eventHead = 0;
+    let ordinal = window.leadingPartialLines;
+    const diagnose = (message, line) => {
+        diagnostics.push({ message, path, ...(line === undefined ? {} : { line }) });
+        if (diagnostics.length > Limits.TRACE_EVENT_MAX_READ)
+            diagnostics.shift();
+    };
+    const retain = (event) => {
+        events.push({ event, ordinal });
+        if (events.length - eventHead > Limits.TRACE_JOURNAL_MAX_EVENTS)
+            eventHead += 1;
+        if (eventHead > Limits.TRACE_JOURNAL_MAX_EVENTS) {
+            events = events.slice(eventHead);
+            eventHead = 0;
+        }
+    };
+    if (window.leadingPartialLines) {
+        diagnose("Omitted partial leading Trace line", 1);
+    }
+    let start = 0;
+    while (start < window.content.length) {
+        ordinal += 1;
+        const newline = window.content.indexOf(0x0a, start);
+        if (newline < 0) {
+            diagnose("Incomplete trailing Trace line", ordinal);
+            break;
+        }
+        try {
+            retain(decodeTraceLine(window.content.subarray(start, newline)).event);
+        }
+        catch (error) {
+            diagnose(error instanceof Error ? error.message : String(error), ordinal);
+        }
+        start = newline + 1;
+    }
+    return {
+        diagnostics,
+        events: events.slice(eventHead),
+        fileBytes: window.fileBytes,
+        omittedPrefixBytes: window.omittedPrefixBytes,
+        readBytes: window.readBytes,
+    };
+}
+export function summarizeRunTraceJournal(read) {
+    const marker = [...read.events].reverse().map(({ event }) => markerData(event)).find(Boolean);
+    const incomplete = Boolean(marker) || read.omittedPrefixBytes > 0;
+    return {
+        history_complete: !incomplete, compacted: Boolean(marker),
+        compactions_total: marker?.compactions_total ?? 0,
+        dropped_events: marker?.dropped_valid_events_total ?? 0,
+        dropped_bytes: marker?.dropped_bytes_total ?? read.omittedPrefixBytes,
+        dropped_event_count_exact: marker?.dropped_event_count_exact ?? !incomplete,
+        retained_events: read.events.length, retained_bytes: read.readBytes,
+    };
+}
+export function readRunTraceEvents(stateDir, limit = Limits.TRACE_EVENT_MAX_READ) {
+    return readRunTraceJournal(stateDir).events
+        .slice(-Math.max(1, Math.min(limit, Limits.TRACE_EVENT_MAX_READ)))
+        .map(({ event }) => event);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Immutable runtime package identity.
+ * Zones: source/installed package version resolution and Run-state schema marker
+ * Owns package-local identity reads; runtime status and Run persistence remain in their domains.
+ */
+export declare const RUN_STATE_SCHEMA: "run-kernel-v1";
+export declare function getPackageVersion(): string;

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

@@ -0,0 +1,35 @@
+/**
+ * Immutable runtime package identity.
+ * Zones: source/installed package version resolution and Run-state schema marker
+ * Owns package-local identity reads; runtime status and Run persistence remain in their domains.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const RUN_STATE_SCHEMA = "run-kernel-v1";
+let cachedVersion;
+export function getPackageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    for (const path of [
+        join(moduleDir, "..", "package.json"),
+        join(moduleDir, "..", "..", "package.json"),
+    ]) {
+        try {
+            const pkg = JSON.parse(readFileSync(path, "utf8"));
+            if (pkg.name === "@llblab/pi-actors" &&
+                typeof pkg.version === "string" &&
+                pkg.version.length > 0 &&
+                pkg.version.length <= 128 &&
+                pkg.version.trim() === pkg.version) {
+                cachedVersion = pkg.version;
+                return cachedVersion;
+            }
+        }
+        catch {
+            // Source and installed-dist modes resolve through different package ancestors.
+        }
+    }
+    throw new Error("pi-actors package identity is unavailable");
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Pure runtime Control triage policy.
+ * Zones: pending admission, status-age classification, terminal/replacement staleness
+ * Owns Control triage decisions; journal reads and owner filtering stay in adapters, while safe fields come from control-projection.
+ */
+import * as ControlProjection from "./control-projection.ts";
+export declare const RUNTIME_CONTROL_STALE_AFTER_MS: number;
+export interface RuntimeTriageRun {
+    run: string;
+    runInstanceId?: string;
+    status: string;
+}
+export interface RuntimePendingControl extends ControlProjection.ProjectedRunControl {
+    age_ms: number;
+    reason: "age_threshold_reached" | "run_generation_replaced" | "run_generation_unavailable" | "run_terminal" | "within_age_threshold";
+    run: string;
+    status: "queued" | "delivered" | "claimed";
+    status_at: string;
+}
+export interface RuntimeControlDiagnostic {
+    reason: "invalid_action" | "invalid_control_id" | "invalid_generation" | "invalid_record" | "invalid_status" | "invalid_status_timestamp";
+    run: string;
+}
+export interface RuntimeControlClassification {
+    diagnostic?: RuntimeControlDiagnostic;
+    pending?: RuntimePendingControl;
+    stale?: RuntimePendingControl;
+}
+export declare function classifyRuntimeControl(run: RuntimeTriageRun, value: unknown, nowMs: number): RuntimeControlClassification;

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

@@ -0,0 +1,60 @@
+/**
+ * Pure runtime Control triage policy.
+ * Zones: pending admission, status-age classification, terminal/replacement staleness
+ * Owns Control triage decisions; journal reads and owner filtering stay in adapters, while safe fields come from control-projection.
+ */
+import * as ControlProjection from "./control-projection.js";
+import { classifyRunControlRecord, runControlStatusTimestamp, } from "./run-evidence-policy.js";
+export const RUNTIME_CONTROL_STALE_AFTER_MS = 5 * 60 * 1_000;
+function diagnostic(run, reason) {
+    return { diagnostic: { reason, run } };
+}
+export function classifyRuntimeControl(run, value, nowMs) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return diagnostic(run.run, "invalid_record");
+    }
+    const record = value;
+    const status = record.status;
+    const recordClass = classifyRunControlRecord(record);
+    if (!recordClass)
+        return diagnostic(run.run, "invalid_status");
+    if (typeof record.id !== "string" || !record.id) {
+        return diagnostic(run.run, "invalid_control_id");
+    }
+    if (typeof record.action !== "string" || !record.action) {
+        return diagnostic(run.run, "invalid_action");
+    }
+    if (typeof record.run_instance_id !== "string" || !record.run_instance_id) {
+        return diagnostic(run.run, "invalid_generation");
+    }
+    const timestamp = runControlStatusTimestamp(record, status);
+    const timestampMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+    if (!Number.isFinite(timestampMs)) {
+        return diagnostic(run.run, "invalid_status_timestamp");
+    }
+    if (recordClass === "terminal")
+        return {};
+    const ageMs = Math.max(0, Math.floor(nowMs - timestampMs));
+    const staleReason = !run.runInstanceId
+        ? "run_generation_unavailable"
+        : record.run_instance_id !== run.runInstanceId
+            ? "run_generation_replaced"
+            : run.status !== "running"
+                ? "run_terminal"
+                : ageMs >= RUNTIME_CONTROL_STALE_AFTER_MS
+                    ? "age_threshold_reached"
+                    : undefined;
+    const projected = ControlProjection.projectRunControl(record);
+    const pending = {
+        ...projected,
+        age_ms: ageMs,
+        reason: staleReason ?? "within_age_threshold",
+        run: run.run,
+        status: status,
+        status_at: runControlStatusTimestamp(projected, status),
+    };
+    return {
+        pending,
+        ...(staleReason ? { stale: pending } : {}),
+    };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Tool registry runtime coordinator
+ * Zones: runtime coordination, registry loading, pi tools
+ * Owns persisted tool loading, reserved-name guards, runtime registration, and warning notification
+ */
+import { watch } from "node:fs";
+import * as Config from "./config.ts";
+import type { RegisteredToolExec } from "./execution.ts";
+import type { RecipeResolutionContext } from "./recipes-context.ts";
+import * as ToolsLocal from "./tools-local.ts";
+export interface RuntimeContext {
+    hasUI: boolean;
+    ui: {
+        notify(message: string, type?: "info" | "warning" | "error"): void;
+    };
+}
+export interface RuntimeToolActivation {
+    active_tool: boolean;
+    activation: "current_session" | "unverified";
+    callable_now: boolean;
+    host_registered: boolean;
+}
+export interface ToolRegistryRuntimeDeps {
+    configPath: string;
+    exec: RegisteredToolExec;
+    recipeRoot?: string;
+    getActiveTools?: () => string[];
+    getAllTools?: () => Array<{
+        name: string;
+    }>;
+    registerTool: (definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>) => void;
+    reservedToolNames: Set<string>;
+    setActiveTools?: (toolNames: string[]) => void;
+}
+export interface RecipeRegistryStatus {
+    active_tool_count: number;
+    last_scan_counts: {
+        active: number;
+        rejected: number;
+        scanned: number;
+    };
+    last_scan_at?: string;
+    registry_generation: number;
+    resolution_generation?: string;
+    watch_status: "closed" | "failed" | "watching_parent" | "watching_root";
+    watched_root: string;
+}
+export interface ToolRegistryRuntime {
+    getStatus(): RecipeRegistryStatus;
+    getToolStatus(name: string): Record<string, unknown> | undefined;
+    getToolNameBlocker(name: string): string | undefined;
+    getTools(): Map<string, Config.RegisteredTool>;
+    loadTools(ctx: RuntimeContext, resolutionContext?: RecipeResolutionContext): void;
+    notify(ctx: RuntimeContext, message: string, type: "info" | "warning" | "error"): void;
+    registerRuntimeTool(cfg: Config.RegisteredTool): RuntimeToolActivation;
+    setWatchStatus(status: RecipeRegistryStatus["watch_status"]): void;
+}
+export interface RecipeToolReloadWatcher {
+    close(): void;
+    watch(ctx: RuntimeContext): void;
+}
+export declare function createAutoToolsRuntime(deps: ToolRegistryRuntimeDeps): ToolRegistryRuntime;
+export interface RecipeToolReloadWatcherDeps {
+    exists?: (path: string) => boolean;
+    getResolutionContext?: () => RecipeResolutionContext | undefined;
+    recipeRoot?: string;
+    watchPath?: typeof watch;
+}
+export declare function createRecipeToolReloadWatcher(runtime: Pick<ToolRegistryRuntime, "loadTools"> & Partial<Pick<ToolRegistryRuntime, "setWatchStatus">>, deps?: RecipeToolReloadWatcherDeps): RecipeToolReloadWatcher;