@agentmark-ai/shared-utils 0.5.1 → 0.6.1

package/dist/trace-io.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Canonical trace-level input/output derivation — the ONE definition of
+ * "what is a trace's input and output", shared by every read path that
+ * projects spans into a trace summary: the cloud gateway's
+ * `transformTraceDetail`, the local CLI's `mapRawTraceToDetail`
+ * (`GET /v1/traces/:id`), and the CLI's dataset import-from-traces source
+ * mapper. Before this helper existed each call site had its own semantics
+ * (root span vs first/last GENERATION span), so the same trace answered
+ * differently depending on which endpoint you asked.
+ *
+ * Layered semantics, per-field:
+ *
+ * 1. **Root span first.** The WebhookRunner owns the prompt (root) span and
+ *    records `agentmark.input` / `agentmark.output` on it — the true
+ *    end-to-end request/response boundary. When the root span carries a
+ *    value, it wins.
+ * 2. **GENERATION fallback.** Traces emitted without the runner (third-party
+ *    OTEL instrumentation pointed straight at the collector, or pre-runner
+ *    SDK versions) have no root-span I/O. Fall back to the first GENERATION
+ *    span's input and the last GENERATION span's output, in timestamp order
+ *    — the model's view of the run.
+ *
+ * Fields resolve independently: a trace whose root span has only an output
+ * (e.g. written by an older runner that recorded output but not input)
+ * gets its input from the GENERATION fallback.
+ */
+/** Minimal span projection the derivation needs — both the camelCase
+ * service-layer `Span` and mapped wire spans satisfy it. */
+interface TraceIOSpan {
+    /** null/undefined/'' parent marks a root span. */
+    parentId?: string | null;
+    /** Span classification; only 'GENERATION' participates in the fallback. */
+    type?: string | null;
+    /** Sort key for first/last GENERATION. ISO strings and epoch numbers both
+     * order correctly under `<`. */
+    timestamp?: string | number;
+    input?: unknown;
+    output?: unknown;
+}
+interface TraceIO {
+    input?: unknown;
+    output?: unknown;
+}
+/**
+ * Derive trace-level input/output from a trace's spans. Returns each field
+ * only when a value exists — callers spread the result so absent fields stay
+ * absent on the wire (`{...deriveTraceIO(spans)}`).
+ */
+declare function deriveTraceIO(spans: readonly TraceIOSpan[]): TraceIO;
+
+export { type TraceIO, type TraceIOSpan, deriveTraceIO };

package/dist/trace-io.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Canonical trace-level input/output derivation — the ONE definition of
+ * "what is a trace's input and output", shared by every read path that
+ * projects spans into a trace summary: the cloud gateway's
+ * `transformTraceDetail`, the local CLI's `mapRawTraceToDetail`
+ * (`GET /v1/traces/:id`), and the CLI's dataset import-from-traces source
+ * mapper. Before this helper existed each call site had its own semantics
+ * (root span vs first/last GENERATION span), so the same trace answered
+ * differently depending on which endpoint you asked.
+ *
+ * Layered semantics, per-field:
+ *
+ * 1. **Root span first.** The WebhookRunner owns the prompt (root) span and
+ *    records `agentmark.input` / `agentmark.output` on it — the true
+ *    end-to-end request/response boundary. When the root span carries a
+ *    value, it wins.
+ * 2. **GENERATION fallback.** Traces emitted without the runner (third-party
+ *    OTEL instrumentation pointed straight at the collector, or pre-runner
+ *    SDK versions) have no root-span I/O. Fall back to the first GENERATION
+ *    span's input and the last GENERATION span's output, in timestamp order
+ *    — the model's view of the run.
+ *
+ * Fields resolve independently: a trace whose root span has only an output
+ * (e.g. written by an older runner that recorded output but not input)
+ * gets its input from the GENERATION fallback.
+ */
+/** Minimal span projection the derivation needs — both the camelCase
+ * service-layer `Span` and mapped wire spans satisfy it. */
+interface TraceIOSpan {
+    /** null/undefined/'' parent marks a root span. */
+    parentId?: string | null;
+    /** Span classification; only 'GENERATION' participates in the fallback. */
+    type?: string | null;
+    /** Sort key for first/last GENERATION. ISO strings and epoch numbers both
+     * order correctly under `<`. */
+    timestamp?: string | number;
+    input?: unknown;
+    output?: unknown;
+}
+interface TraceIO {
+    input?: unknown;
+    output?: unknown;
+}
+/**
+ * Derive trace-level input/output from a trace's spans. Returns each field
+ * only when a value exists — callers spread the result so absent fields stay
+ * absent on the wire (`{...deriveTraceIO(spans)}`).
+ */
+declare function deriveTraceIO(spans: readonly TraceIOSpan[]): TraceIO;
+
+export { type TraceIO, type TraceIOSpan, deriveTraceIO };

