datanotes 3.2.0 → 3.3.0

package/dist/api/index.cjs

@@ -16927,125 +16927,397 @@ function classOf(cp) {
   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 } };
-  if (typeof v === "number") return Number.isInteger(v) ? { key, value: { intValue: String(v) } } : { key, value: { doubleValue: v } };
-  return { key, value: { stringValue: v } };
+// 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) } : {} };
 }
-var attrs = (a) => Object.entries(a).map(([k, v]) => attr(k, v)).filter((x) => x !== null);
-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();
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.sampled ? "01" : "00"}`;
 }
-var Pb = class {
-  constructor() {
-    this.parts = [];
-  }
-  varint(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);
-    while (x >= b128) {
-      this.parts.push(Number(x & low7) | 128);
-      x >>= seven;
-    }
-    this.parts.push(Number(x));
-  }
-  tag(field, wire) {
-    this.varint(field << 3 | wire);
+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);
   }
-  uint(field, v) {
-    this.tag(field, 0);
-    this.varint(v);
+  setAttribute(key, value) {
+    if (value !== void 0 && value !== null) this.attributes[key] = value;
     return this;
   }
-  fixed32(field, v) {
-    this.tag(field, 5);
-    for (let i = 0; i < 4; i++) this.parts.push(v >>> 8 * i & 255);
+  setAttributes(attributes) {
+    for (const k in attributes) this.setAttribute(k, attributes[k]);
     return this;
   }
-  fixed64(field, v) {
-    this.tag(field, 1);
-    for (let i = 0; i < 8; i++) this.parts.push(Number(v >> BigInt(8 * i) & BigInt(255)));
+  addEvent(name, attributes = {}) {
+    this.events.push({ name, timeMs: this.tracer.now(), attributes });
     return this;
   }
-  double(field, v) {
-    this.tag(field, 1);
-    const b = new DataView(new ArrayBuffer(8));
-    b.setFloat64(0, v, true);
-    for (let i = 0; i < 8; i++) this.parts.push(b.getUint8(i));
-    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);
   }
-  bytes(field, data) {
-    this.tag(field, 2);
-    this.varint(data.length);
-    for (const x of data) this.parts.push(x);
+  setStatus(code, message) {
+    if (this.status.code === "error" && code !== "error") return this;
+    this.status = code === "error" && message ? { code, message } : { code };
     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);
+  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
+    });
   }
-  string(field, s) {
-    return this.bytes(field, new TextEncoder().encode(s));
+};
+var Tracer = class {
+  constructor(o) {
+    this.o = o;
+    this.now = o.now ?? defaultNow;
   }
-  message(field, m) {
-    return this.bytes(field, m.finish());
+  /** 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, {});
   }
-  finish() {
-    return Uint8Array.from(this.parts);
+  /** @internal */
+  send(span) {
+    try {
+      this.o.export([span]);
+    } catch {
+    }
   }
 };
-function pbValue(v) {
-  if (typeof v === "string") return new Pb().string(1, v);
-  if (typeof v === "boolean") return new Pb().uint(2, v ? 1 : 0);
-  return Number.isInteger(v) ? new Pb().uint(3, BigInt(v)) : new Pb().double(4, v);
+
+// src/api/client.ts
+var ACTOR_HEADER = "X-Datanotes-Actor";
+var UNREACHABLE = {
+  hint: "Start the engine (datanotes serve --database <folder>) or check its address; datanotes status --database <folder> shows whether it runs and where.",
+  docs: `${DOCS_BASE}/start/connect-agents.md#how-the-mcp-server-reaches-the-engine`
+};
+var AUTH = {
+  hint: "Send the engine's owner token (httpServerToken in settings.json in the engine's store: datanotes store path shows where) or a named token the owner made with POST /datanotes/tokens/create/, as Authorization: Bearer <token>.",
+  docs: `${DOCS_BASE}/develop/http-api.md#authenticate-your-requests`
+};
+var DatanotesError = class extends Error {
+  /** `unreachable`: the engine did not answer; `auth`: the token was refused. */
+  constructor(message, kind = "http", status = 0, guidance = kind === "unreachable" ? UNREACHABLE : kind === "auth" ? AUTH : null) {
+    super(guidedText(message, guidance));
+    this.kind = kind;
+    this.status = status;
+    this.name = "DatanotesError";
+    if (guidance) {
+      this.hint = guidance.hint;
+      this.docs = guidance.docs;
+    }
+  }
+};
+var fetchTransport = async (req) => {
+  const res = await fetch(req.url, { method: req.method, headers: req.headers, ...req.body !== void 0 ? { body: req.body } : {} });
+  return { status: res.status, text: await res.text() };
+};
+function isEngineAnswer(json) {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) return false;
+  const o = json;
+  return typeof o.ok === "boolean" || typeof o.error === "string";
 }
