@agentex/agent 0.0.23 → 0.0.26

package/src/providers/codex/usage-scanner.ts

@@ -0,0 +1,178 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as readline from "node:readline";
+import { createReadStream } from "node:fs";
+import type { TokenUsage } from "../../types.js";
+
+// ---------------------------------------------------------------------------
+// Log path resolution
+// ---------------------------------------------------------------------------
+
+function getCodexHome(): string {
+  return process.env["CODEX_HOME"] || path.join(os.homedir(), ".codex");
+}
+
+/**
+ * Find session log files that may contain usage data for a given time range.
+ * Codex stores logs at: `CODEX_HOME/sessions/YYYY/MM/DD/*.jsonl`
+ */
+async function findLogFiles(startedAfter: Date): Promise<string[]> {
+  const sessionsDir = path.join(getCodexHome(), "sessions");
+  const files: string[] = [];
+
+  // Walk date-partitioned directories starting from the startedAfter date
+  const startDate = new Date(startedAfter);
+  const now = new Date();
+
+  for (let d = new Date(startDate); d <= now; d.setDate(d.getDate() + 1)) {
+    const year = String(d.getFullYear());
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    const dayDir = path.join(sessionsDir, year, month, day);
+
+    try {
+      const entries = await fs.readdir(dayDir);
+      for (const entry of entries) {
+        if (entry.endsWith(".jsonl")) {
+          files.push(path.join(dayDir, entry));
+        }
+      }
+    } catch {
+      // Directory doesn't exist — skip
+    }
+  }
+
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// JSONL scanning
+// ---------------------------------------------------------------------------
+
+interface ScanOptions {
+  /** Only include events after this timestamp */
+  startedAfter: Date;
+  /** Optional thread ID to filter by */
+  threadId?: string;
+}
+
+/**
+ * Scan Codex session log files for token usage events and aggregate them.
+ *
+ * Codex logs `token_count` events in session JSONL files with fields like
+ * `InputTokens`, `OutputTokens`, `CachedInputTokens`, `CacheReadInputTokens`.
+ *
+ * Returns aggregated usage keyed by model name, or null if no usage found.
+ */
+export async function scanCodexSessionUsage(
+  options: ScanOptions,
+): Promise<Record<string, TokenUsage> | undefined> {
+  const logFiles = await findLogFiles(options.startedAfter);
+  if (logFiles.length === 0) return undefined;
+
+  const usageByModel = new Map<string, {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    cacheCreationInputTokens: number;
+  }>();
+
+  for (const file of logFiles) {
+    await scanFile(file, options, usageByModel);
+  }
+
+  if (usageByModel.size === 0) return undefined;
+
+  const result: Record<string, TokenUsage> = {};
+  for (const [model, usage] of usageByModel) {
+    const entry: TokenUsage = {
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+    };
+    if (usage.cachedInputTokens > 0) entry.cachedInputTokens = usage.cachedInputTokens;
+    if (usage.cacheCreationInputTokens > 0) entry.cacheCreationInputTokens = usage.cacheCreationInputTokens;
+    result[model] = entry;
+  }
+  return result;
+}
+
+async function scanFile(
+  filePath: string,
+  options: ScanOptions,
+  usageByModel: Map<string, { inputTokens: number; outputTokens: number; cachedInputTokens: number; cacheCreationInputTokens: number }>,
+): Promise<void> {
+  let stream: ReturnType<typeof createReadStream>;
+  try {
+    stream = createReadStream(filePath, { encoding: "utf-8" });
+  } catch {
+    return;
+  }
+
+  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+
+  try {
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      let parsed: Record<string, unknown>;
+      try {
+        parsed = JSON.parse(trimmed);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) continue;
+      } catch {
+        continue;
+      }
+
+      const type = typeof parsed["type"] === "string" ? parsed["type"] : "";
+      if (type !== "token_count") continue;
+
+      // Check timestamp
+      const ts = typeof parsed["timestamp"] === "string" ? parsed["timestamp"]
+        : typeof parsed["created_at"] === "string" ? parsed["created_at"]
+        : null;
+      if (ts) {
+        const eventTime = new Date(ts);
+        if (eventTime < options.startedAfter) continue;
+      }
+
+      // Check thread ID filter
+      if (options.threadId) {
+        const eventThreadId = typeof parsed["thread_id"] === "string" ? parsed["thread_id"]
+          : typeof parsed["threadId"] === "string" ? parsed["threadId"]
+          : null;
+        if (eventThreadId && eventThreadId !== options.threadId) continue;
+      }
+
+      // Extract usage
+      const model = typeof parsed["model"] === "string" ? parsed["model"] : "unknown";
+      const inputTokens = typeof parsed["InputTokens"] === "number" ? parsed["InputTokens"]
+        : typeof parsed["input_tokens"] === "number" ? parsed["input_tokens"]
+        : 0;
+      const outputTokens = typeof parsed["OutputTokens"] === "number" ? parsed["OutputTokens"]
+        : typeof parsed["output_tokens"] === "number" ? parsed["output_tokens"]
+        : 0;
+      const cachedInputTokens = typeof parsed["CacheReadInputTokens"] === "number" ? parsed["CacheReadInputTokens"]
+        : typeof parsed["cached_input_tokens"] === "number" ? parsed["cached_input_tokens"]
+        : 0;
+      const cacheCreationInputTokens = typeof parsed["CachedInputTokens"] === "number" ? parsed["CachedInputTokens"]
+        : typeof parsed["cache_creation_input_tokens"] === "number" ? parsed["cache_creation_input_tokens"]
+        : 0;
+
+      const existing = usageByModel.get(model) ?? {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedInputTokens: 0,
+        cacheCreationInputTokens: 0,
+      };
+      existing.inputTokens += inputTokens;
+      existing.outputTokens += outputTokens;
+      existing.cachedInputTokens += cachedInputTokens;
+      existing.cacheCreationInputTokens += cacheCreationInputTokens;
+      usageByModel.set(model, existing);
+    }
+  } finally {
+    rl.close();
+    stream.destroy();
+  }
+}

