@zihin/agent-client 0.8.0 → 0.9.0

package/dist/index.js

@@ -24,10 +24,10 @@ __export(index_exports, {
   DEFAULT_LIMITS: () => DEFAULT_LIMITS,
   MAX_TASK_PAYLOAD_BYTES: () => MAX_TASK_PAYLOAD_BYTES,
   OPERATION_TIMEOUT_MS: () => OPERATION_TIMEOUT_MS,
-  ZihinAgentClient: () => ZihinAgentClient,
+  ZihinAgentClient: () => ZihinAgentClient2,
   ZihinAgentError: () => ZihinAgentError,
   classifyStreamErrorKind: () => classifyStreamErrorKind,
-  createClient: () => createClient,
+  createClient: () => createClient2,
   errorFromDoneChunk: () => errorFromDoneChunk,
   errorFromOutcome: () => errorFromOutcome,
   errorFromStreamChunk: () => errorFromStreamChunk,
@@ -91,16 +91,11 @@ function isTerminalStatus(status) {
   return !RUNNING_STATUSES.has(status.toLowerCase().replace(/-/g, "_"));
 }
 var _warnedDeprecations = /* @__PURE__ */ new Set();
-function warnDeprecatedOnce(code, message) {
+function warnDeprecatedOnce(code, message, warn) {
   if (_warnedDeprecations.has(code)) return;
   _warnedDeprecations.add(code);
   try {
-    const proc = globalThis.process;
-    if (typeof proc?.emitWarning === "function") {
-      proc.emitWarning(message, { type: "ZihinDeprecationWarning", code });
-      return;
-    }
-    console.warn(`[${code}] ${message}`);
+    warn?.(code, message);
   } catch {
   }
 }
@@ -498,8 +493,11 @@ function normalizeTimeoutMs(value, label = "timeoutMs") {
 var DEFAULT_MAX_RETRIES = 2;
 var DEFAULT_MAX_EVENT_BYTES = 1 * 1024 * 1024;
 var DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+function globalFetch() {
+  return typeof fetch === "function" ? fetch : void 0;
+}
 function resolveFetch(injected) {
-  const f = injected ?? globalThis.fetch;
+  const f = injected ?? globalFetch();
   if (typeof f !== "function") {
     throw new ZihinAgentError("config", "Global fetch is unavailable in this runtime.");
   }
@@ -518,7 +516,13 @@ function resolveConfig(config) {
   if (!urlCheck.valid) {
     throw new ZihinAgentError("config", urlCheck.error || "Invalid base URL.");
   }
-  if (typeof (config.fetch ?? globalThis.fetch) !== "function") {
+  if (typeof config.runtime?.sleep !== "function") {
+    throw new ZihinAgentError(
+      "config",
+      'A runtime is required: import from "@zihin/agent-client" (default runtime) or pass `runtime` to the "@zihin/agent-client/core" client.'
+    );
+  }
+  if (typeof (config.fetch ?? globalFetch()) !== "function") {
     throw new ZihinAgentError(
       "config",
       "Global fetch is unavailable in this runtime. Use Node >=20.16 or pass a `fetch` implementation in the client config."
@@ -532,6 +536,7 @@ function resolveConfig(config) {
     maxStreamEventBytes: config.maxStreamEventBytes ?? DEFAULT_MAX_EVENT_BYTES,
     maxStreamTotalBytes: config.maxStreamTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES,
     fetchImpl: config.fetch,
+    runtime: config.runtime,
     onRetry: config.onRetry,
     onError: config.onError
   };
@@ -564,35 +569,32 @@ function buildHeaders(apiKey, extra = {}) {
     ...extra
   };
 }
-function delay(ms, signal, meta) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(new ZihinAgentError("aborted", "Request was aborted by the caller.", meta));
-      return;
-    }
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(new ZihinAgentError("aborted", "Request was aborted by the caller.", meta));
-    };
-    const timer = setTimeout(() => {
-      if (signal) signal.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    if (signal) signal.addEventListener("abort", onAbort, { once: true });
-  });
+async function delay(runtime, ms, signal, meta) {
+  const aborted = () => new ZihinAgentError("aborted", "Request was aborted by the caller.", meta);
+  if (signal?.aborted) throw aborted();
+  try {
+    await runtime.sleep(ms, signal);
+  } catch {
+    throw aborted();
+  }
 }
 function backoffMs(attempt) {
   const base = Math.min(1e3 * 2 ** attempt, 1e4);
   return base / 2 + Math.random() * (base / 2);
 }
-function createDeadline(timeoutMs, callerSignal) {
+function createDeadline(runtime, timeoutMs, callerSignal) {
   const controller = new AbortController();
+  const clock = new AbortController();
   let timedOut = false;
   let abortedByCaller = false;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    controller.abort();
-  }, timeoutMs);
+  runtime.sleep(timeoutMs, clock.signal).then(
+    () => {
+      timedOut = true;
+      controller.abort();
+    },
+    () => {
+    }
+  );
   const onAbort = () => {
     abortedByCaller = true;
     controller.abort();
@@ -604,7 +606,7 @@ function createDeadline(timeoutMs, callerSignal) {
   return {
     signal: controller.signal,
     dispose: () => {
-      clearTimeout(timer);
+      clock.abort();
       if (callerSignal) callerSignal.removeEventListener("abort", onAbort);
     },
     timedOut: () => timedOut,
@@ -635,7 +637,7 @@ async function requestBuffered(args) {
   const budget = budgetTracker({ ...args, endpoint });
   let lastError = null;
   for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
-    const d = createDeadline(args.timeoutMs, args.callerSignal);
+    const d = createDeadline(args.runtime, args.timeoutMs, args.callerSignal);
     try {
       const res = await doFetch(args.url, {
         method: args.method,
@@ -662,7 +664,7 @@ async function requestBuffered(args) {
         }
         d.dispose();
         args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "status", status: res.status });
-        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
+        await delay(args.runtime, wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       const text = peeked ?? await res.text();
@@ -681,7 +683,7 @@ async function requestBuffered(args) {
       const wait = backoffMs(attempt);
       if (budget.overheadLeft() <= wait) throw lastError;
       args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "network" });
-      await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
+      await delay(args.runtime, wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
     }
   }
   throw lastError ?? new ZihinAgentError("unknown", "Max retries exceeded.", { endpoint });
@@ -692,7 +694,7 @@ async function openStream(args) {
   const budget = budgetTracker({ ...args, endpoint });
   const policy = args.idempotent ? "idempotent" : "side-effecting";
   for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
-    const d = createDeadline(args.timeoutMs, args.callerSignal);
+    const d = createDeadline(args.runtime, args.timeoutMs, args.callerSignal);
     try {
       const response = await doFetch(args.url, {
         method: "POST",
@@ -712,7 +714,7 @@ async function openStream(args) {
         }
         d.dispose();
         args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "status", status: 429 });
-        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
+        await delay(args.runtime, wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       if (wait !== null && budget.overheadLeft() > wait) {
@@ -728,7 +730,7 @@ async function openStream(args) {
           reason: "status",
           status: response.status
         });
-        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
+        await delay(args.runtime, wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       return { response, deadline: d, endpoint };
@@ -743,7 +745,7 @@ async function openStream(args) {
       const wait = backoffMs(attempt);
       if (policy === "idempotent" && netErr.retryable && attempt < args.maxRetries && budget.overheadLeft() > wait) {
         args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "network" });
-        await delay(wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
+        await delay(args.runtime, wait, args.callerSignal, { endpoint, attempts: attempt + 1 });
         continue;
       }
       throw netErr;
@@ -772,6 +774,7 @@ async function requestJson(cfg, args) {
     policy: args.policy,
     callerSignal: args.signal,
     fetchImpl: cfg.fetchImpl,
+    runtime: cfg.runtime,
     onRetry: cfg.onRetry
   });
   if (!res.ok) {
@@ -806,6 +809,7 @@ async function listAgents(cfg, opts = {}) {
     policy: "idempotent",
     callerSignal: opts.signal,
     fetchImpl: cfg.fetchImpl,
+    runtime: cfg.runtime,
     onRetry: cfg.onRetry
   });
   if (!res.ok) {
@@ -1093,7 +1097,7 @@ function buildRequestBody(params, normalizedTimeoutMs) {
   }
   return body;
 }
-function validateParams(params) {
+function validateParams(params, warn) {
   if (!params.agentId) {
     throw new ZihinAgentError("config", "agentId is required.");
   }
@@ -1107,7 +1111,7 @@ function validateParams(params) {
     }
   }
   validateStructuredInput(params);
-  warnDeprecatedOptions(params);
+  warnDeprecatedOptions(params, warn);
   if (params.options?.timeoutMs !== void 0) {
     normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs");
   }
@@ -1118,19 +1122,21 @@ function validateParams(params) {
     }
   }
 }
-function warnDeprecatedOptions(params) {
+function warnDeprecatedOptions(params, warn) {
   const o = params.options;
   if (!o) return;
   if (o.jitMode !== void 0) {
     warnDeprecatedOnce(
       "ZIHIN_DEP001",
-      "`options.jitMode` is deprecated and has no effect (the server discontinued it). Remove it; it will be dropped from the SDK in 1.0."
+      "`options.jitMode` is deprecated and has no effect (the server discontinued it). Remove it; it will be dropped from the SDK in 1.0.",
+      warn
     );
   }
   if (o.temperature !== void 0 || o.maxTokens !== void 0) {
     warnDeprecatedOnce(
       "ZIHIN_DEP002",
-      "`options.temperature`/`options.maxTokens` have no effect: the agent's own configuration (`llm_config`) decides them \u2014 change it in the Zihin console or with `update_agent`. They will be dropped from the SDK in 1.0."
+      "`options.temperature`/`options.maxTokens` have no effect: the agent's own configuration (`llm_config`) decides them \u2014 change it in the Zihin console or with `update_agent`. They will be dropped from the SDK in 1.0.",
+      warn
     );
   }
 }
@@ -1303,7 +1309,7 @@ function checkInputCapability(params, chunk) {
 var TURN_EVENTS = /* @__PURE__ */ new Set(["phase", "thinking", "tool", "action_proposed", "action_forwarded", "token", "response", "metrics", "done"]);
 async function* streamAgent(cfg, rawParams) {
   const params = snapshotStructuredInput(rawParams);
-  validateParams(params);
+  validateParams(params, cfg.runtime.warn);
   const callerTimeoutMs = params.options?.timeoutMs !== void 0 ? normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs") : void 0;
   const timeoutMs = callerTimeoutMs !== void 0 ? callerTimeoutMs + DEADLINE_GRACE_MS : resolveTimeout(cfg, "stream");
   const reportedMs = callerTimeoutMs ?? timeoutMs;
@@ -1319,6 +1325,7 @@ async function* streamAgent(cfg, rawParams) {
     maxRetries: cfg.maxRetries,
     callerSignal: params.signal,
     fetchImpl: cfg.fetchImpl,
+    runtime: cfg.runtime,
     onRetry: cfg.onRetry,
     // Retry do POST só ANTES dos headers chegarem. O que o torna seguro é a ordem do BE: o SSE faz
     // `flushHeaders()` antes de reservar o id e antes de qualquer trabalho do turno, então falhar
@@ -1868,6 +1875,7 @@ async function dispatchAgent(cfg, params) {
     // S1: nunca duplica disparo por erro de rede
     callerSignal: params.signal,
     fetchImpl: cfg.fetchImpl,
+    runtime: cfg.runtime,
     onRetry: cfg.onRetry
   });
   if (!res.ok) {
@@ -2051,6 +2059,7 @@ async function deleteTrigger(cfg, params) {
     // DELETE é idempotente
     callerSignal: params.signal,
     fetchImpl: cfg.fetchImpl,
+    runtime: cfg.runtime,
     onRetry: cfg.onRetry
   });
   if (!res.ok) {
@@ -2193,9 +2202,38 @@ var ZihinAgentClient = class {
     return this.guard(listAgents(this.cfg, opts));
   }
 };
-function createClient(config) {
-  return new ZihinAgentClient(config);
-}
+
+// src/runtime-node.ts
+var defaultRuntime = {
+  sleep: (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  }),
+  /**
+   * Tipo PRÓPRIO (`ZihinDeprecationWarning`), não `DeprecationWarning`: com `--throw-deprecation`
+   * o Node transformaria o aviso em exceção e quebraria a chamada de quem só precisava ser avisado.
+   * Fora do Node (browser/edge), `console.warn`.
+   */
+  warn: (code, message) => {
+    const proc = globalThis.process;
+    if (typeof proc?.emitWarning === "function") {
+      proc.emitWarning(message, { type: "ZihinDeprecationWarning", code });
+      return;
+    }
+    console.warn(`[${code}] ${message}`);
+  }
+};
 
 // src/signing.ts
 function loadNodeCrypto() {
@@ -2224,6 +2262,16 @@ function signRequest(payload, secretKey, timestamp) {
     "X-Zihin-Nonce": nonce
   };
 }
+
+// src/index.ts
+var ZihinAgentClient2 = class extends ZihinAgentClient {
+  constructor(config) {
+    super({ ...config, runtime: config.runtime ?? defaultRuntime });
+  }
+};
+function createClient2(config) {
+  return new ZihinAgentClient2(config);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEADLINE_GRACE_MS,