@gullabs/claude-cli 0.6.1 → 0.16.0

package/dist/index.js

@@ -1,11 +1,109 @@
 import { mkdtemp, rm } from 'fs/promises';
 import { tmpdir } from 'os';
 import { join } from 'path';
-import { zodToStandardSchema, toConfigJsonSchema, createModelRegistry, LlmError } from '@gullabs/core';
+import { zodToStandardSchema, toConfigJsonSchema, toConfigKeys, createModelRegistry, LlmError } from '@gullabs/core';
 import { spawn } from 'child_process';
+import { StringDecoder } from 'string_decoder';
 import { z } from 'zod';
 
 // src/adapter.ts
+var INHERITED_NAMES = /* @__PURE__ */ new Set([
+  // Process basics.
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "LANG",
+  "LANGUAGE",
+  "TERM",
+  "TMPDIR",
+  "TEMP",
+  "TMP",
+  "SHELL",
+  "TZ",
+  // Windows equivalents of the above.
+  "SYSTEMROOT",
+  "SYSTEMDRIVE",
+  "WINDIR",
+  "COMSPEC",
+  "PATHEXT",
+  "USERPROFILE",
+  "APPDATA",
+  "LOCALAPPDATA",
+  "PROGRAMDATA",
+  "HOMEDRIVE",
+  "HOMEPATH",
+  // Network: proxies and trust roots.
+  "HTTPS_PROXY",
+  "HTTP_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "https_proxy",
+  "http_proxy",
+  "all_proxy",
+  "no_proxy",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  // The CLI's own documented settings that keep the subscription login usable:
+  // where its login lives, the long-lived subscription token from
+  // `claude setup-token`, and client certificates for an mTLS proxy.
+  "CLAUDE_CONFIG_DIR",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "CLAUDE_CODE_CLIENT_CERT",
+  "CLAUDE_CODE_CLIENT_KEY",
+  "CLAUDE_CODE_CLIENT_KEY_PASSPHRASE",
+  "CLAUDE_CODE_PROXY_RESOLVES_HOSTS"
+]);
+var INHERITED_PREFIXES = ["LC_", "XDG_"];
+function isInherited(name, windows) {
+  const key = windows ? name.toUpperCase() : name;
+  if (INHERITED_NAMES.has(key)) return true;
+  return INHERITED_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+function buildChildEnv(parent, extra, windows) {
+  const env = {};
+  for (const [name, value] of Object.entries(parent)) {
+    if (value !== void 0 && isInherited(name, windows)) env[name] = value;
+  }
+  if (extra !== void 0) {
+    if (windows) {
+      const overridden = new Set(Object.keys(extra).map((name) => name.toUpperCase()));
+      for (const name of Object.keys(env)) {
+        if (overridden.has(name.toUpperCase())) delete env[name];
+      }
+    }
+    Object.assign(env, extra);
+  }
+  return env;
+}
+function badEnv(message) {
+  return new LlmError(message, {
+    kind: "bad_request",
+    retryable: false,
+    provider: "claude-cli"
+  });
+}
+function parseExtraEnv(env) {
+  if (env === void 0) return void 0;
+  if (env === null || typeof env !== "object" || Array.isArray(env)) {
+    throw badEnv("claudeCliAdapter: `env` must be an object of string values");
+  }
+  const copy = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (name === "" || name.includes("=") || name.includes("\0")) {
+      throw badEnv(`claudeCliAdapter: \`env\` has an invalid name "${name}"`);
+    }
+    if (typeof value !== "string" || value.includes("\0")) {
+      throw badEnv(
+        `claudeCliAdapter: \`env.${name}\` must be a string without NUL characters`
+      );
+    }
+    copy[name] = value;
+  }
+  return Object.freeze(copy);
+}
+var MAX_STDOUT_BYTES = 32 * 1024 * 1024;
 function buildClaudeCliRunner(claudePath = "claude") {
   return {
     run(args, input, opts) {
@@ -18,9 +116,14 @@ function buildClaudeCliRunner(claudePath = "claude") {
         }
         const child = spawn(claudePath, args, {
           cwd: opts.cwd,
-          stdio: ["pipe", "pipe", "pipe"]
+          stdio: ["pipe", "pipe", "pipe"],
+          detached: process.platform !== "win32",
+          env: buildChildEnv(process.env, opts.env, process.platform === "win32")
         });
+        const stdoutDecoder = new StringDecoder("utf8");
+        const stderrDecoder = new StringDecoder("utf8");
         let stdout = "";
+        let stdoutBytes = 0;
         let stderr = "";
         let settled = false;
         let pendingError;
@@ -36,12 +139,31 @@ function buildClaudeCliRunner(claudePath = "claude") {
             opts.signal.removeEventListener("abort", onAbort);
           }
         };
+        const signalTree = (signal) => {
+          if (process.platform !== "win32" && child.pid !== void 0) {
+            try {
+              process.kill(-child.pid, signal);
+              return;
+            } catch {
+            }
+          }
+          child.kill(signal);
+        };
         const killChild = () => {
-          child.kill("SIGTERM");
+          signalTree("SIGTERM");
           killTimeoutHandle = setTimeout(() => {
-            child.kill("SIGKILL");
+            signalTree("SIGKILL");
+            child.stdout.destroy();
+            child.stderr.destroy();
           }, 5e3);
         };
+        const sweepGroup = () => {
+          if (process.platform === "win32" || child.pid === void 0) return;
+          try {
+            process.kill(-child.pid, "SIGKILL");
+          } catch {
+          }
+        };
         const beginReject = (err) => {
           if (settled || pendingError !== void 0) return;
           pendingError = err;
@@ -64,10 +186,22 @@ function buildClaudeCliRunner(claudePath = "claude") {
           }, opts.timeoutMs);
         }
         child.stdout.on("data", (chunk) => {
-          stdout += chunk.toString("utf8");
+          if (pendingError !== void 0) return;
+          stdoutBytes += chunk.length;
+          if (stdoutBytes > MAX_STDOUT_BYTES) {
+            const err = new Error(
+              `claude-cli stdout exceeded ${MAX_STDOUT_BYTES} bytes; the process was killed`
+            );
+            err.name = "OutputLimitError";
+            beginReject(err);
+            return;
+          }
+          stdout += stdoutDecoder.write(chunk);
         });
         child.stderr.on("data", (chunk) => {
-          stderr += chunk.toString("utf8");
+          stderr = (stderr + stderrDecoder.write(chunk)).slice(-1048576);
+        });
+        child.stdin.on("error", () => {
         });
         child.once("error", (err) => {
           if (settled) return;
@@ -80,8 +214,11 @@ function buildClaudeCliRunner(claudePath = "claude") {
           settled = true;
           cleanup();
           if (pendingError !== void 0) {
+            sweepGroup();
             reject(pendingError);
           } else {
+            stdout += stdoutDecoder.end();
+            stderr = (stderr + stderrDecoder.end()).slice(-1048576);
             resolve({ stdout, stderr, exitCode });
           }
         });
@@ -92,31 +229,52 @@ function buildClaudeCliRunner(claudePath = "claude") {
 }
 
 // src/adapter.ts
+function abortError() {
+  const err = new Error("claude-cli call aborted");
+  err.name = "AbortError";
+  return err;
+}
 var Semaphore = class {
   available;
-  queue = [];
+  waiters = [];
   constructor(max) {
     this.available = max;
   }
-  async acquire() {
+  /**
+   * Take a slot. A caller that has to wait leaves the queue, and rejects with an
+   * `AbortError`, as soon as `signal` fires: a call the engine already gave up
+   * on must not hold a place in line.
+   */
+  acquire(signal) {
+    if (signal?.aborted === true) return Promise.reject(abortError());
     if (this.available > 0) {
       this.available -= 1;
-      return () => {
+      return Promise.resolve(() => {
         this.release();
-      };
+      });
     }
-    await new Promise((resolve) => {
-      this.queue.push(resolve);
+    return new Promise((resolve, reject) => {
+      const grant = () => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve(() => {
+          this.release();
+        });
+      };
+      const onAbort = () => {
+        const at = this.waiters.indexOf(grant);
+        if (at >= 0) this.waiters.splice(at, 1);
+        reject(abortError());
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.waiters.push(grant);
     });
-    this.available -= 1;
-    return () => {
-      this.release();
-    };
   }
+  // A freed slot goes straight to the next waiter, so a new caller cannot
+  // overtake it between the release and the waiter's wake-up.
   release() {
-    this.available += 1;
-    const next = this.queue.shift();
+    const next = this.waiters.shift();
     if (next !== void 0) next();
+    else this.available += 1;
   }
 };
 function mapFinishReason(stopReason) {
@@ -124,6 +282,8 @@ function mapFinishReason(stopReason) {
   switch (stopReason) {
     case "end_turn":
       return "stop";
+    case "refusal":
+      return "content_filter";
     case "tool_use":
       return "stop";
     default:
@@ -131,14 +291,19 @@ function mapFinishReason(stopReason) {
   }
 }
 function mapUsage(usage) {
-  const inputTokens = usage?.input_tokens ?? 0;
+  const cacheRead = usage?.cache_read_input_tokens;
+  const cacheWrite = usage?.cache_creation_input_tokens;
+  const inputTokens = (usage?.input_tokens ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
   const outputTokens = usage?.output_tokens ?? 0;
-  const cachedInputTokens = usage?.cache_read_input_tokens;
+  const cachedInputTokens = cacheRead;
+  const thinkingTokens = usage?.output_tokens_details?.thinking_tokens;
   const totalTokens = usage !== void 0 ? inputTokens + outputTokens : void 0;
   const details = {
     input: inputTokens,
     output: outputTokens,
     ...cachedInputTokens !== void 0 ? { cached: cachedInputTokens } : {},
+    ...cacheWrite !== void 0 ? { cacheWrite } : {},
+    ...thinkingTokens !== void 0 ? { thinking: thinkingTokens } : {},
     ...totalTokens !== void 0 ? { total: totalTokens } : {}
   };
   const raw = usage !== void 0 ? usage : null;
@@ -148,6 +313,7 @@ function mapUsage(usage) {
     details,
     raw,
     ...cachedInputTokens !== void 0 ? { cachedInputTokens } : {},
+    ...thinkingTokens !== void 0 ? { thinkingTokens } : {},
     ...totalTokens !== void 0 ? { totalTokens } : {}
   };
 }
@@ -177,20 +343,47 @@ function buildPrompt(messages) {
 ${messageText(msg)}`;
   }).join("\n\n");
 }
+var AUTH_FAILURE = /\b(?:log ?in|auth|oauth|authentication|unauthori[sz]ed|401)\b/i;
+var RATE_LIMITED = /\brate[ -]?limit(?:ed|s|ing)?\b|\btoo many requests\b|(?<![\w.:/-])429(?![\w-]|\.\d)/i;
 function looksAuthy(text) {
-  return /login|auth|unauthorized/i.test(text);
+  return AUTH_FAILURE.test(text);
 }
 function looksRateLimited(text) {
-  return /rate limit|429/i.test(text);
+  return RATE_LIMITED.test(text);
 }
-function classifyRunFailure(envelope, result) {
-  const combinedText = `${envelope?.subtype ?? ""} ${result.stderr}`;
-  if (looksAuthy(combinedText)) {
-    return new LlmError(
-      `claude CLI reported an authentication failure: ${result.stderr.slice(-500)}`,
-      { kind: "invalid_auth", retryable: false, provider: "claude-cli" }
+function assertServedModel(envelope, requestedModel) {
+  const modelUsage = envelope.modelUsage;
+  if (modelUsage === null || typeof modelUsage !== "object" || Array.isArray(modelUsage)) {
+    throw new LlmError("claude CLI did not report a valid modelUsage object.", {
+      kind: "server",
+      retryable: false,
+      provider: "claude-cli"
+    });
+  }
+  for (const served of Object.keys(modelUsage)) {
+    if (served !== requestedModel) {
+      throw new LlmError(
+        `claude CLI served model "${served}" but the request asked for "${requestedModel}".`,
+        { kind: "server", retryable: false, provider: "claude-cli" }
+      );
+    }
+  }
+  if (!Object.hasOwn(modelUsage, requestedModel)) {
+    throw new LlmError(
+      `claude CLI did not report the requested model "${requestedModel}" in modelUsage.`,
+      { kind: "server", retryable: false, provider: "claude-cli" }
     );
   }
+}
+function classifyRunFailure(envelope, result) {
+  if (envelope?.stop_reason === "refusal") {
+    return new LlmError("claude CLI refused the prompt (stop_reason: refusal).", {
+      kind: "content_filter",
+      retryable: false,
+      provider: "claude-cli"
+    });
+  }
+  const combinedText = `${envelope?.subtype ?? ""} ${result.stderr}`;
   if (looksRateLimited(combinedText)) {
     return new LlmError(
       `claude CLI reported rate limiting: ${result.stderr.slice(-500)}`,
@@ -201,6 +394,12 @@ function classifyRunFailure(envelope, result) {
       }
     );
   }
+  if (looksAuthy(combinedText)) {
+    return new LlmError(
+      `claude CLI reported an authentication failure: ${result.stderr.slice(-500)}`,
+      { kind: "invalid_auth", retryable: false, provider: "claude-cli" }
+    );
+  }
   if (envelope?.is_error === true) {
     return new LlmError(
       `claude CLI reported an error (subtype: ${envelope.subtype ?? "unknown"}): ${result.stderr.slice(-500)}`,
@@ -216,6 +415,7 @@ function classifyRunFailure(envelope, result) {
 function claudeCliAdapter(opts) {
   const runner = opts?.runner ?? buildClaudeCliRunner(opts?.claudePath);
   const semaphore = new Semaphore(opts?.maxConcurrency ?? 2);
+  const env = parseExtraEnv(opts?.env);
   return {
     id: "claude-cli",
     async run(req, ctx) {
@@ -241,6 +441,27 @@ function claudeCliAdapter(opts) {
       const warnings = [];
       const model = req.model;
       const config = req.config;
+      if (req.modelDescriptor?.model !== model || req.modelDescriptor.provider !== "claude-cli") {
+        throw new LlmError(`No matching Claude model descriptor for "${model}".`, {
+          kind: "bad_request",
+          retryable: false,
+          provider: "claude-cli"
+        });
+      }
+      if (req.transientProviderState !== void 0) {
+        throw new LlmError(`Model "${model}" does not admit transientProviderState.`, {
+          kind: "bad_request",
+          retryable: false,
+          provider: "claude-cli"
+        });
+      }
+      if (config.reasoning !== void 0 && req.modelDescriptor.capabilities?.reasoningApi === void 0) {
+        throw new LlmError(`Model "${model}" does not admit reasoning.`, {
+          kind: "bad_request",
+          retryable: false,
+          provider: "claude-cli"
+        });
+      }
       const prompt = buildPrompt(req.messages);
       const args = [
         "-p",
@@ -250,7 +471,9 @@ function claudeCliAdapter(opts) {
         "--tools",
         "",
         "--disable-slash-commands",
-        "--no-session-persistence"
+        "--no-session-persistence",
+        "--settings",
+        '{"switchModelsOnFlag":false}'
       ];
       args.push("--model", model);
       const effort = config.reasoning?.effort;
@@ -264,14 +487,29 @@ function claudeCliAdapter(opts) {
         args.push("--json-schema", JSON.stringify(req.outputJsonSchema));
       }
       const timeoutMs = req.attemptTimeoutMs ?? config.timeoutMs;
-      const cwd = await mkdtemp(join(tmpdir(), "claude-cli-"));
-      const release = await semaphore.acquire();
+      let release;
+      try {
+        release = await semaphore.acquire(ctx.signal);
+      } catch (waitErr) {
+        throw new LlmError(
+          waitErr instanceof Error ? waitErr.message : "claude-cli call aborted",
+          { kind: "aborted", retryable: false, provider: "claude-cli" }
+        );
+      }
+      let cwd;
+      try {
+        cwd = await mkdtemp(join(tmpdir(), "claude-cli-"));
+      } catch (mkdirErr) {
+        release();
+        throw mkdirErr;
+      }
       let result;
       try {
         result = await runner.run(args, prompt, {
           cwd,
           ...timeoutMs !== void 0 ? { timeoutMs } : {},
-          ...ctx.signal !== void 0 ? { signal: ctx.signal } : {}
+          ...ctx.signal !== void 0 ? { signal: ctx.signal } : {},
+          ...env !== void 0 ? { env } : {}
         });
       } catch (rawErr) {
         release();
@@ -313,6 +551,7 @@ function claudeCliAdapter(opts) {
       if (result.exitCode !== 0 || envelope?.is_error === true || envelope === void 0) {
         throw classifyRunFailure(envelope, result);
       }
+      assertServedModel(envelope, model);
       const text = envelope.result ?? "";
       let rawStructured;
       if (req.outputJsonSchema !== void 0) {
@@ -335,6 +574,10 @@ function claudeCliAdapter(opts) {
       };
       const adapterResult = {
         model,
+        message: {
+          role: "assistant",
+          parts: text.length > 0 ? [{ kind: "text", text }] : []
+        },
         usage,
         warnings,
         ...text.length > 0 ? { text } : {},
@@ -347,13 +590,13 @@ function claudeCliAdapter(opts) {
   };
 }
 var CLAUDE_CLI_MODEL_IDS = [
-  "claude-fable-5",
-  "claude-opus-4-8",
+  "claude-fable-5-1",
+  "claude-opus-5-5",
   "claude-sonnet-5",
   "claude-haiku-4-5-20251001"
 ];
 var CLAUDE_CLI_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
-function buildClaudeCliConfigSchema(modelName) {
+function buildEffortConfigSchema(modelName) {
   return z.strictObject({
     reasoning: z.strictObject({
       effort: z.enum(CLAUDE_CLI_EFFORTS).meta({
@@ -373,32 +616,51 @@ function buildClaudeCliConfigSchema(modelName) {
     description: `Strict claude-cli config for model ${modelName}. Text-only, no sampling knobs, effort-based reasoning.`
   });
 }
-var ClaudeFable5ConfigSchema = buildClaudeCliConfigSchema("claude-fable-5");
-var ClaudeOpus48ConfigSchema = buildClaudeCliConfigSchema("claude-opus-4-8");
-var ClaudeSonnet5ConfigSchema = buildClaudeCliConfigSchema("claude-sonnet-5");
-var ClaudeHaiku45ConfigSchema = buildClaudeCliConfigSchema(
-  "claude-haiku-4-5-20251001"
-);
+function buildHaikuConfigSchema() {
+  return z.strictObject({
+    timeoutMs: z.number().int().positive().max(18e5).optional().meta({
+      title: "Timeout",
+      description: "Logical request timeout in milliseconds; forwarded to the CLI runner."
+    })
+  }).meta({
+    title: "claude-haiku-4-5-20251001Config",
+    description: "Strict claude-cli config for claude-haiku-4-5-20251001. No reasoning key: the CLI drops --effort."
+  });
+}
+var ClaudeFable51ConfigSchema = buildEffortConfigSchema("claude-fable-5-1");
+var ClaudeOpus55ConfigSchema = buildEffortConfigSchema("claude-opus-5-5");
+var ClaudeSonnet5ConfigSchema = buildEffortConfigSchema("claude-sonnet-5");
+var ClaudeHaiku45ConfigSchema = buildHaikuConfigSchema();
 var CONFIG_SCHEMAS = {
-  "claude-fable-5": ClaudeFable5ConfigSchema,
-  "claude-opus-4-8": ClaudeOpus48ConfigSchema,
+  "claude-fable-5-1": ClaudeFable51ConfigSchema,
+  "claude-opus-5-5": ClaudeOpus55ConfigSchema,
   "claude-sonnet-5": ClaudeSonnet5ConfigSchema,
   "claude-haiku-4-5-20251001": ClaudeHaiku45ConfigSchema
 };
+var CLAUDE_CLI_LIMITS = {
+  "claude-fable-5-1": { contextWindow: 1e6, maxOutputTokens: 64e3 },
+  "claude-opus-5-5": { contextWindow: 1e6, maxOutputTokens: 128e3 },
+  "claude-sonnet-5": { contextWindow: 1e6, maxOutputTokens: 128e3 },
+  "claude-haiku-4-5-20251001": { contextWindow: 2e5, maxOutputTokens: 32e3 }
+};
 var claudeCliModelDescriptors = CLAUDE_CLI_MODEL_IDS.map(
   (id) => {
     const configSchema = CONFIG_SCHEMAS[id];
     return {
       model: id,
       provider: "claude-cli",
+      limits: CLAUDE_CLI_LIMITS[id],
       capabilities: {
+        // The CLI runs text-only: the adapter rejects every non-text part.
+        inputMimeTypes: [],
         structuredOutput: true,
         nativeStructuredOutput: true,
-        reasoningApi: "level",
-        sampling: "fixed",
-        vision: false
+        ...id !== "claude-haiku-4-5-20251001" ? { reasoningApi: "level" } : {},
+        admittedReasoningEfforts: id === "claude-haiku-4-5-20251001" ? [] : CLAUDE_CLI_EFFORTS,
+        sampling: "fixed"
       },
       configSchema,
+      configKeys: toConfigKeys(configSchema),
       configJsonSchema: toConfigJsonSchema(configSchema),
       validateConfig: zodToStandardSchema(configSchema)
     };
@@ -416,6 +678,6 @@ function claudeCliProvider(opts) {
   };
 }
 
-export { ClaudeFable5ConfigSchema, ClaudeHaiku45ConfigSchema, ClaudeOpus48ConfigSchema, ClaudeSonnet5ConfigSchema, buildClaudeCliRunner, claudeCliAdapter, claudeCliModelDescriptors, claudeCliProvider, claudeCliRegistry };
+export { CLAUDE_CLI_EFFORTS, CLAUDE_CLI_MODEL_IDS, ClaudeFable51ConfigSchema, ClaudeHaiku45ConfigSchema, ClaudeOpus55ConfigSchema, ClaudeSonnet5ConfigSchema, buildClaudeCliRunner, claudeCliAdapter, claudeCliModelDescriptors, claudeCliProvider, claudeCliRegistry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map