@aria-cli/tools 1.0.10 → 1.0.12

package/dist-cjs/executors/meta.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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 type { ToolContext, ToolResult, QuestStoreStatus } from "../types.js";
+export interface AskUserInput {
+    questions: Array<{
+        question: string;
+        options?: string[];
+    }>;
+}
+/**
+ * Reset the ask_user rate limit counter.
+ * Should be called by the runner at the start of each turn.
+ */
+export declare function resetAskUserCounter(): void;
+/**
+ * Prompt the user with one or more questions.
+ * Rate-limited to ASK_USER_MAX_CALLS per turn to prevent abuse loops.
+ */
+export declare function executeAskUser(input: AskUserInput, ctx: ToolContext): Promise<ToolResult>;
+export interface QuestUpdateInput {
+    quests: Array<{
+        id?: string;
+        title?: string;
+        status?: QuestStoreStatus;
+        priority?: number;
+        blocked_by?: string;
+        notes?: string;
+    }>;
+}
+export interface QuestUpdateOutput {
+    quests: Array<{
+        id: string;
+        title: string;
+        status: string;
+        action: "created" | "updated" | "failed";
+        error?: string;
+    }>;
+}
+/**
+ * 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 declare function executeQuestUpdate(input: QuestUpdateInput, ctx: ToolContext): Promise<ToolResult>;
+export interface QuestListInput {
+    status?: "all" | QuestStoreStatus;
+}
+export interface QuestListOutput {
+    quests: Array<{
+        id: string;
+        title: string;
+        status: string;
+        priority: number;
+        blocked_by: string;
+        notes: string;
+        updatedAt: number;
+    }>;
+    count: number;
+}
+/**
+ * List quests from QuestStore with optional status filtering.
+ */
+export declare function executeQuestList(input: QuestListInput, ctx: ToolContext): Promise<ToolResult>;

package/dist-cjs/executors/meta.js

@@ -0,0 +1,226 @@
+"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.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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.
+ */
+export interface TrackedProcessMetadata {
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    interactive?: boolean;
+}
+export interface ProcessExitMetadata {
+    exitCode?: number | null;
+    signal?: string | null;
+}
+export interface ProcessInfoSnapshot {
+    pid: number;
+    command: string | null;
+    args: string[];
+    cwd: string | null;
+    interactive: boolean;
+    startedAt: string;
+    runtimeMs: number;
+    status: "running" | "exited";
+    exitCode: number | null;
+    signal: string | null;
+    endedAt: string | null;
+}
+export interface ProcessWaitResult {
+    pid: number;
+    status: "running" | "exited" | "not_found";
+    timedOut: boolean;
+    process?: ProcessInfoSnapshot;
+}
+/**
+ * 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 declare class SpawnedProcessRegistry {
+    private readonly active;
+    private readonly exited;
+    private readonly waiters;
+    private readonly reapers;
+    /**
+     * Register a spawned process PID.
+     */
+    add(pid: number, metadata?: TrackedProcessMetadata): void;
+    /**
+     * Deregister a process PID (e.g., after normal exit).
+     */
+    remove(pid: number, exit?: ProcessExitMetadata): void;
+    /**
+     * Check whether a PID is tracked.
+     */
+    has(pid: number): boolean;
+    recordExitMetadata(pid: number, exit?: ProcessExitMetadata): void;
+    /**
+     * Number of tracked PIDs.
+     */
+    get size(): number;
+    /**
+     * Return a snapshot of all tracked PIDs.
+     */
+    getAll(): number[];
+    /**
+     * Return process snapshots for observability.
+     */
+    listProcesses(options?: {
+        includeExited?: boolean;
+    }): ProcessInfoSnapshot[];
+    /**
+     * Return a single process snapshot by PID.
+     */
+    getProcess(pid: number): ProcessInfoSnapshot | undefined;
+    /**
+     * Wait for a tracked process to exit, up to timeoutMs.
+     */
+    waitForExit(pid: number, timeoutMs?: number): Promise<ProcessWaitResult>;
+    /**
+     * 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.
+     */
+    killAll(): Promise<number[]>;
+    private toRunningSnapshot;
+    private toExitedSnapshot;
+    private pruneExitedHistory;
+    private ensureReaper;
+    private clearReaper;
+    private reapIfExited;
+}