package/src/providers/copilot/index.ts

@@ -0,0 +1,19 @@
+import { acpProvider } from "../acp/index.js";
+
+/**
+ * GitHub Copilot CLI via the Agent Client Protocol (`copilot --acp`). Copilot
+ * handles its own GitHub auth.
+ *
+ * Adding Copilot is the whole point of the ACP tier — it's a handful of lines
+ * because the ACP base does the work (sessions, streaming, tool-call
+ * correlation, permission bridging, mode discovery).
+ *
+ * NOTE: Copilot also exposes an "allow-all" approval mode through an ACP
+ * `setSessionConfigOption` (distinct from `setSessionMode`). Fully surfacing it
+ * would need a config-option transformer hook (future work); the standard
+ * mode + permission flow works today.
+ */
+export const copilotProvider = acpProvider({
+  id: "copilot",
+  command: ["copilot", "--acp"],
+});

package/src/providers/cursor/codec.ts

@@ -0,0 +1,44 @@
+import type { SessionCodec } from "../../types.js";
+
+function readNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function parseAsObject(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  return raw as Record<string, unknown>;
+}
+
+export const cursorSessionCodec: SessionCodec = {
+  deserialize(raw: unknown): Record<string, unknown> | null {
+    const obj = parseAsObject(raw);
+    if (!obj) return null;
+    const sessionId =
+      readNonEmptyString(obj["sessionId"]) ??
+      readNonEmptyString(obj["session_id"]);
+    if (!sessionId) return null;
+    const cwd = readNonEmptyString(obj["cwd"]);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+    };
+  },
+
+  serialize(params: Record<string, unknown> | null): Record<string, unknown> | null {
+    if (!params) return null;
+    const sessionId =
+      readNonEmptyString(params["sessionId"]) ??
+      readNonEmptyString(params["session_id"]);
+    if (!sessionId) return null;
+    const cwd = readNonEmptyString(params["cwd"]);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+    };
+  },
+
+  getDisplayId(params: Record<string, unknown> | null): string | null {
+    if (!params) return null;
+    return readNonEmptyString(params["sessionId"]) ?? readNonEmptyString(params["session_id"]);
+  },
+};