-function pbAttrs(m, field, a) {
-  for (const [k, v] of Object.entries(a)) {
-    if (v === void 0 || v === null) continue;
-    m.message(field, new Pb().string(1, k).message(2, pbValue(v)));
+function clientSpan(tracer, method, url, parent) {
+  let target;
+  try {
+    target = new URL(url);
+  } catch {
+    target = null;
   }
-  return m;
+  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
+    }
+  });
 }
-var OtlpBatcher = class {
-  constructor(o, path, maxBatch) {
+function parse(text) {
+  try {
+    return text.trim() ? JSON.parse(text) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function trimTrailingSlashes(s) {
+  let end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
+  return end === s.length ? s : s.slice(0, end);
+}
+var DatanotesClient = class {
+  constructor(o) {
     this.o = o;
-    this.path = path;
-    this.maxBatch = maxBatch;
-    this.buffer = [];
-    this.inflight = Promise.resolve();
-    this.timer = null;
-    /** 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;
-    if (every > 0) {
-      this.timer = setInterval(() => void this.flush(), every);
-      this.timer.unref?.();
-    }
+    this.url = trimTrailingSlashes(o.url);
+    this.send = o.transport ?? fetchTransport;
+  }
+  /** 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({
+        url: `${this.url}${path}`,
+        method,
+        headers: {
+          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) } : {},
+          ...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);
+    if (unreachable) throw new DatanotesError(`engine unreachable at ${this.url} (HTTP ${res.status})`, "unreachable", res.status);
+    return { status: res.status, json, text: res.text };
+  }
+  /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
+  async post(route, body = {}, actor) {
+    const r = await this.request("POST", `/datanotes${route}`, body, actor ? { actor } : {});
+    if (r.status >= 400) throw Object.assign(new DatanotesError(resultOf(r.status, r.json, r.text).value, "http", r.status), guidanceIn(r.json));
+    return r.json;
+  }
+  /**
+   * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
+   * 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, options = {}) {
+    let req;
+    try {
+      req = operationRequest(name, args);
+    } catch (e) {
+      if (e instanceof OperationInputError) return { ok: false, value: e.message };
+      throw e;
+    }
+    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 } : {}, ...options.trace ? { trace: options.trace } : {} });
+    return resultOf(r.status, r.json, r.text);
+  }
+  /** True when the engine answers `GET /` (no token needed). */
+  async ping() {
+    try {
+      const r = await this.send({ url: `${this.url}/`, method: "GET", headers: {} });
+      return r.status === 200;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * 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) {
+    return this.post("/tool-calls/record/", call, actor);
+  }
+};
+
+// 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 } };
+  if (typeof v === "number") return Number.isInteger(v) ? { key, value: { intValue: String(v) } } : { key, value: { doubleValue: v } };
+  return { key, value: { stringValue: v } };
+}
+var attrs = (a) => Object.entries(a).map(([k, v]) => attr(k, v)).filter((x) => x !== null);
+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) {
+    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);
+    while (x >= b128) {
+      this.parts.push(Number(x & low7) | 128);
+      x >>= seven;
+    }
+    this.parts.push(Number(x));
+  }
+  tag(field, wire) {
+    this.varint(field << 3 | wire);
+  }
+  uint(field, v) {
+    this.tag(field, 0);
+    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) {
+    this.tag(field, 1);
+    for (let i = 0; i < 8; i++) this.parts.push(Number(v >> BigInt(8 * i) & BigInt(255)));
+    return this;
+  }
+  double(field, v) {
+    this.tag(field, 1);
+    const b = new DataView(new ArrayBuffer(8));
+    b.setFloat64(0, v, true);
+    for (let i = 0; i < 8; i++) this.parts.push(b.getUint8(i));
+    return this;
+  }
+  bytes(field, data) {
+    this.tag(field, 2);
+    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));
+  }
+  message(field, m) {
+    return this.bytes(field, m.finish());
+  }
+  finish() {
+    return Uint8Array.from(this.parts);
+  }
+};
+function pbValue(v) {
+  if (typeof v === "string") return new Pb().string(1, v);
+  if (typeof v === "boolean") return new Pb().uint(2, v ? 1 : 0);
+  return Number.isInteger(v) ? new Pb().uint(3, BigInt(v)) : new Pb().double(4, v);
+}
+function pbAttrs(m, field, a) {
+  for (const [k, v] of Object.entries(a)) {
+    if (v === void 0 || v === null) continue;
+    m.message(field, new Pb().string(1, k).message(2, pbValue(v)));
+  }
+  return m;
+}
+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;
+    /** 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;
+    if (every > 0) {
+      this.timer = setInterval(() => void this.flush(), every);
+      this.timer.unref?.();
+    }
   }
   push(items) {
     const room = this.maxBatch * 8 - this.buffer.length;
@@ -17060,7 +17332,7 @@ var OtlpBatcher = class {
   flush() {
     if (this.buffer.length === 0) return this.inflight;
     const send = this.o.send ?? fetchSend;
-    const url = `${this.o.endpoint.replace(/\/+$/, "")}${this.path}`;
+    const url = `${trimTrailingSlashes(this.o.endpoint)}${this.path}`;
     const protobuf = (this.o.protocol ?? "http/protobuf") === "http/protobuf";
     const headers = { "Content-Type": protobuf ? "application/x-protobuf" : "application/json", ...this.o.headers ?? {} };
     while (this.buffer.length > 0) {
@@ -17252,270 +17524,3 @@ 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 = {
-  hint: "Start the engine (datanotes serve --database <folder>) or check its address; datanotes status --database <folder> shows whether it runs and where.",
-  docs: `${DOCS_BASE}/start/connect-agents.md#how-the-mcp-server-reaches-the-engine`
-};
-var AUTH = {
-  hint: "Send the engine's owner token (httpServerToken in settings.json in the engine's store: datanotes store path shows where) or a named token the owner made with POST /datanotes/tokens/create/, as Authorization: Bearer <token>.",
-  docs: `${DOCS_BASE}/develop/http-api.md#authenticate-your-requests`
-};
-var DatanotesError = class extends Error {
-  /** `unreachable`: the engine did not answer; `auth`: the token was refused. */
-  constructor(message, kind = "http", status = 0, guidance = kind === "unreachable" ? UNREACHABLE : kind === "auth" ? AUTH : null) {
-    super(guidedText(message, guidance));
-    this.kind = kind;
-    this.status = status;
-    this.name = "DatanotesError";
-    if (guidance) {
-      this.hint = guidance.hint;
-      this.docs = guidance.docs;
-    }
-  }
-};
-var fetchTransport = async (req) => {
-  const res = await fetch(req.url, { method: req.method, headers: req.headers, ...req.body !== void 0 ? { body: req.body } : {} });
-  return { status: res.status, text: await res.text() };
-};
-function isEngineAnswer(json) {
-  if (json === null || typeof json !== "object" || Array.isArray(json)) return false;
-  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;
-  } catch {
-    return void 0;
-  }
-}
-var DatanotesClient = class {
-  constructor(o) {
-    this.o = o;
-    this.url = o.url.replace(/\/+$/, "");
-    this.send = o.transport ?? fetchTransport;
-  }
-  /** 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({
-        url: `${this.url}${path}`,
-        method,
-        headers: {
-          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) } : {},
-          ...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);
-    if (unreachable) throw new DatanotesError(`engine unreachable at ${this.url} (HTTP ${res.status})`, "unreachable", res.status);
-    return { status: res.status, json, text: res.text };
-  }
-  /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
-  async post(route, body = {}, actor) {
-    const r = await this.request("POST", `/datanotes${route}`, body, actor ? { actor } : {});
-    if (r.status >= 400) throw Object.assign(new DatanotesError(resultOf(r.status, r.json, r.text).value, "http", r.status), guidanceIn(r.json));
-    return r.json;
-  }
-  /**
-   * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
-   * 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, options = {}) {
-    let req;
-    try {
-      req = operationRequest(name, args);
-    } catch (e) {
-      if (e instanceof OperationInputError) return { ok: false, value: e.message };
-      throw e;
-    }
-    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 } : {}, ...options.trace ? { trace: options.trace } : {} });
-    return resultOf(r.status, r.json, r.text);
-  }
-  /** True when the engine answers `GET /` (no token needed). */
-  async ping() {
-    try {
-      const r = await this.send({ url: `${this.url}/`, method: "GET", headers: {} });
-      return r.status === 200;
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * 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) {
-    return this.post("/tool-calls/record/", call, actor);
-  }
-};