fascicle 0.9.0 → 0.9.2

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,5 +1,5 @@
1
1
  import { G as Step, J as TrajectoryLogger } from "./index-JhJahQNi.js";
2
- import { P as Tool } from "./index-CJRUqgsV.js";
2
+ import { R as Tool } from "./index-DyjXGal_.js";
3
3
  import { z } from "zod";
4
4
  import { Client } from "@modelcontextprotocol/sdk/client/index.js";
5
5
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
package/dist/otel.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ import { J as TrajectoryLogger } from "./index-JhJahQNi.js";
2
+ import { Tracer } from "@opentelemetry/api";
3
+
4
+ //#region src/otel/trajectory_logger.d.ts
5
+ type OtelTrajectoryLoggerOptions = {
6
+ /**
7
+ * Tracer to open spans on. Defaults to `trace.getTracer('fascicle')`, which
8
+ * resolves against whatever global TracerProvider the host has registered.
9
+ */
10
+ readonly tracer?: Tracer;
11
+ /**
12
+ * Prefix for span + event attributes derived from event metadata, keeping
13
+ * them out of the OTel semantic-convention namespace. Defaults to `fascicle.`.
14
+ */
15
+ readonly attribute_prefix?: string;
16
+ };
17
+ declare function create_otel_trajectory_logger(options?: OtelTrajectoryLoggerOptions): TrajectoryLogger;
18
+ //#endregion
19
+ export { type OtelTrajectoryLoggerOptions, create_otel_trajectory_logger };
20
+ //# sourceMappingURL=otel.d.ts.map
package/dist/otel.js ADDED
@@ -0,0 +1,127 @@
1
+ import { SpanStatusCode, context, trace } from "@opentelemetry/api";
2
+ //#region src/otel/trajectory_logger.ts
3
+ /**
4
+ * OpenTelemetry bridge for fascicle trajectory events (D7, Layer 1).
5
+ *
6
+ * `create_otel_trajectory_logger` returns a plain TrajectoryLogger that turns
7
+ * the engine's own span + event stream into OpenTelemetry spans: the
8
+ * `engine.generate` span becomes an OTel root span, each `engine.generate.step`
9
+ * a child span, and every `record`ed event (tool_call, tool_result, cost, ...)
10
+ * an OTel span event on the currently-open span. It is transport-neutral: the
11
+ * spans come from events the engine already emits, so native and external
12
+ * transports get traces without any AI-SDK involvement.
13
+ *
14
+ * This module is the ONLY place `@opentelemetry/api` is imported, and it lives
15
+ * outside `src/engine/` on purpose (C2): the engine's `ai + zod` npm-dep
16
+ * invariant holds unmodified, and an app that never imports `fascicle/otel`
17
+ * pulls in zero OTel packages at runtime.
18
+ *
19
+ * Nesting is resolved two ways, in order: an explicit `parent_span_id` on the
20
+ * start meta (how the composition runner threads composer-span parenthood) wins;
21
+ * otherwise the currently-open span (top of the open stack) is the parent. This
22
+ * is exact for the sequential engine flow (generate → step → step) and for
23
+ * runner-nested spans; genuinely interleaved sibling spans that carry no
24
+ * `parent_span_id` (concurrent branches sharing one logger) fall back to stack
25
+ * order, which is this bridge's one documented approximation.
26
+ */
27
+ const INTERNAL_KEYS = /* @__PURE__ */ new Set([
28
+ "kind",
29
+ "span_id",
30
+ "parent_span_id"
31
+ ]);
32
+ function safe_json(value) {
33
+ try {
34
+ return JSON.stringify(value) ?? String(value);
35
+ } catch {
36
+ return String(value);
37
+ }
38
+ }
39
+ function to_attribute_value(value) {
40
+ if (value === null || value === void 0) return void 0;
41
+ const kind = typeof value;
42
+ if (kind === "string" || kind === "number" || kind === "boolean") return value;
43
+ if (Array.isArray(value)) {
44
+ if (value.every((v) => typeof v === "string")) return value;
45
+ if (value.every((v) => typeof v === "number")) return value;
46
+ if (value.every((v) => typeof v === "boolean")) return value;
47
+ return safe_json(value);
48
+ }
49
+ return safe_json(value);
50
+ }
51
+ function to_attributes(meta, prefix) {
52
+ const attrs = {};
53
+ if (meta === void 0) return attrs;
54
+ for (const [key, value] of Object.entries(meta)) {
55
+ if (INTERNAL_KEYS.has(key)) continue;
56
+ const attr = to_attribute_value(value);
57
+ if (attr !== void 0) attrs[`${prefix}${key}`] = attr;
58
+ }
59
+ return attrs;
60
+ }
61
+ function create_otel_trajectory_logger(options = {}) {
62
+ const tracer = options.tracer ?? trace.getTracer("fascicle");
63
+ const prefix = options.attribute_prefix ?? "fascicle.";
64
+ const open = /* @__PURE__ */ new Map();
65
+ const stack = [];
66
+ let counter = 0;
67
+ const top_context = () => {
68
+ const top = stack[stack.length - 1];
69
+ if (top === void 0) return void 0;
70
+ return open.get(top)?.context;
71
+ };
72
+ const parent_context = (meta) => {
73
+ const explicit = meta?.["parent_span_id"];
74
+ if (typeof explicit === "string") {
75
+ const parent = open.get(explicit);
76
+ if (parent !== void 0) return parent.context;
77
+ }
78
+ return top_context() ?? context.active();
79
+ };
80
+ const target_for_event = (event) => {
81
+ if (typeof event.span_id === "string") {
82
+ const target = open.get(event.span_id);
83
+ if (target !== void 0) return target.span;
84
+ }
85
+ const top = stack[stack.length - 1];
86
+ return top !== void 0 ? open.get(top)?.span : void 0;
87
+ };
88
+ return {
89
+ start_span(name, meta) {
90
+ const parent = parent_context(meta);
91
+ const span = tracer.startSpan(name, { attributes: to_attributes(meta, prefix) }, parent);
92
+ counter += 1;
93
+ const id = `fascicle-otel-${counter}`;
94
+ open.set(id, {
95
+ span,
96
+ context: trace.setSpan(parent, span)
97
+ });
98
+ stack.push(id);
99
+ return id;
100
+ },
101
+ end_span(id, meta) {
102
+ const entry = open.get(id);
103
+ if (entry === void 0) return;
104
+ const { span } = entry;
105
+ span.setAttributes(to_attributes(meta, prefix));
106
+ const error = meta?.["error"];
107
+ if (typeof error === "string" && error.length > 0) span.setStatus({
108
+ code: SpanStatusCode.ERROR,
109
+ message: error
110
+ });
111
+ span.end();
112
+ open.delete(id);
113
+ const idx = stack.lastIndexOf(id);
114
+ if (idx !== -1) stack.splice(idx, 1);
115
+ },
116
+ record(event) {
117
+ const span = target_for_event(event);
118
+ if (span === void 0) return;
119
+ const name = typeof event.kind === "string" ? event.kind : "event";
120
+ span.addEvent(name, to_attributes(event, prefix));
121
+ }
122
+ };
123
+ }
124
+ //#endregion
125
+ export { create_otel_trajectory_logger };
126
+
127
+ //# sourceMappingURL=otel.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"otel.js","names":["otel_context"],"sources":["../src/otel/trajectory_logger.ts"],"sourcesContent":["/**\n * OpenTelemetry bridge for fascicle trajectory events (D7, Layer 1).\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 (C2): the engine's `ai + zod` npm-dep\n * invariant holds unmodified, and an app that never imports `fascicle/otel`\n * 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'\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\nfunction safe_json(value: unknown): string {\n try {\n return JSON.stringify(value) ?? String(value)\n } catch {\n return String(value)\n }\n}\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\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\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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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fascicle",
3
- "version": "0.9.0",
3
+ "version": "0.9.2",
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",
@@ -55,6 +55,10 @@
55
55
  "types": "./dist/mcp.d.ts",
