@ar-ai/brink-cli 0.0.0-stage → 1.0.6

package/support/transport.js

@@ -0,0 +1,485 @@
+"use strict";
+
+const https = require("https");
+const { PassThrough } = require("stream");
+const { StringDecoder } = require("string_decoder");
+const zlib = require("zlib");
+
+const MAX_RETRIES = 5;
+// Responses preambles can echo the client's tool catalog and instructions.
+// Bound both raw and decoded bytes without committing ordinary large metadata.
+const MAX_PRELUDE_BYTES = 8 * 1024 * 1024;
+const RETRY_OWNER_HEADER = "x-agentrouter-retry-owner";
+
+const CONNECT_TIMEOUT_MS = 30_000;
+const HEADER_TIMEOUT_MS = 120_000;
+const IDLE_TIMEOUT_MS = 300_000;
+const HOP_HEADERS = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+];
+
+function cleanHeaders(source) {
+  const headers = { ...source };
+  const nominated = String(headers.connection || "").split(",");
+  for (const key of [...HOP_HEADERS, ...nominated])
+    delete headers[key.trim().toLowerCase()];
+  delete headers[RETRY_OWNER_HEADER];
+  return headers;
+}
+
+function createUpstreamAgent() {
+  return new https.Agent({
+    keepAlive: true,
+    keepAliveMsecs: 1_000,
+    maxSockets: 64,
+    maxTotalSockets: 64,
+    maxFreeSockets: 8,
+    scheduling: "lifo",
+    timeout: IDLE_TIMEOUT_MS,
+  });
+}
+
+// Deadlines cover connection and response headers only. Once headers arrive,
+// arbitrarily long inference streams are allowed while the socket stays active.
+function watchUpstream(request) {
+  let response;
+  let socket;
+  let headerTimer;
+  const expire = (code) => {
+    const error = Object.assign(new Error("AgentRouter upstream timed out"), {
+      code,
+      status: 504,
+    });
+    if (response && !response.destroyed) response.destroy(error);
+    request.destroy(error);
+  };
+  const connectTimer = setTimeout(
+    () => expire("upstream_connect_timeout"),
+    CONNECT_TIMEOUT_MS,
+  );
+  connectTimer.unref();
+  const connected = () => {
+    clearTimeout(connectTimer);
+    headerTimer = setTimeout(
+      () => expire("upstream_header_timeout"),
+      HEADER_TIMEOUT_MS,
+    );
+    headerTimer.unref();
+  };
+  const clearDeadlines = () => {
+    clearTimeout(connectTimer);
+    clearTimeout(headerTimer);
+    socket?.off("secureConnect", connected);
+  };
+  const timedOut = () => expire("upstream_idle_timeout");
+  request.setTimeout(IDLE_TIMEOUT_MS, timedOut);
+  request.once("socket", (assigned) => {
+    socket = assigned;
+    if (socket.connecting || socket.secureConnecting)
+      socket.once("secureConnect", connected);
+    else connected();
+  });
+  request.once("response", (upstream) => {
+    response = upstream;
+    clearDeadlines();
+  });
+  request.on("error", (error) => {
+    clearDeadlines();
+    if (response && !response.destroyed) response.destroy(error);
+  });
+  request.once("close", () => {
+    clearDeadlines();
+    request.off("timeout", timedOut);
+  });
+}
+
+function errorDetails(value) {
+  if (!value || typeof value !== "object") return value;
+  return value.error || value.response?.error || value;
+}
+function permanentFailure(status, value, text = "") {
+  if ([401, 402, 403].includes(status)) return true;
+  const error = errorDetails(value);
+  const message = typeof error === "string" ? error : error?.message || text;
+  return /quota|billing|credit|balance|authentication|unauthori[sz]ed|invalid[_ -]?(?:api[_ -]?)?key|permission|access[_ -]?denied|account[_ -]?(?:disabled|suspended)/i.test(`${error?.code || ""} ${error?.type || ""} ${message}`);
+}
+
+function isRateLimit(status, value, text = "") {
+  if (permanentFailure(status, value, text)) return false;
+  const error = errorDetails(value);
+  const code = String(error?.code || "");
+  const type = String(error?.type || "");
+  const message = typeof error === "string" ? error : error?.message || text;
+  const structured = /^rate_limit_(?:exceeded|error)$/i.test(code) ||
+    /^rate_limit_(?:exceeded|error)$/i.test(type);
+  if (status === 400) return structured;
+  return status === 429 || structured || /\brate_limit_exceeded\b/i.test(message);
+}
+
+// Fixed classifications only: never retain upstream text in retry telemetry.
+function retryableFailure(status, value, text = "") {
+  if (permanentFailure(status, value, text)) return null;
+  if (isRateLimit(status, value, text)) return "rate_limit_exceeded";
+  if (status >= 400 && status < 500) return null;
+  const error = errorDetails(value);
+  const code = String(error?.code || error?.type || "");
+  const message = typeof error === "string" ? error : error?.message || text;
+  if (/^(?:ECONNRESET|ECONNREFUSED|EPIPE|ETIMEDOUT|EAI_AGAIN|upstream_connect_timeout|upstream_header_timeout|upstream_idle_timeout|incomplete_stream|upstream_connection_error)$/.test(code) ||
+      /upstream connect error|disconnect\/reset before headers|reset reason:\s*connection termination/i.test(message))
+    return "upstream_connection_error";
+  if ([500, 502, 503, 504].includes(status) || /^(?:server_error|internal_server_error|service_unavailable|overloaded_error)$/.test(code) ||
+      /\bthe server had an error processing your request\b/i.test(message))
+    return "server_error";
+  return null;
+}
+
+function retryDelay(retry) {
+  return retry * 1000;
+}
+
+function cancelledError() {
+  return Object.assign(new Error("Client disconnected"), {
+    code: "client_disconnected", status: 499,
+  });
+}
+
+// The fixed 1–5 second retry waits remain cancellable on client disconnect.
+function waitForRetry(delay, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(cancelledError());
+    const abort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      reject(cancelledError());
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, delay);
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+function harmlessPrelude(value, event) {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value.choices)) {
+    return value.choices.every((choice) => {
+      const delta = choice.delta;
+      return !choice.finish_reason && delta && Object.entries(delta).every(
+        ([key, entry]) => key === "role" || entry == null || entry === "" ||
+          (Array.isArray(entry) && entry.length === 0),
+      );
+    });
+  }
+  const type = value.type || event;
+  if (["response.created", "response.in_progress", "response.queued"].includes(type))
+    return !value.response?.output?.length;
+  if (type === "response.output_item.added")
+    return value.item?.type === "message" && !value.item.content?.length;
+  if (type === "response.content_part.added")
+    return value.part?.type === "output_text" && !value.part.text;
+  if (type === "ping") return true;
+  if (type === "message_start") return !value.message?.content?.length;
+  if (type === "content_block_start")
+    return value.content_block?.type === "text" && !value.content_block.text;
+  // Unknown events lock replay off. A new protocol must never duplicate tools.
+  return false;
+}
+
+// Inspect only a bounded prefix, withholding even metadata so discarded attempt
+// IDs cannot leak. All accepted response bytes (including compressed bytes) are
+// replayed verbatim. Reaching the limit commits the response without retrying.
+function inspectPrelude(response, signal) {
+  const status = response.statusCode || 502;
+  const contentType = String(response.headers["content-type"] || "").toLowerCase();
+  const sse = status === 200 && contentType.includes("text/event-stream");
+  const inspect = sse || status >= 400 ||
+    (status === 200 && contentType.includes("application/json"));
+  if (!inspect || [401, 402, 403].includes(status))
+    return Promise.resolve({ chunks: [], retryReason: null, ended: false });
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const decoder = new StringDecoder("utf8");
+    let rawBytes = 0;
+    let decodedBytes = 0;
+    let text = "";
+    let line = "";
+    let skipLF = false;
+    let first = true;
+    let data = [];
+    let event = "";
+    let settled = false;
+    let ended = false;
+    let unzip;
+    const encoding = String(response.headers["content-encoding"] || "identity").toLowerCase();
+    if (encoding === "gzip") unzip = zlib.createGunzip();
+    else if (encoding === "deflate") unzip = zlib.createInflate();
+    else if (encoding === "br") unzip = zlib.createBrotliDecompress();
+    else if (encoding !== "identity") {
+      resolve({ chunks, retryReason: null, ended });
+      return;
+    }
+    const cleanup = () => {
+      response.pause();
+      response.off("data", onData);
+      response.off("end", onEnd);
+      response.off("error", onError);
+      response.off("close", onClose);
+      signal?.removeEventListener("abort", onAbort);
+      unzip?.destroy();
+    };
+    const finish = (retryReason, limitReached = false) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve({ chunks, retryReason: retryReason || null, ended, limitReached });
+    };
+    const onError = (error) => {
+      if (settled) return;
+      // A partial/unknown event may contain tool output. Retry a reset only
+      // before bytes arrive or after fully parsed, harmless identity metadata.
+      error.retrySafe = rawBytes === 0 || (sse && !unzip && !line && !data.length);
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const onAbort = () => onError(cancelledError());
+    const onClose = () => {
+      if (!response.complete) onError(Object.assign(new Error("Upstream response aborted"), {
+        code: "incomplete_stream",
+      }));
+    };
+    const consumeLine = () => {
+      if (!line) {
+        if (!data.length) { event = ""; return; }
+        const payload = data.join("\n");
+        data = [];
+        if (payload.trim() === "[DONE]") return finish(false);
+        let value;
+        try { value = JSON.parse(payload); } catch { return finish(false); }
+        const error = value?.error || value?.response?.error ||
+          event === "error" || value?.type === "error" || value?.type === "response.failed" ||
+          /^rate_limit_(?:exceeded|error)$/i.test(String(value?.code || "")) ||
+          /^rate_limit_(?:exceeded|error)$/i.test(String(value?.type || ""));
+        if (error) finish(value?.response?.output?.length ? null : retryableFailure(status, value));
+        else if (!harmlessPrelude(value, event)) finish(false);
+        event = "";
+        return;
+      }
+      const colon = line.indexOf(":");
+      const field = colon < 0 ? line : line.slice(0, colon);
+      let value = colon < 0 ? "" : line.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+      if (field === "data") data.push(value);
+      else if (field === "event") event = value;
+    };
+    const consume = (chunk) => {
+      if (settled) return;
+      decodedBytes += chunk.length;
+      if (decodedBytes > MAX_PRELUDE_BYTES) return finish(false, true);
+      let decoded = decoder.write(chunk);
+      if (!sse) { text += decoded; return; }
+      if (first && decoded.length) {
+        first = false;
+        if (decoded.charCodeAt(0) === 0xfeff) decoded = decoded.slice(1);
+      }
+      let start = 0;
+      for (let i = 0; i < decoded.length; i++) {
+        if (settled) return;
+        const char = decoded[i];
+        if (skipLF) {
+          skipLF = false;
+          if (char === "\n") { start = i + 1; continue; }
+        }
+        if (char === "\r" || char === "\n") {
+          line += decoded.slice(start, i);
+          consumeLine();
+          line = "";
+          start = i + 1;
+          skipLF = char === "\r";
+        }
+      }
+      if (!settled) line += decoded.slice(start);
+    };
+    const complete = () => {
+      if (settled) return;
+      if (sse) return finish(false); // Never retry truncated or unknown SSE.
+      text += decoder.end();
+      let value;
+      try { value = JSON.parse(text); } catch { /* Plain-text HTTP errors exist. */ }
+      if (status === 200 && (!errorDetails(value) || (!value?.error && !value?.response?.error))) return finish(false);
+      if (value?.output?.length || value?.response?.output?.length) return finish(false);
+      finish(retryableFailure(status, value, text));
+    };
+    const onData = (chunk) => {
+      chunks.push(chunk);
+      rawBytes += chunk.length;
+      if (rawBytes > MAX_PRELUDE_BYTES) return finish(false, true);
+      if (unzip) {
+        if (!unzip.write(chunk)) response.pause();
+      } else consume(chunk);
+    };
+    const onEnd = () => {
+      ended = true;
+      if (unzip) unzip.end();
+      else complete();
+    };
+    if (unzip) {
+      unzip.on("data", consume);
+      unzip.on("end", complete);
+      unzip.on("error", () => finish(false));
+      unzip.on("drain", () => { if (!settled) response.resume(); });
+    }
+    response.on("data", onData);
+    response.once("end", onEnd);
+    response.on("error", onError);
+    response.once("close", onClose);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    if (response.errored) onError(response.errored);
+    else if (response.destroyed && !response.complete) onClose();
+  });
+}
+
+async function requestWithRetries(target, options, body, {
+  signal, tracker, clientOwnsRetries = false,
+} = {}) {
+  let request;
+  let response;
+  let stream;
+  const abort = () => {
+    response?.destroy();
+    request?.destroy();
+    stream?.destroy(cancelledError());
+  };
+  const cleanup = () => signal?.removeEventListener("abort", abort);
+  signal?.addEventListener("abort", abort, { once: true });
+  try {
+    for (let attempt = 0; ; attempt++) {
+      if (signal?.aborted) throw cancelledError();
+      response = undefined;
+      let inspected;
+      let attemptError;
+      let retryReason;
+      try {
+        response = await new Promise((resolve, reject) => {
+          let received = false;
+          request = https.request(target, options, (upstream) => {
+            received = true;
+            upstream.on("error", () => {});
+            resolve(upstream);
+          });
+          request.on("error", reject);
+          request.once("close", () => {
+            if (!received) reject(signal?.aborted ? cancelledError() :
+              Object.assign(new Error("Upstream connection closed"), { code: "incomplete_stream" }));
+          });
+          watchUpstream(request);
+          request.end(body);
+        });
+        if (signal?.aborted) throw cancelledError();
+        inspected = await inspectPrelude(response, signal);
+        retryReason = inspected.retryReason;
+      } catch (error) {
+        attemptError = error;
+        if (!response || error.retrySafe)
+          retryReason = retryableFailure(response?.statusCode, error);
+      }
+      if (signal?.aborted) throw cancelledError();
+      if (retryReason && !clientOwnsRetries && attempt < MAX_RETRIES) {
+        const retry = attempt + 1;
+        const delay = retryDelay(retry);
+        response?.destroy();
+        request?.destroy();
+        tracker?.note("warn", `${upstreamFailure(null, { code: retryReason })}; retry ${retry}/${MAX_RETRIES} in ${delay}ms`);
+        await waitForRetry(delay, signal);
+        continue;
+      }
+      if (attemptError) throw attemptError;
+      if (inspected.limitReached)
+        tracker?.note("warn", "Retry inspection exceeded 8 MiB; forwarding without automatic replay");
+      stream = new PassThrough();
+      stream.on("error", () => {});
+      stream.once("end", cleanup);
+      stream.once("close", () => {
+        cleanup();
+        if (!response.complete) {
+          response.destroy();
+          request.destroy();
+        }
+      });
+      response.on("error", (error) => stream.destroy(error));
+      response.once("aborted", () => stream.destroy(Object.assign(
+        new Error("Upstream response aborted"), { code: "incomplete_stream" },
+      )));
+      response.once("close", () => {
+        if (!response.complete) stream.destroy(Object.assign(
+          new Error("Upstream response ended before completion"), { code: "incomplete_stream" },
+        ));
+      });
+      for (const chunk of inspected.chunks) stream.write(chunk);
+      if (inspected.ended) stream.end();
+      else response.pipe(stream);
+      return { request, response, stream, retryReason };
+    }
+  } catch (error) {
+    cleanup();
+    abort();
+    throw error;
+  }
+}
+
+// Only fixed classifications enter telemetry: never upstream messages, bodies,
+// request headers, URLs, or arbitrary provider error codes.
+function upstreamFailure(status, error) {
+  const code = error?.code;
+  if (
+    status === 429 ||
+    code === "rate_limit_exceeded" ||
+    code === "rate_limit_error"
+  )
+    return "AgentRouter rate limit reached";
+  if (
+    status === 401 ||
+    status === 403 ||
+    code === "authentication_error" ||
+    code === "invalid_api_key" ||
+    code === "permission_error"
+  )
+    return "AgentRouter authentication or access denied";
+  if (code === "upstream_connect_timeout")
+    return "AgentRouter connection deadline exceeded";
+  if (code === "upstream_header_timeout")
+    return "AgentRouter response-header deadline exceeded";
+  if (code === "upstream_idle_timeout")
+    return "AgentRouter idle timeout exceeded";
+  if (code === "upstream_connection_error" || ["ECONNRESET", "ECONNREFUSED", "EPIPE", "ETIMEDOUT", "EAI_AGAIN"].includes(code))
+    return "AgentRouter upstream connection reset or unavailable";
+  if (code === "server_error") return "AgentRouter upstream server error";
+  if (code === "incomplete_stream")
+    return "AgentRouter stream ended before completion";
+  if (status === 400 || error?.status === 400)
+    return "Request rejected as invalid";
+  if (status >= 400 && status < 500) return "AgentRouter rejected the request";
+  if (status >= 500) return "AgentRouter upstream server error";
+  return "AgentRouter connection or response failed";
+}
+
+module.exports = {
+  cleanHeaders,
+  createUpstreamAgent,
+  watchUpstream,
+  requestWithRetries,
+  retryDelay,
+  isRateLimit,
+  retryableFailure,
+  upstreamFailure,
+};

