@witqq/agent-sdk 0.7.0 → 0.8.0

package/dist/backends/vercel-ai.cjs

@@ -1,6 +1,44 @@
 'use strict';
 
-// src/types.ts
+// src/types/errors.ts
+var RECOVERABLE_CODES = /* @__PURE__ */ new Set([
+  "TIMEOUT" /* TIMEOUT */,
+  "RATE_LIMIT" /* RATE_LIMIT */,
+  "NETWORK" /* NETWORK */,
+  "TOOL_EXECUTION" /* TOOL_EXECUTION */,
+  "MODEL_OVERLOADED" /* MODEL_OVERLOADED */,
+  "PROVIDER_ERROR" /* PROVIDER_ERROR */
+]);
+function isRecoverableErrorCode(code) {
+  return RECOVERABLE_CODES.has(code);
+}
+function classifyAgentError(error) {
+  const msg = (error instanceof Error ? error.message : error).toLowerCase();
+  if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("timedout") || msg.includes("etimedout")) {
+    return "TIMEOUT" /* TIMEOUT */;
+  }
+  if (msg.includes("rate limit") || msg.includes("rate_limit") || msg.includes("429") || msg.includes("too many requests")) {
+    return "RATE_LIMIT" /* RATE_LIMIT */;
+  }
+  if (msg.includes("unauthorized") || msg.includes("401") || msg.includes("auth") && (msg.includes("expired") || msg.includes("invalid") || msg.includes("denied") || msg.includes("failed"))) {
+    return "AUTH_EXPIRED" /* AUTH_EXPIRED */;
+  }
+  if (msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("enotfound") || msg.includes("network") || msg.includes("fetch failed") || msg.includes("socket hang up")) {
+    return "NETWORK" /* NETWORK */;
+  }
+  if (msg.includes("subprocess") || msg.includes("process exited") || msg.includes("spawn") || msg.includes("enoent") || msg.includes("killed")) {
+    return "DEPENDENCY_MISSING" /* DEPENDENCY_MISSING */;
+  }
+  if (msg.includes("abort") || msg.includes("cancel")) {
+    return "ABORTED" /* ABORTED */;
+  }
+  if (msg.includes("500") || msg.includes("502") || msg.includes("503") || msg.includes("internal server error") || msg.includes("service unavailable") || msg.includes("bad gateway") || msg.includes("overloaded")) {
+    return "PROVIDER_ERROR" /* PROVIDER_ERROR */;
+  }
+  return "PROVIDER_ERROR" /* PROVIDER_ERROR */;
+}
+
+// src/types/guards.ts
 function getTextContent(content) {
   if (typeof content === "string") return content;
   return content.filter((p) => p.type === "text").map((p) => p.text).join("\n");
@@ -10,9 +48,18 @@ function getTextContent(content) {
 var AgentSDKError = class extends Error {
   /** @internal Marker for cross-bundle identity checks */
   _agentSDKError = true;
+  /** Machine-readable error code. Prefer values from the ErrorCode enum. */
+  code;
+  /** Whether this error is safe to retry */
+  retryable;
+  /** HTTP status code hint for error classification */
+  httpStatus;
   constructor(message, options) {
     super(message, options);
     this.name = "AgentSDKError";
+    this.code = options?.code;
+    this.retryable = options?.retryable ?? false;
+    this.httpStatus = options?.httpStatus;
   }
   /** Check if an error is an AgentSDKError (works across bundled copies) */
   static is(error) {
@@ -21,38 +68,53 @@ var AgentSDKError = class extends Error {
 };
 var ReentrancyError = class extends AgentSDKError {
   constructor() {
-    super("Agent is already running. Await the current run before starting another.");
+    super("Agent is already running. Await the current run before starting another.", {
+      code: "REENTRANCY" /* REENTRANCY */
+    });
     this.name = "ReentrancyError";
   }
 };
 var DisposedError = class extends AgentSDKError {
   constructor(entity) {
-    super(`${entity} has been disposed and cannot be used.`);
+    super(`${entity} has been disposed and cannot be used.`, {
+      code: "DISPOSED" /* DISPOSED */
+    });
     this.name = "DisposedError";
   }
 };
 var DependencyError = class extends AgentSDKError {
   packageName;
   constructor(packageName) {
-    super(`${packageName} is not installed. Install it: npm install ${packageName}`);
+    super(`${packageName} is not installed. Install it: npm install ${packageName}`, {
+      code: "DEPENDENCY_MISSING" /* DEPENDENCY_MISSING */
+    });
     this.name = "DependencyError";
     this.packageName = packageName;
   }
 };
 var AbortError = class extends AgentSDKError {
   constructor() {
-    super("Agent run was aborted.");
+    super("Agent run was aborted.", { code: "ABORTED" /* ABORTED */ });
     this.name = "AbortError";
   }
 };
 var ToolExecutionError = class extends AgentSDKError {
   toolName;
   constructor(toolName, message, options) {
-    super(`Tool "${toolName}" failed: ${message}`, options);
+    super(`Tool "${toolName}" failed: ${message}`, { ...options, code: "TOOL_EXECUTION" /* TOOL_EXECUTION */ });
     this.name = "ToolExecutionError";
     this.toolName = toolName;
   }
 };
+var ActivityTimeoutError = class extends AgentSDKError {
+  constructor(timeoutMs) {
+    super(`Stream activity timeout: no event received within ${timeoutMs}ms.`, {
+      code: "TIMEOUT" /* TIMEOUT */,
+      retryable: true
+    });
+    this.name = "ActivityTimeoutError";
+  }
+};
 
 // src/base-agent.ts
 var BaseAgent = class {
@@ -60,6 +122,7 @@ var BaseAgent = class {
   abortController = null;
   config;
   _cleanupExternalSignal = null;
+  _streamMiddleware = [];
   /** CLI session ID for persistent mode. Override in backends that support it. */
   get sessionId() {
     return void 0;
@@ -75,8 +138,11 @@ var BaseAgent = class {
     this.state = "running";
     try {
       const messages = [{ role: "user", content: prompt }];
-      const result = await this.executeRun(messages, options, ac.signal);
-      this.enrichAndNotifyUsage(result);
+      const result = await this.withRetry(
+        () => this.executeRun(messages, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
       return result;
     } finally {
       this.cleanupRun();
@@ -88,8 +154,11 @@ var BaseAgent = class {
     const ac = this.createAbortController(options?.signal);
     this.state = "running";
     try {
-      const result = await this.executeRun(messages, options, ac.signal);
-      this.enrichAndNotifyUsage(result);
+      const result = await this.withRetry(
+        () => this.executeRun(messages, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
       return result;
     } finally {
       this.cleanupRun();
@@ -102,13 +171,11 @@ var BaseAgent = class {
     this.state = "running";
     try {
       const messages = [{ role: "user", content: prompt }];
-      const result = await this.executeRunStructured(
-        messages,
-        schema,
-        options,
-        ac.signal
+      const result = await this.withRetry(
+        () => this.executeRunStructured(messages, schema, options, ac.signal),
+        options
       );
-      this.enrichAndNotifyUsage(result);
+      this.enrichAndNotifyUsage(result, options);
       return result;
     } finally {
       this.cleanupRun();
@@ -121,8 +188,10 @@ var BaseAgent = class {
     this.state = "streaming";
     try {
       const messages = [{ role: "user", content: prompt }];
-      const enriched = this.enrichStream(this.executeStream(messages, options, ac.signal));
-      yield* this.heartbeatStream(enriched);
+      yield* this.streamWithRetry(
+        () => this.applyStreamPipeline(this.executeStream(messages, options, ac.signal), options, ac),
+        options
+      );
     } finally {
       this.cleanupRun();
     }
@@ -133,12 +202,37 @@ var BaseAgent = class {
     const ac = this.createAbortController(options?.signal);
     this.state = "streaming";
     try {
-      const enriched = this.enrichStream(this.executeStream(messages, options, ac.signal));
-      yield* this.heartbeatStream(enriched);
+      yield* this.streamWithRetry(
+        () => this.applyStreamPipeline(this.executeStream(messages, options, ac.signal), options, ac),
+        options
+      );
     } finally {
       this.cleanupRun();
     }
   }
+  /** Register a stream middleware. Applied in registration order after built-in transforms. */
+  addStreamMiddleware(middleware) {
+    this.guardDisposed();
+    this._streamMiddleware.push(middleware);
+  }
+  /** Apply built-in transforms (enrich→timeout→heartbeat) then custom middleware */
+  async *applyStreamPipeline(source, options, ac) {
+    let stream = this.enrichStream(source, options);
+    stream = this.activityTimeoutStream(stream, options?.activityTimeoutMs, ac);
+    stream = this.heartbeatStream(stream);
+    if (this._streamMiddleware.length > 0) {
+      const ctx = {
+        model: options.model,
+        backend: this.backendName,
+        abortController: ac,
+        config: Object.freeze({ ...this.config })
+      };
+      for (const mw of this._streamMiddleware) {
+        stream = mw(stream, ctx);
+      }
+    }
+    yield* stream;
+  }
   abort() {
     if (this.abortController) {
       this.abortController.abort();
@@ -161,26 +255,109 @@ var BaseAgent = class {
     this.abort();
     this.state = "disposed";
   }
+  // ─── Retry Logic ─────────────────────────────────────────────
+  /** Check if an error should be retried given the retry configuration. */
+  isRetryableError(error, retry) {
+    if (error instanceof AbortError || error instanceof ReentrancyError || error instanceof DisposedError) {
+      return false;
+    }
+    if (AgentSDKError.is(error)) {
+      if (retry.retryableErrors && retry.retryableErrors.length > 0 && error.code) {
+        return retry.retryableErrors.includes(error.code);
+      }
+      if (error.retryable) return true;
+      if (error.code) return isRecoverableErrorCode(error.code);
+    }
+    return false;
+  }
+  /** Execute a function with retry logic per RetryConfig. */
+  async withRetry(fn, options) {
+    const retry = options?.retry;
+    if (!retry || !retry.maxRetries || retry.maxRetries <= 0) {
+      return fn();
+    }
+    const maxRetries = retry.maxRetries;
+    const initialDelay = retry.initialDelayMs ?? 1e3;
+    const multiplier = retry.backoffMultiplier ?? 2;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastError = err;
+        if (attempt >= maxRetries || !this.isRetryableError(err, retry)) {
+          throw err;
+        }
+        const delay = initialDelay * Math.pow(multiplier, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (options?.signal?.aborted || this.abortController?.signal.aborted) {
+          throw err;
+        }
+      }
+    }
+    throw lastError;
+  }
+  /** Execute a stream factory with pre-stream retry: retries until first event, then committed. */
+  async *streamWithRetry(factory, options) {
+    const retry = options?.retry;
+    if (!retry || !retry.maxRetries || retry.maxRetries <= 0) {
+      yield* factory();
+      return;
+    }
+    const maxRetries = retry.maxRetries;
+    const initialDelay = retry.initialDelayMs ?? 1e3;
+    const multiplier = retry.backoffMultiplier ?? 2;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const stream = factory();
+        const iterator = stream[Symbol.asyncIterator]();
+        const first = await iterator.next();
+        if (first.done) return;
+        yield first.value;
+        while (true) {
+          const next = await iterator.next();
+          if (next.done) break;
+          yield next.value;
+        }
+        return;
+      } catch (err) {
+        if (attempt >= maxRetries || !this.isRetryableError(err, retry)) {
+          throw err;
+        }
+        const delay = initialDelay * Math.pow(multiplier, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (options?.signal?.aborted || this.abortController?.signal.aborted) {
+          throw err;
+        }
+      }
+    }
+  }
+  // ─── CallOptions Resolution ──────────────────────────────────
+  /** Resolve tools to use for this call (per-call override > config default) */
+  resolveTools(options) {
+    return options?.tools ?? this.config.tools ?? [];
+  }
   // ─── Usage Enrichment ───────────────────────────────────────────
   /** Enrich result usage with model/backend and fire onUsage callback */
-  enrichAndNotifyUsage(result) {
+  enrichAndNotifyUsage(result, options) {
     if (result.usage) {
       result.usage = {
         ...result.usage,
-        model: this.config.model,
+        model: options.model,
         backend: this.backendName
       };
       this.callOnUsage(result.usage);
     }
   }
   /** Wrap a stream to enrich usage_update events and fire onUsage callback */
-  async *enrichStream(source) {
+  async *enrichStream(source, options) {
+    const model = options.model;
     for await (const event of source) {
       if (event.type === "usage_update") {
         const usage = {
           promptTokens: event.promptTokens,
           completionTokens: event.completionTokens,
-          model: this.config.model,
+          model,
           backend: this.backendName
         };
         this.callOnUsage(usage);
@@ -250,6 +427,35 @@ var BaseAgent = class {
       heartbeatResolve = null;
     }
   }
+  // ─── Activity Timeout ────────────────────────────────────────
+  /** Wrap a stream to abort on inactivity. Resets timer on every event.
+   *  When timeoutMs is not set, passes through directly. */
+  async *activityTimeoutStream(source, timeoutMs, ac) {
+    if (!timeoutMs || timeoutMs <= 0) {
+      yield* source;
+      return;
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    let timerId;
+    try {
+      while (true) {
+        const timeoutPromise = new Promise((_, reject) => {
+          timerId = setTimeout(() => reject(new ActivityTimeoutError(timeoutMs)), timeoutMs);
+        });
+        const result = await Promise.race([iterator.next(), timeoutPromise]);
+        clearTimeout(timerId);
+        if (result.done) break;
+        yield result.value;
+      }
+    } catch (err) {
+      if (err instanceof ActivityTimeoutError) {
+        ac.abort(err);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timerId);
+    }
+  }
   // ─── Guards ───────────────────────────────────────────────────
   guardReentrancy() {
     if (this.state === "running" || this.state === "streaming") {
@@ -349,35 +555,33 @@ function extractSchemaFromDef(schema) {
 }
 
 // src/backends/vercel-ai.ts
-var sdkModule = null;
-var compatModule = null;
+var _sdkMock = null;
+var _compatMock = null;
 async function loadSDK() {
-  if (sdkModule) return sdkModule;
+  if (_sdkMock) return _sdkMock;
   try {
-    sdkModule = await import('ai');
-    return sdkModule;
+    return await import('ai');
   } catch {
     throw new DependencyError("ai");
   }
 }
 async function loadCompat() {
-  if (compatModule) return compatModule;
+  if (_compatMock) return _compatMock;
   try {
-    compatModule = await import('@ai-sdk/openai-compatible');
-    return compatModule;
+    return await import('@ai-sdk/openai-compatible');
   } catch {
     throw new DependencyError("@ai-sdk/openai-compatible");
   }
 }
 function _injectSDK(mock) {
-  sdkModule = mock;
+  _sdkMock = mock;
 }
 function _injectCompat(mock) {
-  compatModule = mock;
+  _compatMock = mock;
 }
 function _resetSDK() {
-  sdkModule = null;
-  compatModule = null;
+  _sdkMock = null;
+  _compatMock = null;
 }
 var DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
 var DEFAULT_PROVIDER = "openrouter";
@@ -423,13 +627,14 @@ function mapToolsToSDK(sdk, tools, config, sessionApprovals, permissionStore, si
   return toolMap;
 }
 function wrapToolExecute(ourTool, supervisor, sessionApprovals, permissionStore, signal) {
-  return async (args) => {
+  return async (args, options) => {
     if (ourTool.needsApproval && supervisor?.onPermission) {
       const storeApproved = permissionStore && await permissionStore.isApproved(ourTool.name);
       if (!storeApproved && !sessionApprovals.has(ourTool.name)) {
         const request = {
           toolName: ourTool.name,
-          toolArgs: args ?? {}
+          toolArgs: args ?? {},
+          toolCallId: options?.toolCallId
         };
         const decision = await supervisor.onPermission(
           request,
@@ -536,7 +741,8 @@ function mapStreamPart(part) {
       return {
         type: "error",
         error: p.error instanceof Error ? p.error.message : String(p.error ?? "Tool execution failed"),
-        recoverable: true
+        recoverable: true,
+        code: "TOOL_EXECUTION" /* TOOL_EXECUTION */
       };
     }
     case "reasoning-start":
@@ -557,10 +763,13 @@ function mapStreamPart(part) {
     }
     case "error": {
       const p = part;
+      const errorMsg = p.error instanceof Error ? p.error.message : String(p.error ?? "Unknown error");
+      const code = classifyAgentError(errorMsg);
       return {
         type: "error",
-        error: p.error instanceof Error ? p.error.message : String(p.error ?? "Unknown error"),
-        recoverable: false
+        error: errorMsg,
+        recoverable: isRecoverableErrorCode(code),
+        code
       };
     }
     default:
@@ -576,28 +785,33 @@ var VercelAIAgent = class extends BaseAgent {
     super(config);
     this.backendOptions = backendOptions;
   }
-  async getModel() {
-    if (this.model) return this.model;
+  async getModel(options) {
+    const requestedModel = options.model;
+    const defaultModel = this.config.model;
+    if (requestedModel === defaultModel && this.model) return this.model;
     const compat = await loadCompat();
     const provider = compat.createOpenAICompatible({
       name: this.backendOptions.provider ?? DEFAULT_PROVIDER,
       baseURL: this.backendOptions.baseUrl ?? DEFAULT_BASE_URL,
       apiKey: this.backendOptions.apiKey
     });
-    const modelId = this.config.model ?? "anthropic/claude-sonnet-4-5";
-    this.model = provider.chatModel(modelId);
-    return this.model;
+    const model = provider.chatModel(requestedModel);
+    if (requestedModel === defaultModel) {
+      this.model = model;
+    }
+    return model;
   }
-  async getSDKTools(signal) {
+  async getSDKTools(signal, options) {
     const sdk = await loadSDK();
-    return mapToolsToSDK(sdk, this.config.tools ?? [], this.config, this.sessionApprovals, this.config.permissionStore, signal);
+    const tools = this.resolveTools(options);
+    return mapToolsToSDK(sdk, tools, this.config, this.sessionApprovals, this.config.permissionStore, signal);
   }
   // ─── executeRun ─────────────────────────────────────────────────
-  async executeRun(messages, _options, signal) {
+  async executeRun(messages, options, signal) {
     this.checkAbort(signal);
     const sdk = await loadSDK();
-    const model = await this.getModel();
-    const tools = await this.getSDKTools(signal);
+    const model = await this.getModel(options);
+    const tools = await this.getSDKTools(signal, options);
     const maxTurns = this.config.maxTurns ?? DEFAULT_MAX_TURNS;
     const sdkMessages = messagesToSDK(messages);
     const hasTools = Object.keys(tools).length > 0;
@@ -653,10 +867,10 @@ var VercelAIAgent = class extends BaseAgent {
     };
   }
   // ─── executeRunStructured ───────────────────────────────────────
-  async executeRunStructured(messages, schema, _options, signal) {
+  async executeRunStructured(messages, schema, options, signal) {
     this.checkAbort(signal);
     const sdk = await loadSDK();
-    const model = await this.getModel();
+    const model = await this.getModel(options);
     const sdkMessages = messagesToSDK(messages);
     const jsonSchema = zodToJsonSchema(schema.schema);
     const result = await sdk.generateObject({
@@ -698,11 +912,11 @@ var VercelAIAgent = class extends BaseAgent {
     };
   }
   // ─── executeStream ──────────────────────────────────────────────
-  async *executeStream(messages, _options, signal) {
+  async *executeStream(messages, options, signal) {
     this.checkAbort(signal);
     const sdk = await loadSDK();
-    const model = await this.getModel();
-    const tools = await this.getSDKTools(signal);
+    const model = await this.getModel(options);
+    const tools = await this.getSDKTools(signal, options);
     const maxTurns = this.config.maxTurns ?? DEFAULT_MAX_TURNS;
     const sdkMessages = messagesToSDK(messages);
     const hasTools = Object.keys(tools).length > 0;
@@ -748,9 +962,11 @@ var VercelAIAgent = class extends BaseAgent {
         promptTokens: Number(totalUsage?.inputTokens ?? 0),
         completionTokens: Number(totalUsage?.outputTokens ?? 0)
       };
+      const hasStreamed = finalText.length > 0;
       yield {
         type: "done",
-        finalOutput: finalText || null
+        finalOutput: hasStreamed ? null : finalText || null,
+        ...hasStreamed ? { streamed: true } : {}
       };
     } catch (e) {
       if (signal.aborted) throw new AbortError();
@@ -779,16 +995,33 @@ var VercelAIAgentService = class {
     const baseUrl = (this.options.baseUrl || "https://api.openai.com/v1").replace(/\/+$/, "");
     try {
       const res = await globalThis.fetch(`${baseUrl}/models`, {
-        headers: { Authorization: `Bearer ${this.options.apiKey}` }
+        headers: {
+          Authorization: `Bearer ${this.options.apiKey}`,
+          // OpenRouter requires HTTP-Referer for API access
+          "HTTP-Referer": "https://github.com/nicepkg/agent-sdk"
+        }
       });
       if (!res.ok) {
         return [];
       }
       const body = await res.json();
-      if (!body.data || body.data.length === 0) {
-        return [];
+      if (body.data && Array.isArray(body.data)) {
+        return body.data.filter((m) => typeof m.id === "string").map((m) => ({
+          id: m.id,
+          ...typeof m.name === "string" && { name: m.name },
+          ...typeof m.description === "string" && { description: m.description },
+          ...typeof m.context_length === "number" && { contextWindow: m.context_length }
+        }));
+      }
+      if (Array.isArray(body)) {
+        return body.filter((m) => typeof m.id === "string").map((m) => ({
+          id: m.id,
+          ...typeof m.name === "string" && { name: m.name },
+          ...typeof m.description === "string" && { description: m.description },
+          ...typeof m.context_length === "number" && { contextWindow: m.context_length }
+        }));
       }
-      return body.data.map((m) => ({ id: m.id }));
+      return [];
     } catch {
       return [];
     }