fascicle 0.12.3 → 0.12.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/mcp.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { a as Step, d as TrajectoryLogger } from "./types-DBpU27sQ.js";
2
2
  import { r as ToolSchema } from "./types-BK0UW28o.js";
3
- import { w as Tool } from "./types-DU6cvoA4.js";
3
+ import { T as Tool } from "./types-CLigYA62.js";
4
4
  import { Client } from "@modelcontextprotocol/sdk/client/index.js";
5
5
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
6
6
  import { z } from "zod";
package/dist/otel.d.ts CHANGED
@@ -1,6 +1,16 @@
1
1
  import { d as TrajectoryLogger } from "./types-DBpU27sQ.js";
2
- import { Tracer } from "@opentelemetry/api";
2
+ import { Meter, Tracer } from "@opentelemetry/api";
3
3
 
4
+ //#region src/otel/metrics.d.ts
5
+ type OtelMetricsOptions = {
6
+ /**
7
+ * Meter to create instruments on. Defaults to
8
+ * `metrics.getMeter('fascicle')`, which resolves against the global
9
+ * MeterProvider the host has registered.
10
+ */
11
+ readonly meter?: Meter;
12
+ };
13
+ //#endregion
4
14
  //#region src/otel/trajectory_logger.d.ts
5
15
  type OtelTrajectoryLoggerOptions = {
6
16
  /**
@@ -13,6 +23,14 @@ type OtelTrajectoryLoggerOptions = {
13
23
  * them out of the OTel semantic-convention namespace. Defaults to `fascicle.`.
14
24
  */
15
25
  readonly attribute_prefix?: string;
26
+ /**
27
+ * Opt-in metric instruments recorded from the same trajectory stream the
28
+ * spans mirror (GenAI semconv client histograms plus Fascicle's cost and
29
+ * retry instruments; see metrics.ts). `true` uses the global MeterProvider's
30
+ * `fascicle` meter; an object supplies a custom Meter. Off by default so the
31
+ * bridge stays a pure tracer for hosts without a metrics pipeline.
32
+ */
33
+ readonly metrics?: boolean | OtelMetricsOptions;
16
34
  };
17
35
  /**
18
36
  * Create a `TrajectoryLogger` that mirrors spans and events onto
@@ -23,5 +41,5 @@ type OtelTrajectoryLoggerOptions = {
23
41
  */
24
42
  declare function create_otel_trajectory_logger(options?: OtelTrajectoryLoggerOptions): TrajectoryLogger;
25
43
  //#endregion
26
- export { type OtelTrajectoryLoggerOptions, create_otel_trajectory_logger };
44
+ export { type OtelMetricsOptions, type OtelTrajectoryLoggerOptions, create_otel_trajectory_logger };
27
45
  //# sourceMappingURL=otel.d.ts.map
