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/CHANGELOG.md +35 -6
- package/README.md +3 -2
- package/dist/agents.d.ts +1 -1
- package/dist/{engine-J4lIxpw5.js → engine-CdXegeqC.js} +164 -26
- package/dist/engine-CdXegeqC.js.map +1 -0
- package/dist/index.d.ts +28 -2
- package/dist/index.js +46 -2
- package/dist/index.js.map +1 -1
- package/dist/mcp.d.ts +1 -1
- package/dist/otel.d.ts +20 -2
- package/dist/otel.js +228 -8
- package/dist/otel.js.map +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +1 -1
- package/dist/{types-DU6cvoA4.d.ts → types-CLigYA62.d.ts} +28 -2
- package/package.json +6 -2
- package/dist/engine-J4lIxpw5.js.map +0 -1
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 {
|
|
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
|
-
*
|
|
15
|
-
* outside `src/engine/` on purpose: the engine's `ai + zod`
|
|
16
|
-
* holds unmodified, and an app that never imports
|
|
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 {
|
|
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
|
@@ -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 {
|
|
605
|
-
//# sourceMappingURL=types-
|
|
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
|
+
"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/
|
|
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",
|