package/src/providers/cursor/execute.ts

@@ -0,0 +1,271 @@
+import * as path from "node:path";
+import type { ExecutionContext, ExecutionResult } from "../../types.js";
+import { findBinary } from "../../utils/binary.js";
+import { buildEnv, ensurePathInEnv } from "../../utils/env.js";
+import { runChildProcess, deriveErrorCode } from "../../utils/process.js";
+import { detectAuth } from "../../utils/auth.js";
+import { injectHomeSkills } from "../../utils/skills.js";
+import { resolveInstructions } from "../../utils/instructions.js";
+import { prepareWorkspace } from "../../utils/workspace.js";
+import type { PreparedWorkspace } from "../../utils/workspace.js";
+import { uuidv7 } from "../../utils/uuid.js";
+import {
+  parseCursorJsonl,
+  parseCursorStreamLine,
+  normalizeCursorStreamLine,
+  isCursorUnknownSessionError,
+  isCursorAuthRequired,
+} from "./parse.js";
+
+export async function executeCursorProvider(ctx: ExecutionContext): Promise<ExecutionResult> {
+  const runId = ctx.runId ?? uuidv7();
+  let cwd = ctx.cwd ?? process.cwd();
+  const model = ctx.model ?? ctx.config?.model ?? "";
+  const config = ctx.config ?? {};
+  const startedAt = new Date().toISOString();
+
+  // 1. Resolve binary
+  ctx.onLifecycle?.({ phase: "preparing", step: "binary" });
+  let resolvedBinary;
+  try {
+    resolvedBinary = await findBinary("agent", config.command);
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : "Binary not found";
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage });
+    return {
+      runId,
+      exitCode: null,
+      signal: null,
+      status: "failed" as const,
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - new Date(startedAt).getTime(),
+      errorMessage,
+      errorCode: "binary_not_found",
+      costUsd: null,
+      model: null,
+      summary: null,
+      sessionParams: null,
+      sessionDisplayId: null,
+      clearSession: false,
+      billingType: null,
+    };
+  }
+
+  // 2. Workspace isolation
+  let workspace: PreparedWorkspace | undefined;
+  if (config.workspace) {
+    ctx.onLifecycle?.({ phase: "preparing", step: "workspace" });
+    workspace = await prepareWorkspace(cwd, config.workspace);
+    cwd = workspace.cwd;
+  }
+
+  // 3. Build env & detect auth/billing
+  ctx.onLifecycle?.({ phase: "preparing", step: "auth" });
+  const env = buildEnv(ctx.env);
+  ensurePathInEnv(env);
+  const billingType = detectAuth("cursor", env).billingType;
+
+  // 3. Resolve instructions
+  ctx.onLifecycle?.({ phase: "preparing", step: "instructions" });
+  const instructions = await resolveInstructions(config.instructionsFile);
+  const fullPrompt = instructions ? `${instructions}\n\n${ctx.prompt}` : ctx.prompt;
+
+  // 4. Inject skills into ~/.cursor/skills/
+  ctx.onLifecycle?.({ phase: "preparing", step: "skills" });
+  if (config.skillDirs && config.skillDirs.length > 0) {
+    try {
+      await injectHomeSkills(config.skillDirs, "cursor");
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // 4. Determine session resume
+  const sessionParams = ctx.sessionParams ?? null;
+  const sessionId = (() => {
+    if (!sessionParams) return null;
+    const id =
+      (sessionParams["sessionId"] as string | undefined) ??
+      (sessionParams["session_id"] as string | undefined);
+    if (!id || typeof id !== "string") return null;
+    const sessionCwd = sessionParams["cwd"] as string | undefined;
+    if (sessionCwd && path.resolve(sessionCwd) !== path.resolve(cwd)) return null;
+    return id;
+  })();
+
+  // 5. Build args
+  const buildArgs = (resumeSessionId: string | null): string[] => {
+    const args = [...resolvedBinary.prefixArgs, "-p", "--output-format", "stream-json", "--workspace", cwd];
+    if (resumeSessionId) args.push("--resume", resumeSessionId);
+    if (model) args.push("--model", model);
+    if (config.mode) args.push("--mode", config.mode);
+    if (config.skipPermissions) args.push("--yolo");
+    if (config.extraArgs) args.push(...config.extraArgs);
+    return args;
+  };
+
+  // 6. Run attempt
+  const runAttempt = async (resumeSessionId: string | null) => {
+    const args = buildArgs(resumeSessionId);
+    let stdoutLineBuffer = "";
+
+    ctx.onLifecycle?.({ phase: "spawning" });
+    const proc = await runChildProcess({
+      runId,
+      command: resolvedBinary.bin,
+      args,
+      cwd,
+      env,
+      stdin: fullPrompt,
+      timeoutSec: config.timeoutSec,
+      graceSec: config.graceSec,
+      onStart: (pid) => {
+        ctx.onLifecycle?.({ phase: "running", pid });
+        ctx.onStart?.(pid);
+      },
+      signal: ctx.signal,
+      onOutput: async (stream, chunk) => {
+        if (stream !== "stdout") {
+          if (ctx.onOutput) {
+            try { await ctx.onOutput(stream, chunk); } catch { /* swallow */ }
+          }
+          return;
+        }
+
+        // Buffer stdout and normalize cursor stream lines
+        stdoutLineBuffer += chunk;
+        const lines = stdoutLineBuffer.split("\n");
+        stdoutLineBuffer = lines.pop() ?? "";
+
+        for (const rawLine of lines) {
+          const normalized = normalizeCursorStreamLine(rawLine);
+          if (!normalized.line) continue;
+
+          if (ctx.onOutput) {
+            try { await ctx.onOutput(normalized.stream ?? "stdout", `${normalized.line}\n`); } catch { /* swallow */ }
+          }
+
+          if (ctx.onEvent) {
+            const event = parseCursorStreamLine(rawLine);
+            if (event) {
+              try { await ctx.onEvent(event); } catch { /* swallow */ }
+            }
+          }
+        }
+      },
+    });
+
+    // Flush remaining buffer
+    if (stdoutLineBuffer.trim()) {
+      const normalized = normalizeCursorStreamLine(stdoutLineBuffer);
+      if (normalized.line && ctx.onOutput) {
+        try { await ctx.onOutput(normalized.stream ?? "stdout", `${normalized.line}\n`); } catch { /* swallow */ }
+      }
+      if (ctx.onEvent) {
+        const event = parseCursorStreamLine(stdoutLineBuffer);
+        if (event) {
+          try { await ctx.onEvent(event); } catch { /* swallow */ }
+        }
+      }
+    }
+
+    return proc;
+  };
+
+  // 7. Initial attempt
+  let proc = await runAttempt(sessionId);
+  let clearSession = false;
+
+  // 8. Check for unknown session — retry once
+  if (
+    sessionId &&
+    !proc.timedOut &&
+    (proc.exitCode ?? 0) !== 0 &&
+    isCursorUnknownSessionError(proc.stdout, proc.stderr)
+  ) {
+    proc = await runAttempt(null);
+    clearSession = true;
+  }
+
+  // 9. Parse result
+  const parsed = parseCursorJsonl(proc.stdout);
+  const processErrorCode = deriveErrorCode(proc);
+
+  let errorCode = processErrorCode;
+  if (!errorCode && isCursorAuthRequired(proc.stdout, proc.stderr)) {
+    errorCode = "auth_required";
+    if (ctx.onEvent) {
+      try {
+        await ctx.onEvent({
+          type: "auth_required",
+          httpStatus: null,
+          reason: "missing",
+          loginCommand: "cursor-agent login",
+          message: parsed.errorMessage,
+          timestamp: new Date().toISOString(),
+          providerType: "cursor",
+          sessionId: parsed.sessionId,
+          messageId: null,
+          eventId: null,
+          turnId: null,
+          parentToolCallId: null,
+          raw: {},
+        });
+      } catch { /* swallow */ }
+    }
+  }
+
+  const errorMessage = (() => {
+    if (proc.timedOut) return `Timed out after ${config.timeoutSec ?? 0}s`;
+    if (errorCode === "auth_required") return "Cursor requires authentication.";
+    if (parsed.errorMessage) return parsed.errorMessage;
+    if ((proc.exitCode ?? 0) !== 0 && !parsed.summary) {
+      const stderrLine = proc.stderr.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+      return stderrLine ?? `Cursor exited with code ${proc.exitCode ?? -1}`;
+    }
+    return null;
+  })();
+
+  const resolvedSessionId = parsed.sessionId;
+  const resultSessionParams = resolvedSessionId ? { sessionId: resolvedSessionId, cwd } : null;
+
+  const completedAt = new Date().toISOString();
+  const resolvedModel = parsed.model ?? model ?? null;
+  const status = proc.aborted ? "aborted" as const
+    : proc.timedOut ? "timeout" as const
+    : (errorCode || errorMessage) ? "failed" as const
+    : "completed" as const;
+
+  if (status === "completed") {
+    ctx.onLifecycle?.({ phase: "completed" });
+  } else if (status === "aborted") {
+    ctx.onLifecycle?.({ phase: "cancelled" });
+  } else {
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage ?? "Unknown error" });
+  }
+
+  return {
+    runId,
+    exitCode: proc.exitCode,
+    signal: proc.signal ?? null,
+    status,
+    startedAt,
+    completedAt,
+    durationMs: new Date(completedAt).getTime() - new Date(startedAt).getTime(),
+    errorMessage,
+    errorCode,
+    usage: parsed.usage && resolvedModel
+      ? { [resolvedModel]: { inputTokens: parsed.usage.inputTokens, outputTokens: parsed.usage.outputTokens, cachedInputTokens: parsed.usage.cachedInputTokens } }
+      : undefined,
+    costUsd: parsed.costUsd,
+    model: resolvedModel,
+    summary: parsed.summary,
+    sessionParams: resultSessionParams,
+    sessionDisplayId: resolvedSessionId,
+    clearSession,
+    billingType,
+    raw: null,
+    workspace,
+  };
+}

package/src/providers/cursor/index.ts

@@ -0,0 +1,25 @@
+import type { ProviderModule } from "../../types.js";
+import { cursorSessionCodec } from "./codec.js";
+import { resolveAuthForProvider } from "../../utils/auth.js";
+
+export const cursorProvider: ProviderModule = {
+  type: "cursor",
+  capabilities: {
+    sessions: false,
+    modelDiscovery: false,
+    quotaProbing: false,
+    mcp: false,
+    skills: true,
+    instructions: true,
+    workspace: true,
+    planMode: false,
+    concurrentSend: false,
+    cancelQueuedMessage: false,
+    stopTask: false,
+    modes: false,
+  },
+  // execute.ts loads lazily on first use.
+  execute: async (ctx) => (await import("./execute.js")).executeCursorProvider(ctx),
+  resolveAuth: (ctx) => resolveAuthForProvider("cursor", ctx),
+  sessionCodec: cursorSessionCodec,
+};