@tangle-network/traces 0.23.1 → 1.0.1

package/dist/chunk-TOCNGML5.js

@@ -0,0 +1,273 @@
+import {
+  isMetadataAttribute,
+  metadataOnly
+} from "./chunk-6GOG5KIK.js";
+import {
+  scanSessions
+} from "./chunk-7USMM4MA.js";
+import {
+  ATTR,
+  INGEST_SOURCE_CLI
+} from "./chunk-UQSAGXPH.js";
+import {
+  writeOtlpFile
+} from "./chunk-CQ6UYZG6.js";
+import {
+  redactSpans
+} from "./chunk-RZL5GAWH.js";
+import {
+  parseIsoToEpochMs
+} from "./chunk-DU534HAX.js";
+
+// src/upload.ts
+import { readFile as readFile2 } from "fs/promises";
+import { createRequire } from "module";
+import { hostname } from "os";
+import { basename, join as join2 } from "path";
+import { hostedClientFromEnv } from "@tangle-network/agent-eval/hosted";
+import { assessShareSafety, combineVerdicts, REDACTION_VERSION, redact, shareAllowed } from "@tangle-network/agent-eval/traces";
+
+// src/upload-state.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { contentHash } from "@tangle-network/agent-eval";
+function stateHome() {
+  return process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+}
+function stateFile() {
+  return join(stateHome(), "traces", "uploaded.json");
+}
+function legacyStateFile() {
+  return join(stateHome(), "tangle-traces", "uploaded.json");
+}
+function uploadKey(harness, sessionId) {
+  return `${harness}:${sessionId}`;
+}
+function sessionHash(spans) {
+  return contentHash(spans).slice(0, 32);
+}
+function outboundHash(events, identity) {
+  return contentHash({ events, identity }).slice(0, 32);
+}
+async function loadState() {
+  for (const file of [stateFile(), legacyStateFile()]) {
+    try {
+      return JSON.parse(await readFile(file, "utf8"));
+    } catch {
+    }
+  }
+  return {};
+}
+async function saveState(state) {
+  const f = stateFile();
+  await mkdir(dirname(f), { recursive: true });
+  await writeFile(f, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+}
+function alreadyUploaded(state, harness, sessionId, hash) {
+  return state[uploadKey(harness, sessionId)]?.hash === hash;
+}
+
+// src/upload.ts
+var require2 = createRequire(import.meta.url);
+var TRACES_VERSION = require2("../package.json").version;
+async function planUpload(opts = {}) {
+  return { ...await planUploadFrom(scanSessions(opts)), sinceMs: opts.sinceMs };
+}
+async function planUploadFrom(sessions) {
+  const state = await loadState();
+  const items = [];
+  for await (const { ref, spans: raw } of sessions) {
+    const { spans, report } = redactSpans(raw);
+    const hash = sessionHash(spans);
+    items.push({
+      ref,
+      spans,
+      redaction: report,
+      hash,
+      isNew: true
+    });
+  }
+  return { items, state };
+}
+async function gitBranch(cwd) {
+  if (!cwd) return void 0;
+  try {
+    const head = await readFile2(join2(cwd, ".git", "HEAD"), "utf8");
+    const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
+    return m?.[1]?.trim();
+  } catch {
+    return void 0;
+  }
+}
+async function sessionMeta(item) {
+  const meta = {
+    [ATTR.HARNESS]: item.ref.harness,
+    [ATTR.SESSION_FILE]: basename(item.ref.path),
+    [ATTR.HOST]: hostname(),
+    [ATTR.UPLOADER]: `tangle-traces@${TRACES_VERSION}`,
+    [ATTR.REDACTION_VERSION]: REDACTION_VERSION,
+    [ATTR.REDACTION_COUNT]: item.redaction.redactionCount
+  };
+  if (item.ref.cwd) meta[ATTR.CWD] = item.ref.cwd;
+  const branch = await gitBranch(item.ref.cwd);
+  if (branch) meta[ATTR.GIT_BRANCH] = branch;
+  return redact(meta).value;
+}
+var msToNano = (epochMs) => (BigInt(epochMs) * 1000000n).toString();
+function toTraceSpanEvents(spans, rootMeta) {
+  return spans.map((s) => {
+    const attributes = {};
+    for (const [k, v] of Object.entries(s.attributes)) {
+      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") attributes[k] = v;
+      else if (v != null) attributes[k] = JSON.stringify(v);
+    }
+    attributes[ATTR.SESSION_ID] = s.trace_id;
+    attributes[ATTR.INGEST_SOURCE] = INGEST_SOURCE_CLI;
+    if (s.parent_span_id === null) Object.assign(attributes, rootMeta);
+    const startMs = parseIsoToEpochMs(s.start_time);
+    const endMs = Math.max(startMs, parseIsoToEpochMs(s.end_time));
+    return {
+      traceId: s.trace_id,
+      spanId: s.span_id,
+      ...s.parent_span_id ? { parentSpanId: s.parent_span_id } : {},
+      name: s.name,
+      startTimeUnixNano: msToNano(startMs),
+      endTimeUnixNano: msToNano(endMs),
+      attributes,
+      ...s.status.code === "UNSET" ? {} : { status: { code: s.status.code, ...s.status.message ? { message: s.status.message } : {} } }
+    };
+  });
+}
+var PartialUploadError = class extends Error {
+  sessionKey;
+  accepted;
+  expected;
+  constructor(sessionKey, accepted, expected) {
+    super(`upload: backend accepted ${accepted} of ${expected} spans for ${sessionKey}`);
+    this.name = "PartialUploadError";
+    this.sessionKey = sessionKey;
+    this.accepted = accepted;
+    this.expected = expected;
+  }
+};
+async function prepareOutbound(plan, opts, uploadedAt) {
+  let candidates = plan.items;
+  if (opts.stripContent) {
+    candidates = candidates.map((item) => ({ ...item, spans: metadataOnly(item.spans).spans }));
+  }
+  const identity = {
+    stripContent: opts.stripContent === true,
+    redactor: null,
+    redactionVersion: REDACTION_VERSION
+  };
+  const items = [];
+  const refused = [];
+  const verdicts = [];
+  for (const item of candidates) {
+    const key = uploadKey(item.ref.harness, item.ref.sessionId);
+    const previous = plan.state[key];
+    const meta = await sessionMeta(item);
+    if (opts.stripContent) {
+      for (const [key2, value] of Object.entries(meta)) if (!isMetadataAttribute(key2, value)) delete meta[key2];
+    }
+    const eventsAt = (timestamp) => toTraceSpanEvents(item.spans, { ...meta, [ATTR.UPLOADED_AT]: timestamp });
+    let eventTimestamp = previous?.uploadedAt ?? uploadedAt;
+    let events = eventsAt(eventTimestamp);
+    let hash = outboundHash(events, identity);
+    if (alreadyUploaded(plan.state, item.ref.harness, item.ref.sessionId, hash)) continue;
+    if (eventTimestamp !== uploadedAt) {
+      eventTimestamp = uploadedAt;
+      events = eventsAt(eventTimestamp);
+      hash = outboundHash(events, identity);
+    }
+    const verdict = assessShareSafety(events);
+    verdicts.push(verdict);
+    if (!shareAllowed(verdict)) {
+      refused.push({ harness: item.ref.harness, sessionId: item.ref.sessionId, verdict });
+      continue;
+    }
+    items.push({ item, events, hash });
+  }
+  return {
+    items,
+    skipped: plan.items.length - items.length - refused.length,
+    refused,
+    ...verdicts.length > 0 ? { verdict: combineVerdicts("default", verdicts) } : {}
+  };
+}
+async function executeUpload(plan, opts = {}) {
+  const uploadedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const { items, skipped, refused, verdict } = await prepareOutbound(plan, opts, uploadedAt);
+  const redactionCount = items.reduce((n, { item }) => n + item.redaction.redactionCount, 0);
+  if (opts.dryRun) {
+    const path = opts.otlpOut === void 0 ? void 0 : await writeOtlpFile(items.flatMap(({ item }) => item.spans), opts.otlpOut);
+    return {
+      uploadedSessions: 0,
+      skippedSessions: skipped,
+      acceptedSpans: 0,
+      redactionCount,
+      dryRun: true,
+      ...path === void 0 ? {} : { otlpPath: path },
+      refused,
+      ...verdict ? { verdict } : {}
+    };
+  }
+  if (items.length === 0) {
+    return {
+      uploadedSessions: 0,
+      skippedSessions: skipped,
+      acceptedSpans: 0,
+      redactionCount,
+      dryRun: false,
+      refused,
+      ...verdict ? { verdict } : {}
+    };
+  }
+  const client = opts.backend ?? hostedClientFromEnv();
+  if (!client) {
+    throw new Error(
+      "upload: no backend. Pass opts.backend, or configure the hosted Tangle Intelligence client via TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), and TANGLE_TENANT_ID. Use --dry-run to preview without uploading."
+    );
+  }
+  const state = plan.state;
+  let acceptedSpans = 0;
+  const completed = [];
+  for (const outbound of items) {
+    const { item, events, hash } = outbound;
+    const key = uploadKey(item.ref.harness, item.ref.sessionId);
+    const idempotencyKey = `${key}:${hash}`;
+    const res = await client.ingestTraces(events, idempotencyKey);
+    if (res.accepted !== events.length) throw new PartialUploadError(key, res.accepted, events.length);
+    acceptedSpans += res.accepted;
+    completed.push({ key, item, hash, spanCount: events.length });
+    opts.log?.(`uploaded ${item.ref.harness} ${item.ref.sessionId.slice(0, 8)} \u2014 ${res.accepted} spans`);
+  }
+  for (const { key, item, hash, spanCount } of completed) {
+    state[key] = {
+      hash,
+      uploadedAt,
+      harness: item.ref.harness,
+      spanCount
+    };
+  }
+  await saveState(state);
+  return {
+    uploadedSessions: items.length,
+    skippedSessions: skipped,
+    acceptedSpans,
+    redactionCount,
+    dryRun: false,
+    refused,
+    ...verdict ? { verdict } : {}
+  };
+}
+
+export {
+  planUpload,
+  planUploadFrom,
+  toTraceSpanEvents,
+  PartialUploadError,
+  executeUpload
+};

package/dist/chunk-UQSAGXPH.js

@@ -0,0 +1,208 @@
+import {
+  span
+} from "./chunk-CQ6UYZG6.js";
+
+// src/attributes.ts
+var ATTR = {
+  /** = the trace/session id. Wire contract (dedup linkage). */
+  SESSION_ID: "tangle.sessionId",
+  /** "cli" marks a CLI upload so the platform can drop a re-upload of a session
+   *  that also streamed live. Wire contract. */
+  INGEST_SOURCE: "tangle.ingest_source",
+  HARNESS: "tangle.harness",
+  CWD: "tangle.cwd",
+  /** THE per-session grouping key the spine derives subjects from
+   *  (`deriveSubjectKey` reads `tangle.subject.key` first). Resolves to the git
+   *  remote (host/owner/repo) when readable, else the cwd path basename. */
+  SUBJECT_KEY: "tangle.subject.key",
+  /** Normalized git remote (e.g. `github.com/tangle-network/agent-container`). */
+  GIT_REPOSITORY: "git.repository",
+  /** Current branch at conversion time. */
+  GIT_BRANCH_NAME: "git.branch",
+  /** HEAD short sha at conversion time. */
+  GIT_COMMIT: "git.commit",
+  /** How traces resolved the session cwd: recorded cwd, repaired cwd, or span path. */
+  REPO_RESOLUTION_SOURCE: "traces.repo_resolution_source",
+  GIT_BRANCH: "tangle.git_branch",
+  HOST: "tangle.host",
+  /** Basename of the session file. (Renamed from the ambiguous `tangle.source`,
+   *  which collided with `tangle.ingest_source`.) */
+  SESSION_FILE: "tangle.session_file",
+  UPLOADED_AT: "tangle.uploaded_at",
+  UPLOADER: "tangle.uploader",
+  REDACTION_VERSION: "redaction.version",
+  REDACTION_COUNT: "redaction.count",
+  /** Upload contract: bounded root summary plus location-only receipt child spans.
+   *  Receipt hashes are deliberate integrity evidence; raw malformed bytes never upload. */
+  SESSION_INTEGRITY: "traces.session.integrity",
+  CORRUPTION_COUNT: "traces.session.corruption_count",
+  CORRUPTION_DIGEST: "traces.session.corruption_digest",
+  CORRUPTION_RECEIPT_VERSION: "traces.session.corruption.receipt_version",
+  CORRUPTION_RECEIPT_KIND: "traces.session.corruption.kind",
+  CORRUPTION_SOURCE_PATH: "traces.session.corruption.source_path",
+  CORRUPTION_LINE_NUMBER: "traces.session.corruption.line_number",
+  CORRUPTION_BYTE_OFFSET: "traces.session.corruption.byte_offset",
+  CORRUPTION_BYTE_LENGTH: "traces.session.corruption.byte_length",
+  CORRUPTION_SHA256: "traces.session.corruption.sha256",
+  RAW_SOURCE_RETENTION: "traces.session.raw_source_retention",
+  /** Container image reference the session executed in (OTel semconv key). */
+  CONTAINER_IMAGE: "container.image.name",
+  /** Immutable image digest (`sha256:…`) — the replay-grade environment pin. */
+  CONTAINER_IMAGE_DIGEST: "container.image.digest",
+  /** Sandbox/container instance id that executed the session. */
+  SANDBOX_ID: "tangle.sandbox.id",
+  /** Recorded execution cwd, verbatim. Unlike `tangle.cwd` it is never
+   *  repaired against the host filesystem — replay verification needs the
+   *  in-container path even when no such path exists on this host. */
+  ENVIRONMENT_CWD: "tangle.environment.cwd"
+};
+var SESSION_CWD_ATTR = "traces.session.cwd";
+var SESSION_TOTAL_TOKENS_ATTR = "traces.session.total_tokens";
+var SESSION_TOTAL_INPUT_ATTR = "traces.session.total_input_tokens";
+var SESSION_TOTAL_OUTPUT_ATTR = "traces.session.total_output_tokens";
+var SESSION_TOTAL_CACHED_INPUT_ATTR = "traces.session.total_cached_input_tokens";
+var SESSION_TOTAL_CACHE_WRITE_ATTR = "traces.session.total_cache_write_input_tokens";
+var SESSION_TOTAL_REASONING_ATTR = "traces.session.total_reasoning_tokens";
+var INGEST_SOURCE_CLI = "cli";
+function environmentAttributes(environment) {
+  if (!environment) return {};
+  const attrs = {};
+  if (environment.image) attrs[ATTR.CONTAINER_IMAGE] = environment.image;
+  if (environment.imageDigest) attrs[ATTR.CONTAINER_IMAGE_DIGEST] = environment.imageDigest;
+  if (environment.sandboxId) attrs[ATTR.SANDBOX_ID] = environment.sandboxId;
+  if (environment.cwd) attrs[ATTR.ENVIRONMENT_CWD] = environment.cwd;
+  if (environment.gitCommit) attrs[ATTR.GIT_COMMIT] = environment.gitCommit;
+  return attrs;
+}
+function stampEnvironmentAttrs(spans, environment) {
+  const attrs = environmentAttributes(environment);
+  const keys = Object.keys(attrs);
+  if (keys.length === 0) return;
+  for (const span2 of spans) {
+    for (const key of keys) {
+      if (span2.attributes[key] === void 0) span2.attributes[key] = attrs[key];
+    }
+  }
+}
+var SESSION_ID_ATTRIBUTE_KEYS = [ATTR.SESSION_ID, "session.id", "traces.session.id"];
+function sessionIdFromAttributes(attributes) {
+  return SESSION_ID_ATTRIBUTE_KEYS.map((key) => attributes[key]).find(
+    (value) => typeof value === "string" && value.length > 0
+  );
+}
+function indexSessionIdsByTrace(spans) {
+  const candidatesByTrace = /* @__PURE__ */ new Map();
+  for (const span2 of spans) {
+    const candidates = candidatesByTrace.get(span2.trace_id) ?? /* @__PURE__ */ new Set();
+    for (const key of SESSION_ID_ATTRIBUTE_KEYS) {
+      const value = span2.attributes[key];
+      if (typeof value === "string" && value.length > 0) candidates.add(value);
+    }
+    if (candidates.size > 0) candidatesByTrace.set(span2.trace_id, candidates);
+  }
+  const sessionByTrace = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  for (const [traceId, candidates] of candidatesByTrace) {
+    const sessionIds = [...candidates].sort();
+    if (sessionIds.length === 1) {
+      sessionByTrace.set(traceId, sessionIds[0]);
+    } else {
+      conflicts.push({ traceId, sessionIds });
+    }
+  }
+  conflicts.sort((a, b) => a.traceId.localeCompare(b.traceId));
+  return { sessionByTrace, conflicts };
+}
+function stampSessionIdentity(spans, fallbackSessionId) {
+  const { sessionByTrace, conflicts } = indexSessionIdsByTrace(spans);
+  const conflictingTraceIds = new Set(conflicts.map((conflict) => conflict.traceId));
+  const traceIds = new Set(spans.map((span2) => span2.trace_id));
+  const singleTraceId = traceIds.size === 1 ? traceIds.values().next().value : void 0;
+  for (const span2 of spans) {
+    if (conflictingTraceIds.has(span2.trace_id)) continue;
+    const sessionId = sessionByTrace.get(span2.trace_id) ?? singleTraceId ?? fallbackSessionId;
+    if (!sessionIdFromAttributes(span2.attributes)) {
+      span2.attributes[ATTR.SESSION_ID] = sessionId;
+    }
+  }
+}
+
+// src/adapters/conversation.ts
+var CONTENT_CAP = 8e3;
+function capText(raw, limit = CONTENT_CAP) {
+  const t = raw.trim();
+  if (t.length <= limit) return t;
+  return `${t.slice(0, limit)}\u2026 [+${t.length - limit} chars]`;
+}
+var ACTOR_ATTR = "tangle.actor";
+function userPromptSpan(o) {
+  return span({
+    traceId: o.traceId,
+    spanId: o.spanId,
+    parentSpanId: o.parentSpanId,
+    name: "user.prompt",
+    kind: "CHAIN",
+    startTime: o.startTime,
+    service: o.service ?? null,
+    agent: o.agent ?? null,
+    step: o.step,
+    content: o.content,
+    contentSource: o.contentSource,
+    extra: { [ACTOR_ATTR]: o.actor ?? "human" }
+  });
+}
+
+// src/adapters/provenance.ts
+var SYNTHESIZED_SPAN_ATTR = "traces.span.synthesized";
+var SYNTHESIZED_SOURCE_ATTR = "traces.span.synthesized_from";
+var INHERITED_SPAN_ATTR = "traces.session.inherited";
+var INHERITED_SOURCE_ATTR = "traces.session.inherited_source";
+var INHERITED_SPAN_COUNT_ATTR = "traces.session.inherited_span_count";
+var INHERITED_SPANS_OMITTED_ATTR = "traces.session.inherited_spans_omitted";
+var SUBAGENT_SPAN_ATTR = "traces.span.subagent";
+var SUBAGENT_TASK_ATTR = "traces.span.subagent_task";
+var SUBAGENT_SPAN_COUNT_ATTR = "traces.session.subagent_span_count";
+var SUBAGENT_SPAWN_ATTR = "traces.agent.spawn";
+var SUBAGENT_SPAWN_TASK_ATTR = "traces.agent.spawn_task";
+function isSynthesizedSpan(attributes) {
+  return attributes[SYNTHESIZED_SPAN_ATTR] === true;
+}
+function isInheritedSpan(attributes) {
+  return attributes[INHERITED_SPAN_ATTR] === true;
+}
+function isSubagentSpan(attributes) {
+  return attributes[SUBAGENT_SPAN_ATTR] === true;
+}
+
+export {
+  ATTR,
+  SESSION_CWD_ATTR,
+  SESSION_TOTAL_TOKENS_ATTR,
+  SESSION_TOTAL_INPUT_ATTR,
+  SESSION_TOTAL_OUTPUT_ATTR,
+  SESSION_TOTAL_CACHED_INPUT_ATTR,
+  SESSION_TOTAL_CACHE_WRITE_ATTR,
+  SESSION_TOTAL_REASONING_ATTR,
+  INGEST_SOURCE_CLI,
+  stampEnvironmentAttrs,
+  sessionIdFromAttributes,
+  indexSessionIdsByTrace,
+  stampSessionIdentity,
+  capText,
+  ACTOR_ATTR,
+  userPromptSpan,
+  SYNTHESIZED_SPAN_ATTR,
+  SYNTHESIZED_SOURCE_ATTR,
+  INHERITED_SPAN_ATTR,
+  INHERITED_SOURCE_ATTR,
+  INHERITED_SPAN_COUNT_ATTR,
+  INHERITED_SPANS_OMITTED_ATTR,
+  SUBAGENT_SPAN_ATTR,
+  SUBAGENT_TASK_ATTR,
+  SUBAGENT_SPAN_COUNT_ATTR,
+  SUBAGENT_SPAWN_ATTR,
+  SUBAGENT_SPAWN_TASK_ATTR,
+  isSynthesizedSpan,
+  isInheritedSpan,
+  isSubagentSpan
+};