56
56
  "import": "./dist/mcp.js"
57
57
  },
58
+ "./otel": {
59
+ "types": "./dist/otel.d.ts",
60
+ "import": "./dist/otel.js"
61
+ },
58
62
  "./stdio": {
59
63
  "types": "./dist/stdio.d.ts",
60
64
  "import": "./dist/stdio.js"
@@ -116,8 +120,10 @@
116
120
  "@ai-sdk/google": "^4.0.0",
117
121
  "@ai-sdk/openai": "^4.0.0",
118
122
  "@ai-sdk/openai-compatible": "^3.0.0",
123
+ "@ai-sdk/otel": "^1.0.0",
119
124
  "@modelcontextprotocol/sdk": "^1.29.0",
120
125
  "@openrouter/ai-sdk-provider": "^3.0.0",
126
+ "@opentelemetry/api": "^1.9.0",
121
127
  "ai": "^7.0.0",
122
128
  "ai-sdk-ollama": "^4.0.0",
123
129
  "zod": "^4.0.0"
@@ -138,12 +144,18 @@
138
144
  "@ai-sdk/openai-compatible": {
139
145
  "optional": true
140
146
  },
147
+ "@ai-sdk/otel": {
148
+ "optional": true
149
+ },
141
150
  "@modelcontextprotocol/sdk": {
142
151
  "optional": true
143
152
  },
144
153
  "@openrouter/ai-sdk-provider": {
145
154
  "optional": true
146
155
  },
156
+ "@opentelemetry/api": {
157
+ "optional": true
158
+ },
147
159
  "ai-sdk-ollama": {
148
160
  "optional": true
149
161
  }
@@ -152,6 +164,7 @@
152
164
  "@arethetypeswrong/cli": "0.18.4",
153
165
  "@ast-grep/cli": "0.44.1",
154
166
  "@modelcontextprotocol/sdk": "1.29.0",
167
+ "@opentelemetry/sdk-trace-base": "2.9.0",
155
168
  "@stryker-mutator/core": "9.6.1",
156
169
  "@stryker-mutator/vitest-runner": "9.6.1",
157
170
  "@types/node": "26.1.0",