@aria-cli/tools 1.0.0

package/src/executors/session-history.ts

@@ -0,0 +1,435 @@
+/**
+ * @aria/tools - Session History tool executor
+ *
+ * Implementation of session history operations for ARIA tool system.
+ * Provides list, search, get, current, stats, delete, and set_title actions
+ * against the SessionHistory SQLite database.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import type {
+  ToolContext,
+  ToolResult,
+  SessionHistoryRef,
+  SessionSummaryRef,
+  SessionContextRef,
+} from "../types.js";
+import { success, fail, getErrorMessage } from "./utils.js";
+
+// ============================================================================
+// Input / Output Types
+// ============================================================================
+
+export type SessionHistoryAction =
+  | "list"
+  | "search"
+  | "get"
+  | "current"
+  | "stats"
+  | "delete"
+  | "set_title";
+
+export interface SessionHistoryInput {
+  /** Action to perform */
+  action: SessionHistoryAction;
+  /** Search query (for 'search' action) */
+  query?: string;
+  /** Session ID or prefix (for 'get', 'delete', 'set_title') */
+  sessionId?: string;
+  /** New title (for 'set_title' action) */
+  title?: string;
+  /** Max results (default 20) */
+  limit?: number;
+  /** Pagination offset (default 0) */
+  offset?: number;
+  /** Max messages to return per session (for 'get', default 50) */
+  messageLimit?: number;
+}
+
+export interface SessionListOutput {
+  sessions: Array<{
+    id: string;
+    title: string | null;
+    arion: string;
+    model: string;
+    messageCount: number;
+    updatedAt: string;
+    completedAt?: string;
+    preview: string;
+  }>;
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+export interface SessionGetOutput {
+  id: string;
+  arion: string;
+  model: string;
+  messageCount: number;
+  messages: Array<{
+    role: string;
+    content: string;
+    createdAt: string;
+    toolCallId?: string;
+  }>;
+  metrics?: Array<{
+    turnCount?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    estimatedCost?: number;
+    wallTimeMs?: number;
+  }>;
+}
+
+export interface SessionCurrentOutput {
+  sessionId: string;
+}
+
+export interface SessionStatsOutput {
+  totalSessions: number;
+  incompleteSessions: number;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Max content length per message in 'get' output to prevent context blowout */
+const MAX_MESSAGE_CONTENT_LENGTH = 2000;
+
+/**
+ * Cached fallback SessionHistory instance — created once per process via
+ * dynamic import of @aria/cli's SessionHistory class.  This avoids a hard
+ * package dependency (tools → cli) while still giving the tool access to
+ * the real SQLite history DB when ctx.sessionHistory isn't wired through.
+ */
+/** Cached fallback SessionHistory — resolved once per process via dynamic import. */
+let _fallbackSessionHistory: SessionHistoryRef | null | undefined;
+let _fallbackPromise: Promise<SessionHistoryRef | null> | null = null;
+
+async function resolveFallbackSessionHistory(): Promise<SessionHistoryRef | null> {
+  if (_fallbackSessionHistory !== undefined) return _fallbackSessionHistory;
+  if (_fallbackPromise) return _fallbackPromise;
+
+  _fallbackPromise = (async () => {
+    try {
+      // Dynamic import of @aria/cli (optionalDependency, ESM-only).
+      // Using a variable prevents TS from resolving the specifier statically
+      // and from downleveling to require() in CJS output.
+      const _specifier = "@aria/cli";
+      const mod = (await import(_specifier)) as {
+        SessionHistory: {
+          resolvePerArionPath(ariaDir: string, arionName: string): string;
+          new (dbPath: string): SessionHistoryRef;
+        };
+      };
+      const SessionHistory = mod.SessionHistory;
+      const ariaHome = process.env.ARIA_HOME ?? path.join(os.homedir(), ".aria");
+      // Determine active arion from config or default to "ARIA"
+      let arionName = "ARIA";
+      try {
+        const { readFileSync, existsSync } = await import("node:fs");
+        const configPath = path.join(ariaHome, "config.json");
+        if (existsSync(configPath)) {
+          const raw = JSON.parse(readFileSync(configPath, "utf-8")) as { activeArion?: string };
+          if (raw.activeArion) arionName = raw.activeArion;
+        }
+      } catch {
+        // Ignore config read errors
+      }
+      const dbPath = SessionHistory.resolvePerArionPath(ariaHome, arionName);
+      _fallbackSessionHistory = new SessionHistory(dbPath);
+      return _fallbackSessionHistory;
+    } catch {
+      // @aria/cli not available (e.g. isolated worker) — no fallback
+      _fallbackSessionHistory = null;
+      return null;
+    }
+  })();
+  return _fallbackPromise;
+}
+
+/**
+ * Get the SessionHistoryRef — from ToolContext if wired, otherwise create
+ * a fallback instance by dynamically importing @aria/cli's SessionHistory.
+ */
+export async function getSessionHistory(ctx: ToolContext): Promise<SessionHistoryRef | null> {
+  if (ctx.sessionHistory) return ctx.sessionHistory;
+  return resolveFallbackSessionHistory();
+}
+
+function formatSessions(sessions: SessionSummaryRef[]): SessionListOutput["sessions"] {
+  return sessions.map((s) => ({
+    id: s.id,
+    title: s.title,
+    arion: s.arion,
+    model: s.model,
+    messageCount: s.messageCount,
+    updatedAt: s.updatedAt.toISOString(),
+    completedAt: s.completedAt?.toISOString(),
+    preview: s.preview,
+  }));
+}
+
+function truncateContent(content: string, max: number): string {
+  if (content.length <= max) return content;
+  return content.slice(0, max - 3) + "...";
+}
+
+function resolveSessionId(sh: SessionHistoryRef, rawId: string): string | null {
+  // Try exact match first (full UUID), then prefix
+  if (rawId.length === 36) {
+    const session = sh.getSession(rawId);
+    return session ? rawId : null;
+  }
+  return sh.findSessionByPrefix(rawId);
+}
+
+// ============================================================================
+// Main Executor
+// ============================================================================
+
+/**
+ * Execute a session_history action.
+ */
+export async function executeSessionHistory(
+  input: SessionHistoryInput,
+  ctx: ToolContext,
+): Promise<ToolResult> {
+  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
+
+  if (!input.action) {
+    return fail(
+      "action is required. Valid actions: list, search, get, current, stats, delete, set_title",
+    );
+  }
+
+  const sh = await getSessionHistory(ctx);
+  if (!sh) {
+    return fail("Session history is not available in this context");
+  }
+
+  try {
+    switch (input.action) {
+      case "list":
+        return executeList(input, sh);
+      case "search":
+        return executeSearch(input, sh);
+      case "get":
+        return executeGet(input, sh);
+      case "current":
+        return executeCurrent(ctx, sh);
+      case "stats":
+        return executeStats(sh);
+      case "delete":
+        return executeDelete(input, sh);
+      case "set_title":
+        return executeSetTitle(input, sh);
+      default:
+        return fail(
+          `Unknown action "${input.action}". Valid actions: list, search, get, current, stats, delete, set_title`,
+        );
+    }
+  } catch (err) {
+    return fail(getErrorMessage(err));
+  }
+}
+
+// ============================================================================
+// Action Implementations
+// ============================================================================
+
+function executeList(input: SessionHistoryInput, sh: SessionHistoryRef): ToolResult {
+  const limit = input.limit ?? 20;
+  const offset = input.offset ?? 0;
+  const sessions = sh.listSessions(limit, offset);
+  const formatted = formatSessions(sessions);
+
+  const output: SessionListOutput = {
+    sessions: formatted,
+    total: formatted.length,
+    limit,
+    offset,
+  };
+
+  if (formatted.length === 0) {
+    return success("No sessions found", output);
+  }
+
+  const summaryLines = formatted.map(
+    (s) =>
+      `• ${s.id.slice(0, 8)}… | ${s.title || "(untitled)"} | ${s.messageCount} msgs | ${s.arion} | ${s.updatedAt.slice(0, 10)}`,
+  );
+
+  return success(`Found ${formatted.length} session(s):\n${summaryLines.join("\n")}`, output);
+}
+
+function executeSearch(input: SessionHistoryInput, sh: SessionHistoryRef): ToolResult {
+  if (!input.query || input.query.trim() === "") {
+    return fail("query is required for 'search' action");
+  }
+
+  const limit = input.limit ?? 20;
+  const offset = input.offset ?? 0;
+  const sessions = sh.searchSessionsFts(input.query, limit, offset);
+  const formatted = formatSessions(sessions);
+
+  const output: SessionListOutput = {
+    sessions: formatted,
+    total: formatted.length,
+    limit,
+    offset,
+  };
+
+  if (formatted.length === 0) {
+    return success(`No sessions found matching "${input.query}"`, output);
+  }
+
+  const summaryLines = formatted.map(
+    (s) =>
+      `• ${s.id.slice(0, 8)}… | ${s.title || "(untitled)"} | ${s.messageCount} msgs | ${s.arion} | ${s.updatedAt.slice(0, 10)}`,
+  );
+
+  return success(
+    `Found ${formatted.length} session(s) matching "${input.query}":\n${summaryLines.join("\n")}`,
+    output,
+  );
+}
+
+function executeGet(input: SessionHistoryInput, sh: SessionHistoryRef): ToolResult {
+  if (!input.sessionId || input.sessionId.trim() === "") {
+    return fail("sessionId is required for 'get' action");
+  }
+
+  const resolvedId = resolveSessionId(sh, input.sessionId);
+  if (!resolvedId) {
+    return fail(`Session not found for ID/prefix "${input.sessionId}"`);
+  }
+
+  const session: SessionContextRef | null = sh.getSession(resolvedId);
+  if (!session) {
+    return fail(`Session ${resolvedId} not found`);
+  }
+
+  const messageLimit = input.messageLimit ?? 50;
+
+  // Take the last N messages to avoid context blowout
+  const messagesSlice = session.messages.slice(-messageLimit);
+  const formattedMessages = messagesSlice.map((m) => ({
+    role: m.role,
+    content: truncateContent(m.content, MAX_MESSAGE_CONTENT_LENGTH),
+    createdAt: m.createdAt.toISOString(),
+    toolCallId: m.toolCallId,
+  }));
+
+  // Also fetch metrics if available (getRunMetrics may not exist on all impls)
+  let metrics: SessionGetOutput["metrics"];
+  try {
+    const rawMetrics = sh.getRunMetrics?.(resolvedId) ?? [];
+    metrics =
+      rawMetrics.length > 0
+        ? rawMetrics.map((rm) => ({
+            turnCount: rm.turnCount,
+            inputTokens: rm.inputTokens,
+            outputTokens: rm.outputTokens,
+            estimatedCost: rm.estimatedCost,
+            wallTimeMs: rm.wallTimeMs,
+          }))
+        : undefined;
+  } catch {
+    // Non-critical — metrics may not be available
+  }
+
+  const output: SessionGetOutput = {
+    id: session.id,
+    arion: session.arion,
+    model: session.model,
+    messageCount: session.messages.length,
+    messages: formattedMessages,
+    metrics,
+  };
+
+  const truncNote =
+    session.messages.length > messageLimit
+      ? ` (showing last ${messageLimit} of ${session.messages.length})`
+      : "";
+
+  return success(
+    `Session ${session.id.slice(0, 8)}… | ${session.arion} | ${session.model} | ${session.messages.length} messages${truncNote}`,
+    output,
+  );
+}
+
+function executeCurrent(ctx: ToolContext, sh: SessionHistoryRef): ToolResult {
+  if (!ctx.currentSessionId) {
+    return fail("No current session ID available");
+  }
+
+  const output: SessionCurrentOutput = {
+    sessionId: ctx.currentSessionId,
+  };
+
+  // Try to get session details if available
+  const session = sh.getSession(ctx.currentSessionId);
+  if (session) {
+    return success(
+      `Current session: ${session.id.slice(0, 8)}… | ${session.arion} | ${session.model} | ${session.messages.length} messages`,
+      {
+        ...output,
+        arion: session.arion,
+        model: session.model,
+        messageCount: session.messages.length,
+      },
+    );
+  }
+
+  return success(`Current session: ${ctx.currentSessionId}`, output);
+}
+
+function executeStats(sh: SessionHistoryRef): ToolResult {
+  const totalSessions = sh.getSessionCount?.() ?? 0;
+  const incompleteSessions = (sh.getIncompleteSessions?.(1000) ?? []).length;
+
+  const output: SessionStatsOutput = {
+    totalSessions,
+    incompleteSessions,
+  };
+
+  return success(
+    `Session stats: ${totalSessions} total, ${incompleteSessions} incomplete, ${totalSessions - incompleteSessions} completed`,
+    output,
+  );
+}
+
+function executeDelete(input: SessionHistoryInput, sh: SessionHistoryRef): ToolResult {
+  if (!input.sessionId || input.sessionId.trim() === "") {
+    return fail("sessionId is required for 'delete' action");
+  }
+
+  const resolvedId = resolveSessionId(sh, input.sessionId);
+  if (!resolvedId) {
+    return fail(`Session not found for ID/prefix "${input.sessionId}"`);
+  }
+
+  sh.deleteSession(resolvedId);
+  return success(`Deleted session ${resolvedId}`);
+}
+
+function executeSetTitle(input: SessionHistoryInput, sh: SessionHistoryRef): ToolResult {
+  if (!input.sessionId || input.sessionId.trim() === "") {
+    return fail("sessionId is required for 'set_title' action");
+  }
+  if (!input.title || input.title.trim() === "") {
+    return fail("title is required for 'set_title' action");
+  }
+
+  const resolvedId = resolveSessionId(sh, input.sessionId);
+  if (!resolvedId) {
+    return fail(`Session not found for ID/prefix "${input.sessionId}"`);
+  }
+
+  sh.setSessionTitle(resolvedId, input.title);
+  return success(`Set title of session ${resolvedId.slice(0, 8)}… to "${input.title}"`);
+}