@aria-cli/tools 1.0.19 → 1.0.31

package/dist/executors/meta.js

@@ -0,0 +1,221 @@
+/**
+ * @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
+ */
+import { nanoid } from "nanoid";
+import { success, fail, getErrorMessage } from "./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.
+ */
+export 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.
+ */
+export async function executeAskUser(input, ctx) {
+    if (ctx.abortSignal?.aborted)
+        return fail("Operation cancelled");
+    // Check if user interaction handler is wired
+    if (!ctx.userInteraction) {
+        return 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 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 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 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 fail(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.
+ */
+export async function executeQuestUpdate(input, ctx) {
+    if (ctx.abortSignal?.aborted)
+        return fail("Operation cancelled");
+    if (!ctx.questStore) {
+        return fail("QuestStore is not available — quest persistence requires a database");
+    }
+    if (!input.quests || !Array.isArray(input.quests) || input.quests.length === 0) {
+        return 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_${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: 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 fail(`All quests failed: ${parts.join(", ")}`, data);
+    }
+    if (failures > 0) {
+        return success(`Quests: ${parts.join(", ")} (partial failure)`, data);
+    }
+    return success(`Quests: ${parts.join(", ")}`, data);
+}
+/**
+ * List quests from QuestStore with optional status filtering.
+ */
+export async function executeQuestList(input, ctx) {
+    if (ctx.abortSignal?.aborted)
+        return fail("Operation cancelled");
+    if (!ctx.questStore) {
+        return 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 success(`Found ${quests.length} quest${quests.length === 1 ? "" : "s"}`, {
+            quests,
+            count: quests.length,
+        });
+    }
+    catch (err) {
+        return fail(getErrorMessage(err));
+    }
+}
+//# sourceMappingURL=meta.js.map

package/dist/executors/process-registry.js

@@ -0,0 +1,466 @@
+/**
+ * @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.
+ */
+/**
+ * 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
+ */
+export 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;
+    }
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=process-registry.js.map