datanotes 3.0.0 → 3.1.0

package/dist/api/index.cjs

@@ -28,21 +28,33 @@ __export(index_exports, {
   OPERATIONS: () => OPERATIONS,
   OperationInputError: () => OperationInputError,
   OtlpLogExporter: () => OtlpLogExporter,
+  OtlpTraceExporter: () => OtlpTraceExporter,
   ROUTE_PREFIX: () => ROUTE_PREFIX,
+  TRACEPARENT_HEADER: () => TRACEPARENT_HEADER,
+  TRACESTATE_HEADER: () => TRACESTATE_HEADER,
+  TraceSpan: () => TraceSpan,
+  Tracer: () => Tracer,
   argumentsOf: () => argumentsOf,
   checkArguments: () => checkArguments,
   describeBatch: () => describeBatch,
   describeRefusal: () => describeRefusal,
   estimateTokens: () => estimateTokens,
   fetchTransport: () => fetchTransport,
+  formatTraceparent: () => formatTraceparent,
   guidanceIn: () => guidanceIn,
   guidedText: () => guidedText,
+  newSpanId: () => newSpanId,
+  newTraceId: () => newTraceId,
   operationRequest: () => operationRequest,
   operationRoute: () => operationRoute,
   otlpFromEnv: () => otlpFromEnv,
+  otlpTracesFromEnv: () => otlpTracesFromEnv,
   parseOtlpHeaders: () => parseOtlpHeaders,
+  parseTraceparent: () => parseTraceparent,
   resultOf: () => resultOf,
-  toolDocs: () => toolDocs
+  samplerRatioFromEnv: () => samplerRatioFromEnv,
+  toolDocs: () => toolDocs,
+  traceHeaders: () => traceHeaders
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -16003,7 +16015,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_neighbors",
-    "description": 'Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,\nbacklinks), with counts per edge label. `direction`: out, in or both (default).\n\n`from_nodes` selects the notes: `{"paths": [...]}` and/or `{"table": ..., "where": {...}}`.\nEdges are labelled with their link column (`people`, `event`, \u2026) or `link` for other links.',
+    "description": 'Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,\nbacklinks), with counts per edge label. `direction`: out, in or both (default).\n\n`from_nodes` selects the notes: `{"paths": [...]}`, `{"table": ..., "where": {...}}` and/or\n`{"tables": [...]}`: the rows of several tables, by name or pattern (`["*"]` every table, `["personal.*"]` a\ncatalog\'s). The whole vault\'s graph in one call: `{"tables": ["*"]}` with direction `out` (at most 5000\nstart notes). Edges are labelled with their link column (`people`, `event`, \u2026) or `link` for other links.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -16122,7 +16134,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_traverse",
-    "description": 'Breadth-first walk over links from `from_nodes` (`{"paths": [...]}` and/or `{"table", "where"}`).\n\n- `direction`: out (default, follow links), in (follow backlinks) or both.\n- `edges`: edge labels to follow (link columns such as `people`, `event`, or `link`).\n- `tables`: return only notes of these tables; `through`: only walk on through these tables.\n- `min_depth` (default 1) / `max_depth` (default 2, max 10), `limit` (default 500).\n\nEach node comes with `depth` and `via` (one shortest route). Example \u2014 moods tied to events\nwith Alice: from `{"table": "person", "where": {"name": "Alice"}}`, direction `in`, edges\n`["people", "event"]`, tables `["mood"]`, max_depth 2. Feed the paths to `select_rows` with\n`where: {"path": {"in": [...]}}` to aggregate them.',
+    "description": 'Breadth-first walk over links from `from_nodes` (`{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`).\n\n- `direction`: out (default, follow links), in (follow backlinks) or both.\n- `edges`: edge labels to follow (link columns such as `people`, `event`, or `link`).\n- `tables`: return only notes of these tables; `through`: only walk on through these tables.\n- `min_depth` (default 1) / `max_depth` (default 2, max 10), `limit` (default 500).\n\nEach node comes with `depth` and `via` (one shortest route). Example \u2014 moods tied to events\nwith Alice: from `{"table": "person", "where": {"name": "Alice"}}`, direction `in`, edges\n`["people", "event"]`, tables `["mood"]`, max_depth 2. Feed the paths to `select_rows` with\n`where: {"path": {"in": [...]}}` to aggregate them.',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -16318,7 +16330,7 @@ var OPERATIONS = [
   },
   {
     "name": "graph_path",
-    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}` and/or\n`{"table", "where"}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
+    "description": 'Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}`\nand/or `{"tables": [...]}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`).\n`direction` both by default; `max_depth` default 6 (max 10).',
     "inputSchema": {
       "additionalProperties": false,
       "properties": {
@@ -16706,17 +16718,52 @@ function resultOf(status, json, text) {
 // src/api/tokens.ts
 function estimateTokens(text) {
   let n = 0;
-  for (const m of text.matchAll(/\p{L}+|\p{N}+|[^\s\p{L}\p{N}]/gu)) {
-    const s = m[0];
-    if (/^\p{L}/u.test(s)) n += Math.ceil(s.length / 4);
-    else if (/^\p{N}/u.test(s)) n += Math.ceil(s.length / 3);
-    else n += 1;
+  let run = 0;
+  for (let i = 0; i < text.length; ) {
+    const c = text.charCodeAt(i);
+    const cp = c >= 55296 && c <= 56319 ? text.codePointAt(i) : c;
+    const width = cp > 65535 ? 2 : 1;
+    const kind = classOf(cp);
+    if (kind === LETTER && run >= 0) run += width;
+    else if (kind === DIGIT && run <= 0) run -= width;
+    else {
+      n += run > 0 ? Math.ceil(run / 4) : Math.ceil(-run / 3);
+      run = kind === LETTER ? width : kind === DIGIT ? -width : 0;
+      if (kind === OTHER) n += 1;
+    }
+    i += width;
+  }
+  return n + (run > 0 ? Math.ceil(run / 4) : Math.ceil(-run / 3));
+}
+var LETTER = 0;
+var DIGIT = 1;
+var SPACE = 2;
+var OTHER = 3;
+function test(cp) {
+  const ch = String.fromCodePoint(cp);
+  return /\p{L}/u.test(ch) ? LETTER : /\p{N}/u.test(ch) ? DIGIT : /\s/u.test(ch) ? SPACE : OTHER;
+}
+var BMP = new Uint8Array(65536).fill(255);
+var ASTRAL = /* @__PURE__ */ new Map();
+var ASTRAL_KEPT = 4096;
+function classOf(cp) {
+  if (cp <= 65535) {
+    let k2 = BMP[cp];
+    if (k2 === 255) BMP[cp] = k2 = test(cp);
+    return k2;
+  }
+  let k = ASTRAL.get(cp);
+  if (k === void 0) {
+    k = test(cp);
+    if (ASTRAL.size < ASTRAL_KEPT) ASTRAL.set(cp, k);
   }
-  return n;
+  return k;
 }
 
 // src/api/otlp.ts
 var SEVERITY_NUMBER = { DEBUG: 5, INFO: 9, WARN: 13, ERROR: 17 };
+var SPAN_KIND = { internal: 1, server: 2, client: 3, producer: 4, consumer: 5 };
+var STATUS_CODE = { unset: 0, ok: 1, error: 2 };
 function attr(key, v) {
   if (v === void 0 || v === null) return null;
   if (typeof v === "boolean") return { key, value: { boolValue: v } };
@@ -16728,12 +16775,26 @@ var fetchSend = async (url, body, headers) => {
   const res = await fetch(url, { method: "POST", headers, body });
   if (!res.ok) throw new Error(`OTLP HTTP ${res.status}`);
 };
+function unixNano(ms) {
+  const whole = Math.floor(ms);
+  const frac = Math.round((ms - whole) * 1e6);
+  return (BigInt(whole) * BigInt(1e6) + BigInt(frac)).toString();
+}
 var Pb = class {
   constructor() {
     this.parts = [];
   }
   varint(v) {
-    let x = BigInt.asUintN(64, v);
+    if (typeof v === "number" && v >= 0 && v < 2 ** 31) {
+      let x2 = v;
+      while (x2 >= 128) {
+        this.parts.push(x2 & 127 | 128);
+        x2 >>>= 7;
+      }
+      this.parts.push(x2);
+      return;
+    }
+    let x = BigInt.asUintN(64, BigInt(v));
     const b128 = BigInt(128);
     const low7 = BigInt(127);
     const seven = BigInt(7);
@@ -16744,11 +16805,16 @@ var Pb = class {
     this.parts.push(Number(x));
   }
   tag(field, wire) {
-    this.varint(BigInt(field << 3 | wire));
+    this.varint(field << 3 | wire);
   }
   uint(field, v) {
     this.tag(field, 0);
-    this.varint(BigInt(v));
+    this.varint(v);
+    return this;
+  }
+  fixed32(field, v) {
+    this.tag(field, 5);
+    for (let i = 0; i < 4; i++) this.parts.push(v >>> 8 * i & 255);
     return this;
   }
   fixed64(field, v) {
@@ -16765,10 +16831,16 @@ var Pb = class {
   }
   bytes(field, data) {
     this.tag(field, 2);
-    this.varint(BigInt(data.length));
+    this.varint(data.length);
     for (const x of data) this.parts.push(x);
     return this;
   }
+  /** An id given in hex (trace and span ids), as bytes. */
+  hex(field, hex) {
+    const out = [];
+    for (let i = 0; i < hex.length; i += 2) out.push(parseInt(hex.slice(i, i + 2), 16));
+    return this.bytes(field, out);
+  }
   string(field, s) {
     return this.bytes(field, new TextEncoder().encode(s));
   }
@@ -16791,13 +16863,15 @@ function pbAttrs(m, field, a) {
   }
   return m;
 }
-var OtlpLogExporter = class {
-  constructor(o) {
+var OtlpBatcher = class {
+  constructor(o, path, maxBatch) {
     this.o = o;
+    this.path = path;
+    this.maxBatch = maxBatch;
     this.buffer = [];
     this.inflight = Promise.resolve();
     this.timer = null;
-    /** Records sent, and records lost because the collector did not take them. */
+    /** Items sent, and items lost because the collector did not take them (or the buffer was full). */
     this.sent = 0;
     this.dropped = 0;
     const every = o.flushMs ?? 5e3;
@@ -16806,19 +16880,60 @@ var OtlpLogExporter = class {
       this.timer.unref?.();
     }
   }
-  log(severity, body, attributes = {}) {
-    const ms = (this.o.now ?? Date.now)();
-    this.buffer.push({ timeUnixNano: `${Math.round(ms)}000000`, severity, body, attributes });
-    if (this.buffer.length >= (this.o.maxBatch ?? 50)) void this.flush();
+  push(items) {
+    const room = this.maxBatch * 8 - this.buffer.length;
+    if (room < items.length) this.dropped += items.length - Math.max(room, 0);
+    for (let i = 0; i < Math.min(items.length, Math.max(room, 0)); i++) this.buffer.push(items[i]);
+    if (this.buffer.length >= this.maxBatch) void this.flush();
+  }
+  resource() {
+    return { "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource };
   }
   /** Send what is buffered. Never rejects. */
   flush() {
     if (this.buffer.length === 0) return this.inflight;
-    const batch = this.buffer;
-    this.buffer = [];
-    const resource = { "service.name": this.o.serviceName, "service.version": this.o.serviceVersion, ...this.o.resource };
+    const send = this.o.send ?? fetchSend;
+    const url = `${this.o.endpoint.replace(/\/+$/, "")}${this.path}`;
     const protobuf = (this.o.protocol ?? "http/protobuf") === "http/protobuf";
-    const body = protobuf ? this.protobuf(resource, batch) : JSON.stringify({
+    const headers = { "Content-Type": protobuf ? "application/x-protobuf" : "application/json", ...this.o.headers ?? {} };
+    while (this.buffer.length > 0) {
+      const batch = this.buffer.splice(0, this.maxBatch);
+      let body;
+      try {
+        body = this.encode(batch, protobuf);
+      } catch {
+        this.dropped += batch.length;
+        continue;
+      }
+      this.inflight = this.inflight.then(
+        () => send(url, body, headers).then(
+          () => void (this.sent += batch.length),
+          () => void (this.dropped += batch.length)
+        )
+      );
+    }
+    return this.inflight;
+  }
+  /** Stop the timer and send what is left. */
+  async close() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    await this.flush();
+  }
+};
+var OtlpLogExporter = class extends OtlpBatcher {
+  constructor(o) {
+    super(o, "/v1/logs", o.maxBatch ?? 50);
+  }
+  /** Buffer a record; `context`: the span it was made in (its trace and span id go with it). */
+  log(severity, body, attributes = {}, context) {
+    const ms = (this.o.now ?? Date.now)();
+    this.push([{ timeUnixNano: `${Math.round(ms)}000000`, severity, body, attributes, ...context ? { context } : {} }]);
+  }
+  encode(batch, protobuf) {
+    const resource = this.resource();
+    if (protobuf) return this.protobuf(resource, batch);
+    return JSON.stringify({
       resourceLogs: [
         {
           resource: { attributes: attrs(resource) },
@@ -16831,39 +16946,90 @@ var OtlpLogExporter = class {
                 severityNumber: SEVERITY_NUMBER[r.severity],
                 severityText: r.severity,
                 body: { stringValue: r.body },
-                attributes: attrs(r.attributes)
+                attributes: attrs(r.attributes),
+                ...r.context ? { traceId: r.context.traceId, spanId: r.context.spanId, flags: r.context.sampled ? 1 : 0 } : {}
               }))
             }
           ]
         }
       ]
     });
-    const url = `${this.o.endpoint.replace(/\/+$/, "")}/v1/logs`;
-    const send = this.o.send ?? fetchSend;
-    this.inflight = this.inflight.then(
-      () => send(url, body, { "Content-Type": protobuf ? "application/x-protobuf" : "application/json", ...this.o.headers ?? {} }).then(
-        () => void (this.sent += batch.length),
-        () => void (this.dropped += batch.length)
-      )
-    );
-    return this.inflight;
   }
   protobuf(resource, batch) {
     const scope = new Pb().message(1, new Pb().string(1, this.o.serviceName));
     for (const r of batch) {
       const t = BigInt(r.timeUnixNano);
       const rec = new Pb().fixed64(1, t).uint(2, SEVERITY_NUMBER[r.severity]).string(3, r.severity).message(5, new Pb().string(1, r.body));
-      pbAttrs(rec, 6, r.attributes).fixed64(11, t);
+      pbAttrs(rec, 6, r.attributes);
+      if (r.context) rec.fixed32(8, r.context.sampled ? 1 : 0).hex(9, r.context.traceId).hex(10, r.context.spanId);
+      rec.fixed64(11, t);
       scope.message(2, rec);
     }
     const resourceLogs = new Pb().message(1, pbAttrs(new Pb(), 1, resource)).message(2, scope);
     return new Pb().message(1, resourceLogs).finish();
   }
-  /** Stop the timer and send what is left. */
-  async close() {
-    if (this.timer) clearInterval(this.timer);
-    this.timer = null;
-    await this.flush();
+};
+var OtlpTraceExporter = class extends OtlpBatcher {
+  constructor(o) {
+    super(o, "/v1/traces", o.maxBatch ?? 512);
+  }
+  /** Buffer finished spans (sent with the next batch). Never throws. */
+  export(spans) {
+    this.push(Array.isArray(spans) ? spans : [spans]);
+  }
+  encode(batch, protobuf) {
+    const resource = this.resource();
+    if (protobuf) return this.protobuf(resource, batch);
+    return JSON.stringify({
+      resourceSpans: [
+        {
+          resource: { attributes: attrs(resource) },
+          scopeSpans: [
+            {
+              scope: { name: this.o.serviceName, ...this.o.serviceVersion ? { version: this.o.serviceVersion } : {} },
+              spans: batch.map((s) => ({
+                traceId: s.traceId,
+                spanId: s.spanId,
+                ...s.parentSpanId ? { parentSpanId: s.parentSpanId } : {},
+                ...s.traceState ? { traceState: s.traceState } : {},
+                flags: 1,
+                name: s.name,
+                kind: SPAN_KIND[s.kind],
+                startTimeUnixNano: unixNano(s.startMs),
+                endTimeUnixNano: unixNano(s.endMs),
+                attributes: attrs(s.attributes),
+                ...s.droppedAttributes ? { droppedAttributesCount: s.droppedAttributes } : {},
+                events: s.events.map((e) => ({ timeUnixNano: unixNano(e.timeMs), name: e.name, attributes: attrs(e.attributes) })),
+                ...s.droppedEvents ? { droppedEventsCount: s.droppedEvents } : {},
+                status: { code: STATUS_CODE[s.status.code], ...s.status.message ? { message: s.status.message } : {} }
+              }))
+            }
+          ]
+        }
+      ]
+    });
+  }
+  protobuf(resource, batch) {
+    const scopeInfo = new Pb().string(1, this.o.serviceName);
+    if (this.o.serviceVersion) scopeInfo.string(2, this.o.serviceVersion);
+    const scope = new Pb().message(1, scopeInfo);
+    for (const s of batch) {
+      const span = new Pb().hex(1, s.traceId).hex(2, s.spanId);
+      if (s.traceState) span.string(3, s.traceState);
+      if (s.parentSpanId) span.hex(4, s.parentSpanId);
+      span.string(5, s.name).uint(6, SPAN_KIND[s.kind]).fixed64(7, BigInt(unixNano(s.startMs))).fixed64(8, BigInt(unixNano(s.endMs)));
+      pbAttrs(span, 9, s.attributes);
+      if (s.droppedAttributes) span.uint(10, s.droppedAttributes);
+      for (const e of s.events) span.message(11, pbAttrs(new Pb().fixed64(1, BigInt(unixNano(e.timeMs))).string(2, e.name), 3, e.attributes));
+      if (s.droppedEvents) span.uint(12, s.droppedEvents);
+      const status = new Pb();
+      if (s.status.message) status.string(2, s.status.message);
+      if (s.status.code !== "unset") status.uint(3, STATUS_CODE[s.status.code]);
+      span.message(15, status).fixed32(16, 1);
+      scope.message(2, span);
+    }
+    const resourceSpans = new Pb().message(1, pbAttrs(new Pb(), 1, resource)).message(2, scope);
+    return new Pb().message(1, resourceSpans).finish();
   }
 };
 function parseOtlpHeaders(text) {
@@ -16885,12 +17051,18 @@ function parseOtlpHeaders(text) {
 var parseResourceAttributes = parseOtlpHeaders;
 var truthy = (v) => (v ?? "").trim().toLowerCase() === "true";
 function otlpFromEnv(env, defaults) {
-  if (truthy(env.OTEL_SDK_DISABLED) || (env.OTEL_LOGS_EXPORTER ?? "").trim().toLowerCase() === "none") return null;
-  const logs = env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT?.trim();
+  return fromEnv(env, defaults, "LOGS", "logs");
+}
+function otlpTracesFromEnv(env, defaults) {
+  return fromEnv(env, defaults, "TRACES", "traces");
+}
+function fromEnv(env, defaults, signal, path) {
+  if (truthy(env.OTEL_SDK_DISABLED) || (env[`OTEL_${signal}_EXPORTER`] ?? "").trim().toLowerCase() === "none") return null;
+  const own = env[`OTEL_EXPORTER_OTLP_${signal}_ENDPOINT`]?.trim();
   const base = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
-  const endpoint = logs ? logs.replace(/\/v1\/logs\/?$/, "") : base;
+  const endpoint = own ? own.replace(new RegExp(`/v1/${path}/?$`), "") : base;
   if (!endpoint) return null;
-  const protocol = otlpProtocol(env.OTEL_EXPORTER_OTLP_LOGS_PROTOCOL ?? env.OTEL_EXPORTER_OTLP_PROTOCOL);
+  const protocol = otlpProtocol(env[`OTEL_EXPORTER_OTLP_${signal}_PROTOCOL`] ?? env.OTEL_EXPORTER_OTLP_PROTOCOL);
   const resource = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
   return {
     endpoint,
@@ -16898,14 +17070,139 @@ function otlpFromEnv(env, defaults) {
     ...defaults.serviceVersion ? { serviceVersion: defaults.serviceVersion } : {},
     ...protocol ? { protocol } : {},
     ...Object.keys(resource).length ? { resource } : {},
-    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_LOGS_HEADERS) }
+    headers: { ...parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS), ...parseOtlpHeaders(env[`OTEL_EXPORTER_OTLP_${signal}_HEADERS`]) }
   };
 }
+function samplerRatioFromEnv(env) {
+  const sampler = (env.OTEL_TRACES_SAMPLER ?? "").trim().toLowerCase().replace(/^parentbased_/, "");
+  if (sampler === "always_on") return 1;
+  if (sampler === "always_off") return 0;
+  if (sampler !== "traceidratio") return void 0;
+  const arg = Number((env.OTEL_TRACES_SAMPLER_ARG ?? "").trim() || "1");
+  return Number.isFinite(arg) && arg >= 0 && arg <= 1 ? arg : 1;
+}
 function otlpProtocol(v) {
   const p = (v ?? "").trim().toLowerCase();
   return p === "http/protobuf" || p === "http/json" ? p : void 0;
 }
 
+// src/api/tracing.ts
+var TRACEPARENT_HEADER = "traceparent";
+var TRACESTATE_HEADER = "tracestate";
+var TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
+function parseTraceparent(traceparent, tracestate) {
+  const m = TRACEPARENT.exec((typeof traceparent === "string" ? traceparent : "").trim().toLowerCase());
+  if (!m) return null;
+  const [, version, traceId, spanId, flags, rest] = m;
+  if (version === "ff" || version === "00" && rest !== void 0) return null;
+  if (/^0+$/.test(traceId) || /^0+$/.test(spanId)) return null;
+  const state = (typeof tracestate === "string" ? tracestate : "").trim();
+  return { traceId, spanId, sampled: (parseInt(flags, 16) & 1) === 1, ...state ? { traceState: state.slice(0, 512) } : {} };
+}
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
+}
+function traceHeaders(ctx) {
+  return { [TRACEPARENT_HEADER]: formatTraceparent(ctx), ...ctx.traceState ? { [TRACESTATE_HEADER]: ctx.traceState } : {} };
+}
+function randomHex(bytes) {
+  const b = new Uint8Array(bytes);
+  const c = globalThis.crypto;
+  if (c?.getRandomValues) c.getRandomValues(b);
+  else for (let i = 0; i < bytes; i++) b[i] = Math.floor(Math.random() * 256);
+  const hex = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+  return /^0+$/.test(hex) ? randomHex(bytes) : hex;
+}
+var newTraceId = () => randomHex(16);
+var newSpanId = () => randomHex(8);
+var perf = globalThis.performance;
+var defaultNow = perf ? () => perf.timeOrigin + perf.now() : () => Date.now();
+var TraceSpan = class {
+  constructor(tracer, name, kind, parent, recording, attributes) {
+    this.tracer = tracer;
+    this.name = name;
+    this.kind = kind;
+    this.parent = parent;
+    this.recording = recording;
+    this.attributes = {};
+    this.events = [];
+    this.status = { code: "unset" };
+    this.ended = false;
+    this.context = {
+      traceId: parent?.traceId ?? newTraceId(),
+      spanId: newSpanId(),
+      sampled: recording,
+      ...parent?.traceState ? { traceState: parent.traceState } : {}
+    };
+    this.startMs = tracer.now();
+    this.setAttributes(attributes);
+  }
+  setAttribute(key, value) {
+    if (value !== void 0 && value !== null) this.attributes[key] = value;
+    return this;
+  }
+  setAttributes(attributes) {
+    for (const k in attributes) this.setAttribute(k, attributes[k]);
+    return this;
+  }
+  addEvent(name, attributes = {}) {
+    this.events.push({ name, timeMs: this.tracer.now(), attributes });
+    return this;
+  }
+  /** An `exception` event, `error.type` and status ERROR. */
+  recordException(e) {
+    const type = e instanceof Error ? e.name : typeof e;
+    const message = e instanceof Error ? e.message : String(e);
+    this.addEvent("exception", { "exception.type": type, "exception.message": message, ...e instanceof Error && e.stack ? { "exception.stacktrace": e.stack.slice(0, 8192) } : {} });
+    if (!("error.type" in this.attributes)) this.attributes["error.type"] = type;
+    return this.setStatus("error", message);
+  }
+  setStatus(code, message) {
+    if (this.status.code === "error" && code !== "error") return this;
+    this.status = code === "error" && message ? { code, message } : { code };
+    return this;
+  }
+  end() {
+    if (this.ended) return;
+    this.ended = true;
+    if (!this.recording) return;
+    this.tracer.send({
+      traceId: this.context.traceId,
+      spanId: this.context.spanId,
+      ...this.parent ? { parentSpanId: this.parent.spanId } : {},
+      ...this.context.traceState ? { traceState: this.context.traceState } : {},
+      name: this.name,
+      kind: this.kind,
+      startMs: this.startMs,
+      endMs: this.tracer.now(),
+      attributes: this.attributes,
+      events: this.events,
+      status: this.status
+    });
+  }
+};
+var Tracer = class {
+  constructor(o) {
+    this.o = o;
+    this.now = o.now ?? defaultNow;
+  }
+  /** A new span: a child of `parent` (a context or a `traceparent` header), or a new trace. */
+  startSpan(name, opts = {}) {
+    const parent = typeof opts.parent === "string" ? parseTraceparent(opts.parent) : opts.parent ?? null;
+    const ratio = this.o.sampleRatio ?? 1;
+    const span = new TraceSpan(this, name, opts.kind ?? "internal", parent, true, opts.attributes ?? {});
+    const recording = parent ? parent.sampled : ratio >= 1 || ratio > 0 && parseInt(span.context.traceId.slice(-13), 16) / 2 ** 52 < ratio;
+    return recording ? span : new TraceSpan(this, name, opts.kind ?? "internal", parent ?? { ...span.context, sampled: false }, false, {});
+  }
+  /** @internal */
+  send(span) {
+    try {
+      this.o.export([span]);
+    } catch {
+    }
+  }
+};
+
 // src/api/client.ts
 var ACTOR_HEADER = "X-Datanotes-Actor";
 var UNREACHABLE = {
@@ -16938,6 +17235,24 @@ function isEngineAnswer(json) {
   const o = json;
   return typeof o.ok === "boolean" || typeof o.error === "string";
 }
+function clientSpan(tracer, method, url, parent) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    target = null;
+  }
+  return tracer.startSpan(target ? `${method} ${target.pathname}` : method, {
+    kind: "client",
+    parent,
+    attributes: {
+      "http.request.method": method,
+      "url.full": target ? `${target.protocol}//${target.host}${target.pathname}` : void 0,
+      "server.address": target?.hostname,
+      "server.port": target ? Number(target.port || (target.protocol === "https:" ? 443 : 80)) : void 0
+    }
+  });
+}
 function parse(text) {
   try {
     return text.trim() ? JSON.parse(text) : void 0;
@@ -16951,11 +17266,22 @@ var DatanotesClient = class {
     this.url = o.url.replace(/\/+$/, "");
     this.send = o.transport ?? fetchTransport;
   }
-  /** Send a request; the answer's status, its JSON (when it is JSON) and its text. */
+  /** The parent of a request: the call's own `trace`, else the client's. */
+  parentOf(trace) {
+    const given = trace ?? (typeof this.o.trace === "function" ? this.o.trace() : this.o.trace);
+    return typeof given === "string" ? parseTraceparent(given) : given ?? null;
+  }
+  /**
+   * Send a request; the answer's status, its JSON (when it is JSON) and its text. `trace`: the
+   * trace this request continues (over the client's `trace` option).
+   */
   async request(method, path, body, opts = {}) {
     if (!this.url) throw new DatanotesError("engine address not set", "unreachable");
     if (!this.o.token) throw new DatanotesError("token not set", "auth");
     const actor = opts.actor ?? this.o.actor;
+    const parent = this.parentOf(opts.trace);
+    const span = this.o.tracer ? clientSpan(this.o.tracer, method, `${this.url}${path}`, parent) : void 0;
+    const sent = span?.context ?? parent;
     let res;
     try {
       res = await this.send({
@@ -16965,13 +17291,20 @@ var DatanotesClient = class {
           Authorization: `Bearer ${this.o.token}`,
           ...body !== void 0 ? { "Content-Type": "application/json" } : {},
           ...opts.accept ? { Accept: opts.accept } : {},
-          ...actor && Object.keys(actor).length ? { [ACTOR_HEADER]: JSON.stringify(actor) } : {}
+          ...actor && Object.keys(actor).length ? { [ACTOR_HEADER]: JSON.stringify(actor) } : {},
+          ...sent ? traceHeaders(sent) : {}
         },
         ...body !== void 0 ? { body: JSON.stringify(body) } : {}
       });
     } catch (e) {
+      span?.recordException(e);
+      span?.end();
       throw new DatanotesError(`engine unreachable at ${this.url}: ${e instanceof Error ? e.message : String(e)}`, "unreachable");
     }
+    span?.setAttribute("http.response.status_code", res.status);
+    if (res.status >= 400) span?.setAttribute("error.type", String(res.status));
+    if (res.status >= 500) span?.setStatus("error", `HTTP ${res.status}`);
+    span?.end();
     if (res.status === 401) throw new DatanotesError("token refused by the engine", "auth", 401);
     const json = parse(res.text);
     const unreachable = res.status === 0 || res.status === 502 || res.status === 504 || res.status === 503 && !isEngineAnswer(json);
@@ -16989,7 +17322,7 @@ var DatanotesClient = class {
    * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
    * with the same message the engine gives.
    */
-  async call(name, args = {}, actor) {
+  async call(name, args = {}, actor, options = {}) {
     let req;
     try {
       req = operationRequest(name, args);
@@ -16999,7 +17332,7 @@ var DatanotesClient = class {
     }
     const problem = checkArguments(name, args);
     if (problem) return { ok: false, value: guidedText(problem.message, problem) };
-    const r = await this.request(req.method, req.path, req.body, actor ? { actor } : {});
+    const r = await this.request(req.method, req.path, req.body, { ...actor ? { actor } : {}, ...options.trace ? { trace: options.trace } : {} });
     return resultOf(r.status, r.json, r.text);
   }
   /** True when the engine answers `GET /` (no token needed). */
@@ -17011,8 +17344,11 @@ var DatanotesClient = class {
       return false;
     }
   }
-  /** Record an agent's tool call in the change feed (what MCP servers report). */
+  /**
+   * Record an agent's tool call in the change feed (what MCP servers report). Answers what the
+   * engine said: `takes_summary` when it records a `value` sent cut with its `summary`.
+   */
   async recordToolCall(call, actor) {
-    await this.post("/tool-calls/record/", call, actor);
+    return this.post("/tool-calls/record/", call, actor);
   }
 };

package/dist/api/index.d.cts

@@ -9,5 +9,6 @@ export { operationRequest, operationRoute, CALLABLE_OPERATIONS, OperationInputEr
 export { resultOf, describeRefusal, describeBatch, type OperationResult } from "./results.cjs";
 export { estimateTokens } from "./tokens.cjs";
 export { argumentsOf, checkArguments, DOCS_BASE, guidanceIn, guidedText, toolDocs, type ArgumentProblem, type Guidance } from "./guidance.cjs";
-export { OtlpLogExporter, otlpFromEnv, parseOtlpHeaders, type OtlpOptions, type Severity, type AttrValue } from "./otlp.cjs";
-export { DatanotesClient, DatanotesError, fetchTransport, ACTOR_HEADER, type ActorInfo, type ClientOptions, type HttpRequest, type HttpResponse, type ToolCallRecord, type Transport, } from "./client.cjs";
+export { OtlpLogExporter, OtlpTraceExporter, otlpFromEnv, otlpTracesFromEnv, samplerRatioFromEnv, parseOtlpHeaders, type OtlpOptions, type Severity, type AttrValue } from "./otlp.cjs";
+export { Tracer, TraceSpan, parseTraceparent, formatTraceparent, traceHeaders, newTraceId, newSpanId, TRACEPARENT_HEADER, TRACESTATE_HEADER, type TraceContext, type TracerOptions, type SpanRecord, type SpanKind, type SpanStatusCode, } from "./tracing.cjs";
+export { DatanotesClient, DatanotesError, fetchTransport, ACTOR_HEADER, type ActorInfo, type ClientOptions, type HttpRequest, type HttpResponse, type RecordedToolCall, type ToolCallRecord, type TraceParent, type Transport, } from "./client.cjs";

package/dist/api/index.d.ts

@@ -9,5 +9,6 @@ export { operationRequest, operationRoute, CALLABLE_OPERATIONS, OperationInputEr
 export { resultOf, describeRefusal, describeBatch, type OperationResult } from "./results.js";
 export { estimateTokens } from "./tokens.js";
 export { argumentsOf, checkArguments, DOCS_BASE, guidanceIn, guidedText, toolDocs, type ArgumentProblem, type Guidance } from "./guidance.js";
-export { OtlpLogExporter, otlpFromEnv, parseOtlpHeaders, type OtlpOptions, type Severity, type AttrValue } from "./otlp.js";
-export { DatanotesClient, DatanotesError, fetchTransport, ACTOR_HEADER, type ActorInfo, type ClientOptions, type HttpRequest, type HttpResponse, type ToolCallRecord, type Transport, } from "./client.js";
+export { OtlpLogExporter, OtlpTraceExporter, otlpFromEnv, otlpTracesFromEnv, samplerRatioFromEnv, parseOtlpHeaders, type OtlpOptions, type Severity, type AttrValue } from "./otlp.js";
+export { Tracer, TraceSpan, parseTraceparent, formatTraceparent, traceHeaders, newTraceId, newSpanId, TRACEPARENT_HEADER, TRACESTATE_HEADER, type TraceContext, type TracerOptions, type SpanRecord, type SpanKind, type SpanStatusCode, } from "./tracing.js";
+export { DatanotesClient, DatanotesError, fetchTransport, ACTOR_HEADER, type ActorInfo, type ClientOptions, type HttpRequest, type HttpResponse, type RecordedToolCall, type ToolCallRecord, type TraceParent, type Transport, } from "./client.js";