@aria-cli/tools 1.0.12 → 1.0.13

package/dist-cjs/executors/meta.js

@@ -1,226 +0,0 @@
-"use strict";
-/**
- * @aria/tools - Meta tool executors
- *
- * Implementation of meta operations for ARIA tool system:
- * - ask_user: Interactive user prompting with rate limiting
- * - quest_update: Create/update quests persisted via QuestStore
- * - quest_list: List quests with status filtering
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetAskUserCounter = resetAskUserCounter;
-exports.executeAskUser = executeAskUser;
-exports.executeQuestUpdate = executeQuestUpdate;
-exports.executeQuestList = executeQuestList;
-const nanoid_1 = require("nanoid");
-const utils_js_1 = require("./utils.js");
-/**
- * Module-level ask_user call counter for rate limiting.
- * Reset via resetAskUserCounter() between turns (called by the runner).
- */
-let askUserCallCount = 0;
-const ASK_USER_MAX_CALLS = 3;
-function isAskUserAnswersExhaustedError(error) {
-    if (!error || typeof error !== "object")
-        return false;
-    const candidate = error;
-    return (candidate.code === "ASK_USER_ANSWERS_EXHAUSTED" ||
-        candidate.name === "AskUserAnswersExhaustedError");
-}
-/**
- * Reset the ask_user rate limit counter.
- * Should be called by the runner at the start of each turn.
- */
-function resetAskUserCounter() {
-    askUserCallCount = 0;
-}
-/**
- * Prompt the user with one or more questions.
- * Rate-limited to ASK_USER_MAX_CALLS per turn to prevent abuse loops.
- */
-async function executeAskUser(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return (0, utils_js_1.fail)("Operation cancelled");
-    // Check if user interaction handler is wired
-    if (!ctx.userInteraction) {
-        return (0, utils_js_1.fail)("ask_user not available in this context");
-    }
-    // Rate limit — prefer per-session counter from ToolContext, fall back to module-level global
-    const counter = ctx.askUserCallCounter ?? { count: askUserCallCount };
-    if (counter.count >= ASK_USER_MAX_CALLS) {
-        return (0, utils_js_1.fail)(`Rate limit: max ${ASK_USER_MAX_CALLS} ask_user calls per turn`);
-    }
-    // Validate input
-    if (!input.questions || !Array.isArray(input.questions) || input.questions.length === 0) {
-        return (0, utils_js_1.fail)("questions array is required and must not be empty");
-    }
-    try {
-        const answers = await ctx.userInteraction.ask(input.questions);
-        // Only exhaustion retries are free. A completed prompt attempt, even if it
-        // fails for another reason, still burns the turn-local ask_user budget.
-        counter.count++;
-        if (!ctx.askUserCallCounter)
-            askUserCallCount = counter.count;
-        return (0, utils_js_1.success)(`Received ${answers.length} answer${answers.length === 1 ? "" : "s"} from user`, { answers });
-    }
-    catch (err) {
-        if (isAskUserAnswersExhaustedError(err)) {
-            throw err;
-        }
-        counter.count++;
-        if (!ctx.askUserCallCounter)
-            askUserCallCount = counter.count;
-        return (0, utils_js_1.fail)((0, utils_js_1.getErrorMessage)(err));
-    }
-}
-// ============================================================================
-// Quest Update
-// ============================================================================
-/** Valid quest statuses — used for runtime validation of LLM-provided values */
-const VALID_STATUSES = new Set(["open", "active", "blocked", "done"]);
-/**
- * Create or update quests, persisted via QuestStore (structured SQL storage).
- *
- * New quests get a nanoid-generated ID. Existing quests (with `id`) are updated
- * in-place via QuestStore.updateQuest().
- *
- * Each quest in the batch is processed independently — a failure on one quest
- * does not prevent others from being processed.
- */
-async function executeQuestUpdate(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return (0, utils_js_1.fail)("Operation cancelled");
-    if (!ctx.questStore) {
-        return (0, utils_js_1.fail)("QuestStore is not available — quest persistence requires a database");
-    }
-    if (!input.quests || !Array.isArray(input.quests) || input.quests.length === 0) {
-        return (0, utils_js_1.fail)("quests array is required and must not be empty");
-    }
-    const results = [];
-    let failures = 0;
-    for (const quest of input.quests) {
-        // Runtime status validation — LLM may hallucinate invalid values
-        if (quest.status !== undefined && !VALID_STATUSES.has(quest.status)) {
-            results.push({
-                id: quest.id ?? "unknown",
-                title: quest.title ?? "(untitled)",
-                status: quest.status,
-                action: "failed",
-                error: `Invalid status "${quest.status}" — must be one of: open, active, blocked, done`,
-            });
-            failures++;
-            continue;
-        }
-        const isUpdate = !!quest.id;
-        const questId = quest.id ?? `quest_${(0, nanoid_1.nanoid)(12)}`;
-        try {
-            if (isUpdate) {
-                // Update existing quest — only pass defined fields to avoid overwriting
-                const updates = {};
-                if (quest.title !== undefined)
-                    updates.title = quest.title;
-                if (quest.status !== undefined)
-                    updates.status = quest.status;
-                if (quest.notes !== undefined)
-                    updates.progress = quest.notes;
-                if (quest.priority !== undefined)
-                    updates.priority = quest.priority;
-                if (quest.blocked_by !== undefined)
-                    updates.blockedBy = quest.blocked_by;
-                const updated = ctx.questStore.updateQuest(questId, updates);
-                results.push({
-                    id: questId,
-                    title: updated.title,
-                    status: updated.status,
-                    action: "updated",
-                });
-            }
-            else {
-                // Create new quest — title required, status defaults to "open"
-                if (!quest.title) {
-                    results.push({
-                        id: questId,
-                        title: "(untitled)",
-                        status: quest.status ?? "open",
-                        action: "failed",
-                        error: "title is required when creating a new quest",
-                    });
-                    failures++;
-                    continue;
-                }
-                const created = ctx.questStore.createQuest({
-                    id: questId,
-                    title: quest.title,
-                    status: quest.status ?? "open",
-                    priority: quest.priority ?? 2,
-                    progress: quest.notes,
-                    blockedBy: quest.blocked_by,
-                });
-                results.push({
-                    id: questId,
-                    title: created.title,
-                    status: created.status,
-                    action: "created",
-                });
-            }
-        }
-        catch (err) {
-            results.push({
-                id: questId,
-                title: quest.title ?? "(untitled)",
-                status: quest.status ?? "unknown",
-                action: "failed",
-                error: (0, utils_js_1.getErrorMessage)(err),
-            });
-            failures++;
-        }
-    }
-    const created = results.filter((r) => r.action === "created").length;
-    const updated = results.filter((r) => r.action === "updated").length;
-    const parts = [];
-    if (created > 0)
-        parts.push(`${created} created`);
-    if (updated > 0)
-        parts.push(`${updated} updated`);
-    if (failures > 0)
-        parts.push(`${failures} failed`);
-    const data = { quests: results };
-    if (failures > 0 && failures === input.quests.length) {
-        return (0, utils_js_1.fail)(`All quests failed: ${parts.join(", ")}`, data);
-    }
-    if (failures > 0) {
-        return (0, utils_js_1.success)(`Quests: ${parts.join(", ")} (partial failure)`, data);
-    }
-    return (0, utils_js_1.success)(`Quests: ${parts.join(", ")}`, data);
-}
-/**
- * List quests from QuestStore with optional status filtering.
- */
-async function executeQuestList(input, ctx) {
-    if (ctx.abortSignal?.aborted)
-        return (0, utils_js_1.fail)("Operation cancelled");
-    if (!ctx.questStore) {
-        return (0, utils_js_1.fail)("QuestStore is not available — quest listing requires a database");
-    }
-    try {
-        const statusFilter = input.status ?? "all";
-        const filter = statusFilter !== "all" ? { status: statusFilter } : undefined;
-        const rawQuests = ctx.questStore.listQuests(filter);
-        const quests = rawQuests.map((q) => ({
-            id: q.id,
-            title: q.title,
-            status: q.status,
-            priority: q.priority,
-            blocked_by: q.blockedBy ?? "",
-            notes: q.progress ?? "",
-            updatedAt: q.updatedAt,
-        }));
-        return (0, utils_js_1.success)(`Found ${quests.length} quest${quests.length === 1 ? "" : "s"}`, {
-            quests,
-            count: quests.length,
-        });
-    }
-    catch (err) {
-        return (0, utils_js_1.fail)((0, utils_js_1.getErrorMessage)(err));
-    }
-}

