@tangle-network/traces 0.23.0 → 1.0.0

package/dist/chunk-DU534HAX.js

@@ -0,0 +1,263 @@
+// src/adapters/tool-io.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/source-location.ts
+import { createHash } from "crypto";
+import { resolve } from "path";
+var SOURCE_ATTRIBUTE_PREFIX = "traces.source_record.";
+var locations = /* @__PURE__ */ new WeakMap();
+function sourceFileId(path) {
+  return createHash("sha256").update(resolve(path)).digest("hex");
+}
+function pointerPart(value) {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function locateSourceObjects(value, path, bytes, offset = 0) {
+  if (!value || typeof value !== "object") return;
+  const record = {
+    sourceId: sourceFileId(path),
+    recordOffset: offset,
+    recordBytes: bytes.length,
+    recordSha256: createHash("sha256").update(bytes).digest("hex")
+  };
+  const pending = [{ value, pointer: "#" }];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    locations.set(current.value, { ...record, fieldLocator: current.pointer });
+    for (const [key, child] of Object.entries(current.value)) {
+      if (child && typeof child === "object") {
+        pending.push({ value: child, pointer: `${current.pointer}/${pointerPart(key)}` });
+      }
+    }
+  }
+}
+function sourceOf(value, ...fields) {
+  if (!value || typeof value !== "object") return void 0;
+  const location = locations.get(value);
+  return location ? {
+    ...location,
+    fieldLocator: `${location.fieldLocator}${fields.map((field) => `/${pointerPart(field)}`).join("")}`
+  } : void 0;
+}
+function textSources(value, field) {
+  if (!value || typeof value !== "object") return void 0;
+  const content = value[field];
+  if (typeof content === "string") return sourceOf(value, field);
+  if (!Array.isArray(content)) return void 0;
+  return content.flatMap((block, index) => {
+    if (typeof block === "string") {
+      const ref2 = sourceOf(value, field, String(index));
+      return ref2 ? [ref2] : [];
+    }
+    if (!block || typeof block !== "object" || typeof block.text !== "string") return [];
+    if (block.type !== void 0 && !["text", "input_text", "output_text"].includes(block.type)) return [];
+    const ref = sourceOf(block, "text");
+    return ref ? [ref] : [];
+  });
+}
+function sourceAttributes(attribute, sources) {
+  const refs = sources === void 0 ? [] : Array.isArray(sources) ? sources : [sources];
+  return refs.length === 0 ? {} : { [`${SOURCE_ATTRIBUTE_PREFIX}${attribute}`]: JSON.stringify(refs) };
+}
+function appendSourceAttributes(attributes, attribute, sources) {
+  const key = `${SOURCE_ATTRIBUTE_PREFIX}${attribute}`;
+  const added = sourceAttributes(attribute, sources)[key];
+  if (typeof added !== "string") return;
+  const prior = attributes[key];
+  const refs = typeof prior === "string" ? JSON.parse(prior) : [];
+  const known = new Set(refs.map((ref) => JSON.stringify(ref)));
+  for (const ref of JSON.parse(added)) {
+    if (!known.has(JSON.stringify(ref))) {
+      refs.push(ref);
+      known.add(JSON.stringify(ref));
+    }
+  }
+  attributes[key] = JSON.stringify(refs);
+}
+function stripSourceAttributes(attributes) {
+  return Object.fromEntries(Object.entries(attributes).filter(([key]) => !key.startsWith(SOURCE_ATTRIBUTE_PREFIX)));
+}
+
+// src/adapters/tool-io.ts
+var TOOL_IO_VALUE_MAX_BYTES = 16 * 1024;
+var TOOL_CALL_LEVEL_ATTR = "traces.tool_call.level";
+var INNER_TOOL_CALL_LEVEL = "inner";
+function isInnerToolCall(attributes) {
+  return attributes[TOOL_CALL_LEVEL_ATTR] === INNER_TOOL_CALL_LEVEL;
+}
+var TOOL_IO_SIDES = ["input", "output"];
+var LEGACY_TRUNCATION_MARKER = /\n\[truncated (\d+) bytes; sha256=[a-f0-9]{64}\]$/;
+var COUNTED_TRUNCATION_MARKER = /\n\[truncated \d+ bytes\]$/;
+var TRUNCATION_MARKER = /\n\[truncated\]$/;
+function canonicalJson(value) {
+  const sort = (item) => {
+    if (Array.isArray(item)) return item.map(sort);
+    if (!item || typeof item !== "object") return item;
+    return Object.fromEntries(
+      Object.entries(item).filter(([, entry]) => entry !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => [key, sort(entry)])
+    );
+  };
+  const json = JSON.stringify(sort(value));
+  if (json === void 0) throw new TypeError("tool I/O value is not JSON-serializable");
+  return json;
+}
+function serialize(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+      try {
+        return { value: canonicalJson(JSON.parse(trimmed)), mimeType: "application/json" };
+      } catch {
+      }
+    }
+    return { value, mimeType: "text/plain" };
+  }
+  return { value: canonicalJson(value), mimeType: "application/json" };
+}
+function utf8Prefix(value, maxBytes) {
+  let bytes = 0;
+  let end = 0;
+  for (const char of value) {
+    const charBytes = Buffer.byteLength(char);
+    if (bytes + charBytes > maxBytes) break;
+    bytes += charBytes;
+    end += char.length;
+  }
+  return Buffer.from(value.slice(0, end), "utf8").toString("utf8");
+}
+function truncatedValue(value, bytes) {
+  const longestMarker = `
+[truncated ${bytes} bytes]`;
+  const prefix = utf8Prefix(value, TOOL_IO_VALUE_MAX_BYTES - Buffer.byteLength(longestMarker));
+  const omittedBytes = bytes - Buffer.byteLength(prefix);
+  return `${prefix}
+[truncated ${omittedBytes} bytes]`;
+}
+function boundedString(value) {
+  if (value.length <= TOOL_IO_VALUE_MAX_BYTES / 4) return value;
+  const bytes = Buffer.byteLength(value);
+  return bytes > TOOL_IO_VALUE_MAX_BYTES ? truncatedValue(value, bytes) : value;
+}
+function valueAttributes(side, raw) {
+  const serialized = serialize(raw);
+  if (!serialized) return {};
+  const bytes = Buffer.byteLength(serialized.value);
+  const sha256 = createHash2("sha256").update(serialized.value).digest("hex");
+  const truncated = bytes > TOOL_IO_VALUE_MAX_BYTES;
+  const value = truncated ? truncatedValue(serialized.value, bytes) : serialized.value;
+  return {
+    [`${side}.value`]: value,
+    [`${side}.mime_type`]: serialized.mimeType,
+    [`traces.${side}.bytes`]: bytes,
+    [`traces.${side}.sha256`]: sha256,
+    [`traces.${side}.truncated`]: truncated
+  };
+}
+function toolIoAttributes(io) {
+  return {
+    ...valueAttributes("input", io.input),
+    ...valueAttributes("output", io.output),
+    ...io.input === void 0 ? {} : sourceAttributes("input.value", io.inputSource),
+    ...io.output === void 0 ? {} : sourceAttributes("output.value", io.outputSource),
+    ...io.argsCaptured === void 0 ? {} : { "tool.args_captured": io.argsCaptured }
+  };
+}
+function toolArgumentsFromAttributes(attributes) {
+  const declared = attributes["tool.args_captured"];
+  const explicit = typeof declared === "boolean" ? declared : declared === "true" ? true : declared === "false" ? false : void 0;
+  const argsCaptured = explicit ?? attributes["input.value"] !== void 0;
+  return {
+    args: argsCaptured ? attributes["input.value"] : void 0,
+    argsCaptured
+  };
+}
+function normalizeToolIoAttributes(attributes) {
+  for (const side of TOOL_IO_SIDES) {
+    const valueKey = `${side}.value`;
+    const mimeKey = `${side}.mime_type`;
+    const bytesKey = `traces.${side}.bytes`;
+    const digestKey = `traces.${side}.sha256`;
+    const truncatedKey = `traces.${side}.truncated`;
+    const rawValue = attributes[valueKey];
+    if (typeof rawValue !== "string") {
+      delete attributes[mimeKey];
+      delete attributes[bytesKey];
+      delete attributes[digestKey];
+      delete attributes[truncatedKey];
+      continue;
+    }
+    let value = rawValue.replace(LEGACY_TRUNCATION_MARKER, "\n[truncated]").replace(COUNTED_TRUNCATION_MARKER, "\n[truncated]");
+    let truncated = TRUNCATION_MARKER.test(value);
+    const unboundedBytes = Buffer.byteLength(value);
+    if (unboundedBytes > TOOL_IO_VALUE_MAX_BYTES) {
+      value = truncatedValue(value, unboundedBytes);
+      truncated = true;
+    }
+    attributes[valueKey] = value;
+    attributes[bytesKey] = Buffer.byteLength(value);
+    attributes[digestKey] = createHash2("sha256").update(value).digest("hex");
+    attributes[truncatedKey] = truncated;
+  }
+}
+function recordToolOutput(toolSpan, output, source) {
+  if (!toolSpan) return;
+  if (output === void 0) return;
+  delete toolSpan.attributes[`${SOURCE_ATTRIBUTE_PREFIX}output.value`];
+  Object.assign(toolSpan.attributes, valueAttributes("output", output));
+  Object.assign(toolSpan.attributes, sourceAttributes("output.value", source));
+}
+
+// src/time.ts
+function parseIsoToEpochMs(ts) {
+  if (typeof ts !== "string" || ts.trim().length === 0) {
+    throw new TypeError("timestamp must be a non-empty string");
+  }
+  const value = ts.trim();
+  const n = /^\d+$/.test(value) ? Number(value) : Date.parse(value);
+  if (!Number.isFinite(n) || !Number.isFinite(new Date(n).getTime())) {
+    throw new TypeError(`invalid timestamp: ${ts}`);
+  }
+  return n;
+}
+function parseSince(value) {
+  return parseTimeBound(value, "--since");
+}
+function relativeBoundMs(value) {
+  const m = value.match(/^(\d+)\s*([mhd])$/i);
+  if (!m) return void 0;
+  const unit = m[2].toLowerCase();
+  return Number(m[1]) * (unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5);
+}
+function parseTimeBound(value, flag) {
+  const relative = relativeBoundMs(value);
+  if (relative !== void 0) return Date.now() - relative;
+  const t = Date.parse(value);
+  if (Number.isNaN(t)) throw new Error(`${flag}: expected 30m / 2h / 7d or an ISO date, got "${value}"`);
+  return t;
+}
+
+export {
+  SOURCE_ATTRIBUTE_PREFIX,
+  sourceFileId,
+  locateSourceObjects,
+  sourceOf,
+  textSources,
+  sourceAttributes,
+  appendSourceAttributes,
+  stripSourceAttributes,
+  TOOL_IO_VALUE_MAX_BYTES,
+  TOOL_CALL_LEVEL_ATTR,
+  INNER_TOOL_CALL_LEVEL,
+  isInnerToolCall,
+  canonicalJson,
+  boundedString,
+  toolIoAttributes,
+  toolArgumentsFromAttributes,
+  normalizeToolIoAttributes,
+  recordToolOutput,
+  parseIsoToEpochMs,
+  parseSince,
+  relativeBoundMs,
+  parseTimeBound
+};

