@zihin/agent-client 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,33 +1,1304 @@
 "use strict";
-/**
- * @zihin/agent-client — núcleo de invocação de agente Zihin.ai.
- *
- * Padrão híbrido (verificado contra o BE em 2026-06-28):
- *   • Direto:   client.invokeAgent / client.streamAgent  → POST /api/v2/agents/:id/stream
- *   • Triggers: client.createTrigger / dispatchAgent / getExecution  → async + callback
- *   • Auxiliar: client.listAgents  → GET /api/v2/agents (dropdown)
- *
- * Zero dependência de plataforma (n8n / Paperclip). Segurança reusada de `security.ts`.
- *
- * @example
- *   import { createClient } from '@zihin/agent-client';
- *   const zihin = createClient({ apiKey: process.env.ZIHIN_API_KEY! });
- *   const res = await zihin.invokeAgent({ agentId, message: 'Olá' });
- *   console.log(res.content, res.usage, res.sessionId);
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_LIMITS = exports.signRequest = exports.sanitizeApiError = exports.validatePromptSize = exports.validateBaseUrl = exports.validateApiKeyFormat = exports.ZihinAgentError = exports.createClient = exports.ZihinAgentClient = void 0;
-var client_1 = require("./client");
-Object.defineProperty(exports, "ZihinAgentClient", { enumerable: true, get: function () { return client_1.ZihinAgentClient; } });
-Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_1.createClient; } });
-var errors_1 = require("./errors");
-Object.defineProperty(exports, "ZihinAgentError", { enumerable: true, get: function () { return errors_1.ZihinAgentError; } });
-// Primitivas de segurança reutilizáveis pelos shells.
-var security_1 = require("./security");
-Object.defineProperty(exports, "validateApiKeyFormat", { enumerable: true, get: function () { return security_1.validateApiKeyFormat; } });
-Object.defineProperty(exports, "validateBaseUrl", { enumerable: true, get: function () { return security_1.validateBaseUrl; } });
-Object.defineProperty(exports, "validatePromptSize", { enumerable: true, get: function () { return security_1.validatePromptSize; } });
-Object.defineProperty(exports, "sanitizeApiError", { enumerable: true, get: function () { return security_1.sanitizeApiError; } });
-Object.defineProperty(exports, "signRequest", { enumerable: true, get: function () { return security_1.signRequest; } });
-Object.defineProperty(exports, "DEFAULT_LIMITS", { enumerable: true, get: function () { return security_1.DEFAULT_LIMITS; } });
-//# sourceMappingURL=index.js.map
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_LIMITS: () => DEFAULT_LIMITS,
+  ZihinAgentClient: () => ZihinAgentClient,
+  ZihinAgentError: () => ZihinAgentError,
+  createClient: () => createClient,
+  sanitizeApiError: () => sanitizeApiError,
+  signRequest: () => signRequest,
+  validateApiKeyFormat: () => validateApiKeyFormat,
+  validateBaseUrl: () => validateBaseUrl,
+  validatePromptSize: () => validatePromptSize
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/internal.ts
+var _utf8 = new TextEncoder();
+function utf8Len(s) {
+  return _utf8.encode(s).length;
+}
+function rec(x) {
+  return x && typeof x === "object" ? x : {};
+}
+function str(x) {
+  return typeof x === "string" ? x : void 0;
+}
+function num(x) {
+  return typeof x === "number" ? x : void 0;
+}
+function parseUsage(usageRaw) {
+  const u = rec(usageRaw);
+  if (Object.keys(u).length === 0) return void 0;
+  return {
+    inputTokens: num(u.input_tokens) ?? num(u.prompt_tokens),
+    outputTokens: num(u.output_tokens) ?? num(u.completion_tokens),
+    totalTokens: num(u.total_tokens),
+    costUsd: num(u.cost_usd)
+  };
+}
+
+// src/security.ts
+var PRIVATE_IP_PATTERNS = [
+  /^127\./,
+  // 127.0.0.0/8 (localhost)
+  /^10\./,
+  // 10.0.0.0/8 (private)
+  /^172\.(1[6-9]|2[0-9]|3[0-1])\./,
+  // 172.16.0.0/12 (private)
+  /^192\.168\./,
+  // 192.168.0.0/16 (private)
+  /^169\.254\./,
+  // 169.254.0.0/16 (link-local)
+  /^0\./
+  // 0.0.0.0/8
+];
+function parseIpv6(host) {
+  if (!host.includes(":")) return null;
+  let text = host;
+  const words = [];
+  const v4 = /(\d{1,3}(?:\.\d{1,3}){3})$/.exec(text);
+  let tail = [];
+  if (v4) {
+    const octets = v4[1].split(".").map(Number);
+    if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
+    tail = [octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]];
+    text = text.slice(0, v4.index).replace(/:$/, "") || "::";
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const toWords = (part) => {
+    if (!part) return [];
+    const out = [];
+    for (const group of part.split(":")) {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+      out.push(parseInt(group, 16));
+    }
+    return out;
+  };
+  const head = toWords(halves[0]);
+  const rest = halves.length === 2 ? toWords(halves[1]) : [];
+  if (!head || !rest) return null;
+  if (halves.length === 2) {
+    const fill = 8 - (head.length + rest.length + tail.length);
+    if (fill < 0) return null;
+    words.push(...head, ...Array(fill).fill(0), ...rest, ...tail);
+  } else {
+    words.push(...head, ...tail);
+  }
+  return words.length === 8 ? words : null;
+}
+function isPrivateIpv6(words) {
+  const [w0, w1, w2, w3, w4, w5] = words;
+  const allZero = words.every((w) => w === 0);
+  if (allZero) return true;
+  if (words.slice(0, 7).every((w) => w === 0) && words[7] === 1) return true;
+  if (w0 === 0 && w1 === 0 && w2 === 0 && w3 === 0 && w4 === 0 && (w5 === 0 || w5 === 65535)) {
+    const v4 = `${words[6] >> 8}.${words[6] & 255}.${words[7] >> 8}.${words[7] & 255}`;
+    return PRIVATE_IP_PATTERNS.some((p) => p.test(v4));
+  }
+  if ((w0 >> 8 & 254) === 252) return true;
+  if ((w0 & 65472) === 65152) return true;
+  if ((w0 & 65472) === 65216) return true;
+  return false;
+}
+function bareHostname(hostname) {
+  const bare = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  return bare.length > 1 && bare.endsWith(".") ? bare.replace(/\.+$/, "") : bare;
+}
+var BLOCKED_HOSTNAMES = [
+  "localhost",
+  "localtest.me",
+  "metadata.google.internal",
+  // GCP metadata
+  "169.254.169.254",
+  // AWS/Azure/GCP metadata
+  "metadata.azure.com"
+];
+var ALLOWED_ZIHIN_DOMAINS = [
+  "llm.zihin.ai",
+  "api.zihin.ai",
+  "staging.llm.zihin.ai",
+  "dev.llm.zihin.ai"
+];
+function validateBaseUrl(url, options = {}) {
+  if (!url || url.trim() === "") {
+    return { valid: true, sanitizedUrl: "https://llm.zihin.ai" };
+  }
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname.length > 1 && parsed.hostname.endsWith(".")) {
+      parsed.hostname = parsed.hostname.replace(/\.+$/, "");
+    }
+    const hostname = bareHostname(parsed.hostname);
+    const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+    if (isLocalhost && options.allowLocalhost) {
+      const sanitizedUrl2 = parsed.origin + parsed.pathname.replace(/\/+$/, "");
+      return { valid: true, sanitizedUrl: sanitizedUrl2 };
+    }
+    if (!options.allowHttp && parsed.protocol !== "https:") {
+      return {
+        valid: false,
+        error: "Only HTTPS URLs are allowed for security reasons"
+      };
+    }
+    const ipv6 = parseIpv6(hostname);
+    if (ipv6) {
+      if (isPrivateIpv6(ipv6)) {
+        return { valid: false, error: "Private IP addresses are not allowed" };
+      }
+    } else {
+      for (const pattern of PRIVATE_IP_PATTERNS) {
+        if (pattern.test(hostname)) {
+          return { valid: false, error: "Private IP addresses are not allowed" };
+        }
+      }
+    }
+    for (const blocked of BLOCKED_HOSTNAMES) {
+      if (blocked.startsWith("*")) {
+        const suffix = blocked.slice(1);
+        if (hostname.endsWith(suffix)) {
+          return { valid: false, error: "This hostname is not allowed" };
+        }
+      } else if (hostname === blocked || hostname.endsWith("." + blocked)) {
+        return { valid: false, error: "This hostname is not allowed" };
+      }
+    }
+    if (!options.allowCustomDomains) {
+      const isAllowed = ALLOWED_ZIHIN_DOMAINS.some(
+        (domain) => hostname === domain || hostname.endsWith("." + domain)
+      );
+      if (!isAllowed) {
+        return {
+          valid: false,
+          error: `Only Zihin domains are allowed. Use 'allowCustomBaseUrl' for custom endpoints.`
+        };
+      }
+    }
+    const sanitizedUrl = parsed.origin + parsed.pathname.replace(/\/+$/, "");
+    return { valid: true, sanitizedUrl };
+  } catch {
+    return { valid: false, error: "Invalid URL format" };
+  }
+}
+var DEFAULT_LIMITS = {
+  maxPromptBytes: 100 * 1024,
+  // 100KB
+  maxMessageCount: 100,
+  maxSingleMessageBytes: 50 * 1024,
+  // 50KB
+  maxTotalPayloadBytes: 500 * 1024
+  // 500KB
+};
+function validatePromptSize(prompt, limits = {}) {
+  const effectiveLimits = { ...DEFAULT_LIMITS, ...limits };
+  const bytes = utf8Len(prompt);
+  if (bytes > effectiveLimits.maxPromptBytes) {
+    return {
+      valid: false,
+      error: `Prompt size (${Math.round(bytes / 1024)}KB) exceeds maximum allowed (${Math.round(
+        effectiveLimits.maxPromptBytes / 1024
+      )}KB)`,
+      details: { promptBytes: bytes }
+    };
+  }
+  return { valid: true, details: { promptBytes: bytes } };
+}
+var SENSITIVE_PATTERNS = [
+  /zhn_(?:live|test|dev)_[a-zA-Z0-9]+/g,
+  // API keys
+  /Bearer\s+[a-zA-Z0-9._-]+/gi,
+  // Bearer tokens
+  /at\s+[\w./<>]+\s*\(.*:\d+:\d+\)/g,
+  // Stack trace lines
+  /^\s+at\s+.+$/gm,
+  // Stack traces
+  /Error:\s*.*\n\s+at/g
+  // Error stack beginnings
+];
+var ERROR_CODE_MAP = {
+  RATE_LIMIT_EXCEEDED: "Rate limit exceeded. Please wait before retrying.",
+  UNAUTHORIZED: "Authentication failed. Please check your API credentials.",
+  FORBIDDEN: "This API key lacks permission for this action. Use an admin/editor key (member keys cannot create triggers or read telemetry).",
+  INVALID_MODEL: "The specified model is not available.",
+  INTERNAL_ERROR: "An internal error occurred. Please try again later.",
+  TIMEOUT: "Request timed out. Try increasing the timeout.",
+  INVALID_REQUEST: "The request was malformed. Please check your input.",
+  INSUFFICIENT_CREDITS: "Insufficient credits. Please check your account balance.",
+  CONTEXT_LENGTH_EXCEEDED: "The input exceeds the model context length limit.",
+  AGENT_NOT_FOUND: "Agent not found or not active for this tenant."
+};
+function sanitizeApiError(error) {
+  let message = "An unexpected error occurred";
+  let code;
+  let retryable = false;
+  let retryAfter;
+  if (typeof error === "object" && error !== null) {
+    const err = error;
+    const nested = err.error && typeof err.error === "object" ? err.error : void 0;
+    const codeRaw = nested?.code ?? (typeof err.error === "string" ? err.error : err.code);
+    code = typeof codeRaw === "string" ? codeRaw : void 0;
+    const rawMessage = nested?.message ?? err.message;
+    if (code && ERROR_CODE_MAP[code]) {
+      message = ERROR_CODE_MAP[code];
+    } else if (typeof rawMessage === "string" && rawMessage) {
+      message = rawMessage;
+    }
+    if (code === "RATE_LIMIT_EXCEEDED" || code === "TIMEOUT") {
+      retryable = true;
+      retryAfter = err.retryAfter || 60;
+    }
+    if (message.length > 2e3) message = message.slice(0, 2e3);
+    for (const pattern of SENSITIVE_PATTERNS) {
+      message = message.replace(pattern, "[REDACTED]");
+    }
+  } else if (typeof error === "string") {
+    message = error;
+    if (message.length > 2e3) message = message.slice(0, 2e3);
+    for (const pattern of SENSITIVE_PATTERNS) {
+      message = message.replace(pattern, "[REDACTED]");
+    }
+  }
+  if (message.length > 500) {
+    message = message.substring(0, 500) + "...";
+  }
+  return { message, code, retryable, retryAfter };
+}
+var API_KEY_PATTERN = /^zhn_(live|test|dev)_[a-zA-Z0-9]{20,}$/;
+function validateApiKeyFormat(apiKey) {
+  if (!apiKey || apiKey.trim() === "") {
+    return { valid: false, error: "API key is required" };
+  }
+  const trimmed = apiKey.trim();
+  if (!API_KEY_PATTERN.test(trimmed)) {
+    return {
+      valid: false,
+      error: "Invalid API key format. Expected: zhn_live_xxx, zhn_test_xxx or zhn_dev_xxx"
+    };
+  }
+  const environment = trimmed.startsWith("zhn_live_") ? "live" : trimmed.startsWith("zhn_test_") ? "test" : "dev";
+  return { valid: true, environment };
+}
+
+// src/errors.ts
+var ZihinAgentError = class _ZihinAgentError extends Error {
+  constructor(kind, message, opts = {}) {
+    super(buildMessage(message, opts));
+    this.name = "ZihinAgentError";
+    this.kind = kind;
+    this.status = opts.status;
+    this.code = opts.code;
+    this.requestId = opts.requestId;
+    this.attempts = opts.attempts;
+    this.endpoint = opts.endpoint;
+    this.retryable = opts.retryable ?? (kind === "rate_limit" || kind === "server" || kind === "network");
+    Object.setPrototypeOf(this, _ZihinAgentError.prototype);
+  }
+};
+function buildMessage(base, opts) {
+  let s = base;
+  if (opts.endpoint) s += ` [${opts.endpoint}]`;
+  if (opts.attempts && opts.attempts > 1) s += ` (after ${opts.attempts} attempts)`;
+  if (opts.requestId) s += ` (request_id: ${opts.requestId})`;
+  return s;
+}
+function extractRequestId(body) {
+  const b = rec(body);
+  return str(b.request_id) ?? str(b.requestId) ?? str(rec(b.error).request_id);
+}
+function errorFromResponse(status, body, meta = {}) {
+  const sanitized = sanitizeApiError(body);
+  const message = sanitized.message;
+  const code = sanitized.code;
+  const base = { status, code, requestId: extractRequestId(body), ...meta };
+  if (status === 401) return new ZihinAgentError("auth", message || "Authentication failed.", base);
+  if (status === 403)
+    return new ZihinAgentError(
+      "auth",
+      message || "This API key lacks permission. Use an admin/editor key (member keys cannot create triggers or read telemetry).",
+      base
+    );
+  if (status === 404) return new ZihinAgentError("not_found", message || "Resource not found.", base);
+  if (status === 429)
+    return new ZihinAgentError("rate_limit", message || "Rate limit exceeded.", { ...base, retryable: true });
+  if (status >= 500)
+    return new ZihinAgentError("server", message || `Server error (${status}).`, { ...base, retryable: true });
+  return new ZihinAgentError("unknown", message || `Request failed (${status}).`, base);
+}
+var NON_RETRYABLE_NET = /^(ENOTFOUND|EAI_AGAIN|CERT_|ERR_TLS|UNABLE_TO_VERIFY|DEPTH_ZERO)/;
+function errorFromThrow(err, timeoutMs, meta = {}) {
+  if (err instanceof ZihinAgentError) return err;
+  const name = err?.name;
+  if (name === "TimeoutError") {
+    return new ZihinAgentError("timeout", `Request timed out after ${timeoutMs ?? "?"}ms.`, {
+      ...meta,
+      retryable: false
+    });
+  }
+  if (name === "AbortError") {
+    return new ZihinAgentError("aborted", "Request was aborted by the caller.", { ...meta, retryable: false });
+  }
+  const cause = err?.cause;
+  const causeCode = cause?.code;
+  const sanitized = sanitizeApiError(err);
+  const detail = causeCode || sanitized.message || "Network error";
+  const retryable = causeCode ? !NON_RETRYABLE_NET.test(causeCode) : true;
+  return new ZihinAgentError("network", `Network error: ${detail}`, { ...meta, retryable });
+}
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://llm.zihin.ai";
+var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_MAX_EVENT_BYTES = 1 * 1024 * 1024;
+var DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+function resolveFetch(injected) {
+  const f = injected ?? globalThis.fetch;
+  if (typeof f !== "function") {
+    throw new ZihinAgentError("config", "Global fetch is unavailable in this runtime.");
+  }
+  return f;
+}
+function resolveConfig(config) {
+  const keyCheck = validateApiKeyFormat(config.apiKey ?? "");
+  if (!keyCheck.valid) {
+    throw new ZihinAgentError("config", keyCheck.error || "Invalid API key.");
+  }
+  const urlCheck = validateBaseUrl(config.baseUrl ?? "", {
+    allowCustomDomains: config.allowCustomBaseUrl,
+    allowHttp: config.allowHttp,
+    allowLocalhost: config.allowHttp
+  });
+  if (!urlCheck.valid) {
+    throw new ZihinAgentError("config", urlCheck.error || "Invalid base URL.");
+  }
+  if (typeof (config.fetch ?? globalThis.fetch) !== "function") {
+    throw new ZihinAgentError(
+      "config",
+      "Global fetch is unavailable in this runtime. Use Node >=18 or pass a `fetch` implementation in the client config."
+    );
+  }
+  return {
+    apiKey: config.apiKey.trim(),
+    baseUrl: urlCheck.sanitizedUrl || DEFAULT_BASE_URL,
+    timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+    maxStreamEventBytes: config.maxStreamEventBytes ?? DEFAULT_MAX_EVENT_BYTES,
+    maxStreamTotalBytes: config.maxStreamTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES,
+    fetchImpl: config.fetch,
+    onRetry: config.onRetry,
+    onError: config.onError
+  };
+}
+function endpointLabel(method, url) {
+  try {
+    const u = new URL(url);
+    return `${method} ${u.host}${u.pathname}`;
+  } catch {
+    return method;
+  }
+}
+function retryAfterMs(headers, capMs = 3e4) {
+  const raw = headers.get("retry-after");
+  if (!raw) return void 0;
+  const secs = Number(raw);
+  if (Number.isFinite(secs)) return Math.min(Math.max(0, secs * 1e3), capMs);
+  const when = Date.parse(raw);
+  if (Number.isFinite(when)) return Math.min(Math.max(0, when - Date.now()), capMs);
+  return void 0;
+}
+function buildHeaders(apiKey, extra = {}) {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "X-Api-Key": apiKey,
+    ...extra
+  };
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new ZihinAgentError("aborted", "Request was aborted by the caller."));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new ZihinAgentError("aborted", "Request was aborted by the caller."));
+    };
+    const timer = setTimeout(() => {
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    if (signal) signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function backoffMs(attempt) {
+  const base = Math.min(1e3 * 2 ** attempt, 1e4);
+  return base / 2 + Math.random() * (base / 2);
+}
+function createDeadline(timeoutMs, callerSignal) {
+  const controller = new AbortController();
+  let timedOut = false;
+  let abortedByCaller = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  const onAbort = () => {
+    abortedByCaller = true;
+    controller.abort();
+  };
+  if (callerSignal) {
+    if (callerSignal.aborted) onAbort();
+    else callerSignal.addEventListener("abort", onAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timer);
+      if (callerSignal) callerSignal.removeEventListener("abort", onAbort);
+    },
+    timedOut: () => timedOut,
+    abortedByCaller: () => abortedByCaller
+  };
+}
+function shouldRetryStatus(status, policy) {
+  if (policy === "idempotent") return status >= 500 || status === 429;
+  return status === 429 || status === 503;
+}
+async function requestBuffered(args) {
+  const endpoint = endpointLabel(args.method, args.url);
+  const doFetch = resolveFetch(args.fetchImpl);
+  let lastError = null;
+  for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
+    const d = createDeadline(args.timeoutMs, args.callerSignal);
+    try {
+      const res = await doFetch(args.url, {
+        method: args.method,
+        headers: args.headers,
+        body: args.body,
+        signal: d.signal,
+        redirect: "error",
+        // 3xx para outro host vazaria a X-Api-Key
+        cache: "no-store"
+        // evita cache stale (ex.: polling em Next.js/edge)
+      });
+      if (shouldRetryStatus(res.status, args.policy) && attempt < args.maxRetries) {
+        const wait = retryAfterMs(res.headers) ?? backoffMs(attempt);
+        try {
+          await res.body?.cancel();
+        } catch {
+        }
+        d.dispose();
+        args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "status", status: res.status });
+        await delay(wait, args.callerSignal);
+        continue;
+      }
+      const text = await res.text();
+      d.dispose();
+      return { status: res.status, ok: res.ok, text, endpoint, attempts: attempt + 1 };
+    } catch (err) {
+      d.dispose();
+      const meta = { endpoint, attempts: attempt + 1 };
+      if (d.timedOut()) throw new ZihinAgentError("timeout", `Request timed out after ${args.timeoutMs}ms.`, meta);
+      if (d.abortedByCaller())
+        throw new ZihinAgentError("aborted", "Request was aborted by the caller.", meta);
+      lastError = errorFromThrow(err, args.timeoutMs, meta);
+      const canRetry = args.policy === "idempotent" && lastError.retryable && attempt < args.maxRetries;
+      if (!canRetry) throw lastError;
+      const wait = backoffMs(attempt);
+      args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "network" });
+      await delay(wait, args.callerSignal);
+    }
+  }
+  throw lastError ?? new ZihinAgentError("unknown", "Max retries exceeded.", { endpoint });
+}
+async function openStream(args) {
+  const endpoint = endpointLabel("POST", args.url);
+  const doFetch = resolveFetch(args.fetchImpl);
+  for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
+    const d = createDeadline(args.timeoutMs, args.callerSignal);
+    try {
+      const response = await doFetch(args.url, {
+        method: "POST",
+        headers: { ...args.headers, Accept: "text/event-stream" },
+        body: args.body,
+        signal: d.signal,
+        redirect: "error",
+        cache: "no-store"
+      });
+      if (shouldRetryStatus(response.status, "side-effecting") && attempt < args.maxRetries) {
+        const wait = retryAfterMs(response.headers) ?? backoffMs(attempt);
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        d.dispose();
+        args.onRetry?.({
+          endpoint,
+          attempt: attempt + 1,
+          delayMs: wait,
+          reason: "status",
+          status: response.status
+        });
+        await delay(wait, args.callerSignal);
+        continue;
+      }
+      return { response, deadline: d, endpoint };
+    } catch (err) {
+      d.dispose();
+      const meta = { endpoint, attempts: attempt + 1 };
+      if (d.timedOut()) throw new ZihinAgentError("timeout", `Request timed out after ${args.timeoutMs}ms.`, meta);
+      if (d.abortedByCaller())
+        throw new ZihinAgentError("aborted", "Request was aborted by the caller.", meta);
+      throw errorFromThrow(err, args.timeoutMs, meta);
+    }
+  }
+  throw new ZihinAgentError("unknown", "Max retries exceeded.", { endpoint });
+}
+function parseBody(text) {
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+// src/agents.ts
+async function listAgents(cfg, opts = {}) {
+  const res = await requestBuffered({
+    method: "GET",
+    url: `${cfg.baseUrl}/api/v2/agents`,
+    headers: buildHeaders(cfg.apiKey),
+    timeoutMs: cfg.timeoutMs,
+    maxRetries: cfg.maxRetries,
+    policy: "idempotent",
+    callerSignal: opts.signal,
+    fetchImpl: cfg.fetchImpl,
+    onRetry: cfg.onRetry
+  });
+  if (!res.ok) {
+    throw errorFromResponse(res.status, parseBody(res.text), { endpoint: res.endpoint, attempts: res.attempts });
+  }
+  let json;
+  try {
+    json = JSON.parse(res.text);
+  } catch {
+    throw new ZihinAgentError("protocol", "Expected JSON from GET /api/v2/agents.");
+  }
+  const data = rec(json).data;
+  const list = Array.isArray(data) ? data : [];
+  return list.map((item) => {
+    const a = rec(item);
+    return {
+      id: str(a.id) ?? "",
+      name: str(a.name),
+      commercialName: str(a.commercial_name),
+      bio: str(a.bio),
+      type: str(a.type),
+      status: str(a.status),
+      tags: Array.isArray(a.tags) ? a.tags.filter((t) => typeof t === "string") : void 0,
+      toolsCount: typeof a.tools_count === "number" ? a.tools_count : void 0
+    };
+  });
+}
+
+// src/sse.ts
+var DEFAULT_MAX_EVENT_BYTES2 = 1 * 1024 * 1024;
+var DEFAULT_MAX_TOTAL_BYTES2 = 64 * 1024 * 1024;
+async function* parseSse(response, opts = {}) {
+  if (!response.body) {
+    throw new ZihinAgentError("protocol", "SSE response has no body.");
+  }
+  const maxEventBytes = opts.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES2;
+  const maxTotalBytes = opts.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES2;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let eventName = "";
+  let dataLines = [];
+  let dataBytes = 0;
+  let totalBytes = 0;
+  const flush = () => {
+    const had = dataLines.length > 0 || eventName !== "";
+    const rawData = dataLines.join("\n");
+    const evt = eventName || "message";
+    eventName = "";
+    dataLines = [];
+    dataBytes = 0;
+    if (!had || rawData === "") return null;
+    let data = rawData;
+    try {
+      data = JSON.parse(rawData);
+    } catch {
+    }
+    return { event: evt, data, rawData };
+  };
+  try {
+    while (true) {
+      if (opts.signal?.aborted) {
+        throw opts.onAbortError ? opts.onAbortError() : new ZihinAgentError("aborted", "Stream aborted.");
+      }
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (err) {
+        throw opts.onAbortError ? opts.onAbortError() : errorFromThrow(err);
+      }
+      if (chunk.done) break;
+      totalBytes += chunk.value.byteLength;
+      if (totalBytes > maxTotalBytes) {
+        throw new ZihinAgentError("protocol", `SSE stream exceeded ${maxTotalBytes} bytes.`);
+      }
+      buffer += decoder.decode(chunk.value, { stream: true });
+      let nl;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        let line = buffer.slice(0, nl);
+        buffer = buffer.slice(nl + 1);
+        if (line.endsWith("\r")) line = line.slice(0, -1);
+        if (line === "") {
+          const e = flush();
+          if (e) yield e;
+          continue;
+        }
+        if (line.startsWith(":")) continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let val = colon === -1 ? "" : line.slice(colon + 1);
+        if (val.startsWith(" ")) val = val.slice(1);
+        if (field === "event") {
+          eventName = val;
+        } else if (field === "data") {
+          dataBytes += utf8Len(val) + 1;
+          if (dataBytes > maxEventBytes) {
+            throw new ZihinAgentError("protocol", `SSE event exceeded ${maxEventBytes} bytes.`);
+          }
+          dataLines.push(val);
+        }
+      }
+      if (utf8Len(buffer) > maxEventBytes) {
+        throw new ZihinAgentError("protocol", `SSE line exceeded ${maxEventBytes} bytes.`);
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.length > 0) {
+      let line = buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+      if (line && !line.startsWith(":")) {
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let val = colon === -1 ? "" : line.slice(colon + 1);
+        if (val.startsWith(" ")) val = val.slice(1);
+        if (field === "data") dataLines.push(val);
+        else if (field === "event") eventName = val;
+      }
+    }
+    const tail = flush();
+    if (tail) yield tail;
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+    }
+    opts.onEnd?.();
+  }
+}
+
+// src/invoke.ts
+function mapEvent(e) {
+  const d = rec(e.data);
+  switch (e.event) {
+    case "metadata":
+      return {
+        type: "metadata",
+        requestId: str(d.request_id),
+        agentId: str(d.agent_id),
+        sessionId: str(d.session_id),
+        data: e.data
+      };
+    case "status":
+      return { type: "status", phase: str(d.phase), data: e.data };
+    case "attachments":
+      return { type: "attachments", data: e.data };
+    case "phase":
+      return { type: "phase", phase: str(d.phase), data: e.data };
+    case "thinking":
+      return { type: "thinking", thought: str(d.thought), data: e.data };
+    case "tool":
+      return {
+        type: "tool",
+        tool: str(d.tool),
+        callId: str(d.call_id),
+        success: typeof d.success === "boolean" ? d.success : void 0,
+        data: e.data
+      };
+    case "action_proposed":
+      return { type: "action_proposed", data: e.data };
+    case "token":
+      return { type: "token", content: str(d.content) ?? "", data: e.data };
+    case "warning":
+      return { type: "warning", message: str(d.message), data: e.data };
+    case "response":
+      return {
+        type: "response",
+        content: str(d.content) ?? "",
+        sessionId: str(d.session_id),
+        sources: Array.isArray(d.sources) ? d.sources : void 0,
+        blocks: Array.isArray(d.blocks) ? d.blocks : void 0,
+        data: e.data
+      };
+    case "metrics": {
+      const modelConfig = rec(d.model_config);
+      return {
+        type: "metrics",
+        usage: parseUsage(d.usage),
+        model: str(modelConfig.model) ?? str(d.model),
+        iterations: num(d.iterations),
+        executionTimeMs: num(d.execution_time_ms),
+        data: e.data
+      };
+    }
+    default:
+      return { type: "unknown", event: e.event, data: e.data };
+  }
+}
+function buildRequestBody(params) {
+  const body = {};
+  if (params.message !== void 0) body.message = params.message;
+  if (params.sessionId) body.session_id = params.sessionId;
+  if (params.attachments?.length) {
+    body.attachments = params.attachments.map((a) => ({ url: a.url, type: a.type }));
+  }
+  if (params.options) {
+    const o = {};
+    if (params.options.temperature !== void 0) o.temperature = params.options.temperature;
+    if (params.options.maxTokens !== void 0) o.max_tokens = params.options.maxTokens;
+    if (params.options.timeoutMs !== void 0) o.timeout_ms = params.options.timeoutMs;
+    if (params.options.jitMode !== void 0) o.jit_mode = params.options.jitMode;
+    if (Object.keys(o).length) body.options = o;
+  }
+  if (params.metadata) {
+    const m = { ...params.metadata };
+    if (params.metadata.traceId !== void 0) {
+      m.trace_id = params.metadata.traceId;
+      delete m.traceId;
+    }
+    if (params.metadata.correlationId !== void 0) {
+      m.correlation_id = params.metadata.correlationId;
+      delete m.correlationId;
+    }
+    body.metadata = m;
+  }
+  return body;
+}
+function validateParams(params) {
+  if (!params.agentId) {
+    throw new ZihinAgentError("config", "agentId is required.");
+  }
+  if (!params.message && !(params.attachments && params.attachments.length)) {
+    throw new ZihinAgentError("config", "Either `message` or `attachments` is required.");
+  }
+  if (params.message) {
+    const sizeCheck = validatePromptSize(params.message);
+    if (!sizeCheck.valid) {
+      throw new ZihinAgentError("config", sizeCheck.error || "Message too large.");
+    }
+  }
+  for (const att of params.attachments ?? []) {
+    const urlCheck = validateBaseUrl(att.url, { allowCustomDomains: true });
+    if (!urlCheck.valid) {
+      throw new ZihinAgentError("config", `Invalid attachment URL: ${urlCheck.error}`);
+    }
+  }
+}
+async function* streamAgent(cfg, params) {
+  validateParams(params);
+  const timeoutMs = params.options?.timeoutMs ?? cfg.timeoutMs;
+  const url = `${cfg.baseUrl}/api/v2/agents/${encodeURIComponent(params.agentId)}/stream`;
+  const { response, deadline, endpoint } = await openStream({
+    url,
+    headers: buildHeaders(cfg.apiKey),
+    body: JSON.stringify(buildRequestBody(params)),
+    timeoutMs,
+    maxRetries: cfg.maxRetries,
+    callerSignal: params.signal,
+    fetchImpl: cfg.fetchImpl,
+    onRetry: cfg.onRetry
+  });
+  try {
+    if (!response.ok) {
+      let text = "";
+      try {
+        text = await response.text();
+      } catch {
+      }
+      throw errorFromResponse(response.status, parseBody(text), { endpoint });
+    }
+    const onAbortError = () => deadline.timedOut() ? new ZihinAgentError("timeout", `Stream timed out after ${timeoutMs}ms.`, { endpoint }) : deadline.abortedByCaller() ? new ZihinAgentError("aborted", "Stream aborted by the caller.", { endpoint }) : new ZihinAgentError("network", "Stream connection interrupted.", { endpoint });
+    for await (const e of parseSse(response, {
+      signal: params.signal,
+      onAbortError,
+      maxEventBytes: cfg.maxStreamEventBytes,
+      maxTotalBytes: cfg.maxStreamTotalBytes
+    })) {
+      yield mapEvent(e);
+    }
+  } finally {
+    deadline.dispose();
+  }
+}
+async function invokeAgent(cfg, params) {
+  const raw = [];
+  const keepRaw = params.includeRaw === true;
+  let responseChunk;
+  let metricsChunk;
+  let metadataSessionId;
+  let tokenBuffer = "";
+  for await (const chunk of streamAgent(cfg, params)) {
+    if (keepRaw) raw.push(chunk);
+    if (chunk.type === "response") responseChunk = chunk;
+    else if (chunk.type === "metrics") metricsChunk = chunk;
+    else if (chunk.type === "token") tokenBuffer += chunk.content;
+    else if (chunk.type === "metadata" && chunk.sessionId) metadataSessionId = chunk.sessionId;
+  }
+  if (!responseChunk) {
+    if (tokenBuffer) {
+      return {
+        content: tokenBuffer,
+        sessionId: metadataSessionId ?? params.sessionId,
+        usage: metricsChunk?.usage,
+        model: metricsChunk?.model,
+        iterations: metricsChunk?.iterations,
+        executionTimeMs: metricsChunk?.executionTimeMs,
+        raw
+      };
+    }
+    throw new ZihinAgentError("protocol", "Stream ended without a `response` event.");
+  }
+  return {
+    content: responseChunk.content || tokenBuffer,
+    sessionId: responseChunk.sessionId ?? metadataSessionId ?? params.sessionId,
+    model: metricsChunk?.model,
+    usage: metricsChunk?.usage,
+    sources: responseChunk.sources,
+    blocks: responseChunk.blocks,
+    iterations: metricsChunk?.iterations,
+    executionTimeMs: metricsChunk?.executionTimeMs,
+    raw
+  };
+}
+
+// src/triggers.ts
+async function requestJson(cfg, args) {
+  const res = await requestBuffered({
+    method: args.method,
+    url: `${cfg.baseUrl}${args.path}`,
+    headers: buildHeaders(cfg.apiKey),
+    body: args.body !== void 0 ? JSON.stringify(args.body) : void 0,
+    timeoutMs: cfg.timeoutMs,
+    maxRetries: cfg.maxRetries,
+    policy: args.policy,
+    callerSignal: args.signal,
+    fetchImpl: cfg.fetchImpl,
+    onRetry: cfg.onRetry
+  });
+  if (!res.ok) {
+    throw errorFromResponse(res.status, parseBody(res.text), { endpoint: res.endpoint, attempts: res.attempts });
+  }
+  try {
+    return JSON.parse(res.text);
+  } catch {
+    throw new ZihinAgentError("protocol", "Expected JSON response.", { endpoint: res.endpoint });
+  }
+}
+function queryExtractionBody(extraction, queryField) {
+  if (!extraction) return { mode: "field", field: queryField ?? "message" };
+  switch (extraction.mode) {
+    case "field":
+      if (!extraction.field) {
+        throw new ZihinAgentError("config", 'queryExtraction.field is required for mode "field".');
+      }
+      return { mode: "field", field: extraction.field };
+    case "template":
+      if (!extraction.template) {
+        throw new ZihinAgentError("config", 'queryExtraction.template is required for mode "template".');
+      }
+      return { mode: "template", template: extraction.template };
+    case "full_body":
+      return { mode: "full_body" };
+    default:
+      throw new ZihinAgentError("config", "Unknown queryExtraction.mode (use field|template|full_body).");
+  }
+}
+async function createTrigger(cfg, params) {
+  if (!params.agentId) throw new ZihinAgentError("config", "agentId is required.");
+  if (!params.name) throw new ZihinAgentError("config", "name is required.");
+  const mode = params.mode ?? "async";
+  if (mode === "async" && !params.callbackUrl) {
+    throw new ZihinAgentError("config", "callbackUrl is required for async triggers.");
+  }
+  if (params.callbackUrl) {
+    const cb = validateBaseUrl(params.callbackUrl, { allowCustomDomains: true });
+    if (!cb.valid) {
+      throw new ZihinAgentError("config", `Invalid callbackUrl: ${cb.error}`);
+    }
+  }
+  const execution = { mode };
+  if (params.callbackUrl) {
+    execution.callback = {
+      url: params.callbackUrl,
+      method: params.callbackMethod ?? "POST"
+    };
+  }
+  const body = {
+    agent_id: params.agentId,
+    name: params.name,
+    trigger_type: "webhook",
+    trigger_config: {
+      query_extraction: queryExtractionBody(params.queryExtraction, params.queryField),
+      auth: { type: params.dispatchAuth ?? "api_key" },
+      execution
+    }
+  };
+  const json = rec(
+    await requestJson(cfg, { method: "POST", path: "/api/triggers", body, policy: "side-effecting", signal: params.signal })
+  );
+  const data = rec(json.data);
+  const triggerId = str(data.id) ?? str(json.id);
+  const webhookUrl = str(json.webhook_url) ?? (triggerId ? `${cfg.baseUrl}/api/triggers/webhook/${triggerId}` : void 0);
+  if (!triggerId || !webhookUrl) {
+    throw new ZihinAgentError("protocol", "createTrigger: missing trigger id / webhook url in response.");
+  }
+  return { triggerId, webhookUrl };
+}
+async function dispatchAgent(cfg, params) {
+  if (!params.triggerId) throw new ZihinAgentError("config", "triggerId is required.");
+  const res = await requestBuffered({
+    method: "POST",
+    url: `${cfg.baseUrl}/api/triggers/webhook/${encodeURIComponent(params.triggerId)}`,
+    headers: buildHeaders(cfg.apiKey),
+    body: JSON.stringify(params.payload ?? {}),
+    timeoutMs: cfg.timeoutMs,
+    maxRetries: cfg.maxRetries,
+    policy: "side-effecting",
+    // S1: nunca duplica disparo por erro de rede
+    callerSignal: params.signal,
+    fetchImpl: cfg.fetchImpl,
+    onRetry: cfg.onRetry
+  });
+  if (!res.ok) {
+    throw errorFromResponse(res.status, parseBody(res.text), { endpoint: res.endpoint, attempts: res.attempts });
+  }
+  const json = parseBody(res.text);
+  const j = rec(json);
+  return {
+    accepted: true,
+    triggerId: str(j.trigger_id) ?? params.triggerId,
+    executionId: str(j.execution_id),
+    agentResponse: str(j.agent_response),
+    usage: parseUsage(j.usage),
+    raw: json
+  };
+}
+function webhookUrlFor(cfg, t) {
+  if (str(t.webhook_url)) return str(t.webhook_url);
+  const id = str(t.id);
+  return t.trigger_type === "webhook" && id ? `${cfg.baseUrl}/api/triggers/webhook/${id}` : void 0;
+}
+function mapTriggerInfo(cfg, raw) {
+  const t = rec(raw);
+  return {
+    id: str(t.id) ?? "",
+    agentId: str(t.agent_id),
+    name: str(t.name),
+    description: str(t.description),
+    triggerType: str(t.trigger_type),
+    enabled: typeof t.enabled === "boolean" ? t.enabled : void 0,
+    triggerCount: num(t.trigger_count),
+    lastError: str(t.last_error),
+    webhookUrl: webhookUrlFor(cfg, t)
+  };
+}
+async function listTriggers(cfg, params = {}) {
+  const qs = new URLSearchParams();
+  if (params.agentId) qs.set("agentId", params.agentId);
+  if (params.triggerType) qs.set("triggerType", params.triggerType);
+  if (params.enabledOnly) qs.set("enabledOnly", "true");
+  const query = qs.toString();
+  const path = `/api/triggers${query ? `?${query}` : ""}`;
+  const json = await requestJson(cfg, { method: "GET", path, policy: "idempotent", signal: params.signal });
+  const list = Array.isArray(json) ? json : Array.isArray(rec(json).data) ? rec(json).data : [];
+  return list.map((t) => mapTriggerInfo(cfg, t));
+}
+async function getTrigger(cfg, params) {
+  if (!params.triggerId) throw new ZihinAgentError("config", "triggerId is required.");
+  const json = await requestJson(cfg, {
+    method: "GET",
+    path: `/api/triggers/${encodeURIComponent(params.triggerId)}`,
+    policy: "idempotent",
+    signal: params.signal
+  });
+  return mapTriggerInfo(cfg, rec(json).data ?? json);
+}
+async function updateTrigger(cfg, params) {
+  if (!params.triggerId) throw new ZihinAgentError("config", "triggerId is required.");
+  if (params.callbackUrl) {
+    const cb = validateBaseUrl(params.callbackUrl, { allowCustomDomains: true });
+    if (!cb.valid) {
+      throw new ZihinAgentError("config", `Invalid callbackUrl: ${cb.error}`);
+    }
+  }
+  const body = {};
+  if (params.name !== void 0) body.name = params.name;
+  if (params.description !== void 0) body.description = params.description;
+  if (params.enabled !== void 0) body.enabled = params.enabled;
+  const touchesConfig = params.queryExtraction !== void 0 || params.callbackUrl !== void 0 || params.callbackMethod !== void 0 || params.mode !== void 0;
+  if (touchesConfig) {
+    const path = `/api/triggers/${encodeURIComponent(params.triggerId)}`;
+    const currentJson = rec(
+      await requestJson(cfg, { method: "GET", path, policy: "idempotent", signal: params.signal })
+    );
+    const current = rec(currentJson.data ?? currentJson);
+    if (!current.trigger_config || typeof current.trigger_config !== "object" || Object.keys(rec(current.trigger_config)).length === 0) {
+      throw new ZihinAgentError(
+        "protocol",
+        "updateTrigger: current trigger_config unavailable \u2014 refusing to overwrite it partially."
+      );
+    }
+    const config = rec(current.trigger_config);
+    const merged = { ...config };
+    if (params.queryExtraction !== void 0) {
+      merged.query_extraction = queryExtractionBody(params.queryExtraction, void 0);
+    }
+    if (params.mode !== void 0 || params.callbackUrl !== void 0 || params.callbackMethod !== void 0) {
+      const execution = rec(config.execution);
+      const callback = rec(execution.callback);
+      const newExecution = { ...execution };
+      if (params.mode !== void 0) newExecution.mode = params.mode;
+      if (params.callbackUrl !== void 0 || params.callbackMethod !== void 0) {
+        const url = params.callbackUrl ?? str(callback.url);
+        if (!url) {
+          throw new ZihinAgentError(
+            "config",
+            "callbackUrl is required: this trigger has no callback configured yet."
+          );
+        }
+        newExecution.callback = {
+          url,
+          method: params.callbackMethod ?? str(callback.method) ?? "POST"
+        };
+      }
+      if (newExecution.mode === "async" && !rec(newExecution.callback).url) {
+        throw new ZihinAgentError("config", "callbackUrl is required for async triggers.");
+      }
+      merged.execution = newExecution;
+    }
+    body.trigger_config = merged;
+  }
+  if (Object.keys(body).length === 0) {
+    throw new ZihinAgentError("config", "updateTrigger: no fields to update.");
+  }
+  const json = await requestJson(cfg, {
+    method: "PATCH",
+    path: `/api/triggers/${encodeURIComponent(params.triggerId)}`,
+    body,
+    // PATCH aqui é replay-safe: reaplicar os mesmos valores produz o mesmo estado.
+    policy: "idempotent",
+    signal: params.signal
+  });
+  return mapTriggerInfo(cfg, rec(json).data ?? json);
+}
+async function deleteTrigger(cfg, params) {
+  if (!params.triggerId) throw new ZihinAgentError("config", "triggerId is required.");
+  const res = await requestBuffered({
+    method: "DELETE",
+    url: `${cfg.baseUrl}/api/triggers/${encodeURIComponent(params.triggerId)}`,
+    headers: buildHeaders(cfg.apiKey),
+    timeoutMs: cfg.timeoutMs,
+    maxRetries: cfg.maxRetries,
+    policy: "idempotent",
+    // DELETE é idempotente
+    callerSignal: params.signal,
+    fetchImpl: cfg.fetchImpl,
+    onRetry: cfg.onRetry
+  });
+  if (!res.ok) {
+    throw errorFromResponse(res.status, parseBody(res.text), { endpoint: res.endpoint, attempts: res.attempts });
+  }
+  const j = rec(parseBody(res.text));
+  return { deleted: j.deleted === true || res.status === 200 };
+}
+async function findOrCreateTrigger(cfg, params) {
+  if (!params.agentId) throw new ZihinAgentError("config", "agentId is required.");
+  if (!params.name) throw new ZihinAgentError("config", "name is required.");
+  const existing = await listTriggers(cfg, { agentId: params.agentId, signal: params.signal });
+  const match = existing.find((t) => t.name === params.name);
+  if (match && match.id) {
+    const webhookUrl = match.webhookUrl ?? `${cfg.baseUrl}/api/triggers/webhook/${match.id}`;
+    return { triggerId: match.id, webhookUrl, created: false };
+  }
+  const ref = await createTrigger(cfg, params);
+  return { ...ref, created: true };
+}
+async function getExecution(cfg, params) {
+  if (!params.triggerId || !params.executionId) {
+    throw new ZihinAgentError("config", "triggerId and executionId are required.");
+  }
+  const path = `/api/triggers/${encodeURIComponent(params.triggerId)}/executions/${encodeURIComponent(
+    params.executionId
+  )}`;
+  const json = rec(await requestJson(cfg, { method: "GET", path, policy: "idempotent", signal: params.signal }));
+  const data = rec(json.data);
+  const exec = rec(data.execution ?? json.execution);
+  const metrics = rec(data.metrics ?? json.metrics);
+  return {
+    executionId: str(exec.id) ?? params.executionId,
+    status: str(exec.status) ?? "unknown",
+    startedAt: str(exec.started_at),
+    finishedAt: str(exec.finished_at),
+    executionTimeMs: num(exec.execution_time_ms),
+    usage: parseUsage(metrics.usage ?? metrics) ?? parseUsage(exec.usage),
+    result: str(exec.agent_response) ?? str(exec.result),
+    raw: json
+  };
+}
+
+// src/client.ts
+var ZihinAgentClient = class {
+  constructor(config) {
+    this.cfg = resolveConfig(config);
+  }
+  /** Base URL efetiva (após validação SSRF). */
+  get baseUrl() {
+    return this.cfg.baseUrl;
+  }
+  /** Notifica `config.onError` (falha definitiva); o callback nunca derruba o fluxo. */
+  report(err) {
+    if (this.cfg.onError && err instanceof ZihinAgentError) {
+      try {
+        this.cfg.onError(err);
+      } catch {
+      }
+    }
+  }
+  guard(p) {
+    return p.catch((err) => {
+      this.report(err);
+      throw err;
+    });
+  }
+  // ---- Caminho A: direto (SSE) ----
+  /** Invoca o agente e retorna o resultado final consolidado (response + metrics). */
+  invokeAgent(params) {
+    return this.guard(invokeAgent(this.cfg, params));
+  }
+  /** Emite deltas ao vivo do agente (async iterator). */
+  async *streamAgent(params) {
+    try {
+      yield* streamAgent(this.cfg, params);
+    } catch (err) {
+      this.report(err);
+      throw err;
+    }
+  }
+  // ---- Caminho B: triggers (async/callback) ----
+  /** Provisiona (1x) um trigger de webhook ligado a um agente. */
+  createTrigger(params) {
+    return this.guard(createTrigger(this.cfg, params));
+  }
+  /** Reaproveita (por agente+nome) ou cria um trigger — evita duplicação. */
+  findOrCreateTrigger(params) {
+    return this.guard(findOrCreateTrigger(this.cfg, params));
+  }
+  /** Lista os triggers do tenant (filtros opcionais). */
+  listTriggers(params = {}) {
+    return this.guard(listTriggers(this.cfg, params));
+  }
+  /** Obtém um trigger pelo id (inclui webhookUrl). */
+  getTrigger(params) {
+    return this.guard(getTrigger(this.cfg, params));
+  }
+  /** Atualiza um trigger (name/description/enabled/extração/callback) via PATCH. */
+  updateTrigger(params) {
+    return this.guard(updateTrigger(this.cfg, params));
+  }
+  /** Remove um trigger (requer key admin/owner). */
+  deleteTrigger(params) {
+    return this.guard(deleteTrigger(this.cfg, params));
+  }
+  /** Dispara um trigger: 202 (async) ou JSON imediato (sync). */
+  dispatchAgent(params) {
+    return this.guard(dispatchAgent(this.cfg, params));
+  }
+  /** Consulta o resultado de uma execução disparada por trigger (polling). */
+  getExecution(params) {
+    return this.guard(getExecution(this.cfg, params));
+  }
+  // ---- Auxiliar ----
+  /** Lista os agentes do tenant (dropdown). */
+  listAgents(opts = {}) {
+    return this.guard(listAgents(this.cfg, opts));
+  }
+};
+function createClient(config) {
+  return new ZihinAgentClient(config);
+}
+
+// src/signing.ts
+function loadNodeCrypto() {
+  const proc = globalThis.process;
+  if (typeof proc?.getBuiltinModule === "function") {
+    return proc.getBuiltinModule("node:crypto");
+  }
+  try {
+    return require("crypto");
+  } catch {
+    throw new ZihinAgentError(
+      "config",
+      "signRequest requires Node.js crypto, unavailable in this runtime (the ESM build needs Node >=20.16)."
+    );
+  }
+}
+function signRequest(payload, secretKey, timestamp) {
+  const { createHmac, randomBytes } = loadNodeCrypto();
+  const ts = timestamp || Date.now();
+  const nonce = randomBytes(16).toString("hex");
+  const message = `${ts}.${nonce}.${payload}`;
+  const signature = createHmac("sha256", secretKey).update(message).digest("hex");
+  return {
+    "X-Zihin-Signature": `sha256=${signature}`,
+    "X-Zihin-Timestamp": ts.toString(),
+    "X-Zihin-Nonce": nonce
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_LIMITS,
+  ZihinAgentClient,
+  ZihinAgentError,
+  createClient,
+  sanitizeApiError,
+  signRequest,
+  validateApiKeyFormat,
+  validateBaseUrl,
+  validatePromptSize
+});