@zihin/agent-client 0.2.0 → 0.4.0

package/dist/index.mjs

@@ -29,6 +29,21 @@ function parseUsage(usageRaw) {
     costUsd: num(u.cost_usd)
   };
 }
+var RUNNING_STATUSES = /* @__PURE__ */ new Set([
+  "running",
+  "pending",
+  "queued",
+  "processing",
+  "in_progress",
+  "waiting",
+  "retrying",
+  "scheduled",
+  "awaiting_approval"
+  // HITL: turno pausado esperando decisão humana não terminou
+]);
+function isTerminalStatus(status) {
+  return !RUNNING_STATUSES.has(status.toLowerCase().replace(/-/g, "_"));
+}
 
 // src/security.ts
 var PRIVATE_IP_PATTERNS = [
@@ -211,14 +226,19 @@ var SENSITIVE_PATTERNS = [
 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).",
+  FORBIDDEN: "This API key's role does not allow this action. The required role depends on the endpoint \u2014 check the key's role in Zihin \u2192 Settings \u2192 API Keys.",
   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."
+  AGENT_NOT_FOUND: "Agent not found or not active for this tenant.",
+  // Bloqueios comerciais. As mensagens do BE vêm em português e estes shells são em inglês;
+  // além disso cada caso tem uma ação DIFERENTE, e o texto precisa dizer qual.
+  TRIAL_EXPIRED: "Your Zihin trial has ended. Upgrade the plan to keep invoking agents \u2014 the API key is fine.",
+  QUOTA_EXCEEDED: "Your Zihin token quota is exhausted. Upgrade the plan or wait for the next cycle \u2014 retrying will not help, and the API key is fine.",
+  NO_ACTIVE_SUBSCRIPTION: "This tenant has no active Zihin subscription. Activate a plan to invoke agents \u2014 the API key is fine."
 };
 function sanitizeApiError(error) {
   let message = "An unexpected error occurred";
@@ -231,8 +251,10 @@ function sanitizeApiError(error) {
     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];
+    const reason = typeof err.reason === "string" ? err.reason : void 0;
+    const effectiveCode = code === "QUOTA_EXCEEDED" && reason === "no_active_subscription" ? "NO_ACTIVE_SUBSCRIPTION" : code;
+    if (effectiveCode && ERROR_CODE_MAP[effectiveCode]) {
+      message = ERROR_CODE_MAP[effectiveCode];
     } else if (typeof rawMessage === "string" && rawMessage) {
       message = rawMessage;
     }
@@ -281,6 +303,7 @@ var ZihinAgentError = class _ZihinAgentError extends Error {
     this.status = opts.status;
     this.code = opts.code;
     this.requestId = opts.requestId;
+    this.executionId = opts.executionId;
     this.attempts = opts.attempts;
     this.endpoint = opts.endpoint;
     this.retryable = opts.retryable ?? (kind === "rate_limit" || kind === "server" || kind === "network");
@@ -292,25 +315,65 @@ function buildMessage(base, opts) {
   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})`;
+  if (opts.executionId) s += ` (execution_id: ${opts.executionId})`;
   return s;
 }
+var COMMERCIAL_BLOCK_CODES = /* @__PURE__ */ new Set(["TRIAL_EXPIRED", "QUOTA_EXCEEDED", "NO_ACTIVE_SUBSCRIPTION"]);
+function errorCodeOf(body) {
+  const b = rec(body);
+  return str(b.error) ?? str(rec(b.error).code) ?? str(b.code);
+}
+function isCommercialBlock(body) {
+  const code = errorCodeOf(body);
+  return code !== void 0 && COMMERCIAL_BLOCK_CODES.has(code);
+}
+function commercialKind(body) {
+  const code = errorCodeOf(body);
+  if (code === "TRIAL_EXPIRED") return "trial_expired";
+  if (code === "NO_ACTIVE_SUBSCRIPTION") return "no_subscription";
+  if (code === "QUOTA_EXCEEDED") {
+    return str(rec(body).reason) === "no_active_subscription" ? "no_subscription" : "quota_exceeded";
+  }
+  return void 0;
+}
 function extractRequestId(body) {
   const b = rec(body);
-  return str(b.request_id) ?? str(b.requestId) ?? str(rec(b.error).request_id);
+  return str(b.request_id) ?? str(b.requestId) ?? str(rec(b.error).request_id) ?? str(rec(b.meta).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 };
+  const base = {
+    status,
+    code,
+    requestId: extractRequestId(body),
+    executionId: str(rec(body).execution_id),
+    ...meta
+  };
+  const commercial = commercialKind(body);
+  if (commercial) {
+    return new ZihinAgentError(commercial, message || "Request blocked by your plan.", {
+      ...base,
+      retryable: false
+    });
+  }
   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).",
+      // Não enumerar papéis aqui: o papel exigido varia por rota (triggers aceitam editor,
+      // mas delegar/cancelar uma task exige admin/owner). A frase antiga mandava o usuário
+      // para o papel errado em metade da API.
+      message || "This API key's role does not allow this action. The required role depends on the endpoint \u2014 check the key's role in Zihin \u2192 Settings \u2192 API Keys.",
       base
     );
   if (status === 404) return new ZihinAgentError("not_found", message || "Resource not found.", base);
+  if (status === 408)
+    return new ZihinAgentError("timeout", message || "The server timed out handling the request.", {
+      ...base,
+      retryable: true
+    });
   if (status === 429)
     return new ZihinAgentError("rate_limit", message || "Rate limit exceeded.", { ...base, retryable: true });
   if (status >= 500)
@@ -340,7 +403,25 @@ function errorFromThrow(err, timeoutMs, meta = {}) {
 
 // src/http.ts
 var DEFAULT_BASE_URL = "https://llm.zihin.ai";
-var DEFAULT_TIMEOUT_MS = 12e4;
+var OPERATION_TIMEOUT_MS = Object.freeze({
+  stream: 2e5,
+  dispatch: 26e4,
+  short: 35e3
+});
+var DEADLINE_GRACE_MS = 1e4;
+var RETRY_OVERHEAD_MS = 6e4;
+var MIN_TIMEOUT_MS = 1e3;
+var MAX_TIMEOUT_MS = 9e5;
+function normalizeTimeoutMs(value, label = "timeoutMs") {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new ZihinAgentError(
+      "config",
+      `${label} must be a positive number of milliseconds (got ${JSON.stringify(value)}).`
+    );
+  }
+  return Math.min(Math.max(n, MIN_TIMEOUT_MS), MAX_TIMEOUT_MS);
+}
 var DEFAULT_MAX_RETRIES = 2;
 var DEFAULT_MAX_EVENT_BYTES = 1 * 1024 * 1024;
 var DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
@@ -373,7 +454,7 @@ function resolveConfig(config) {
   return {
     apiKey: config.apiKey.trim(),
     baseUrl: urlCheck.sanitizedUrl || DEFAULT_BASE_URL,
-    timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    timeoutMs: config.timeoutMs === void 0 || config.timeoutMs === null ? void 0 : normalizeTimeoutMs(config.timeoutMs, "timeoutMs"),
     maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
     maxStreamEventBytes: config.maxStreamEventBytes ?? DEFAULT_MAX_EVENT_BYTES,
     maxStreamTotalBytes: config.maxStreamTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES,
@@ -382,6 +463,9 @@ function resolveConfig(config) {
     onError: config.onError
   };
 }
+function resolveTimeout(cfg, operation) {
+  return cfg.timeoutMs ?? OPERATION_TIMEOUT_MS[operation];
+}
 function endpointLabel(method, url) {
   try {
     const u = new URL(url);
@@ -455,12 +539,27 @@ function createDeadline(timeoutMs, callerSignal) {
   };
 }
 function shouldRetryStatus(status, policy) {
-  if (policy === "idempotent") return status >= 500 || status === 429;
+  if (policy === "idempotent") return status >= 500 || status === 429 || status === 408;
   return status === 429 || status === 503;
 }
+function budgetTracker(args) {
+  const startedAt = Date.now();
+  const reported = args.reportedTimeoutMs ?? args.timeoutMs;
+  const overheadCap = Math.min(args.timeoutMs, RETRY_OVERHEAD_MS);
+  return {
+    reported,
+    /** Quanto ainda pode ser gasto com tentativas falhas + backoff. */
+    overheadLeft: () => overheadCap - (Date.now() - startedAt),
+    expired: (attempts) => new ZihinAgentError("timeout", `Request timed out after ${reported}ms.`, {
+      endpoint: args.endpoint,
+      attempts
+    })
+  };
+}
 async function requestBuffered(args) {
   const endpoint = endpointLabel(args.method, args.url);
   const doFetch = resolveFetch(args.fetchImpl);
+  const budget = budgetTracker({ ...args, endpoint });
   let lastError = null;
   for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
     const d = createDeadline(args.timeoutMs, args.callerSignal);
@@ -475,30 +574,39 @@ async function requestBuffered(args) {
         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 {
+      let wait = shouldRetryStatus(res.status, args.policy) && attempt < args.maxRetries ? retryAfterMs(res.headers) ?? backoffMs(attempt) : null;
+      let peeked;
+      if (wait !== null && res.status === 429) {
+        peeked = await res.text();
+        if (isCommercialBlock(parseBody(peeked))) wait = null;
+      }
+      if (wait !== null && budget.overheadLeft() > wait) {
+        if (peeked === void 0) {
+          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();
+      const text = peeked ?? await res.text();
       d.dispose();
       return { status: res.status, ok: res.ok, text, endpoint, attempts: attempt + 1 };
     } catch (err) {
       d.dispose();
+      if (err instanceof ZihinAgentError) throw err;
       const meta = { endpoint, attempts: attempt + 1 };
-      if (d.timedOut()) throw new ZihinAgentError("timeout", `Request timed out after ${args.timeoutMs}ms.`, meta);
+      if (d.timedOut()) throw budget.expired(attempt + 1);
       if (d.abortedByCaller())
         throw new ZihinAgentError("aborted", "Request was aborted by the caller.", meta);
-      lastError = errorFromThrow(err, args.timeoutMs, meta);
+      lastError = errorFromThrow(err, budget.reported, meta);
       const canRetry = args.policy === "idempotent" && lastError.retryable && attempt < args.maxRetries;
       if (!canRetry) throw lastError;
       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);
     }
@@ -508,6 +616,7 @@ async function requestBuffered(args) {
 async function openStream(args) {
   const endpoint = endpointLabel("POST", args.url);
   const doFetch = resolveFetch(args.fetchImpl);
+  const budget = budgetTracker({ ...args, endpoint });
   for (let attempt = 0; attempt <= args.maxRetries; attempt++) {
     const d = createDeadline(args.timeoutMs, args.callerSignal);
     try {
@@ -519,8 +628,20 @@ async function openStream(args) {
         redirect: "error",
         cache: "no-store"
       });
-      if (shouldRetryStatus(response.status, "side-effecting") && attempt < args.maxRetries) {
-        const wait = retryAfterMs(response.headers) ?? backoffMs(attempt);
+      let wait = shouldRetryStatus(response.status, "side-effecting") && attempt < args.maxRetries ? retryAfterMs(response.headers) ?? backoffMs(attempt) : null;
+      if (response.status === 429) {
+        const text = await response.text().catch(() => "");
+        const body = parseBody(text);
+        if (wait === null || isCommercialBlock(body) || budget.overheadLeft() <= wait) {
+          d.dispose();
+          throw errorFromResponse(response.status, body, { endpoint, attempts: attempt + 1 });
+        }
+        d.dispose();
+        args.onRetry?.({ endpoint, attempt: attempt + 1, delayMs: wait, reason: "status", status: 429 });
+        await delay(wait, args.callerSignal);
+        continue;
+      }
+      if (wait !== null && budget.overheadLeft() > wait) {
         try {
           await response.body?.cancel();
         } catch {
@@ -539,15 +660,51 @@ async function openStream(args) {
       return { response, deadline: d, endpoint };
     } catch (err) {
       d.dispose();
+      if (err instanceof ZihinAgentError) throw err;
       const meta = { endpoint, attempts: attempt + 1 };
-      if (d.timedOut()) throw new ZihinAgentError("timeout", `Request timed out after ${args.timeoutMs}ms.`, meta);
+      if (d.timedOut()) throw budget.expired(attempt + 1);
       if (d.abortedByCaller())
         throw new ZihinAgentError("aborted", "Request was aborted by the caller.", meta);
-      throw errorFromThrow(err, args.timeoutMs, meta);
+      throw errorFromThrow(err, budget.reported, meta);
     }
   }
   throw new ZihinAgentError("unknown", "Max retries exceeded.", { endpoint });
 }
+function toJsonBody(value, label = "body") {
+  try {
+    return JSON.stringify(value);
+  } catch (err) {
+    throw new ZihinAgentError(
+      "config",
+      `${label} is not JSON-serializable: ${err?.message ?? "unknown reason"}.`
+    );
+  }
+}
+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 ? toJsonBody(args.body) : void 0,
+    timeoutMs: resolveTimeout(cfg, args.operation ?? "short"),
+    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 parseBody(text) {
   if (!text) return {};
   try {
@@ -563,7 +720,7 @@ async function listAgents(cfg, opts = {}) {
     method: "GET",
     url: `${cfg.baseUrl}/api/v2/agents`,
     headers: buildHeaders(cfg.apiKey),
-    timeoutMs: cfg.timeoutMs,
+    timeoutMs: resolveTimeout(cfg, "short"),
     maxRetries: cfg.maxRetries,
     policy: "idempotent",
     callerSignal: opts.signal,
@@ -730,6 +887,20 @@ function mapEvent(e) {
       return { type: "token", content: str(d.content) ?? "", data: e.data };
     case "warning":
       return { type: "warning", message: str(d.message), data: e.data };
+    case "session":
+      return { type: "session", sessionId: str(d.session_id), data: e.data };
+    case "done":
+      return { type: "done", data: e.data };
+    case "error": {
+      const err = rec(d.error);
+      return {
+        type: "error",
+        code: str(err.code),
+        message: str(err.message),
+        requestId: str(err.request_id),
+        data: e.data
+      };
+    }
     case "response":
       return {
         type: "response",
@@ -754,7 +925,7 @@ function mapEvent(e) {
       return { type: "unknown", event: e.event, data: e.data };
   }
 }
-function buildRequestBody(params) {
+function buildRequestBody(params, normalizedTimeoutMs) {
   const body = {};
   if (params.message !== void 0) body.message = params.message;
   if (params.sessionId) body.session_id = params.sessionId;
@@ -765,7 +936,7 @@ function buildRequestBody(params) {
     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 (normalizedTimeoutMs !== void 0) o.timeout_ms = normalizedTimeoutMs;
     if (params.options.jitMode !== void 0) o.jit_mode = params.options.jitMode;
     if (Object.keys(o).length) body.options = o;
   }
@@ -796,6 +967,9 @@ function validateParams(params) {
       throw new ZihinAgentError("config", sizeCheck.error || "Message too large.");
     }
   }
+  if (params.options?.timeoutMs !== void 0) {
+    normalizeTimeoutMs(params.options.timeoutMs, "options.timeoutMs");
+  }
   for (const att of params.attachments ?? []) {
     const urlCheck = validateBaseUrl(att.url, { allowCustomDomains: true });
     if (!urlCheck.valid) {
@@ -805,13 +979,16 @@ function validateParams(params) {
 }
 async function* streamAgent(cfg, params) {
   validateParams(params);
-  const timeoutMs = params.options?.timeoutMs ?? cfg.timeoutMs;
+  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;
   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)),
+    body: toJsonBody(buildRequestBody(params, callerTimeoutMs), "request body"),
     timeoutMs,
+    reportedTimeoutMs: reportedMs,
     maxRetries: cfg.maxRetries,
     callerSignal: params.signal,
     fetchImpl: cfg.fetchImpl,
@@ -826,7 +1003,7 @@ async function* streamAgent(cfg, params) {
       }
       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 });
+    const onAbortError = () => deadline.timedOut() ? new ZihinAgentError("timeout", `Stream timed out after ${reportedMs}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,
@@ -845,19 +1022,36 @@ async function invokeAgent(cfg, params) {
   let responseChunk;
   let metricsChunk;
   let metadataSessionId;
+  let mintedSessionId;
+  let cleanEnd = false;
   let tokenBuffer = "";
   for await (const chunk of streamAgent(cfg, params)) {
     if (keepRaw) raw.push(chunk);
+    if (chunk.type === "error") {
+      const code = chunk.code ?? "AGENT_ERROR";
+      const kind = /TIMEOUT/i.test(code) ? "timeout" : "server";
+      throw new ZihinAgentError(kind, sanitizeApiError(chunk.message ?? code).message || code, {
+        code,
+        requestId: chunk.requestId,
+        retryable: false
+      });
+    }
     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;
+    else if (chunk.type === "session" && chunk.sessionId) mintedSessionId = chunk.sessionId;
+    else if (chunk.type === "done") cleanEnd = true;
   }
   if (!responseChunk) {
+    if (cleanEnd) {
+      throw new ZihinAgentError("protocol", "Stream ended (done) without a `response` event.");
+    }
     if (tokenBuffer) {
       return {
         content: tokenBuffer,
-        sessionId: metadataSessionId ?? params.sessionId,
+        contentSource: "tokens",
+        sessionId: mintedSessionId ?? metadataSessionId ?? params.sessionId,
         usage: metricsChunk?.usage,
         model: metricsChunk?.model,
         iterations: metricsChunk?.iterations,
@@ -868,8 +1062,9 @@ async function invokeAgent(cfg, params) {
     throw new ZihinAgentError("protocol", "Stream ended without a `response` event.");
   }
   return {
-    content: responseChunk.content || tokenBuffer,
-    sessionId: responseChunk.sessionId ?? metadataSessionId ?? params.sessionId,
+    content: responseChunk.content,
+    contentSource: "response",
+    sessionId: mintedSessionId ?? responseChunk.sessionId ?? metadataSessionId ?? params.sessionId,
     model: metricsChunk?.model,
     usage: metricsChunk?.usage,
     sources: responseChunk.sources,
@@ -880,29 +1075,180 @@ async function invokeAgent(cfg, params) {
   };
 }
 
-// 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
+// src/tasks.ts
+var MAX_TASK_PAYLOAD_BYTES = 64 * 1024;
+var SCHEDULE_PAST_TOLERANCE_MS = 6e4;
+function envelope(json) {
+  const j = rec(json);
+  return { data: rec(j.data ?? j), meta: rec(j.meta) };
+}
+function toIso(value, label) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) {
+    throw new ZihinAgentError("config", `${label} must be a valid ISO 8601 date (got ${JSON.stringify(value)}).`);
+  }
+  return d.toISOString();
+}
+function mapTask(raw) {
+  const t = rec(raw);
+  const status = str(t.status);
+  return {
+    id: str(t.id) ?? "",
+    agentId: str(t.agent_id),
+    title: str(t.title),
+    instruction: str(t.instruction),
+    status: status ?? "unknown",
+    // Mesma regra do Caminho B, e de propósito a MESMA função: status desconhecido conta como
+    // terminal (o polling para em vez de girar), status ausente não (não lemos o envelope).
+    terminal: status === void 0 ? false : isTerminalStatus(status),
+    scheduledFor: str(t.scheduled_for),
+    deadlineAt: str(t.deadline_at),
+    parentTaskId: str(t.parent_task_id),
+    rootTaskId: str(t.root_task_id),
+    sessionId: str(t.session_id),
+    createdAt: str(t.created_at),
+    updatedAt: str(t.updated_at),
+    raw
+  };
+}
+function mapExecution(raw) {
+  const e = rec(raw);
+  return {
+    id: str(e.id) ?? "",
+    status: str(e.status) ?? "unknown",
+    exitReason: str(e.exit_reason),
+    modelUsed: str(e.model_used),
+    totalCostUsd: num(e.total_cost_usd),
+    executionTimeMs: num(e.execution_time_ms),
+    iterations: num(e.iterations),
+    startedAt: str(e.started_at),
+    finishedAt: str(e.finished_at),
+    raw
+  };
+}
+async function delegateTask(cfg, params) {
+  if (!params.agentId) throw new ZihinAgentError("config", "agentId is required.");
+  if (!params.instruction) throw new ZihinAgentError("config", "instruction is required.");
+  const scheduledFor = toIso(params.scheduledFor, "scheduledFor");
+  const deadlineAt = toIso(params.deadlineAt, "deadlineAt");
+  if (scheduledFor && Date.parse(scheduledFor) < Date.now() - SCHEDULE_PAST_TOLERANCE_MS) {
+    throw new ZihinAgentError("config", "scheduledFor is in the past.");
+  }
+  if (deadlineAt && Date.parse(deadlineAt) <= Date.now() - SCHEDULE_PAST_TOLERANCE_MS) {
+    throw new ZihinAgentError("config", "deadlineAt must be in the future.");
+  }
+  if (scheduledFor && deadlineAt && Date.parse(deadlineAt) <= Date.parse(scheduledFor)) {
+    throw new ZihinAgentError("config", "deadlineAt must be after scheduledFor.");
+  }
+  if (params.payload !== void 0) {
+    if (typeof params.payload !== "object" || params.payload === null || Array.isArray(params.payload)) {
+      throw new ZihinAgentError("config", "payload must be an object.");
+    }
+    const bytes = toJsonBody(params.payload, "payload").length;
+    if (bytes > MAX_TASK_PAYLOAD_BYTES) {
+      throw new ZihinAgentError(
+        "config",
+        `payload exceeds ${MAX_TASK_PAYLOAD_BYTES / 1024}KB (got ${Math.ceil(bytes / 1024)}KB).`
+      );
+    }
+  }
+  const body = {
+    agent_id: params.agentId,
+    instruction: params.instruction
+  };
+  if (params.title !== void 0) body.title = params.title;
+  if (params.payload !== void 0) body.payload = params.payload;
+  if (scheduledFor) body.scheduled_for = scheduledFor;
+  if (deadlineAt) body.deadline_at = deadlineAt;
+  if (params.retryPolicy !== void 0) body.retry_policy = params.retryPolicy;
+  if (params.notify !== void 0) body.notify = params.notify;
+  if (params.parentTaskId) body.parent_task_id = params.parentTaskId;
+  const json = await requestJson(cfg, {
+    method: "POST",
+    path: "/api/v1/tasks",
+    body,
+    // Criar uma task E dispará-la é efeito colateral: nunca repetir em erro de rede.
+    policy: "side-effecting",
+    signal: params.signal
   });
-  if (!res.ok) {
-    throw errorFromResponse(res.status, parseBody(res.text), { endpoint: res.endpoint, attempts: res.attempts });
+  const { data } = envelope(json);
+  const task = mapTask(data.task ?? data);
+  if (!task.id) {
+    throw new ZihinAgentError("protocol", "delegateTask: response has no task id.");
   }
-  try {
-    return JSON.parse(res.text);
-  } catch {
-    throw new ZihinAgentError("protocol", "Expected JSON response.", { endpoint: res.endpoint });
+  return task;
+}
+async function listTasks(cfg, params = {}) {
+  const qs = new URLSearchParams();
+  if (params.live) qs.set("live", "true");
+  if (params.status) qs.set("status", params.status);
+  if (params.agentId) qs.set("agent_id", params.agentId);
+  if (params.rootTaskId) qs.set("root_task_id", params.rootTaskId);
+  if (params.limit !== void 0) qs.set("limit", String(params.limit));
+  if (params.offset !== void 0) qs.set("offset", String(params.offset));
+  const query = qs.toString();
+  const json = await requestJson(cfg, {
+    method: "GET",
+    path: `/api/v1/tasks${query ? `?${query}` : ""}`,
+    policy: "idempotent",
+    signal: params.signal
+  });
+  const { data, meta } = envelope(json);
+  const items = Array.isArray(data.items) ? data.items : [];
+  return {
+    items: items.map(mapTask),
+    // ⚠️ `total` vive em `meta`, não no topo — o envelope novo aninhou os campos de paginação.
+    total: num(meta.total),
+    raw: json
+  };
+}
+async function getTask(cfg, params) {
+  if (!params.taskId) throw new ZihinAgentError("config", "taskId is required.");
+  const json = await requestJson(cfg, {
+    method: "GET",
+    path: `/api/v1/tasks/${encodeURIComponent(params.taskId)}`,
+    policy: "idempotent",
+    signal: params.signal
+  });
+  const { data } = envelope(json);
+  const taskRaw = data.task ?? (str(rec(data).id) ? data : void 0);
+  if (!taskRaw || !str(rec(taskRaw).id)) {
+    throw new ZihinAgentError("protocol", "getTask: response has no task.");
   }
+  const executions = Array.isArray(data.executions) ? data.executions : [];
+  const children = Array.isArray(data.children) ? data.children : [];
+  return {
+    task: mapTask(taskRaw),
+    executions: executions.map(mapExecution),
+    children: children.map(mapTask),
+    approvals: Array.isArray(data.approvals) ? data.approvals : [],
+    raw: json
+  };
 }
+async function cancelTask(cfg, params) {
+  if (!params.taskId) throw new ZihinAgentError("config", "taskId is required.");
+  const json = await requestJson(cfg, {
+    method: "POST",
+    path: `/api/v1/tasks/${encodeURIComponent(params.taskId)}/cancel`,
+    body: params.reason ? { reason: params.reason } : {},
+    // Cancelar é side-effecting; repetir num socket caído bateria em 409 e confundiria o chamador.
+    policy: "side-effecting",
+    signal: params.signal
+  });
+  const { data } = envelope(json);
+  const taskRaw = data.task ?? (str(rec(data).id) ? data : void 0);
+  if (!taskRaw || !str(rec(taskRaw).id)) {
+    throw new ZihinAgentError("protocol", "cancelTask: response has no task.");
+  }
+  return {
+    task: mapTask(taskRaw),
+    aborted: data.aborted === true,
+    raw: json
+  };
+}
+
+// src/triggers.ts
 function queryExtractionBody(extraction, queryField) {
   if (!extraction) return { mode: "field", field: queryField ?? "message" };
   switch (extraction.mode) {
@@ -935,11 +1281,18 @@ async function createTrigger(cfg, params) {
       throw new ZihinAgentError("config", `Invalid callbackUrl: ${cb.error}`);
     }
   }
+  if (params.responseTransform && !params.callbackUrl) {
+    throw new ZihinAgentError(
+      "config",
+      "responseTransform requires callbackUrl: the backend only reads it from trigger_config.execution.callback.response_transform, and a callback without a url is rejected."
+    );
+  }
   const execution = { mode };
   if (params.callbackUrl) {
     execution.callback = {
       url: params.callbackUrl,
-      method: params.callbackMethod ?? "POST"
+      method: params.callbackMethod ?? "POST",
+      ...params.responseTransform ? { response_transform: { mode: params.responseTransform } } : {}
     };
   }
   const body = {
@@ -969,8 +1322,8 @@ async function dispatchAgent(cfg, params) {
     method: "POST",
     url: `${cfg.baseUrl}/api/triggers/webhook/${encodeURIComponent(params.triggerId)}`,
     headers: buildHeaders(cfg.apiKey),
-    body: JSON.stringify(params.payload ?? {}),
-    timeoutMs: cfg.timeoutMs,
+    body: toJsonBody(params.payload ?? {}, "payload"),
+    timeoutMs: resolveTimeout(cfg, "dispatch"),
     maxRetries: cfg.maxRetries,
     policy: "side-effecting",
     // S1: nunca duplica disparo por erro de rede
@@ -983,12 +1336,29 @@ async function dispatchAgent(cfg, params) {
   }
   const json = parseBody(res.text);
   const j = rec(json);
+  if (j.success === false) {
+    const detail = sanitizeApiError(str(j.error) ?? "").message;
+    throw new ZihinAgentError("server", detail || "The agent run failed.", {
+      status: res.status,
+      endpoint: res.endpoint,
+      attempts: res.attempts,
+      executionId: str(j.execution_id),
+      // Não é transitório: o turno rodou e falhou. Repetir gastaria outra execução.
+      retryable: false
+    });
+  }
   return {
     accepted: true,
     triggerId: str(j.trigger_id) ?? params.triggerId,
+    agentId: str(j.agent_id),
     executionId: str(j.execution_id),
     agentResponse: str(j.agent_response),
     usage: parseUsage(j.usage),
+    iterations: num(j.iterations),
+    latencyMs: num(j.latency_ms),
+    // Qual texto o BE extraiu do payload — é o campo que denuncia um `query_extraction` mal
+    // configurado (mensagem vazia, ou o payload inteiro serializado virando a pergunta).
+    queryExtracted: str(j.query_extracted),
     raw: json
   };
 }
@@ -1044,7 +1414,7 @@ async function updateTrigger(cfg, params) {
   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;
+  const touchesConfig = params.queryExtraction !== void 0 || params.callbackUrl !== void 0 || params.callbackMethod !== void 0 || params.responseTransform !== void 0 || params.mode !== void 0;
   if (touchesConfig) {
     const path = `/api/triggers/${encodeURIComponent(params.triggerId)}`;
     const currentJson = rec(
@@ -1062,22 +1432,34 @@ async function updateTrigger(cfg, params) {
     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 touchesCallback = params.callbackUrl !== void 0 || params.callbackMethod !== void 0 || params.responseTransform !== void 0;
+    if (params.mode !== void 0 || touchesCallback) {
       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) {
+      if (touchesCallback) {
         const url = params.callbackUrl ?? str(callback.url);
         if (!url) {
           throw new ZihinAgentError(
             "config",
-            "callbackUrl is required: this trigger has no callback configured yet."
+            params.responseTransform ? "responseTransform requires a callback: the backend only reads it from trigger_config.execution.callback.response_transform, and a callback without a url is rejected." : "callbackUrl is required: this trigger has no callback configured yet."
           );
         }
         newExecution.callback = {
+          // Preserva o callback atual: trocar só a URL não pode apagar auth/headers/
+          // body_template/content_type/response_transform. Antes este objeto era
+          // SUBSTITUÍDO por { url, method } — a mesma perda silenciosa que o merge de
+          // trigger_config acima existe para evitar, um nível mais fundo.
+          ...callback,
           url,
-          method: params.callbackMethod ?? str(callback.method) ?? "POST"
+          method: params.callbackMethod ?? str(callback.method) ?? "POST",
+          ...params.responseTransform ? {
+            response_transform: {
+              ...rec(callback.response_transform),
+              mode: params.responseTransform
+            }
+          } : {}
         };
       }
       if (newExecution.mode === "async" && !rec(newExecution.callback).url) {
@@ -1106,7 +1488,7 @@ async function deleteTrigger(cfg, params) {
     method: "DELETE",
     url: `${cfg.baseUrl}/api/triggers/${encodeURIComponent(params.triggerId)}`,
     headers: buildHeaders(cfg.apiKey),
-    timeoutMs: cfg.timeoutMs,
+    timeoutMs: resolveTimeout(cfg, "short"),
     maxRetries: cfg.maxRetries,
     policy: "idempotent",
     // DELETE é idempotente
@@ -1143,9 +1525,11 @@ async function getExecution(cfg, params) {
   const data = rec(json.data);
   const exec = rec(data.execution ?? json.execution);
   const metrics = rec(data.metrics ?? json.metrics);
+  const rawStatus = str(exec.status);
   return {
     executionId: str(exec.id) ?? params.executionId,
-    status: str(exec.status) ?? "unknown",
+    status: rawStatus ?? "unknown",
+    terminal: rawStatus === void 0 ? false : isTerminalStatus(rawStatus),
     startedAt: str(exec.started_at),
     finishedAt: str(exec.finished_at),
     executionTimeMs: num(exec.execution_time_ms),
@@ -1226,6 +1610,26 @@ var ZihinAgentClient = class {
   getExecution(params) {
     return this.guard(getExecution(this.cfg, params));
   }
+  // ---- Caminho C: tasks (delegação assíncrona durável) ----
+  /**
+   * Delega uma tarefa a um agente (requer key owner/admin). Sem `scheduledFor`, o BE dispara na
+   * hora fora do request e devolve só o handle — acompanhe com `getTask`.
+   */
+  delegateTask(params) {
+    return this.guard(delegateTask(this.cfg, params));
+  }
+  /** Board de tasks do tenant (requer key owner/admin/editor). */
+  listTasks(params = {}) {
+    return this.guard(listTasks(this.cfg, params));
+  }
+  /** Dossiê de uma task: task + execuções + filhos + aprovações. */
+  getTask(params) {
+    return this.guard(getTask(this.cfg, params));
+  }
+  /** Cancela uma task (requer key owner/admin); derruba o turno em voo, se houver. */
+  cancelTask(params) {
+    return this.guard(cancelTask(this.cfg, params));
+  }
   // ---- Auxiliar ----
   /** Lista os agentes do tenant (dropdown). */
   listAgents(opts = {}) {
@@ -1264,10 +1668,14 @@ function signRequest(payload, secretKey, timestamp) {
   };
 }
 export {
+  DEADLINE_GRACE_MS,
   DEFAULT_LIMITS,
+  MAX_TASK_PAYLOAD_BYTES,
+  OPERATION_TIMEOUT_MS,
   ZihinAgentClient,
   ZihinAgentError,
   createClient,
+  isCommercialBlock,
   sanitizeApiError,
   signRequest,
   validateApiKeyFormat,