package/dist/chunk-GLUDGUGJ.js

@@ -0,0 +1,232 @@
+import {
+  DEFAULT_QUESTION_TIMEOUT_MS
+} from "./chunk-O52XK7OB.js";
+
+// src/analyst-model-call.ts
+import { accessSync, constants, readFileSync } from "fs";
+import { delimiter, join } from "path";
+import {
+  canonicalAgentProfileDigest,
+  canonicalCandidateDigest
+} from "@tangle-network/agent-interface";
+import { profileOptimizerModelCall } from "@tangle-network/agent-runtime/kernel";
+import { createDspyRlmTraceEngine } from "@tangle-network/agent-eval/analyst";
+var TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
+var BRIDGE_MODULE = "agent_eval_rpc.dspy_rlm_bridge";
+var ANALYST_MAX_OUTPUT_TOKENS = 16384;
+function bridgeVersion() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const version = pkg.dependencies?.["@tangle-network/agent-eval"];
+  if (typeof version !== "string" || !version) {
+    throw new Error("package.json is missing the @tangle-network/agent-eval dependency");
+  }
+  return version;
+}
+function bridgeRunner(env) {
+  if (env.TRACES_PYTHON) return { command: env.TRACES_PYTHON };
+  return { command: "uvx", args: ["--from", `agent-eval-rpc[dspy]==${bridgeVersion()}`, "python", "-m", BRIDGE_MODULE] };
+}
+function runnable(command, path) {
+  const candidates = command.includes("/") ? [command] : (path ?? "").split(delimiter).filter(Boolean).map((dir) => join(dir, command));
+  return candidates.some((candidate) => {
+    try {
+      accessSync(candidate, constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+function missingAskRequirements(env = process.env) {
+  const missing = [];
+  if (!env.TANGLE_API_KEY && !env.OPENAI_API_KEY) {
+    missing.push(
+      "a model key: set TANGLE_API_KEY for the Tangle router, or OPENAI_API_KEY (OPENAI_BASE_URL names any other OpenAI-compatible endpoint)"
+    );
+  }
+  const bridge = env.TRACES_PYTHON ? runnable(env.TRACES_PYTHON, env.PATH) : runnable("uvx", env.PATH);
+  if (!bridge) {
+    missing.push(
+      env.TRACES_PYTHON ? `the Python bridge: TRACES_PYTHON=${env.TRACES_PYTHON} is not an executable` : `the Python bridge: install uv (https://docs.astral.sh/uv/), or set TRACES_PYTHON to a Python with agent-eval-rpc[dspy]==${bridgeVersion()}`
+    );
+  }
+  return missing;
+}
+var UnservableModelError = class extends Error {
+  failure;
+  constructor(failure) {
+    super(failure.message);
+    this.name = "UnservableModelError";
+    this.failure = failure;
+  }
+};
+var TRANSIENT_STATUSES = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504, 520, 522, 524]);
+var UNSERVABLE_MODEL = /model_not_allowed|model_not_found|provider_pricing_unavailable|not in this key's allow-list|unknown model/iu;
+function endpointWords(body) {
+  const message = /"message":"((?:[^"\\]|\\.)*)/u.exec(body)?.[1];
+  return (message ?? body).replace(/\\"/gu, '"').slice(0, 240);
+}
+function classifyModelFailure(error, model) {
+  const served = /reported model ("[^"]*") but AgentProfile requires ("[^"]*")/u.exec(error);
+  if (served) {
+    return {
+      kind: "permanent",
+      failure: {
+        code: "model",
+        message: `the endpoint served ${served[1]} for --model ${served[2]}, and ask refuses an answer from a model it did not ask for; pass the provider-qualified model id (for example zai/glm-5.3)`
+      }
+    };
+  }
+  const refused = /\brouter (\d{3}): (.*)$/su.exec(error);
+  if (!refused) {
+    return /router network failure|router request timeout|ECONNRESET|ETIMEDOUT|socket hang up|fetch failed/u.test(error) ? { kind: "transient", reason: "the endpoint could not be reached" } : { kind: "other" };
+  }
+  const status = Number(refused[1]);
+  const words = endpointWords(refused[2]);
+  if (status === 401 || status === 402 || status === 403) {
+    return {
+      kind: "permanent",
+      failure: { code: "auth", message: `the model endpoint refused the key (${status}: ${words}). Check TANGLE_API_KEY, or OPENAI_API_KEY and OPENAI_BASE_URL` }
+    };
+  }
+  if (UNSERVABLE_MODEL.test(refused[2])) {
+    return {
+      kind: "permanent",
+      failure: { code: "model", message: `the model endpoint cannot serve --model ${model} (${status}: ${words})` }
+    };
+  }
+  return TRANSIENT_STATUSES.has(status) ? { kind: "transient", reason: `${status}: ${words}` } : { kind: "other" };
+}
+var MODEL_CALL_ATTEMPTS = 10;
+var FIRST_RETRY_DELAY_MS = 2e3;
+var MAX_RETRY_DELAY_MS = 6e4;
+function retryDelayMs(attempt) {
+  const delay = Math.min(MAX_RETRY_DELAY_MS, FIRST_RETRY_DELAY_MS * 2 ** (attempt - 1));
+  return Math.round(delay * (0.75 + Math.random() * 0.5));
+}
+function pause(ms, signal) {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const done = (slept) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", aborted);
+      resolve(slept);
+    };
+    const aborted = () => done(false);
+    const timer = setTimeout(() => done(true), ms);
+    signal?.addEventListener("abort", aborted, { once: true });
+  });
+}
+function retryingModelCall(call, opts) {
+  return async (request) => {
+    for (let attempt = 1; ; attempt += 1) {
+      const result = await call(request);
+      if (result.succeeded) return result;
+      const failure = classifyModelFailure(result.error, opts.model);
+      if (failure.kind === "permanent") {
+        opts.onPermanentFailure?.(failure.failure);
+        return result;
+      }
+      if (failure.kind === "other" || attempt >= MODEL_CALL_ATTEMPTS) return result;
+      const delay = retryDelayMs(attempt);
+      opts.log?.(
+        `[analyst] WARN model call failed (${failure.reason}); attempt ${attempt + 1} of ${MODEL_CALL_ATTEMPTS} in ${(delay / 1e3).toFixed(1)} s`
+      );
+      if (!await pause(delay, request.signal)) return result;
+    }
+  };
+}
+function createAnalystModelOwner(opts) {
+  const profile = {
+    name: "traces-analyst",
+    harness: "cli-base",
+    model: {
+      provider: opts.provider,
+      default: opts.model,
+      reasoningEffort: "none",
+      maxVisibleOutputTokens: ANALYST_MAX_OUTPUT_TOKENS,
+      metadata: {
+        // Stream every analyst call. The Tangle Router bounds a buffered request by a deadline that
+        // ends when response headers are sent, and a thinking model's long recursive step outlives
+        // it (`request_deadline_exceeded`). A streamed response sends headers at the first byte.
+        stream: true,
+        // One attempt per call: `retryingModelCall` decides what to retry from the endpoint's
+        // status and code, because Runtime's retry reads the status alone.
+        retry: { maxAttempts: 1 }
+      }
+    }
+  };
+  return {
+    call: profileOptimizerModelCall({
+      profile,
+      context: "traces analyst",
+      executor: {
+        backend: "router",
+        routerBaseUrl: opts.baseUrl,
+        routerKey: opts.apiKey
+      }
+    }),
+    callRef: canonicalCandidateDigest({
+      profile: canonicalAgentProfileDigest(profile),
+      endpoint: opts.baseUrl
+    }),
+    profile
+  };
+}
+function analysisEngineFromEnv(opts) {
+  const env = opts.env ?? process.env;
+  const tangleKey = env.TANGLE_API_KEY;
+  const openAiKey = env.OPENAI_API_KEY;
+  const apiKey = tangleKey || openAiKey;
+  if (!apiKey) {
+    throw new Error(
+      "model-backed analysis needs a model key: TANGLE_API_KEY for the Tangle router (the default endpoint), or OPENAI_API_KEY for OpenAI. Set OPENAI_BASE_URL to target any other OpenAI-compatible gateway. Deterministic analysis needs no key."
+    );
+  }
+  const baseUrl = env.OPENAI_BASE_URL || (tangleKey ? TANGLE_ROUTER_BASE_URL : "https://api.openai.com/v1");
+  const owner = createAnalystModelOwner({
+    apiKey,
+    baseUrl,
+    model: opts.model,
+    provider: baseUrl === TANGLE_ROUTER_BASE_URL ? "tangle-router" : baseUrl.startsWith("https://api.openai.com/") ? "openai" : "openai-compatible"
+  });
+  const log = opts.log;
+  try {
+    return createDspyRlmTraceEngine({
+      call: retryingModelCall(owner.call, {
+        model: opts.model,
+        ...log ? { log } : {},
+        ...opts.onPermanentFailure ? { onPermanentFailure: opts.onPermanentFailure } : {}
+      }),
+      callRef: owner.callRef,
+      recordExecution: (observation) => {
+        log?.(
+          `[analyst] model call ${observation.sequence} ${observation.succeeded ? "ok" : "FAIL"} ${observation.model}`,
+          observation.succeeded ? void 0 : { error: observation.error }
+        );
+      },
+      model: opts.model,
+      maxOutputTokens: ANALYST_MAX_OUTPUT_TOKENS,
+      // The engine's own default ceiling is $1 per investigation, a proxy-side
+      // ceiling separate from any shared ledger; the caller's allocation wins.
+      ...opts.maxCostUsd !== void 0 && Number.isFinite(opts.maxCostUsd) && opts.maxCostUsd > 0 ? { maxCostUsd: opts.maxCostUsd } : {},
+      timeoutMs: opts.timeoutMs ?? DEFAULT_QUESTION_TIMEOUT_MS,
+      runner: bridgeRunner(env)
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/no pricing is configured/u.test(message)) {
+      throw new UnservableModelError({ code: "model", message: `ask cannot price --model ${opts.model}, so it cannot bound the spend: ${message}` });
+    }
+    throw error;
+  }
+}
+
+export {
+  ANALYST_MAX_OUTPUT_TOKENS,
+  bridgeVersion,
+  missingAskRequirements,
+  UnservableModelError,
+  createAnalystModelOwner,
+  analysisEngineFromEnv
+};