package/dist-cjs/executors/process-registry.js

@@ -1,469 +0,0 @@
-"use strict";
-/**
- * @aria/tools - Spawned Process Registry
- *
- * Tracks PIDs of child processes spawned by shell executors.
- * Allows bulk cleanup (SIGTERM then SIGKILL) when a RunSession closes,
- * preventing orphaned processes from lingering.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SpawnedProcessRegistry = void 0;
-/**
- * How long to wait after SIGTERM before escalating to SIGKILL (ms).
- */
-const SIGKILL_TIMEOUT_MS = 2000;
-const POST_KILL_POLL_INTERVAL_MS = 25;
-const PROCESS_REAP_POLL_INTERVAL_MS = 250;
-/**
- * Max number of exited-process snapshots to retain for observability.
- */
-const EXIT_HISTORY_LIMIT = 100;
-/**
- * Registry that tracks spawned child process PIDs.
- *
- * Usage:
- * - Shell executors call `add(pid)` after spawning a process
- * - Shell executors call `remove(pid)` when a process exits normally
- * - RunSession calls `killAll()` during close() to clean up orphans
- */
-class SpawnedProcessRegistry {
-    active = new Map();
-    exited = new Map();
-    waiters = new Map();
-    reapers = new Map();
-    /**
-     * Register a spawned process PID.
-     */
-    add(pid, metadata = {}) {
-        const existing = this.active.get(pid);
-        if (existing) {
-            this.active.set(pid, {
-                ...existing,
-                command: metadata.command ?? existing.command,
-                args: metadata.args ? [...metadata.args] : existing.args,
-                cwd: metadata.cwd ?? existing.cwd,
-                interactive: metadata.interactive ?? existing.interactive,
-            });
-            return;
-        }
-        const startedAtMs = Date.now();
-        this.active.set(pid, {
-            pid,
-            command: metadata.command ?? null,
-            args: metadata.args ? [...metadata.args] : [],
-            cwd: metadata.cwd ?? null,
-            interactive: metadata.interactive ?? false,
-            reapOnExit: isTrackedProcessAlive(pid),
-            deferredExitCode: null,
-            deferredSignal: null,
-            startedAtMs,
-            startedAt: new Date(startedAtMs).toISOString(),
-        });
-        this.exited.delete(pid);
-        this.ensureReaper(pid);
-    }
-    /**
-     * Deregister a process PID (e.g., after normal exit).
-     */
-    remove(pid, exit = {}) {
-        const record = this.active.get(pid);
-        if (!record) {
-            const exitedRecord = this.exited.get(pid);
-            if (exitedRecord) {
-                this.exited.set(pid, {
-                    ...exitedRecord,
-                    exitCode: exitedRecord.exitCode ?? normalizeExitCode(exit.exitCode),
-                    signal: exitedRecord.exitCode !== null
-                        ? exitedRecord.signal
-                        : (exitedRecord.signal ?? normalizeSignal(exit.signal)),
-                });
-            }
-            return;
-        }
-        this.clearReaper(pid);
-        this.active.delete(pid);
-        const endedAtMs = Date.now();
-        const recordedExitCode = normalizeExitCode(exit.exitCode) ?? record.deferredExitCode;
-        const exitedRecord = {
-            ...record,
-            exitCode: recordedExitCode,
-            signal: record.deferredSignal ?? normalizeSignal(exit.signal),
-            endedAtMs,
-            endedAt: new Date(endedAtMs).toISOString(),
-        };
-        this.exited.set(pid, exitedRecord);
-        this.pruneExitedHistory();
-        const waiters = this.waiters.get(pid);
-        if (waiters && waiters.length > 0) {
-            this.waiters.delete(pid);
-            for (const waiter of waiters) {
-                waiter(exitedRecord);
-            }
-        }
-    }
-    /**
-     * Check whether a PID is tracked.
-     */
-    has(pid) {
-        return this.active.has(pid);
-    }
-    recordExitMetadata(pid, exit = {}) {
-        const record = this.active.get(pid);
-        if (!record) {
-            return;
-        }
-        record.deferredExitCode = normalizeExitCode(exit.exitCode);
-        record.deferredSignal = normalizeSignal(exit.signal);
-    }
-    /**
-     * Number of tracked PIDs.
-     */
-    get size() {
-        return this.active.size;
-    }
-    /**
-     * Return a snapshot of all tracked PIDs.
-     */
-    getAll() {
-        return [...this.active.keys()];
-    }
-    /**
-     * Return process snapshots for observability.
-     */
-    listProcesses(options = {}) {
-        const now = Date.now();
-        const snapshots = [];
-        for (const pid of [...this.active.keys()]) {
-            this.reapIfExited(pid);
-        }
-        for (const record of this.active.values()) {
-            snapshots.push(this.toRunningSnapshot(record, now));
-        }
-        if (options.includeExited) {
-            for (const record of this.exited.values()) {
-                snapshots.push(this.toExitedSnapshot(record));
-            }
-        }
-        return snapshots.sort((a, b) => a.pid - b.pid);
-    }
-    /**
-     * Return a single process snapshot by PID.
-     */
-    getProcess(pid) {
-        this.reapIfExited(pid);
-        const activeRecord = this.active.get(pid);
-        if (activeRecord) {
-            return this.toRunningSnapshot(activeRecord);
-        }
-        const exitedRecord = this.exited.get(pid);
-        if (exitedRecord) {
-            return this.toExitedSnapshot(exitedRecord);
-        }
-        return undefined;
-    }
-    /**
-     * Wait for a tracked process to exit, up to timeoutMs.
-     */
-    async waitForExit(pid, timeoutMs = 30_000) {
-        this.reapIfExited(pid);
-        const exitedRecord = this.exited.get(pid);
-        if (exitedRecord) {
-            return {
-                pid,
-                status: "exited",
-                timedOut: false,
-                process: this.toExitedSnapshot(exitedRecord),
-            };
-        }
-        const activeRecord = this.active.get(pid);
-        if (!activeRecord) {
-            return {
-                pid,
-                status: "not_found",
-                timedOut: false,
-            };
-        }
-        if (timeoutMs <= 0) {
-            return {
-                pid,
-                status: "running",
-                timedOut: true,
-                process: this.toRunningSnapshot(activeRecord),
-            };
-        }
-        return new Promise((resolve) => {
-            let settled = false;
-            const settle = (result) => {
-                if (settled)
-                    return;
-                settled = true;
-                resolve(result);
-            };
-            const removeWaiter = (target) => {
-                const existing = this.waiters.get(pid);
-                if (!existing)
-                    return;
-                const next = existing.filter((entry) => entry !== target);
-                if (next.length === 0) {
-                    this.waiters.delete(pid);
-                }
-                else {
-                    this.waiters.set(pid, next);
-                }
-            };
-            const waiter = (record) => {
-                clearTimeout(timeoutId);
-                removeWaiter(waiter);
-                settle({
-                    pid,
-                    status: "exited",
-                    timedOut: false,
-                    process: this.toExitedSnapshot(record),
-                });
-            };
-            const timeoutId = setTimeout(() => {
-                const current = this.active.get(pid);
-                if (current) {
-                    removeWaiter(waiter);
-                    settle({
-                        pid,
-                        status: "running",
-                        timedOut: true,
-                        process: this.toRunningSnapshot(current),
-                    });
-                    return;
-                }
-                const exited = this.exited.get(pid);
-                if (exited) {
-                    removeWaiter(waiter);
-                    settle({
-                        pid,
-                        status: "exited",
-                        timedOut: false,
-                        process: this.toExitedSnapshot(exited),
-                    });
-                    return;
-                }
-                removeWaiter(waiter);
-                settle({
-                    pid,
-                    status: "not_found",
-                    timedOut: false,
-                });
-            }, timeoutMs);
-            const existingWaiters = this.waiters.get(pid) ?? [];
-            existingWaiters.push(waiter);
-            this.waiters.set(pid, existingWaiters);
-            // Close the race window where remove() can happen between the initial
-            // active check above and waiter registration.
-            const exitedAfterRegistration = this.exited.get(pid);
-            if (exitedAfterRegistration) {
-                clearTimeout(timeoutId);
-                removeWaiter(waiter);
-                settle({
-                    pid,
-                    status: "exited",
-                    timedOut: false,
-                    process: this.toExitedSnapshot(exitedAfterRegistration),
-                });
-                return;
-            }
-            if (!this.active.has(pid)) {
-                clearTimeout(timeoutId);
-                removeWaiter(waiter);
-                settle({
-                    pid,
-                    status: "not_found",
-                    timedOut: false,
-                });
-            }
-        });
-    }
-    /**
-     * Send SIGTERM to all tracked PIDs, then SIGKILL after a timeout
-     * for any that are still alive. Clears the registry afterwards.
-     *
-     * Returns the list of PIDs that were signalled.
-     */
-    async killAll() {
-        const tracked = [...this.active.keys()];
-        if (tracked.length === 0)
-            return [];
-        // Phase 1: SIGTERM all tracked processes
-        const alive = [];
-        const signaledTerm = new Set();
-        for (const pid of tracked) {
-            if (isTrackedProcessAlive(pid)) {
-                if (sendSignalToTrackedProcess(pid, "SIGTERM")) {
-                    alive.push(pid);
-                    signaledTerm.add(pid);
-                }
-            }
-        }
-        if (alive.length === 0) {
-            for (const pid of tracked) {
-                this.remove(pid);
-            }
-            return tracked;
-        }
-        // Phase 2: Wait, then SIGKILL any survivors
-        await new Promise((resolve) => setTimeout(resolve, SIGKILL_TIMEOUT_MS));
-        const signaledKill = new Set();
-        for (const pid of alive) {
-            if (isTrackedProcessAlive(pid)) {
-                if (sendSignalToTrackedProcess(pid, "SIGKILL")) {
-                    signaledKill.add(pid);
-                }
-            }
-        }
-        await waitForProcessesToExit([...signaledKill], SIGKILL_TIMEOUT_MS);
-        for (const pid of tracked) {
-            this.remove(pid, {
-                signal: signaledKill.has(pid) ? "SIGKILL" : signaledTerm.has(pid) ? "SIGTERM" : null,
-            });
-        }
-        return tracked;
-    }
-    toRunningSnapshot(record, now = Date.now()) {
-        return {
-            pid: record.pid,
-            command: record.command,
-            args: [...record.args],
-            cwd: record.cwd,
-            interactive: record.interactive,
-            startedAt: record.startedAt,
-            runtimeMs: Math.max(0, now - record.startedAtMs),
-            status: "running",
-            exitCode: null,
-            signal: null,
-            endedAt: null,
-        };
-    }
-    toExitedSnapshot(record) {
-        return {
-            pid: record.pid,
-            command: record.command,
-            args: [...record.args],
-            cwd: record.cwd,
-            interactive: record.interactive,
-            startedAt: record.startedAt,
-            runtimeMs: Math.max(0, record.endedAtMs - record.startedAtMs),
-            status: "exited",
-            exitCode: record.exitCode,
-            signal: record.signal,
-            endedAt: record.endedAt,
-        };
-    }
-    pruneExitedHistory() {
-        while (this.exited.size > EXIT_HISTORY_LIMIT) {
-            const oldestPid = this.exited.keys().next().value;
-            if (oldestPid === undefined) {
-                break;
-            }
-            this.exited.delete(oldestPid);
-        }
-    }
-    ensureReaper(pid) {
-        if (!this.active.get(pid)?.reapOnExit) {
-            return;
-        }
-        if (this.reapers.has(pid)) {
-            return;
-        }
-        const timer = setInterval(() => {
-            this.reapIfExited(pid);
-        }, PROCESS_REAP_POLL_INTERVAL_MS);
-        timer.unref?.();
-        this.reapers.set(pid, timer);
-    }
-    clearReaper(pid) {
-        const timer = this.reapers.get(pid);
-        if (!timer) {
-            return;
-        }
-        clearInterval(timer);
-        this.reapers.delete(pid);
-    }
-    reapIfExited(pid) {
-        const record = this.active.get(pid);
-        if (!record) {
-            this.clearReaper(pid);
-            return false;
-        }
-        if (!record.reapOnExit) {
-            return false;
-        }
-        if (isTrackedProcessAlive(pid)) {
-            return false;
-        }
-        this.remove(pid);
-        return true;
-    }
-}
-exports.SpawnedProcessRegistry = SpawnedProcessRegistry;
-/**
- * Check whether a process is still alive by sending signal 0.
- */
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function isTrackedProcessAlive(pid) {
-    if (pid > 0) {
-        try {
-            process.kill(-pid, 0);
-            return true;
-        }
-        catch {
-            // Fall back to the tracked pid itself when the process group is gone or unsupported.
-        }
-    }
-    return isProcessAlive(pid);
-}
-function sendSignalToTrackedProcess(pid, signal) {
-    try {
-        if (pid > 0) {
-            process.kill(-pid, signal);
-            return true;
-        }
-    }
-    catch {
-        // Fall back to the tracked pid itself when there is no process group to target.
-    }
-    try {
-        process.kill(pid, signal);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function waitForProcessesToExit(pids, timeoutMs) {
-    if (pids.length === 0) {
-        return;
-    }
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if (pids.every((pid) => !isTrackedProcessAlive(pid))) {
-            return;
-        }
-        await new Promise((resolve) => setTimeout(resolve, POST_KILL_POLL_INTERVAL_MS));
-    }
-}
-function normalizeExitCode(value) {
-    if (typeof value !== "number" || Number.isNaN(value)) {
-        return null;
-    }
-    return value;
-}
-function normalizeSignal(value) {
-    if (typeof value !== "string" || value.length === 0) {
-        return null;
-    }
-    return value;
-}