@agentex/agent 0.0.24 → 0.0.26

package/src/utils/binary.ts

@@ -0,0 +1,179 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { execFile } from "node:child_process";
+
+export interface ResolvedBinary {
+  bin: string;
+  prefixArgs: string[];
+}
+
+const cache = new Map<string, ResolvedBinary>();
+
+const COMMON_PATHS_UNIX: Record<string, string[]> = {
+  claude: [
+    path.join(os.homedir(), ".local", "bin", "claude"),
+    "/usr/local/bin/claude",
+    path.join(os.homedir(), ".npm-global", "bin", "claude"),
+  ],
+  codex: [
+    path.join(os.homedir(), ".local", "bin", "codex"),
+    "/usr/local/bin/codex",
+    path.join(os.homedir(), ".npm-global", "bin", "codex"),
+  ],
+  gemini: [
+    path.join(os.homedir(), ".local", "bin", "gemini"),
+    "/usr/local/bin/gemini",
+    path.join(os.homedir(), ".npm-global", "bin", "gemini"),
+  ],
+  agent: [
+    path.join(os.homedir(), ".local", "bin", "agent"),
+    "/usr/local/bin/agent",
+    path.join(os.homedir(), ".npm-global", "bin", "agent"),
+  ],
+  opencode: [
+    path.join(os.homedir(), ".local", "bin", "opencode"),
+    "/usr/local/bin/opencode",
+    path.join(os.homedir(), ".npm-global", "bin", "opencode"),
+  ],
+  pi: [
+    path.join(os.homedir(), ".local", "bin", "pi"),
+    "/usr/local/bin/pi",
+    path.join(os.homedir(), ".npm-global", "bin", "pi"),
+  ],
+};
+
+function getCommonPathsWindows(name: string): string[] {
+  const appData = process.env["APPDATA"] ?? "";
+  const localAppData = process.env["LOCALAPPDATA"] ?? "";
+  const userProfile = process.env["USERPROFILE"] ?? "";
+  return [
+    path.join(appData, "npm", `${name}.cmd`),
+    path.join(localAppData, "pnpm", `${name}.cmd`),
+    path.join(userProfile, ".local", "bin", `${name}.exe`),
+  ];
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runWhich(name: string): Promise<string | null> {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  return new Promise((resolve) => {
+    const child = execFile(cmd, [name], { timeout: 5000 }, (err, stdout) => {
+      if (err) {
+        resolve(null);
+        return;
+      }
+      const result = stdout.trim().split("\n")[0]?.trim();
+      resolve(result ?? null);
+    });
+    child.on("error", () => resolve(null));
+  });
+}
+
+export async function resolveWindowsCmdShim(cmdPath: string): Promise<ResolvedBinary | null> {
+  try {
+    const content = await fs.readFile(cmdPath, "utf-8");
+    // Match patterns like: "%dp0%\node_modules\...\.js" or "%~dp0\...\entry.js"
+    const match = content.match(/%(?:~dp0|dp0)[\\\/]([^\s"]+\.js)/i);
+    if (match?.[1]) {
+      const dir = path.dirname(cmdPath);
+      const jsPath = path.resolve(dir, match[1]);
+      if (await fileExists(jsPath)) {
+        return { bin: "node", prefixArgs: [jsPath] };
+      }
+    }
+  } catch {
+    // Not a .cmd shim or can't read
+  }
+  return null;
+}
+
+export async function findBinary(name: string, configOverride?: string): Promise<ResolvedBinary> {
+  // 1. Config override
+  if (configOverride) {
+    if (await fileExists(configOverride)) {
+      return { bin: configOverride, prefixArgs: [] };
+    }
+    throw new Error(
+      `Configured binary path "${configOverride}" does not exist. ` +
+      `Verify the path is correct.`
+    );
+  }
+
+  // Check cache
+  const cached = cache.get(name);
+  if (cached) return cached;
+
+  // 2. Platform-specific common paths
+  const isWin = process.platform === "win32";
+  const commonPaths = isWin
+    ? getCommonPathsWindows(name)
+    : (COMMON_PATHS_UNIX[name] ?? []);
+
+  for (const p of commonPaths) {
+    if (await fileExists(p)) {
+      if (isWin && p.endsWith(".cmd")) {
+        const resolved = await resolveWindowsCmdShim(p);
+        if (resolved) {
+          cache.set(name, resolved);
+          return resolved;
+        }
+      }
+      const result: ResolvedBinary = { bin: p, prefixArgs: [] };
+      cache.set(name, result);
+      return result;
+    }
+  }
+
+  // 3. PATH via which/where
+  const whichResult = await runWhich(name);
+  if (whichResult) {
+    if (isWin && whichResult.endsWith(".cmd")) {
+      const resolved = await resolveWindowsCmdShim(whichResult);
+      if (resolved) {
+        cache.set(name, resolved);
+        return resolved;
+      }
+    }
+    const result: ResolvedBinary = { bin: whichResult, prefixArgs: [] };
+    cache.set(name, result);
+    return result;
+  }
+
+  const installHints: Record<string, string> = {
+    claude: "Install: npm install -g @anthropic-ai/claude-code",
+    codex: "Install: npm install -g @openai/codex",
+    gemini: "Install: npm install -g @anthropic-ai/claude-code (Gemini CLI)",
+    agent: "Install the Cursor CLI agent",
+    opencode: "Install: npm install -g opencode-ai",
+    pi: "Install: npm install -g @mariozechner/pi-coding-agent",
+  };
+  throw new Error(
+    `Could not find "${name}" binary. Searched common install paths and PATH. ` +
+    (installHints[name] ?? `Ensure "${name}" is installed and on your PATH.`)
+  );
+}
+
+export async function ensureCommandResolvable(command: string): Promise<ResolvedBinary> {
+  // If it's a path (contains separator), check existence directly
+  if (command.includes(path.sep) || command.includes("/")) {
+    if (await fileExists(command)) {
+      return { bin: command, prefixArgs: [] };
+    }
+    throw new Error(`Command not found: "${command}"`);
+  }
+  // Otherwise treat as a binary name
+  return findBinary(command);
+}
+
+export function clearBinaryCache(): void {
+  cache.clear();
+}

package/src/utils/endpoint.ts

@@ -0,0 +1,172 @@
+import type { ProviderEndpointConfig } from "../types.js";
+
+/**
+ * Result of translating a `ProviderEndpointConfig` into what a specific
+ * provider's spawned CLI understands. Since there is no shared wire format
+ * across CLIs, each provider gets its own translation:
+ * - `env` is merged into the child process environment.
+ * - `args` is appended to the child argv (codex `-c` config overrides).
+ * - `unset` names env vars to REMOVE from the child env after merging. Env
+ *   alone can't express deletion, and ambient provider credentials seeded by
+ *   `buildEnv` (e.g. a real `ANTHROPIC_API_KEY` from the host `process.env`)
+ *   must not leak to a third-party `baseUrl`.
+ *
+ * Apply order at every call site: `Object.assign(env, tx.env)` then
+ * `for (const k of tx.unset) delete env[k]`.
+ */
+export interface EndpointTranslation {
+  env: Record<string, string>;
+  args: string[];
+  unset: string[];
+}
+
+/** Fresh empty translation. Not a shared singleton — callers may mutate. */
+function empty(): EndpointTranslation {
+  return { env: {}, args: [], unset: [] };
+}
+
+/**
+ * Stable id of the Codex `model_provider` synthesized for a custom endpoint.
+ * Exposed so advanced Codex knobs can be set via `config.extraArgs` against a
+ * known name, e.g. `-c model_providers.custom.query_params.api-version="..."`.
+ */
+export const CODEX_CUSTOM_PROVIDER_ID = "custom";
+
+/** Env var Codex reads the custom-endpoint credential from (its `env_key`). */
+export const CODEX_CUSTOM_KEY_ENV = "CODEX_CUSTOM_API_KEY";
+
+/** Prefix for the per-header env vars Codex reads via `env_http_headers`. */
+export const CODEX_CUSTOM_HEADER_ENV_PREFIX = "CODEX_CUSTOM_HEADER_";
+
+/**
+ * Ambient Anthropic alternate-routing env (Bedrock/Vertex/Foundry) that must be
+ * cleared when a custom `baseUrl` is set — otherwise Claude Code could be steered
+ * to one of those instead of the endpoint. General AWS/cloud creds are left
+ * intact (the agent may legitimately need them for tool calls).
+ */
+const CLAUDE_ALT_ROUTING_ENV = [
+  "ANTHROPIC_BEDROCK_BASE_URL",
+  "CLAUDE_CODE_USE_BEDROCK",
+  "CLAUDE_CODE_USE_VERTEX",
+  "CLAUDE_CODE_USE_FOUNDRY",
+];
+
+/**
+ * Translate a custom-endpoint config for a provider. Returns `env`/`args`/`unset`
+ * to apply at spawn time. Providers without a custom-endpoint mechanism return
+ * an empty translation (the config is silently ignored, like `allowedTools`
+ * on providers without argv tool filtering).
+ */
+export function translateEndpoint(
+  providerType: string,
+  endpoint: ProviderEndpointConfig | undefined,
+): EndpointTranslation {
+  if (!endpoint) return empty();
+  switch (providerType) {
+    case "claude":
+      return translateClaudeEndpoint(endpoint);
+    case "codex":
+      return translateCodexEndpoint(endpoint);
+    default:
+      return empty();
+  }
+}
+
+/**
+ * Claude Code routes to any Anthropic Messages-API-compatible endpoint purely
+ * through env vars, so the translation is env-only (no argv).
+ *
+ * Credential hygiene: `buildEnv` seeds `ANTHROPIC_API_KEY` from the host's
+ * `process.env`. When we point at a custom `baseUrl`, only the auth declared
+ * here may reach that third party — so we `unset` any ambient Anthropic
+ * credential we didn't choose. Without a custom `baseUrl` (still real
+ * Anthropic) we only enforce the "exactly one auth" invariant.
+ */
+function translateClaudeEndpoint(e: ProviderEndpointConfig): EndpointTranslation {
+  const env: Record<string, string> = {};
+  const unset: string[] = [];
+  if (e.baseUrl) env["ANTHROPIC_BASE_URL"] = e.baseUrl;
+  // authToken (Authorization: Bearer) wins over apiKey (x-api-key) if both are
+  // set. Whichever is NOT chosen is removed from the child env, ambient or not.
+  if (e.authToken) {
+    env["ANTHROPIC_AUTH_TOKEN"] = e.authToken;
+    unset.push("ANTHROPIC_API_KEY");
+  } else if (e.apiKey) {
+    env["ANTHROPIC_API_KEY"] = e.apiKey;
+    unset.push("ANTHROPIC_AUTH_TOKEN");
+  } else if (e.baseUrl) {
+    // Custom endpoint with no declared auth: don't forward ambient Anthropic
+    // credentials to it. The caller must pass auth explicitly via the endpoint.
+    unset.push("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN");
+  }
+  // A custom baseUrl is authoritative — clear ambient alternate-routing config
+  // (Bedrock/Vertex/Foundry) so Claude Code targets the endpoint, not those.
+  if (e.baseUrl) unset.push(...CLAUDE_ALT_ROUTING_ENV);
+  if (e.headers && Object.keys(e.headers).length > 0) {
+    // ANTHROPIC_CUSTOM_HEADERS is newline-separated `Name: Value` pairs.
+    env["ANTHROPIC_CUSTOM_HEADERS"] = Object.entries(e.headers)
+      .map(([k, v]) => `${k}: ${v}`)
+      .join("\n");
+  }
+  if (e.modelMap) {
+    // Tier aliases → concrete ids on the endpoint. Lets alias callers
+    // (`model: "sonnet"`) resolve correctly against a non-Anthropic endpoint.
+    if (e.modelMap.opus) env["ANTHROPIC_DEFAULT_OPUS_MODEL"] = e.modelMap.opus;
+    if (e.modelMap.sonnet) env["ANTHROPIC_DEFAULT_SONNET_MODEL"] = e.modelMap.sonnet;
+    if (e.modelMap.haiku) env["ANTHROPIC_DEFAULT_HAIKU_MODEL"] = e.modelMap.haiku;
+    if (e.modelMap.fable) env["ANTHROPIC_DEFAULT_FABLE_MODEL"] = e.modelMap.fable;
+  }
+  return { env, args: [], unset };
+}
+
+/**
+ * Codex has no base-URL env var — custom endpoints are a `[model_providers.<id>]`
+ * config block (base_url, wire_api, env_key) selected by `model_provider`. We
+ * synthesize that block via `-c` overrides (the same mechanism already used for
+ * `model_reasoning_effort`) and inject the key into env under `env_key`.
+ *
+ * `wire_api` is `"responses"`: Codex removed the Chat Completions ("chat") wire
+ * protocol in Feb 2026, so a custom provider must speak the OpenAI Responses
+ * API (directly or via a translating gateway). `modelMap` is ignored — Codex
+ * has no tier aliases, so pass a concrete `config.model`. Requires `baseUrl`;
+ * without it there is no provider to define, so the translation is empty.
+ *
+ * Codex needs no `unset`: ambient `OPENAI_API_KEY` is the DEFAULT provider's
+ * `env_key`, and we select the synthesized `custom` provider whose `env_key`
+ * is `CODEX_CUSTOM_KEY_ENV`, so the ambient key never reaches the endpoint.
+ */
+function translateCodexEndpoint(e: ProviderEndpointConfig): EndpointTranslation {
+  if (!e.baseUrl) return empty();
+  const env: Record<string, string> = {};
+  const args: string[] = [];
+  const id = CODEX_CUSTOM_PROVIDER_ID;
+  const set = (key: string, value: string) => {
+    // Match the existing `-c key=<json-value>` convention (see codex effort).
+    args.push("-c", `${key}=${JSON.stringify(value)}`);
+  };
+  set("model_provider", id);
+  set(`model_providers.${id}.name`, "Custom");
+  set(`model_providers.${id}.base_url`, e.baseUrl);
+  set(`model_providers.${id}.wire_api`, "responses");
+  const key = e.authToken ?? e.apiKey;
+  if (key) {
+    env[CODEX_CUSTOM_KEY_ENV] = key;
+    set(`model_providers.${id}.env_key`, CODEX_CUSTOM_KEY_ENV);
+  }
+  if (e.headers) {
+    // Route header VALUES through env via `env_http_headers` (header → env-var
+    // name), never argv: argv is world-readable via `ps` and a header can carry
+    // a secret (Authorization, X-API-Key). Mirrors why the claude provider
+    // stages MCP headers to a 0600 file instead of the command line. Header
+    // names are assumed TOML bare keys (letters/digits/`-`/`_`), which real HTTP
+    // header tokens are — a name with a `.` would nest as a sub-table.
+    let i = 0;
+    for (const [name, value] of Object.entries(e.headers)) {
+      const headerEnv = `${CODEX_CUSTOM_HEADER_ENV_PREFIX}${i++}`;
+      env[headerEnv] = value;
+      set(`model_providers.${id}.env_http_headers.${name}`, headerEnv);
+    }
+  }
+  // modelMap intentionally ignored — Codex has no tier aliases.
+  return { env, args, unset: [] };
+}

package/src/utils/env.ts

@@ -0,0 +1,63 @@
+import process from "node:process";
+
+const BASE_ALLOW_LIST = [
+  "PATH", "HOME", "TMPDIR", "TEMP", "TMP", "USER", "LOGNAME", "LANG", "LC_ALL",
+  // Windows essentials
+  "SystemRoot", "WINDIR", "COMSPEC", "PATHEXT", "APPDATA", "LOCALAPPDATA", "USERPROFILE",
+];
+
+/** Auth env vars that providers need for API-key auth and billing detection. */
+const AUTH_ALLOW_LIST = [
+  // Claude / Anthropic
+  "ANTHROPIC_API_KEY", "ANTHROPIC_BEDROCK_BASE_URL",
+  // AWS (Bedrock)
+  "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_REGION", "AWS_PROFILE",
+  // Codex / OpenAI
+  "OPENAI_API_KEY",
+  // Gemini / Google
+  "GEMINI_API_KEY", "GOOGLE_API_KEY",
+  // Cursor
+  "CURSOR_API_KEY",
+];
+
+// HEADER covers custom-endpoint header carriers — `ANTHROPIC_CUSTOM_HEADERS` and
+// the generated `CODEX_CUSTOM_HEADER_*` vars — whose values can hold secret
+// header tokens (Authorization, X-API-Key). Over-redacting a non-secret header
+// in logs is the safe direction.
+const SENSITIVE_PATTERNS = /KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH|HEADER/i;
+
+const ESSENTIAL_PATHS_UNIX = ["/usr/local/bin", "/usr/bin", "/bin"];
+
+export function buildEnv(callerEnv?: Record<string, string>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of BASE_ALLOW_LIST) {
+    const val = process.env[key];
+    if (val !== undefined) env[key] = val;
+  }
+  for (const key of AUTH_ALLOW_LIST) {
+    const val = process.env[key];
+    if (val !== undefined) env[key] = val;
+  }
+  if (callerEnv) Object.assign(env, callerEnv);
+  return env;
+}
+
+export function redactEnvForLogs(env: Record<string, string>): Record<string, string> {
+  const redacted: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    redacted[key] = SENSITIVE_PATTERNS.test(key) ? "[REDACTED]" : value;
+  }
+  return redacted;
+}
+
+export function ensurePathInEnv(env: Record<string, string>): void {
+  const isWin = process.platform === "win32";
+  const sep = isWin ? ";" : ":";
+  const essentials = isWin ? [] : ESSENTIAL_PATHS_UNIX;
+  const current = env["PATH"] ?? env["Path"] ?? "";
+  const parts = current.split(sep);
+  for (const p of essentials) {
+    if (!parts.includes(p)) parts.push(p);
+  }
+  env["PATH"] = parts.join(sep);
+}

package/src/utils/execute-all.ts

@@ -0,0 +1,68 @@
+import type { ExecutionContext, ExecutionResult, ProviderModule } from "../types.js";
+import { getProvider } from "../registry.js";
+
+export interface ExecuteAllOptions {
+  /** Abort all remaining executions if any one fails. Default: false. */
+  cancelOnFailure?: boolean;
+  /** External signal to cancel all executions. */
+  signal?: AbortSignal;
+}
+
+export interface ExecuteAllTask {
+  provider: string | ProviderModule;
+  ctx: ExecutionContext;
+}
+
+/**
+ * Run multiple agent executions concurrently with shared cancellation.
+ *
+ * Returns results in the same order as the input tasks. If `cancelOnFailure`
+ * is true, remaining tasks are aborted as soon as any task returns a
+ * non-completed status.
+ */
+export async function executeAll(
+  tasks: ExecuteAllTask[],
+  options?: ExecuteAllOptions,
+): Promise<ExecutionResult[]> {
+  if (tasks.length === 0) return [];
+
+  const controller = new AbortController();
+
+  // Chain external signal
+  if (options?.signal) {
+    if (options.signal.aborted) {
+      controller.abort(options.signal.reason);
+    } else {
+      const onAbort = () => controller.abort(options.signal!.reason);
+      options.signal.addEventListener("abort", onAbort, { once: true });
+      // Clean up listener when our controller aborts (avoid leak)
+      controller.signal.addEventListener("abort", () => {
+        options.signal!.removeEventListener("abort", onAbort);
+      }, { once: true });
+    }
+  }
+
+  const promises = tasks.map(async (task): Promise<ExecutionResult> => {
+    const provider = typeof task.provider === "string"
+      ? getProvider(task.provider)
+      : task.provider;
+
+    // Merge signals: task's own signal + shared controller signal
+    const taskSignal = task.ctx.signal
+      ? AbortSignal.any([task.ctx.signal, controller.signal])
+      : controller.signal;
+
+    const result = await provider.execute({
+      ...task.ctx,
+      signal: taskSignal,
+    });
+
+    if (options?.cancelOnFailure && result.status !== "completed") {
+      controller.abort("cancelOnFailure");
+    }
+
+    return result;
+  });
+
+  return Promise.all(promises);
+}

package/src/utils/exit-plan-mode.ts

@@ -0,0 +1,40 @@
+import type { UserInputRequest } from "../types.js";
+
+/**
+ * Structured payload for an `ExitPlanMode` permission request.
+ *
+ * The agent calls this when it has finished planning and wants the user to
+ * approve the plan. The host receives the request via `onUserInputRequest`
+ * and decides whether to exit plan mode (allow → the agent continues in the
+ * permission mode the user picked) or stay in plan mode (deny).
+ */
+export interface ExitPlanModeRequest {
+  plan: string;
+}
+
+/**
+ * Parse an `ExitPlanMode` permission request.
+ *
+ * Returns the structured plan payload if the request is for `ExitPlanMode`,
+ * or `null` if it's a different tool. The plan text only flows through the
+ * live SDK control_request — it is not persisted to the saved transcript —
+ * so callers should capture it here when they want to surface it to the user.
+ *
+ * @example
+ * ```ts
+ * onUserInputRequest: async (req) => {
+ *   const plan = parseExitPlanMode(req);
+ *   if (plan) {
+ *     const approved = await showPlanApprovalUI(plan.plan);
+ *     return { allow: approved };
+ *   }
+ *   return { allow: true };
+ * }
+ * ```
+ */
+export function parseExitPlanMode(req: UserInputRequest): ExitPlanModeRequest | null {
+  if (req.toolName !== "ExitPlanMode") return null;
+  const plan = (req.input as Record<string, unknown>)["plan"];
+  if (typeof plan !== "string") return null;
+  return { plan };
+}