package/dist/otel.js CHANGED
@@ -1,4 +1,189 @@
1
- import { SpanStatusCode, context, trace } from "@opentelemetry/api";
1
+ import { SpanStatusCode, context, metrics, trace } from "@opentelemetry/api";
2
+ //#region src/otel/metrics.ts
3
+ /**
4
+ * Opt-in OpenTelemetry metrics derived from the trajectory stream.
5
+ *
6
+ * The bridge's spans answer "what happened on this run"; SRE dashboards ask
7
+ * aggregate questions ("p95 latency by model", "429s per minute", "tokens per
8
+ * hour"), which want real OTel metric instruments rather than a
9
+ * spans-to-metrics pipeline. This recorder listens to the same trajectory
10
+ * events the span bridge mirrors and records the GenAI semantic-convention
11
+ * client histograms, plus two Fascicle-named instruments for the data the
12
+ * conventions do not cover yet (cost, absorbed retries).
13
+ *
14
+ * Instruments and sources:
15
+ * - `gen_ai.client.token.usage` ({token}) from `response_received`, one
16
+ * point per direction via `gen_ai.token.type`.
17
+ * - `gen_ai.client.operation.duration` (s) from `response_received`
18
+ * `duration_ms`, the model-only round trip.
19
+ * - `gen_ai.client.operation.time_to_first_chunk` (s) from
20
+ * `first_chunk_ms` on streamed turns.
21
+ * - `gen_ai.execute_tool.duration` (s) from `tool_result`, tagged
22
+ * `gen_ai.tool.name`.
23
+ * - `fascicle.client.operation.cost` (usd) from the `cost` event's
24
+ * `total_usd`.
25
+ * - `fascicle.client.turn_retries` ({retry}) counter from `turn_retry`,
26
+ * tagged `error.type` with the classified failure kind.
27
+ *
28
+ * Provider and model attributes come from the enclosing `engine.generate`
29
+ * span's start meta, tracked on a stack with the same documented
30
+ * approximation as the span bridge: concurrent generates sharing one logger
31
+ * attribute to the innermost open call. The semantic conventions are still
32
+ * experimental (mid-2026), so a semconv revision may rename instruments;
33
+ * this module tracks the names at implementation time.
34
+ */
35
+ /** Semconv-suggested boundaries for the duration histograms, in seconds. */
36
+ const DURATION_BOUNDARIES = [
37
+ .01,
38
+ .02,
39
+ .04,
40
+ .08,
41
+ .16,
42
+ .32,
43
+ .64,
44
+ 1.28,
45
+ 2.56,
46
+ 5.12,
47
+ 10.24,
48
+ 20.48,
49
+ 40.96,
50
+ 81.92
51
+ ];
52
+ /** Semconv-suggested boundaries for the token-usage histogram. */
53
+ const TOKEN_BOUNDARIES = [
54
+ 1,
55
+ 4,
56
+ 16,
57
+ 64,
58
+ 256,
59
+ 1024,
60
+ 4096,
61
+ 16384,
62
+ 65536,
63
+ 262144,
64
+ 1048576,
65
+ 4194304
66
+ ];
67
+ /**
68
+ * Read `key` off the loose event and return it only when it is a number.
69
+ */
70
+ function event_number(event, key) {
71
+ const value = event[key];
72
+ return typeof value === "number" ? value : void 0;
73
+ }
74
+ /**
75
+ * Read `key` off the loose event and return it only when it is a string.
76
+ */
77
+ function event_string(event, key) {
78
+ const value = event[key];
79
+ return typeof value === "string" ? value : void 0;
80
+ }
81
+ /**
82
+ * Create the metrics recorder: instruments are created once here, and every
83
+ * recording stamps the provider/model of the innermost open generate call.
84
+ */
85
+ function create_metrics_recorder(options) {
86
+ const meter = options.meter ?? metrics.getMeter("fascicle");
87
+ const token_usage = meter.createHistogram("gen_ai.client.token.usage", {
88
+ unit: "{token}",
89
+ description: "Number of input and output tokens used per model turn",
90
+ advice: { explicitBucketBoundaries: TOKEN_BOUNDARIES }
91
+ });
92
+ const operation_duration = meter.createHistogram("gen_ai.client.operation.duration", {
93
+ unit: "s",
94
+ description: "Model round-trip duration of the successful turn attempt",
95
+ advice: { explicitBucketBoundaries: DURATION_BOUNDARIES }
96
+ });
97
+ const time_to_first_chunk = meter.createHistogram("gen_ai.client.operation.time_to_first_chunk", {
98
+ unit: "s",
99
+ description: "Time from turn start to the first streamed chunk",
100
+ advice: { explicitBucketBoundaries: DURATION_BOUNDARIES }
101
+ });
102
+ const tool_duration = meter.createHistogram("gen_ai.execute_tool.duration", {
103
+ unit: "s",
104
+ description: "Tool execution duration",
105
+ advice: { explicitBucketBoundaries: DURATION_BOUNDARIES }
106
+ });
107
+ const cost = meter.createHistogram("fascicle.client.operation.cost", {
108
+ unit: "usd",
109
+ description: "Estimated cost per model turn"
110
+ });
111
+ const retries = meter.createCounter("fascicle.client.turn_retries", {
112
+ unit: "{retry}",
113
+ description: "Provider turn attempts that failed and were retried"
114
+ });
115
+ const generate_ids = /* @__PURE__ */ new Set();
116
+ const context_stack = [];
117
+ const base_attributes = () => {
118
+ const attrs = { "gen_ai.operation.name": "chat" };
119
+ const top = context_stack[context_stack.length - 1];
120
+ if (top?.provider !== void 0) attrs["gen_ai.provider.name"] = top.provider;
121
+ if (top?.model !== void 0) attrs["gen_ai.request.model"] = top.model;
122
+ return attrs;
123
+ };
124
+ const on_response_received = (event) => {
125
+ const base = base_attributes();
126
+ const input = event_number(event, "input_tokens");
127
+ if (input !== void 0) token_usage.record(input, {
128
+ ...base,
129
+ "gen_ai.token.type": "input"
130
+ });
131
+ const output = event_number(event, "output_tokens");
132
+ if (output !== void 0) token_usage.record(output, {
133
+ ...base,
134
+ "gen_ai.token.type": "output"
135
+ });
136
+ const duration_ms = event_number(event, "duration_ms");
137
+ if (duration_ms !== void 0) operation_duration.record(duration_ms / 1e3, base);
138
+ const first_chunk_ms = event_number(event, "first_chunk_ms");
139
+ if (first_chunk_ms !== void 0) time_to_first_chunk.record(first_chunk_ms / 1e3, base);
140
+ };
141
+ return {
142
+ on_start_span(id, name, meta) {
143
+ if (name !== "engine.generate") return;
144
+ generate_ids.add(id);
145
+ const provider = meta?.["provider"];
146
+ const model = meta?.["model_id"];
147
+ context_stack.push({
148
+ ...typeof provider === "string" ? { provider } : {},
149
+ ...typeof model === "string" ? { model } : {}
150
+ });
151
+ },
152
+ on_end_span(id) {
153
+ if (!generate_ids.delete(id)) return;
154
+ context_stack.pop();
155
+ },
156
+ on_record(event) {
157
+ if (event.kind === "response_received") {
158
+ on_response_received(event);
159
+ return;
160
+ }
161
+ if (event.kind === "tool_result") {
162
+ const duration_ms = event_number(event, "duration_ms");
163
+ if (duration_ms === void 0) return;
164
+ const name = event_string(event, "name");
165
+ tool_duration.record(duration_ms / 1e3, {
166
+ ...base_attributes(),
167
+ ...name !== void 0 ? { "gen_ai.tool.name": name } : {}
168
+ });
169
+ return;
170
+ }
171
+ if (event.kind === "cost") {
172
+ const total_usd = event_number(event, "total_usd");
173
+ if (total_usd !== void 0) cost.record(total_usd, base_attributes());
174
+ return;
175
+ }
176
+ if (event.kind === "turn_retry") {
177
+ const failure_kind = event_string(event, "failure_kind");
178
+ retries.add(1, {
179
+ ...base_attributes(),
180
+ ...failure_kind !== void 0 ? { "error.type": failure_kind } : {}
181
+ });
182
+ }
183
+ }
184
+ };
185
+ }
186
+ //#endregion
2
187
  //#region src/otel/trajectory_logger.ts
