@aria-cli/tools 1.0.9 → 1.0.11

package/src/executors/meta.ts

@@ -1,293 +0,0 @@
-/**
- * @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 type { ToolContext, ToolResult, QuestStoreStatus } from "../types.js";
-import { success, fail, getErrorMessage } from "./utils.js";
-
-// ============================================================================
-// Ask User
-// ============================================================================
-
-export interface AskUserInput {
-  questions: Array<{ question: string; options?: string[] }>;
-}
-
-/**
- * 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: unknown): error is Error & {
-  code: "ASK_USER_ANSWERS_EXHAUSTED";
-  questions?: Array<{ question: string; options?: string[] }>;
-} {
-  if (!error || typeof error !== "object") return false;
-  const candidate = error as { code?: unknown; name?: unknown };
-  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(): void {
-  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: AskUserInput, ctx: ToolContext): Promise<ToolResult> {
-  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: Set<string> = new Set(["open", "active", "blocked", "done"]);
-
-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 async function executeQuestUpdate(
-  input: QuestUpdateInput,
-  ctx: ToolContext,
-): Promise<ToolResult> {
-  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: QuestUpdateOutput["quests"] = [];
-  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: Record<string, unknown> = {};
-        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: string[] = [];
-  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 } satisfies QuestUpdateOutput;
-
-  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);
-}
-
-// ============================================================================
-// Quest List
-// ============================================================================
-
-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 async function executeQuestList(
-  input: QuestListInput,
-  ctx: ToolContext,
-): Promise<ToolResult> {
-  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: QuestListOutput["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,
-    } satisfies QuestListOutput);
-  } catch (err) {
-    return fail(getErrorMessage(err));
-  }
-}