package/dist/trace-io.js

@@ -0,0 +1,52 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/trace-io.ts
+var trace_io_exports = {};
+__export(trace_io_exports, {
+  deriveTraceIO: () => deriveTraceIO
+});
+module.exports = __toCommonJS(trace_io_exports);
+function present(v) {
+  if (v === null || v === void 0) return false;
+  if (typeof v === "string") return v.length > 0;
+  return true;
+}
+function deriveTraceIO(spans) {
+  var _a, _b;
+  const rootSpan = (_a = spans.find((s) => !s.parentId)) != null ? _a : spans[0];
+  const generationSpans = spans.filter((s) => s.type === "GENERATION").sort((a, b) => {
+    var _a2, _b2;
+    const ta = (_a2 = a.timestamp) != null ? _a2 : 0;
+    const tb = (_b2 = b.timestamp) != null ? _b2 : 0;
+    return ta < tb ? -1 : ta > tb ? 1 : 0;
+  });
+  const input = present(rootSpan == null ? void 0 : rootSpan.input) ? rootSpan == null ? void 0 : rootSpan.input : (_b = generationSpans.find((s) => present(s.input))) == null ? void 0 : _b.input;
+  const lastGenWithOutput = [...generationSpans].reverse().find((s) => present(s.output));
+  const output = present(rootSpan == null ? void 0 : rootSpan.output) ? rootSpan == null ? void 0 : rootSpan.output : lastGenWithOutput == null ? void 0 : lastGenWithOutput.output;
+  return {
+    ...present(input) ? { input } : {},
+    ...present(output) ? { output } : {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  deriveTraceIO
+});
+//# sourceMappingURL=trace-io.js.map

package/dist/trace-io.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-io.ts"],"sourcesContent":["/**\n * Canonical trace-level input/output derivation — the ONE definition of\n * \"what is a trace's input and output\", shared by every read path that\n * projects spans into a trace summary: the cloud gateway's\n * `transformTraceDetail`, the local CLI's `mapRawTraceToDetail`\n * (`GET /v1/traces/:id`), and the CLI's dataset import-from-traces source\n * mapper. Before this helper existed each call site had its own semantics\n * (root span vs first/last GENERATION span), so the same trace answered\n * differently depending on which endpoint you asked.\n *\n * Layered semantics, per-field:\n *\n * 1. **Root span first.** The WebhookRunner owns the prompt (root) span and\n *    records `agentmark.input` / `agentmark.output` on it — the true\n *    end-to-end request/response boundary. When the root span carries a\n *    value, it wins.\n * 2. **GENERATION fallback.** Traces emitted without the runner (third-party\n *    OTEL instrumentation pointed straight at the collector, or pre-runner\n *    SDK versions) have no root-span I/O. Fall back to the first GENERATION\n *    span's input and the last GENERATION span's output, in timestamp order\n *    — the model's view of the run.\n *\n * Fields resolve independently: a trace whose root span has only an output\n * (e.g. written by an older runner that recorded output but not input)\n * gets its input from the GENERATION fallback.\n */\n\n/** Minimal span projection the derivation needs — both the camelCase\n * service-layer `Span` and mapped wire spans satisfy it. */\nexport interface TraceIOSpan {\n  /** null/undefined/'' parent marks a root span. */\n  parentId?: string | null;\n  /** Span classification; only 'GENERATION' participates in the fallback. */\n  type?: string | null;\n  /** Sort key for first/last GENERATION. ISO strings and epoch numbers both\n   * order correctly under `<`. */\n  timestamp?: string | number;\n  input?: unknown;\n  output?: unknown;\n}\n\nexport interface TraceIO {\n  input?: unknown;\n  output?: unknown;\n}\n\n/** Truthy-and-nonempty check that keeps non-string payloads (objects from\n * already-parsed wire spans) while rejecting '', null, undefined. */\nfunction present(v: unknown): boolean {\n  if (v === null || v === undefined) return false;\n  if (typeof v === \"string\") return v.length > 0;\n  return true;\n}\n\n/**\n * Derive trace-level input/output from a trace's spans. Returns each field\n * only when a value exists — callers spread the result so absent fields stay\n * absent on the wire (`{...deriveTraceIO(spans)}`).\n */\nexport function deriveTraceIO(spans: readonly TraceIOSpan[]): TraceIO {\n  const rootSpan = spans.find((s) => !s.parentId) ?? spans[0];\n\n  const generationSpans = spans\n    .filter((s) => s.type === \"GENERATION\")\n    .sort((a, b) => {\n      const ta = a.timestamp ?? 0;\n      const tb = b.timestamp ?? 0;\n      return ta < tb ? -1 : ta > tb ? 1 : 0;\n    });\n\n  const input = present(rootSpan?.input)\n    ? rootSpan?.input\n    : generationSpans.find((s) => present(s.input))?.input;\n\n  const lastGenWithOutput = [...generationSpans]\n    .reverse()\n    .find((s) => present(s.output));\n  const output = present(rootSpan?.output)\n    ? rootSpan?.output\n    : lastGenWithOutput?.output;\n\n  return {\n    ...(present(input) ? { input } : {}),\n    ...(present(output) ? { output } : {}),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgDA,SAAS,QAAQ,GAAqB;AACpC,MAAI,MAAM,QAAQ,MAAM,OAAW,QAAO;AAC1C,MAAI,OAAO,MAAM,SAAU,QAAO,EAAE,SAAS;AAC7C,SAAO;AACT;AAOO,SAAS,cAAc,OAAwC;AA3DtE;AA4DE,QAAM,YAAW,WAAM,KAAK,CAAC,MAAM,CAAC,EAAE,QAAQ,MAA7B,YAAkC,MAAM,CAAC;AAE1D,QAAM,kBAAkB,MACrB,OAAO,CAAC,MAAM,EAAE,SAAS,YAAY,EACrC,KAAK,CAAC,GAAG,MAAM;AAhEpB,QAAAA,KAAAC;AAiEM,UAAM,MAAKD,MAAA,EAAE,cAAF,OAAAA,MAAe;AAC1B,UAAM,MAAKC,MAAA,EAAE,cAAF,OAAAA,MAAe;AAC1B,WAAO,KAAK,KAAK,KAAK,KAAK,KAAK,IAAI;AAAA,EACtC,CAAC;AAEH,QAAM,QAAQ,QAAQ,qCAAU,KAAK,IACjC,qCAAU,SACV,qBAAgB,KAAK,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,MAA5C,mBAA+C;AAEnD,QAAM,oBAAoB,CAAC,GAAG,eAAe,EAC1C,QAAQ,EACR,KAAK,CAAC,MAAM,QAAQ,EAAE,MAAM,CAAC;AAChC,QAAM,SAAS,QAAQ,qCAAU,MAAM,IACnC,qCAAU,SACV,uDAAmB;AAEvB,SAAO;AAAA,IACL,GAAI,QAAQ,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC;AAAA,IAClC,GAAI,QAAQ,MAAM,IAAI,EAAE,OAAO,IAAI,CAAC;AAAA,EACtC;AACF;","names":["_a","_b"]}

package/dist/trace-io.mjs

@@ -0,0 +1,27 @@
+// src/trace-io.ts
+function present(v) {
+  if (v === null || v === void 0) return false;
+  if (typeof v === "string") return v.length > 0;
+  return true;
+}
+function deriveTraceIO(spans) {
+  var _a, _b;
+  const rootSpan = (_a = spans.find((s) => !s.parentId)) != null ? _a : spans[0];
+  const generationSpans = spans.filter((s) => s.type === "GENERATION").sort((a, b) => {
+    var _a2, _b2;
+    const ta = (_a2 = a.timestamp) != null ? _a2 : 0;
+    const tb = (_b2 = b.timestamp) != null ? _b2 : 0;
+    return ta < tb ? -1 : ta > tb ? 1 : 0;
+  });
+  const input = present(rootSpan == null ? void 0 : rootSpan.input) ? rootSpan == null ? void 0 : rootSpan.input : (_b = generationSpans.find((s) => present(s.input))) == null ? void 0 : _b.input;
+  const lastGenWithOutput = [...generationSpans].reverse().find((s) => present(s.output));
+  const output = present(rootSpan == null ? void 0 : rootSpan.output) ? rootSpan == null ? void 0 : rootSpan.output : lastGenWithOutput == null ? void 0 : lastGenWithOutput.output;
+  return {
+    ...present(input) ? { input } : {},
+    ...present(output) ? { output } : {}
+  };
+}
+export {
+  deriveTraceIO
+};
+//# sourceMappingURL=trace-io.mjs.map

package/dist/trace-io.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-io.ts"],"sourcesContent":["/**\n * Canonical trace-level input/output derivation — the ONE definition of\n * \"what is a trace's input and output\", shared by every read path that\n * projects spans into a trace summary: the cloud gateway's\n * `transformTraceDetail`, the local CLI's `mapRawTraceToDetail`\n * (`GET /v1/traces/:id`), and the CLI's dataset import-from-traces source\n * mapper. Before this helper existed each call site had its own semantics\n * (root span vs first/last GENERATION span), so the same trace answered\n * differently depending on which endpoint you asked.\n *\n * Layered semantics, per-field:\n *\n * 1. **Root span first.** The WebhookRunner owns the prompt (root) span and\n *    records `agentmark.input` / `agentmark.output` on it — the true\n *    end-to-end request/response boundary. When the root span carries a\n *    value, it wins.\n * 2. **GENERATION fallback.** Traces emitted without the runner (third-party\n *    OTEL instrumentation pointed straight at the collector, or pre-runner\n *    SDK versions) have no root-span I/O. Fall back to the first GENERATION\n *    span's input and the last GENERATION span's output, in timestamp order\n *    — the model's view of the run.\n *\n * Fields resolve independently: a trace whose root span has only an output\n * (e.g. written by an older runner that recorded output but not input)\n * gets its input from the GENERATION fallback.\n */\n\n/** Minimal span projection the derivation needs — both the camelCase\n * service-layer `Span` and mapped wire spans satisfy it. */\nexport interface TraceIOSpan {\n  /** null/undefined/'' parent marks a root span. */\n  parentId?: string | null;\n  /** Span classification; only 'GENERATION' participates in the fallback. */\n  type?: string | null;\n  /** Sort key for first/last GENERATION. ISO strings and epoch numbers both\n   * order correctly under `<`. */\n  timestamp?: string | number;\n  input?: unknown;\n  output?: unknown;\n}\n\nexport interface TraceIO {\n  input?: unknown;\n  output?: unknown;\n}\n\n/** Truthy-and-nonempty check that keeps non-string payloads (objects from\n * already-parsed wire spans) while rejecting '', null, undefined. */\nfunction present(v: unknown): boolean {\n  if (v === null || v === undefined) return false;\n  if (typeof v === \"string\") return v.length > 0;\n  return true;\n}\n\n/**\n * Derive trace-level input/output from a trace's spans. Returns each field\n * only when a value exists — callers spread the result so absent fields stay\n * absent on the wire (`{...deriveTraceIO(spans)}`).\n */\nexport function deriveTraceIO(spans: readonly TraceIOSpan[]): TraceIO {\n  const rootSpan = spans.find((s) => !s.parentId) ?? spans[0];\n\n  const generationSpans = spans\n    .filter((s) => s.type === \"GENERATION\")\n    .sort((a, b) => {\n      const ta = a.timestamp ?? 0;\n      const tb = b.timestamp ?? 0;\n      return ta < tb ? -1 : ta > tb ? 1 : 0;\n    });\n\n  const input = present(rootSpan?.input)\n    ? rootSpan?.input\n    : generationSpans.find((s) => present(s.input))?.input;\n\n  const lastGenWithOutput = [...generationSpans]\n    .reverse()\n    .find((s) => present(s.output));\n  const output = present(rootSpan?.output)\n    ? rootSpan?.output\n    : lastGenWithOutput?.output;\n\n  return {\n    ...(present(input) ? { input } : {}),\n    ...(present(output) ? { output } : {}),\n  };\n}\n"],"mappings":";AAgDA,SAAS,QAAQ,GAAqB;AACpC,MAAI,MAAM,QAAQ,MAAM,OAAW,QAAO;AAC1C,MAAI,OAAO,MAAM,SAAU,QAAO,EAAE,SAAS;AAC7C,SAAO;AACT;AAOO,SAAS,cAAc,OAAwC;AA3DtE;AA4DE,QAAM,YAAW,WAAM,KAAK,CAAC,MAAM,CAAC,EAAE,QAAQ,MAA7B,YAAkC,MAAM,CAAC;AAE1D,QAAM,kBAAkB,MACrB,OAAO,CAAC,MAAM,EAAE,SAAS,YAAY,EACrC,KAAK,CAAC,GAAG,MAAM;AAhEpB,QAAAA,KAAAC;AAiEM,UAAM,MAAKD,MAAA,EAAE,cAAF,OAAAA,MAAe;AAC1B,UAAM,MAAKC,MAAA,EAAE,cAAF,OAAAA,MAAe;AAC1B,WAAO,KAAK,KAAK,KAAK,KAAK,KAAK,IAAI;AAAA,EACtC,CAAC;AAEH,QAAM,QAAQ,QAAQ,qCAAU,KAAK,IACjC,qCAAU,SACV,qBAAgB,KAAK,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,MAA5C,mBAA+C;AAEnD,QAAM,oBAAoB,CAAC,GAAG,eAAe,EAC1C,QAAQ,EACR,KAAK,CAAC,MAAM,QAAQ,EAAE,MAAM,CAAC;AAChC,QAAM,SAAS,QAAQ,qCAAU,MAAM,IACnC,qCAAU,SACV,uDAAmB;AAEvB,SAAO;AAAA,IACL,GAAI,QAAQ,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC;AAAA,IAClC,GAAI,QAAQ,MAAM,IAAI,EAAE,OAAO,IAAI,CAAC;AAAA,EACtC;AACF;","names":["_a","_b"]}

package/package.json

@@ -1,8 +1,30 @@
 {
   "name": "@agentmark-ai/shared-utils",
   "main": "./dist/index.js",
-  "types": "./dist/index.ts",
-  "version": "0.5.1",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./trace-io": {
+      "import": {
+        "types": "./dist/trace-io.d.mts",
+        "default": "./dist/trace-io.mjs"
+      },
+      "require": {
+        "types": "./dist/trace-io.d.ts",
+        "default": "./dist/trace-io.js"
+      }
+    }
+  },
+  "version": "0.6.1",
   "scripts": {
     "build": "tsup",
     "lint": "eslint .",