3
188
  /**
4
189
  * OpenTelemetry bridge for Fascicle trajectory events.
@@ -11,10 +196,10 @@ import { SpanStatusCode, context, trace } from "@opentelemetry/api";
11
196
  * spans come from events the engine already emits, so native and external
12
197
  * transports get traces without any AI-SDK involvement.
13
198
  *
14
- * This module is the ONLY place `@opentelemetry/api` is imported, and it lives
15
- * outside `src/engine/` on purpose: the engine's `ai + zod` npm-dep invariant
16
- * holds unmodified, and an app that never imports `fascicle/otel` pulls in
17
- * zero OTel packages at runtime.
199
+ * `@opentelemetry/api` is imported ONLY under `src/otel/` (this module and
200
+ * metrics.ts), outside `src/engine/` on purpose: the engine's `ai + zod`
201
+ * npm-dep invariant holds unmodified, and an app that never imports
202
+ * `fascicle/otel` pulls in zero OTel packages at runtime.
18
203
  *
19
204
  * Nesting is resolved two ways, in order: an explicit `parent_span_id` on the
20
205
  * start meta (how the composition runner threads composer-span parenthood) wins;
@@ -60,17 +245,48 @@ function to_attribute_value(value) {
60
245
  return safe_json(value);
61
246
  }
62
247
  /**
248
+ * True for a plain object value (not null, not an array): the shape span-meta
249
+ * flattening applies to.
250
+ */
251
+ function is_plain_object(value) {
252
+ return value !== null && typeof value === "object" && !Array.isArray(value);
253
+ }
254
+ /**
255
+ * Spread one object-valued span-meta field into dotted attribute keys
256
+ * (`usage` + `input_tokens` becomes `<prefix>usage.input_tokens`), with
257
+ * deeper nesting falling back to `to_attribute_value`'s JSON form.
258
+ */
259
+ function flatten_into(attrs, key, value, prefix) {
260
+ for (const [inner_key, inner_value] of Object.entries(value)) {
261
+ const attr = to_attribute_value(inner_value);
262
+ if (attr !== void 0) attrs[`${prefix}${key}.${inner_key}`] = attr;
263
+ }
264
+ }
265
+ /**
63
266
  * Build an OTel `Attributes` object from event/meta fields.
64
267
  *
65
268
  * Skips the bridge's internal plumbing keys (`kind`, `span_id`,
66
269
  * `parent_span_id`) and prefixes the rest with `prefix` so they stay out of
67
270
  * OTel's semantic-convention namespace.
271
+ *
272
+ * With `flatten`, an object-valued field spreads one level into dotted keys
273
+ * (`usage: { input_tokens: 5 }` becomes `<prefix>usage.input_tokens = 5`), so
274
+ * span metadata like usage and model_resolved lands as numeric attributes a
275
+ * dashboard can aggregate rather than a JSON string it cannot query. Flattening
276
+ * applies to span meta only, never to `record`ed events: an event may carry
277
+ * arbitrary payloads (a tool call's input, a salvage blob) where
278
+ * attribute-per-key would explode cardinality and leak structure, so those
279
+ * keep the JSON-string fallback.
68
280
  */