package/support/usage.js

@@ -0,0 +1,144 @@
+"use strict";
+
+const { Transform } = require("node:stream");
+const { StringDecoder } = require("node:string_decoder");
+const { observeActivity } = require("./activity");
+const { retryableFailure, upstreamFailure } = require("./transport");
+const MAX_EVENT_CHARS = 1024 * 1024;
+const MAX_JSON_CHARS = 8 * 1024 * 1024;
+
+// Observe bounded visible activity, usage and terminal metadata. Forward bytes
+// unchanged; never retain prompts, tool arguments or private reasoning content.
+function createUsageObserver(headers, tracker) {
+  const contentType = String(headers["content-type"] || "").toLowerCase();
+  const encoding = String(
+    headers["content-encoding"] || "identity",
+  ).toLowerCase();
+  const sse = contentType.includes("text/event-stream");
+  const json = contentType.includes("application/json");
+  if ((!sse && !json) || !["", "identity"].includes(encoding)) {
+    tracker.note("info", "Token usage unavailable for this response encoding");
+    return null;
+  }
+  const decoder = new StringDecoder("utf8");
+  let pending = "";
+  let event = [];
+  let eventSize = 0;
+  let discardLine = false;
+  let discardEvent = false;
+  let warned = false;
+  let jsonOverflow = false;
+  function overflow() {
+    if (warned) return;
+    warned = true;
+    tracker.note(
+      "warn",
+      "Oversized usage metadata skipped; response stream unchanged",
+    );
+  }
+  function inspect(text) {
+    if (
+      !/"usage"\s*:|"type"\s*:\s*"response\.|"object"\s*:\s*"response"/.test(
+        text,
+      )
+    )
+      return;
+    try {
+      const value = JSON.parse(text);
+      observeActivity(value, tracker);
+      const usage =
+        value?.response?.usage || value?.message?.usage || value?.usage;
+      if (usage && typeof usage === "object") tracker.usage(usage);
+      // Usage and output_item.done alone do not prove response completion.
+      const type = value?.type;
+      const status = value?.object === "response" ? value.status : null;
+      if (type === "response.completed" || status === "completed") {
+        tracker.complete();
+      } else if (type === "response.failed" || status === "failed") {
+        const reason = retryableFailure(null, value);
+        tracker.fail(
+          reason
+            ? `${upstreamFailure(null, { code: reason })} (failed response; HTTP status may still be 200)`
+            : "AgentRouter reported a failed response (HTTP status may still be 200)",
+        );
+      } else if (type === "response.incomplete" || status === "incomplete") {
+        tracker.fail(
+          "AgentRouter reported an incomplete response (generation limit or content restriction)",
+        );
+      }
+    } catch {
+      /* Malformed metadata must not interrupt response delivery. */
+    }
+  }
+  function dispatch() {
+    if (!discardEvent && event.length) inspect(event.join("\n"));
+    event = [];
+    eventSize = 0;
+    discardEvent = false;
+  }
+  function line(text) {
+    if (text.endsWith("\r")) text = text.slice(0, -1);
+    if (!text) {
+      dispatch();
+      return;
+    }
+    if (discardEvent || !text.startsWith("data:")) return;
+    const data = text.slice(text[5] === " " ? 6 : 5);
+    eventSize += data.length + 1;
+    if (eventSize > MAX_EVENT_CHARS) {
+      event = [];
+      discardEvent = true;
+      overflow();
+    } else event.push(data);
+  }
+  function consume(text) {
+    if (json) {
+      if (jsonOverflow) return;
+      if (pending.length + text.length > MAX_JSON_CHARS) {
+        pending = "";
+        jsonOverflow = true;
+        overflow();
+      } else pending += text;
+      return;
+    }
+    let start = 0;
+    for (;;) {
+      const end = text.indexOf("\n", start);
+      const part = text.slice(start, end < 0 ? undefined : end);
+      if (!discardLine) {
+        if (pending.length + part.length > MAX_EVENT_CHARS) {
+          pending = "";
+          discardLine = true;
+          discardEvent = true;
+          event = [];
+          overflow();
+        } else pending += part;
+      }
+      if (end < 0) break;
+      if (!discardLine) line(pending);
+      pending = "";
+      discardLine = false;
+      start = end + 1;
+    }
+  }
+  return new Transform({
+    transform(chunk, encoding, callback) {
+      consume(decoder.write(chunk));
+      callback(null, chunk);
+    },
+    flush(callback) {
+      consume(decoder.end());
+      if (json) {
+        if (!jsonOverflow) inspect(pending);
+      } else {
+        if (pending && !discardLine) line(pending);
+        dispatch();
+      }
+      pending = "";
+      event = [];
+      callback();
+    },
+  });
+}
+
+module.exports = { createUsageObserver };