69
- function to_attributes(meta, prefix) {
281
+ function to_attributes(meta, prefix, flatten = false) {
70
282
  const attrs = {};
71
283
  if (meta === void 0) return attrs;
72
284
  for (const [key, value] of Object.entries(meta)) {
73
285
  if (INTERNAL_KEYS.has(key)) continue;
286
+ if (flatten && is_plain_object(value)) {
287
+ flatten_into(attrs, key, value, prefix);
288
+ continue;
289
+ }
74
290
  const attr = to_attribute_value(value);
75
291
  if (attr !== void 0) attrs[`${prefix}${key}`] = attr;
76
292
  }
@@ -86,6 +302,7 @@ function to_attributes(meta, prefix) {
86
302
  function create_otel_trajectory_logger(options = {}) {
87
303
  const tracer = options.tracer ?? trace.getTracer("fascicle");
88
304
  const prefix = options.attribute_prefix ?? "fascicle.";
305
+ const metrics_recorder = options.metrics === void 0 || options.metrics === false ? void 0 : create_metrics_recorder(options.metrics === true ? {} : options.metrics);
89
306
  const open = /* @__PURE__ */ new Map();
90
307
  const stack = [];
91
308
  let counter = 0;
@@ -113,7 +330,7 @@ function create_otel_trajectory_logger(options = {}) {
113
330
  return {
114
331
  start_span(name, meta) {
115
332
  const parent = parent_context(meta);
116
- const span = tracer.startSpan(name, { attributes: to_attributes(meta, prefix) }, parent);
333
+ const span = tracer.startSpan(name, { attributes: to_attributes(meta, prefix, true) }, parent);
117
334
  counter += 1;
118
335
  const id = `fascicle-otel-${counter}`;
119
336
  open.set(id, {
@@ -121,13 +338,15 @@ function create_otel_trajectory_logger(options = {}) {
121
338
  context: trace.setSpan(parent, span)
122
339
  });
123
340
  stack.push(id);
341
+ metrics_recorder?.on_start_span(id, name, meta);
124
342
  return id;
125
343
  },
126
344
  end_span(id, meta) {
345
+ metrics_recorder?.on_end_span(id);
127
346
  const entry = open.get(id);
128
347
  if (entry === void 0) return;
129
348
  const { span } = entry;
130
- span.setAttributes(to_attributes(meta, prefix));
349
+ span.setAttributes(to_attributes(meta, prefix, true));
131
350
  const error = meta?.["error"];
132
351
  if (typeof error === "string" && error.length > 0) span.setStatus({
133
352
  code: SpanStatusCode.ERROR,
@@ -139,6 +358,7 @@ function create_otel_trajectory_logger(options = {}) {
139
358
  if (idx !== -1) stack.splice(idx, 1);
140
359
  },
141
360
  record(event) {
361
+ metrics_recorder?.on_record(event);
142
362
  const span = target_for_event(event);
143
363
  if (span === void 0) return;
144
364
  const name = typeof event.kind === "string" ? event.kind : "event";
package/dist/otel.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"otel.js","names":["otel_context"],"sources":["../src/otel/trajectory_logger.ts"],"sourcesContent":["/**\n * OpenTelemetry bridge for Fascicle trajectory events.\n *\n * `create_otel_trajectory_logger` returns a plain TrajectoryLogger that turns\n * the engine's own span + event stream into OpenTelemetry spans: the\n * `engine.generate` span becomes an OTel root span, each `engine.generate.step`\n * a child span, and every `record`ed event (tool_call, tool_result, cost, ...)\n * an OTel span event on the currently open span. It is transport-neutral: the\n * spans come from events the engine already emits, so native and external\n * transports get traces without any AI-SDK involvement.\n *\n * This module is the ONLY place `@opentelemetry/api` is imported, and it lives\n * outside `src/engine/` on purpose: the engine's `ai + zod` npm-dep invariant\n * holds unmodified, and an app that never imports `fascicle/otel` pulls in\n * zero OTel packages at runtime.\n *\n * Nesting is resolved two ways, in order: an explicit `parent_span_id` on the\n * start meta (how the composition runner threads composer-span parenthood) wins;\n * otherwise the currently open span (top of the open stack) is the parent. This\n * is exact for the sequential engine flow (generate → step → step) and for\n * runner-nested spans; genuinely interleaved sibling spans that carry no\n * `parent_span_id` (concurrent branches sharing one logger) fall back to stack\n * order, which is this bridge's one documented approximation.\n */\n\nimport {\n context as otel_context,\n trace,\n SpanStatusCode,\n type AttributeValue,\n type Attributes,\n type Context,\n type Span,\n type Tracer,\n} from '@opentelemetry/api'\nimport type { TrajectoryEvent, TrajectoryLogger } from '#core'\n\nexport type OtelTrajectoryLoggerOptions = {\n /**\n * Tracer to open spans on. Defaults to `trace.getTracer('fascicle')`, which\n * resolves against whatever global TracerProvider the host has registered.\n */\n readonly tracer?: Tracer\n /**\n * Prefix for span + event attributes derived from event metadata, keeping\n * them out of the OTel semantic-convention namespace. Defaults to `fascicle.`.\n */\n readonly attribute_prefix?: string\n}\n\n// Event/meta keys that are bridge plumbing, not span attributes.\nconst INTERNAL_KEYS: ReadonlySet<string> = new Set(['kind', 'span_id', 'parent_span_id'])\n\n/**\n * JSON-stringify `value`, falling back to `String(value)` when `stringify`\n * throws or returns `undefined`, as it does for functions and symbols.\n */\nfunction safe_json(value: unknown): string {\n try {\n return JSON.stringify(value) ?? String(value)\n } catch {\n return String(value)\n }\n}\n\n/**\n * Convert a JS value into an OTel-compatible attribute value.\n *\n * Primitives and homogeneous primitive arrays pass through unchanged;\n * anything else falls back to `safe_json`; `null`/`undefined` drop out\n * entirely (returning `undefined`) so the caller can omit the attribute.\n */\nfunction to_attribute_value(value: unknown): AttributeValue | undefined {\n if (value === null || value === undefined) return undefined\n const kind = typeof value\n if (kind === 'string' || kind === 'number' || kind === 'boolean') {\n // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion\n return value as AttributeValue\n }\n if (Array.isArray(value)) {\n if (value.every((v) => typeof v === 'string')) return value\n if (value.every((v) => typeof v === 'number')) return value\n if (value.every((v) => typeof v === 'boolean')) return value\n return safe_json(value)\n }\n return safe_json(value)\n}\n\n/**\n * Build an OTel `Attributes` object from event/meta fields.\n *\n * Skips the bridge's internal plumbing keys (`kind`, `span_id`,\n * `parent_span_id`) and prefixes the rest with `prefix` so they stay out of\n * OTel's semantic-convention namespace.\n */\nfunction to_attributes(\n meta: Readonly<Record<string, unknown>> | undefined,\n prefix: string,\n): Attributes {\n const attrs: Attributes = {}\n if (meta === undefined) return attrs\n for (const [key, value] of Object.entries(meta)) {\n if (INTERNAL_KEYS.has(key)) continue\n const attr = to_attribute_value(value)\n if (attr !== undefined) attrs[`${prefix}${key}`] = attr\n }\n return attrs\n}\n\ntype OpenSpan = { readonly span: Span; readonly context: Context }\n\n/**\n * Create a `TrajectoryLogger` that mirrors spans and events onto\n * OpenTelemetry, using `options.tracer` (or the global `fascicle` tracer).\n *\n * Parent resolution favors an explicit `parent_span_id` on the start meta;\n * otherwise it falls back to the currently open span on an internal stack.\n */\nexport function create_otel_trajectory_logger(\n options: OtelTrajectoryLoggerOptions = {},\n): TrajectoryLogger {\n const tracer = options.tracer ?? trace.getTracer('fascicle')\n const prefix = options.attribute_prefix ?? 'fascicle.'\n const open = new Map<string, OpenSpan>()\n const stack: string[] = []\n let counter = 0\n\n const top_context = (): Context | undefined => {\n const top = stack[stack.length - 1]\n if (top === undefined) return undefined\n return open.get(top)?.context\n }\n\n const parent_context = (meta: Record<string, unknown> | undefined): Context => {\n const explicit = meta?.['parent_span_id']\n if (typeof explicit === 'string') {\n const parent = open.get(explicit)\n if (parent !== undefined) return parent.context\n }\n return top_context() ?? otel_context.active()\n }\n\n const target_for_event = (event: TrajectoryEvent): Span | undefined => {\n if (typeof event.span_id === 'string') {\n const target = open.get(event.span_id)\n if (target !== undefined) return target.span\n }\n const top = stack[stack.length - 1]\n return top !== undefined ? open.get(top)?.span : undefined\n }\n\n return {\n start_span(name, meta) {\n const parent = parent_context(meta)\n const span = tracer.startSpan(name, { attributes: to_attributes(meta, prefix) }, parent)\n counter += 1\n const id = `fascicle-otel-${counter}`\n open.set(id, { span, context: trace.setSpan(parent, span) })\n stack.push(id)\n return id\n },\n end_span(id, meta) {\n const entry = open.get(id)\n if (entry === undefined) return\n const { span } = entry\n span.setAttributes(to_attributes(meta, prefix))\n const error = meta?.['error']\n if (typeof error === 'string' && error.length > 0) {\n span.setStatus({ code: SpanStatusCode.ERROR, message: error })\n }\n span.end()\n open.delete(id)\n const idx = stack.lastIndexOf(id)\n if (idx !== -1) stack.splice(idx, 1)\n },\n record(event) {\n const span = target_for_event(event)\n if (span === undefined) return\n const name = typeof event.kind === 'string' ? event.kind : 'event'\n span.addEvent(name, to_attributes(event, prefix))\n },\n }\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"otel.js","names":["otel_metrics","otel_context"],"sources":["../src/otel/metrics.ts","../src/otel/trajectory_logger.ts"],"sourcesContent":["/**\n * Opt-in OpenTelemetry metrics derived from the trajectory stream.\n *\n * The bridge's spans answer \"what happened on this run\"; SRE dashboards ask\n * aggregate questions (\"p95 latency by model\", \"429s per minute\", \"tokens per\n * hour\"), which want real OTel metric instruments rather than a\n * spans-to-metrics pipeline. This recorder listens to the same trajectory\n * events the span bridge mirrors and records the GenAI semantic-convention\n * client histograms, plus two Fascicle-named instruments for the data the\n * conventions do not cover yet (cost, absorbed retries).\n *\n * Instruments and sources:\n * - `gen_ai.client.token.usage` ({token}) from `response_received`, one\n * point per direction via `gen_ai.token.type`.\n * - `gen_ai.client.operation.duration` (s) from `response_received`\n * `duration_ms`, the model-only round trip.\n * - `gen_ai.client.operation.time_to_first_chunk` (s) from\n * `first_chunk_ms` on streamed turns.\n * - `gen_ai.execute_tool.duration` (s) from `tool_result`, tagged\n * `gen_ai.tool.name`.\n * - `fascicle.client.operation.cost` (usd) from the `cost` event's\n * `total_usd`.\n * - `fascicle.client.turn_retries` ({retry}) counter from `turn_retry`,\n * tagged `error.type` with the classified failure kind.\n *\n * Provider and model attributes come from the enclosing `engine.generate`\n * span's start meta, tracked on a stack with the same documented\n * approximation as the span bridge: concurrent generates sharing one logger\n * attribute to the innermost open call. The semantic conventions are still\n * experimental (mid-2026), so a semconv revision may rename instruments;\n * this module tracks the names at implementation time.\n */\n\nimport {\n metrics as otel_metrics,\n type Attributes,\n type Counter,\n type Histogram,\n type Meter,\n} from '@opentelemetry/api'\nimport type { TrajectoryEvent } from '#core'\n\nexport type OtelMetricsOptions = {\n /**\n * Meter to create instruments on. Defaults to\n * `metrics.getMeter('fascicle')`, which resolves against the global\n * MeterProvider the host has registered.\n */\n readonly meter?: Meter\n}\n\n/**\n * The span-lifecycle + event listener the trajectory logger drives when\n * metrics are enabled.\n */\nexport type MetricsRecorder = {\n readonly on_start_span: (\n id: string,\n name: string,\n meta: Record<string, unknown> | undefined,\n ) => void\n readonly on_end_span: (id: string) => void\n readonly on_record: (event: TrajectoryEvent) => void\n}\n\n/** Semconv-suggested boundaries for the duration histograms, in seconds. */\nconst DURATION_BOUNDARIES = [\n 0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48,\n 40.96, 81.92,\n]\n\n/** Semconv-suggested boundaries for the token-usage histogram. */\nconst TOKEN_BOUNDARIES = [\n 1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304,\n]\n\n/**\n * Read `key` off the loose event and return it only when it is a number.\n */\nfunction event_number(event: TrajectoryEvent, key: string): number | undefined {\n const value = event[key]\n return typeof value === 'number' ? value : undefined\n}\n\n/**\n * Read `key` off the loose event and return it only when it is a string.\n */\nfunction event_string(event: TrajectoryEvent, key: string): string | undefined {\n const value = event[key]\n return typeof value === 'string' ? value : undefined\n}\n\n/**\n * Create the metrics recorder: instruments are created once here, and every\n * recording stamps the provider/model of the innermost open generate call.\n */\nexport function create_metrics_recorder(options: OtelMetricsOptions): MetricsRecorder {\n const meter = options.meter ?? otel_metrics.getMeter('fascicle')\n\n const token_usage: Histogram = meter.createHistogram('gen_ai.client.token.usage', {\n unit: '{token}',\n description: 'Number of input and output tokens used per model turn',\n advice: { explicitBucketBoundaries: TOKEN_BOUNDARIES },\n })\n const operation_duration: Histogram = meter.createHistogram(\n 'gen_ai.client.operation.duration',\n {\n unit: 's',\n description: 'Model round-trip duration of the successful turn attempt',\n advice: { explicitBucketBoundaries: DURATION_BOUNDARIES },\n },\n )\n const time_to_first_chunk: Histogram = meter.createHistogram(\n 'gen_ai.client.operation.time_to_first_chunk',\n {\n unit: 's',\n description: 'Time from turn start to the first streamed chunk',\n advice: { explicitBucketBoundaries: DURATION_BOUNDARIES },\n },\n )\n const tool_duration: Histogram = meter.createHistogram('gen_ai.execute_tool.duration', {\n unit: 's',\n description: 'Tool execution duration',\n advice: { explicitBucketBoundaries: DURATION_BOUNDARIES },\n })\n const cost: Histogram = meter.createHistogram('fascicle.client.operation.cost', {\n unit: 'usd',\n description: 'Estimated cost per model turn',\n })\n const retries: Counter = meter.createCounter('fascicle.client.turn_retries', {\n unit: '{retry}',\n description: 'Provider turn attempts that failed and were retried',\n })\n\n // Innermost open engine.generate call's identity, for metric attributes.\n const generate_ids = new Set<string>()\n const context_stack: Array<{ provider?: string; model?: string }> = []\n\n const base_attributes = (): Attributes => {\n const attrs: Attributes = { 'gen_ai.operation.name': 'chat' }\n const top = context_stack[context_stack.length - 1]\n if (top?.provider !== undefined) attrs['gen_ai.provider.name'] = top.provider\n if (top?.model !== undefined) attrs['gen_ai.request.model'] = top.model\n return attrs\n }\n\n const on_response_received = (event: TrajectoryEvent): void => {\n const base = base_attributes()\n const input = event_number(event, 'input_tokens')\n if (input !== undefined) {\n token_usage.record(input, { ...base, 'gen_ai.token.type': 'input' })\n }\n const output = event_number(event, 'output_tokens')\n if (output !== undefined) {\n token_usage.record(output, { ...base, 'gen_ai.token.type': 'output' })\n }\n const duration_ms = event_number(event, 'duration_ms')\n if (duration_ms !== undefined) operation_duration.record(duration_ms / 1000, base)\n const first_chunk_ms = event_number(event, 'first_chunk_ms')\n if (first_chunk_ms !== undefined) {\n time_to_first_chunk.record(first_chunk_ms / 1000, base)\n }\n }\n\n return {\n on_start_span(id, name, meta) {\n if (name !== 'engine.generate') return\n generate_ids.add(id)\n const provider = meta?.['provider']\n const model = meta?.['model_id']\n context_stack.push({\n ...(typeof provider === 'string' ? { provider } : {}),\n ...(typeof model === 'string' ? { model } : {}),\n })\n },\n on_end_span(id) {\n if (!generate_ids.delete(id)) return\n context_stack.pop()\n },\n on_record(event) {\n if (event.kind === 'response_received') {\n on_response_received(event)\n return\n }\n if (event.kind === 'tool_result') {\n const duration_ms = event_number(event, 'duration_ms')\n if (duration_ms === undefined) return\n const name = event_string(event, 'name')\n tool_duration.record(duration_ms / 1000, {\n ...base_attributes(),\n ...(name !== undefined ? { 'gen_ai.tool.name': name } : {}),\n })\n return\n }\n if (event.kind === 'cost') {\n const total_usd = event_number(event, 'total_usd')\n if (total_usd !== undefined) cost.record(total_usd, base_attributes())\n return\n }\n if (event.kind === 'turn_retry') {\n const failure_kind = event_string(event, 'failure_kind')\n retries.add(1, {\n ...base_attributes(),\n ...(failure_kind !== undefined ? { 'error.type': failure_kind } : {}),\n })\n }\n },\n }\n}\n","/**\n * OpenTelemetry bridge for Fascicle trajectory events.\n *\n * `create_otel_trajectory_logger` returns a plain TrajectoryLogger that turns\n * the engine's own span + event stream into OpenTelemetry spans: the\n * `engine.generate` span becomes an OTel root span, each `engine.generate.step`\n * a child span, and every `record`ed event (tool_call, tool_result, cost, ...)\n * an OTel span event on the currently open span. It is transport-neutral: the\n * spans come from events the engine already emits, so native and external\n * transports get traces without any AI-SDK involvement.\n *\n * `@opentelemetry/api` is imported ONLY under `src/otel/` (this module and\n * metrics.ts), outside `src/engine/` on purpose: the engine's `ai + zod`\n * npm-dep invariant holds unmodified, and an app that never imports\n * `fascicle/otel` pulls in zero OTel packages at runtime.\n *\n * Nesting is resolved two ways, in order: an explicit `parent_span_id` on the\n * start meta (how the composition runner threads composer-span parenthood) wins;\n * otherwise the currently open span (top of the open stack) is the parent. This\n * is exact for the sequential engine flow (generate → step → step) and for\n * runner-nested spans; genuinely interleaved sibling spans that carry no\n * `parent_span_id` (concurrent branches sharing one logger) fall back to stack\n * order, which is this bridge's one documented approximation.\n */\n\nimport {\n context as otel_context,\n trace,\n SpanStatusCode,\n type AttributeValue,\n type Attributes,\n type Context,\n type Span,\n type Tracer,\n} from '@opentelemetry/api'\nimport type { TrajectoryEvent, TrajectoryLogger } from '#core'\nimport { create_metrics_recorder, type OtelMetricsOptions } from './metrics.js'\n\nexport type OtelTrajectoryLoggerOptions = {\n /**\n * Tracer to open spans on. Defaults to `trace.getTracer('fascicle')`, which\n * resolves against whatever global TracerProvider the host has registered.\n */\n readonly tracer?: Tracer\n /**\n * Prefix for span + event attributes derived from event metadata, keeping\n * them out of the OTel semantic-convention namespace. Defaults to `fascicle.`.\n */\n readonly attribute_prefix?: string\n /**\n * Opt-in metric instruments recorded from the same trajectory stream the\n * spans mirror (GenAI semconv client histograms plus Fascicle's cost and\n * retry instruments; see metrics.ts). `true` uses the global MeterProvider's\n * `fascicle` meter; an object supplies a custom Meter. Off by default so the\n * bridge stays a pure tracer for hosts without a metrics pipeline.\n */\n readonly metrics?: boolean | OtelMetricsOptions\n}\n\n// Event/meta keys that are bridge plumbing, not span attributes.\nconst INTERNAL_KEYS: ReadonlySet<string> = new Set(['kind', 'span_id', 'parent_span_id'])\n\n/**\n * JSON-stringify `value`, falling back to `String(value)` when `stringify`\n * throws or returns `undefined`, as it does for functions and symbols.\n */\nfunction safe_json(value: unknown): string {\n try {\n return JSON.stringify(value) ?? String(value)\n } catch {\n return String(value)\n }\n}\n\n/**\n * Convert a JS value into an OTel-compatible attribute value.\n *\n * Primitives and homogeneous primitive arrays pass through unchanged;\n * anything else falls back to `safe_json`; `null`/`undefined` drop out\n * entirely (returning `undefined`) so the caller can omit the attribute.\n */\nfunction to_attribute_value(value: unknown): AttributeValue | undefined {\n if (value === null || value === undefined) return undefined\n const kind = typeof value\n if (kind === 'string' || kind === 'number' || kind === 'boolean') {\n // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion\n return value as AttributeValue\n }\n if (Array.isArray(value)) {\n if (value.every((v) => typeof v === 'string')) return value\n if (value.every((v) => typeof v === 'number')) return value\n if (value.every((v) => typeof v === 'boolean')) return value\n return safe_json(value)\n }\n return safe_json(value)\n}\n\n/**\n * True for a plain object value (not null, not an array): the shape span-meta\n * flattening applies to.\n */\nfunction is_plain_object(value: unknown): value is Record<string, unknown> {\n return value !== null && typeof value === 'object' && !Array.isArray(value)\n}\n\n/**\n * Spread one object-valued span-meta field into dotted attribute keys\n * (`usage` + `input_tokens` becomes `<prefix>usage.input_tokens`), with\n * deeper nesting falling back to `to_attribute_value`'s JSON form.\n */\nfunction flatten_into(\n attrs: Attributes,\n key: string,\n value: Record<string, unknown>,\n prefix: string,\n): void {\n for (const [inner_key, inner_value] of Object.entries(value)) {\n const attr = to_attribute_value(inner_value)\n if (attr !== undefined) attrs[`${prefix}${key}.${inner_key}`] = attr\n }\n}\n\n/**\n * Build an OTel `Attributes` object from event/meta fields.\n *\n * Skips the bridge's internal plumbing keys (`kind`, `span_id`,\n * `parent_span_id`) and prefixes the rest with `prefix` so they stay out of\n * OTel's semantic-convention namespace.\n *\n * With `flatten`, an object-valued field spreads one level into dotted keys\n * (`usage: { input_tokens: 5 }` becomes `<prefix>usage.input_tokens = 5`), so\n * span metadata like usage and model_resolved lands as numeric attributes a\n * dashboard can aggregate rather than a JSON string it cannot query. Flattening\n * applies to span meta only, never to `record`ed events: an event may carry\n * arbitrary payloads (a tool call's input, a salvage blob) where\n * attribute-per-key would explode cardinality and leak structure, so those\n * keep the JSON-string fallback.\n */\nfunction to_attributes(\n meta: Readonly<Record<string, unknown>> | undefined,\n prefix: string,\n flatten = false,\n): Attributes {\n const attrs: Attributes = {}\n if (meta === undefined) return attrs\n for (const [key, value] of Object.entries(meta)) {\n if (INTERNAL_KEYS.has(key)) continue\n if (flatten && is_plain_object(value)) {\n flatten_into(attrs, key, value, prefix)\n continue\n }\n const attr = to_attribute_value(value)\n if (attr !== undefined) attrs[`${prefix}${key}`] = attr\n }\n return attrs\n}\n\ntype OpenSpan = { readonly span: Span; readonly context: Context }\n\n/**\n * Create a `TrajectoryLogger` that mirrors spans and events onto\n * OpenTelemetry, using `options.tracer` (or the global `fascicle` tracer).\n *\n * Parent resolution favors an explicit `parent_span_id` on the start meta;\n * otherwise it falls back to the currently open span on an internal stack.\n */\nexport function create_otel_trajectory_logger(\n options: OtelTrajectoryLoggerOptions = {},\n): TrajectoryLogger {\n const tracer = options.tracer ?? trace.getTracer('fascicle')\n const prefix = options.attribute_prefix ?? 'fascicle.'\n const metrics_recorder =\n options.metrics === undefined || options.metrics === false\n ? undefined\n : create_metrics_recorder(options.metrics === true ? {} : options.metrics)\n const open = new Map<string, OpenSpan>()\n const stack: string[] = []\n let counter = 0\n\n const top_context = (): Context | undefined => {\n const top = stack[stack.length - 1]\n if (top === undefined) return undefined\n return open.get(top)?.context\n }\n\n const parent_context = (meta: Record<string, unknown> | undefined): Context => {\n const explicit = meta?.['parent_span_id']\n if (typeof explicit === 'string') {\n const parent = open.get(explicit)\n if (parent !== undefined) return parent.context\n }\n return top_context() ?? otel_context.active()\n }\n\n const target_for_event = (event: TrajectoryEvent): Span | undefined => {\n if (typeof event.span_id === 'string') {\n const target = open.get(event.span_id)\n if (target !== undefined) return target.span\n }\n const top = stack[stack.length - 1]\n return top !== undefined ? open.get(top)?.span : undefined\n }\n\n return {\n start_span(name, meta) {\n const parent = parent_context(meta)\n const span = tracer.startSpan(\n name,\n { attributes: to_attributes(meta, prefix, true) },\n parent,\n )\n counter += 1\n const id = `fascicle-otel-${counter}`\n open.set(id, { span, context: trace.setSpan(parent, span) })\n stack.push(id)\n metrics_recorder?.on_start_span(id, name, meta)\n return id\n },\n end_span(id, meta) {\n metrics_recorder?.on_end_span(id)\n const entry = open.get(id)\n if (entry === undefined) return\n const { span } = entry\n span.setAttributes(to_attributes(meta, prefix, true))\n const error = meta?.['error']\n if (typeof error === 'string' && error.length > 0) {\n span.setStatus({ code: SpanStatusCode.ERROR, message: error })\n }\n span.end()\n open.delete(id)\n const idx = stack.lastIndexOf(id)\n if (idx !== -1) stack.splice(idx, 1)\n },\n record(event) {\n metrics_recorder?.on_record(event)\n const span = target_for_event(event)\n if (span === undefined) return\n const name = typeof event.kind === 'string' ? event.kind : 'event'\n span.addEvent(name, to_attributes(event, prefix))\n },\n }\n}\n"],"mappings":"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"}
package/dist/testing.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { D as ToolCallRecord, a as Engine, c as FinishReason, j as UsageTotals, l as GenerateOptions, u as GenerateResult } from "./types-DU6cvoA4.js";
1
+ import { M as UsageTotals, O as ToolCallRecord, a as Engine, c as FinishReason, l as GenerateOptions, u as GenerateResult } from "./types-CLigYA62.js";
2
2
 
3
3
  //#region src/testing/engine_from_generate.d.ts
4
4
  /**
package/dist/testing.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { O as aborted_error } from "./core-DdJEhyQc.js";
2
- import "./engine-J4lIxpw5.js";
2
+ import "./engine-CdXegeqC.js";
3
3
  import { y as schema_validation_error } from "./leading_system-BUCT-PwD.js";
4
4
  //#region src/testing/engine_from_generate.ts
5
5
  /**
@@ -164,6 +164,20 @@ type CostBreakdown = {
164
164
  is_estimate: true;
165
165
  };
166
166
  type SalvageFormat = 'hermes' | 'json' | 'qwen_xml';
167
+ /**
168
+ * Wall-clock timing of one step's provider round-trip, measured by the engine
169
+ * around the successful turn attempt: failed attempts and retry backoff are
170
+ * excluded, as is tool execution (that is ToolCallRecord.duration_ms).
171
+ * `first_chunk_ms` is present only on streamed turns: milliseconds from the
172
+ * attempt start to the first chunk, so `duration_ms - first_chunk_ms` is the
173
+ * window the model spent emitting output. See `throughput()` for the derived
174
+ * tokens-per-second view.
175
+ */
176
+ type StepTiming = {
177
+ /** Epoch ms when the successful provider attempt started. */started_at: number; /** Wall-clock ms from attempt start to the turn result. */
178
+ duration_ms: number; /** Streamed turns only: ms from attempt start to the first chunk. */
179
+ first_chunk_ms?: number;
180
+ };
167
181
  type ToolCallRecord = {
168
182
  id: string;
169
183
  name: string;
@@ -188,6 +202,12 @@ type StepRecord = {
188
202
  tool_calls: ToolCallRecord[];
189
203
  usage: UsageTotals;
190
204
  cost?: CostBreakdown;
205
+ /**
206
+ * Present on every step the engine's tool loop produced (both transports),
207
+ * absent on steps built by external adapters (claude_cli) and injected test
208
+ * seams that return a TurnResult without one.
209
+ */
210
+ timing?: StepTiming;
191
211
  finish_reason: FinishReason;
192
212
  /**
193
213
  * This turn's provider-reported detail, keyed by provider name. See
@@ -313,6 +333,12 @@ type TurnResult = {
313
333
  }>;
314
334
  readonly finish_reason: FinishReason;
315
335
  readonly usage: UsageTotals;
336
+ /**
337
+ * Stamped by the engine's retry wrapper around the successful attempt, not
338
+ * by adapters: an adapter-returned TurnResult never carries one, and the
339
+ * wrapper's value would overwrite it if it did. See StepTiming.
340
+ */
341
+ readonly timing?: StepTiming;
316
342
  /**
317
343
  * Opaque detail the provider reported about this turn, keyed by provider
318
344
  * name: Bedrock's guardrail trace, Anthropic's cache breakdown, whatever a
@@ -601,5 +627,5 @@ type Engine = {
601
627
  dispose: () => Promise<void>;
602
628
  };
603
629
  //#endregion
604
- export { TurnResult as A, ProviderTransport as B, StreamChunk as C, ToolCallRecord as D, ToolApprovalRequest as E, ExternalAgentAdapter as F, default_normalize_usage as H, NativeProviderAdapter as I, ProviderAdapter as L, UserContentPart as M, AiSdkProviderAdapter as N, ToolExecContext as O, EffortTranslation as P, ProviderCapability as R, StepRecord as S, ToolApprovalHandler as T, RawProviderUsage as V, ProviderConfigMap as _, Engine as a, RetryFailureKind as b, FinishReason as c, Message as d, PrepareStepContext as f, PricingTable as g, Pricing as h, EffortLevel as i, UsageTotals as j, TurnRequest as k, GenerateOptions as l, PrepareStepResult as m, AssistantContentPart as n, EngineConfig as o, PrepareStepHook as p, CostBreakdown as r, EngineDefaults as s, AiSdkTelemetrySettings as t, GenerateResult as u, ProviderInit as v, Tool as w, RetryPolicy as x, ResolvedModel as y, ProviderFactory as z };
605
- //# sourceMappingURL=types-DU6cvoA4.d.ts.map
630
+ export { TurnRequest as A, ProviderFactory as B, StepTiming as C, ToolApprovalRequest as D, ToolApprovalHandler as E, EffortTranslation as F, RawProviderUsage as H, ExternalAgentAdapter as I, NativeProviderAdapter as L, UsageTotals as M, UserContentPart as N, ToolCallRecord as O, AiSdkProviderAdapter as P, ProviderAdapter as R, StepRecord as S, Tool as T, default_normalize_usage as U, ProviderTransport as V, ProviderConfigMap as _, Engine as a, RetryFailureKind as b, FinishReason as c, Message as d, PrepareStepContext as f, PricingTable as g, Pricing as h, EffortLevel as i, TurnResult as j, ToolExecContext as k, GenerateOptions as l, PrepareStepResult as m, AssistantContentPart as n, EngineConfig as o, PrepareStepHook as p, CostBreakdown as r, EngineDefaults as s, AiSdkTelemetrySettings as t, GenerateResult as u, ProviderInit as v, StreamChunk as w, RetryPolicy as x, ResolvedModel as y, ProviderCapability as z };
631
+ //# sourceMappingURL=types-CLigYA62.d.ts.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fascicle",
3
- "version": "0.12.3",
3
+ "version": "0.12.5",
4
4
  "description": "Compose agents like plain values. A TypeScript toolkit that wires LLM calls, tools, and functions into typed steps over eight providers. No framework, no ambient state.",
5
5
  "keywords": [
6
6
  "agents",
@@ -199,7 +199,11 @@
199
199
  "@arethetypeswrong/cli": "0.18.4",
200
200
  "@ast-grep/cli": "0.44.1",
201
201
  "@modelcontextprotocol/sdk": "1.30.0",
202
- "@opentelemetry/sdk-trace-base": "2.9.0",
202
+ "@opentelemetry/exporter-metrics-otlp-http": "^0.221.0",
203
+ "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
204
+ "@opentelemetry/resources": "^2.10.0",
205
+ "@opentelemetry/sdk-metrics": "2.10.0",
206
+ "@opentelemetry/sdk-trace-base": "2.10.0",
203
207
  "@standard-schema/spec": "1.1.0",
204
208
  "@stryker-mutator/core": "9.6.1",
205
209
  "@stryker-mutator/vitest-runner": "9.6.1",