fascicle 0.16.5 → 0.17.1

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.
Files changed (41) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +3 -2
  3. package/dist/AGENTS.md +69 -18
  4. package/dist/acp.d.ts +1 -1
  5. package/dist/acp.js +7 -2
  6. package/dist/acp.js.map +1 -1
  7. package/dist/agents.d.ts +1 -1
  8. package/dist/{engine-B6rIIM4J.js → engine-Bde18P7H.js} +1163 -236
  9. package/dist/engine-Bde18P7H.js.map +1 -0
  10. package/dist/index.d.ts +114 -16
  11. package/dist/index.js +226 -16
  12. package/dist/index.js.map +1 -1
  13. package/dist/{invoke-LbzZLZFw.js → invoke-BbJLQcLl.js} +62 -106
  14. package/dist/invoke-BbJLQcLl.js.map +1 -0
  15. package/dist/{leading_system-WhW76tRn.js → leading_system-DmNxhvzL.js} +45 -16
  16. package/dist/leading_system-DmNxhvzL.js.map +1 -0
  17. package/dist/mcp.d.ts +2 -1
  18. package/dist/mcp.js +6 -3
  19. package/dist/mcp.js.map +1 -1
  20. package/dist/otel.js +48 -3
  21. package/dist/otel.js.map +1 -1
  22. package/dist/{search-CpCJYMUm.js → search-DjhdMsJ8.js} +4 -1
  23. package/dist/search-DjhdMsJ8.js.map +1 -0
  24. package/dist/search_worker.js +1 -1
  25. package/dist/testing.d.ts +77 -2
  26. package/dist/testing.js +202 -19
  27. package/dist/testing.js.map +1 -1
  28. package/dist/{types-Sw0oHW-_.d.ts → types-C7pO0jLq.d.ts} +218 -21
  29. package/dist/viewer-app/assets/index-9eVv6Mar.css +1 -0
  30. package/dist/viewer-app/assets/index-BkS2ZQu0.js +4 -0
  31. package/dist/viewer-app/index.html +2 -2
  32. package/dist/viewer.d.ts +64 -10
  33. package/dist/viewer.js +265 -64
  34. package/dist/viewer.js.map +1 -1
  35. package/package.json +1 -1
  36. package/dist/engine-B6rIIM4J.js.map +0 -1
  37. package/dist/invoke-LbzZLZFw.js.map +0 -1
  38. package/dist/leading_system-WhW76tRn.js.map +0 -1
  39. package/dist/search-CpCJYMUm.js.map +0 -1
  40. package/dist/viewer-app/assets/index-Cev83tcH.css +0 -1
  41. package/dist/viewer-app/assets/index-D8UmFVfR.js +0 -2
package/dist/mcp.js CHANGED
@@ -205,16 +205,19 @@ function build_transport(sdk, config) {
205
205
  }
206
206
  /**
207
207
  * Wraps one advertised MCP tool as a Fascicle `Tool` whose `execute` forwards
208
- * to `callTool` on the shared client.
208
+ * to `callTool` on the shared client. Only the `Tool`'s name carries
209
+ * `name_prefix`; the call, the fallback description, and the errors use the
210
+ * server's own name.
209
211
  *
210
212
  * An already-aborted signal short-circuits before the wire call; otherwise the
211
213
  * signal is passed through so cancelling the run cancels the remote call.
212
214
  */
213
215
  function to_fascicle_tool(client, advertised, options) {
214
216
  const name = advertised.name;
217
+ const description = advertised.description ?? options.default_description?.(name) ?? `MCP tool ${name}`;
215
218
  return {
216
- name,
217
- description: advertised.description ?? options.default_description?.(name) ?? `MCP tool ${name}`,
219
+ name: `${options.name_prefix ?? ""}${name}`,
220
+ description,
218
221
  input_schema: json_schema_to_standard(advertised.inputSchema),
219
222
  execute: async (input, ctx) => {
220
223
  if (ctx.abort.aborted) throw ctx.abort.reason instanceof Error ? ctx.abort.reason : new mcp_error(`MCP tool ${name} aborted before invocation`, { tool_name: name });
package/dist/mcp.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"mcp.js","names":[],"sources":["../src/mcp/errors.ts","../src/mcp/result_mapping.ts","../src/mcp/sdk_loader.ts","../src/mcp/client.ts","../src/mcp/serve.ts"],"sourcesContent":["/**\n * Typed errors for the MCP adapter.\n *\n * Listed alongside src/core/errors.ts and src/engine/errors.ts in the\n * `no-class` rule ignores: `instanceof` branching is how callers distinguish a\n * missing optional peer from a tool-level failure surfaced over the wire.\n */\n\nexport class mcp_sdk_missing_error extends Error {\n readonly kind = 'mcp_sdk_missing_error' as const;\n constructor(\n message = '@modelcontextprotocol/sdk is required for fascicle/mcp; install it: pnpm add @modelcontextprotocol/sdk',\n ) {\n super(message)\n this.name = 'mcp_sdk_missing_error'\n }\n}\n\nexport class mcp_error extends Error {\n readonly kind = 'mcp_error' as const;\n readonly tool_name: string | undefined;\n constructor(message: string, metadata: { tool_name?: string } = {}) {\n super(message)\n this.name = 'mcp_error'\n this.tool_name = metadata.tool_name\n }\n}\n","/**\n * Mapping between MCP `CallToolResult` payloads and Fascicle tool values, in\n * both directions: inbound results from `mcp_client` tools, outbound results\n * for `serve_flow`.\n */\n\nimport { as_record, is_record } from '#schema'\nimport { mcp_error } from './errors.js'\n\nexport type McpToolResult = {\n content: Array<{ type: 'text'; text: string }>\n structuredContent?: Record<string, unknown>\n}\n\n/**\n * Converts a remote tool's `CallToolResult` into the value a Fascicle\n * `Tool.execute` returns.\n *\n * `isError: true` marks a tool-level failure, so it throws `mcp_error` rather\n * than returning, letting the tool loop's error policy feed it back to the\n * model. `structuredContent` is preferred over joined text parts when present;\n * with neither, the raw `content` (or `null`) is returned.\n */\nexport function call_result_to_output(result: unknown, tool_name?: string): unknown {\n const record = as_record(result) ?? {}\n\n if (record['isError'] === true) {\n const detail = join_text(record['content']) ?? 'MCP tool returned an error'\n throw new mcp_error(detail, tool_name !== undefined ? { tool_name } : {})\n }\n\n if (is_record(record['structuredContent'])) return record['structuredContent']\n\n const text = join_text(record['content'])\n if (text !== undefined) return text\n\n return record['content'] ?? null\n}\n\n/**\n * Converts a Fascicle flow's output into a `CallToolResult` for `serve_flow`.\n *\n * A `to_result` override takes precedence over the default mapping. By\n * default, objects are emitted as both a JSON text part (every MCP host can\n * read text) and `structuredContent` (typed hosts get the object); everything\n * else becomes a single text part.\n */\nexport function output_to_call_result<o>(\n output: o,\n to_result?: (output: o) => { text: string; structured?: Record<string, unknown> },\n): McpToolResult {\n if (to_result !== undefined) {\n const shaped = to_result(output)\n return build_result(shaped.text, shaped.structured)\n }\n if (typeof output === 'string') return build_result(output)\n if (is_record(output)) return build_result(stringify(output), output)\n if (Array.isArray(output)) return build_result(stringify(output))\n return build_result(String(output))\n}\n\n/**\n * Assembles a `CallToolResult` with one text part and, when given, structured\n * content.\n */\nfunction build_result(text: string, structured?: Record<string, unknown>): McpToolResult {\n return structured !== undefined\n ? { content: [{ type: 'text', text }], structuredContent: structured }\n : { content: [{ type: 'text', text }] }\n}\n\n/**\n * Joins the `text` parts of an MCP content array with newlines, skipping\n * non-text parts; `undefined` when there is nothing to join.\n */\nfunction join_text(content: unknown): string | undefined {\n if (!Array.isArray(content)) return undefined\n const parts: string[] = []\n for (const part of content) {\n if (is_record(part) && part['type'] === 'text' && typeof part['text'] === 'string') {\n parts.push(part['text'])\n }\n }\n return parts.length > 0 ? parts.join('\\n') : undefined\n}\n\n/**\n * `JSON.stringify` that falls back to `String` instead of throwing on\n * unserializable values (circular references, BigInt).\n */\nfunction stringify(value: unknown): string {\n try {\n return JSON.stringify(value)\n } catch {\n return String(value)\n }\n}\n","/**\n * Lazy loader for the optional `@modelcontextprotocol/sdk` peer.\n *\n * `mcp_client` needs SDK values (the Client and transport constructors), so it\n * imports them dynamically rather than statically: a consumer can import\n * `fascicle/mcp` without the SDK installed and only pays the cost when they\n * actually connect. A missing peer surfaces as a typed `mcp_sdk_missing_error`\n * with install guidance, mirroring the engine's `load_optional_peer`.\n *\n * `serve_flow` is not covered here: it operates on a caller-constructed\n * `McpServer`, so it needs only a type-only import and no runtime SDK load.\n */\n\nimport { mcp_sdk_missing_error } from './errors.js'\n\nexport type McpClientSdk = Awaited<ReturnType<typeof load_client_sdk>>\n\n/**\n * Dynamically imports the `@modelcontextprotocol/sdk` client modules,\n * throwing a typed `mcp_sdk_missing_error` when the optional peer is not\n * installed.\n */\nexport async function load_client_sdk() {\n try {\n const [client_mod, stdio_mod, http_mod] = await Promise.all([\n import('@modelcontextprotocol/sdk/client/index.js'),\n import('@modelcontextprotocol/sdk/client/stdio.js'),\n import('@modelcontextprotocol/sdk/client/streamableHttp.js'),\n ])\n return {\n Client: client_mod.Client,\n StdioClientTransport: stdio_mod.StdioClientTransport,\n StreamableHTTPClientTransport: http_mod.StreamableHTTPClientTransport,\n }\n } catch (err: unknown) {\n const detail = err instanceof Error ? err.message : String(err)\n throw new mcp_sdk_missing_error(\n `@modelcontextprotocol/sdk is required for fascicle/mcp; install it: pnpm add @modelcontextprotocol/sdk (cause: ${detail})`,\n )\n }\n}\n","/**\n * Inbound MCP: connect to an external MCP server and surface its tools as plain\n * Fascicle `Tool[]`.\n */\n\nimport type { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'\nimport type { Tool, ToolExecContext } from '#engine'\nimport { is_record, json_schema_to_standard } from '#schema'\nimport { mcp_error } from './errors.js'\nimport { call_result_to_output } from './result_mapping.js'\nimport { load_client_sdk, type McpClientSdk } from './sdk_loader.js'\n\nconst DEFAULT_CLIENT_INFO = { name: 'fascicle', version: '0.0.0' }\n\nexport type McpStdioConfig = {\n transport: 'stdio'\n command: string\n args?: string[]\n env?: Record<string, string>\n cwd?: string\n}\n\nexport type McpStreamableHttpConfig = {\n transport: 'http'\n url: string\n headers?: Record<string, string>\n}\n\n// Escape hatch: hand in an already-connected Client (a transport the adapter\n// does not build, a test harness, a shared connection). Its lifecycle stays\n// with the caller, so the returned `close` is a no-op for this variant.\nexport type McpExistingClientConfig = {\n transport: 'client'\n client: Client\n}\n\nexport type McpClientConfig =\n | McpStdioConfig\n | McpStreamableHttpConfig\n | McpExistingClientConfig\n\nexport type McpClientOptions = {\n // Identity sent in the MCP handshake; defaults to Fascicle.\n client_info?: { name: string; version: string }\n // When set, only tools whose name is listed are surfaced.\n include?: ReadonlyArray<string>\n // Supplies a description for tools that advertise none.\n default_description?: (tool_name: string) => string\n}\n\nexport type McpClientHandle = {\n readonly tools: ReadonlyArray<Tool>\n readonly close: () => Promise<void>\n}\n\n/**\n * Connects to an MCP server and surfaces its advertised tools as Fascicle\n * `Tool[]`, plus a `close` handle for the connection.\n *\n * Owns the connection lifecycle (config in, `{ tools, close }` out) so callers\n * do not have to import SDK transport classes themselves. Each advertised MCP\n * tool becomes an ordinary `Tool`: its JSON Schema is wrapped as a `ToolSchema`\n * the loop validates against and the provider receives back unchanged, and\n * `execute` forwards to `callTool`, propagating the run's abort signal. For the\n * `client` transport variant the caller keeps ownership of the connection, so\n * `close` is a no-op. A connection this call opened is closed again when\n * listing its tools fails.\n */\nexport async function mcp_client(\n config: McpClientConfig,\n options: McpClientOptions = {},\n): Promise<McpClientHandle> {\n const owns_client = config.transport !== 'client'\n const client = await connect_client(config, options)\n\n const include = options.include !== undefined ? new Set(options.include) : undefined\n const listed = await client.listTools().catch(async (err: unknown) => {\n // A client this call connected has no other owner yet, so it closes here,\n // taking a spawned stdio server with it. The listing failure is the one\n // the caller sees, even if the close fails too.\n if (owns_client) await client.close().catch(() => undefined)\n throw err\n })\n const tools: Tool[] = []\n for (const advertised of listed.tools) {\n if (include !== undefined && !include.has(advertised.name)) continue\n tools.push(to_fascicle_tool(client, advertised, options))\n }\n\n return {\n tools,\n close: async () => {\n if (owns_client) await client.close()\n },\n }\n}\n\n/**\n * Returns the caller's already-connected client as-is, or lazily loads the\n * SDK and connects a fresh client over the configured transport.\n */\nasync function connect_client(\n config: McpClientConfig,\n options: McpClientOptions,\n): Promise<Client> {\n if (config.transport === 'client') return config.client\n const sdk = await load_client_sdk()\n const client = new sdk.Client(options.client_info ?? DEFAULT_CLIENT_INFO)\n await client.connect(build_transport(sdk, config))\n return client\n}\n\n/**\n * Constructs the SDK transport matching the config: a spawned child process\n * for `stdio`, a Streamable HTTP connection for `http`.\n */\nfunction build_transport(\n sdk: McpClientSdk,\n config: McpStdioConfig | McpStreamableHttpConfig,\n): Transport {\n if (config.transport === 'stdio') {\n return new sdk.StdioClientTransport({\n command: config.command,\n ...(config.args !== undefined ? { args: config.args } : {}),\n ...(config.env !== undefined ? { env: config.env } : {}),\n ...(config.cwd !== undefined ? { cwd: config.cwd } : {}),\n })\n }\n const opts = config.headers !== undefined ? { requestInit: { headers: config.headers } } : {}\n // The SDK declares this class `implements Transport`, but its `onmessage`\n // overload is narrower than the interface's, which only strict mode flags.\n // eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion\n return new sdk.StreamableHTTPClientTransport(new URL(config.url), opts) as Transport\n}\n\n/**\n * Wraps one advertised MCP tool as a Fascicle `Tool` whose `execute` forwards\n * to `callTool` on the shared client.\n *\n * An already-aborted signal short-circuits before the wire call; otherwise the\n * signal is passed through so cancelling the run cancels the remote call.\n */\nfunction to_fascicle_tool(\n client: Client,\n advertised: { name: string; description?: string | undefined; inputSchema: unknown },\n options: McpClientOptions,\n): Tool {\n const name = advertised.name\n const description =\n advertised.description ?? options.default_description?.(name) ?? `MCP tool ${name}`\n return {\n name,\n description,\n input_schema: json_schema_to_standard(advertised.inputSchema),\n execute: async (input: unknown, ctx: ToolExecContext) => {\n if (ctx.abort.aborted) {\n throw ctx.abort.reason instanceof Error\n ? ctx.abort.reason\n : new mcp_error(`MCP tool ${name} aborted before invocation`, { tool_name: name })\n }\n const result = await client.callTool(\n { name, arguments: is_record(input) ? input : undefined },\n undefined,\n { signal: ctx.abort },\n )\n return call_result_to_output(result, name)\n },\n }\n}\n","/**\n * Outbound MCP: expose a composed Fascicle flow as an MCP tool.\n *\n * `serve_flow` registers onto a caller-constructed `McpServer` (the caller owns\n * the transport, identity, and lifecycle, and can host many flows on one\n * server), so it needs only a type-only SDK import. The registered handler\n * drives the existing `run`, threading the per-request abort signal so an MCP\n * client cancellation aborts the in-flight flow, and maps the result into a\n * `CallToolResult`. A thrown flow becomes an `isError` result rather than a\n * JSON-RPC protocol error.\n */\n\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport type { z } from 'zod'\nimport { run } from '#core'\nimport type { Step, TrajectoryLogger } from '#core'\nimport { output_to_call_result } from './result_mapping.js'\n\nexport type ServeFlowConfig<i, o> = {\n server: McpServer\n flow: Step<i, o>\n name: string\n description: string\n /**\n * Stays zod rather than joining the rest of the surface on `ToolSchema`.\n * `McpServer.registerTool` types `inputSchema` as a zod schema and offers no\n * JSON Schema entry point, and the SDK carries zod as a hard runtime\n * dependency, so a `serve_flow` caller already has zod resolved. Widening\n * this to a neutral schema would typecheck and then fail inside the SDK.\n */\n input_schema: z.ZodType<i>\n trajectory?: TrajectoryLogger\n // Overrides the default value-to-CallToolResult mapping.\n to_result?: (output: o) => { text: string; structured?: Record<string, unknown> }\n}\n\n/**\n * Registers a Fascicle flow as a tool on a caller-owned MCP server.\n *\n * Drives the flow with `run`, threading the per-request abort signal so an\n * MCP client cancellation aborts the in-flight flow, and maps the result\n * into a `CallToolResult`. A thrown flow becomes an `isError` result rather\n * than a JSON-RPC protocol error.\n */\nexport function serve_flow<i, o>(config: ServeFlowConfig<i, o>): void {\n const { server, flow, name, description, input_schema, trajectory, to_result } = config\n server.registerTool(\n name,\n { description, inputSchema: input_schema },\n async (input: i, extra) => {\n try {\n const output = await run(flow, input, {\n install_signal_handlers: false,\n abort: extra.signal,\n ...(trajectory !== undefined ? { trajectory } : {}),\n })\n return output_to_call_result(output, to_result)\n } catch (err: unknown) {\n return {\n isError: true,\n content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],\n }\n }\n },\n )\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"mcp.js","names":[],"sources":["../src/mcp/errors.ts","../src/mcp/result_mapping.ts","../src/mcp/sdk_loader.ts","../src/mcp/client.ts","../src/mcp/serve.ts"],"sourcesContent":["/**\n * Typed errors for the MCP adapter.\n *\n * Listed alongside src/core/errors.ts and src/engine/errors.ts in the\n * `no-class` rule ignores: `instanceof` branching is how callers distinguish a\n * missing optional peer from a tool-level failure surfaced over the wire.\n */\n\nexport class mcp_sdk_missing_error extends Error {\n readonly kind = 'mcp_sdk_missing_error' as const;\n constructor(\n message = '@modelcontextprotocol/sdk is required for fascicle/mcp; install it: pnpm add @modelcontextprotocol/sdk',\n ) {\n super(message)\n this.name = 'mcp_sdk_missing_error'\n }\n}\n\nexport class mcp_error extends Error {\n readonly kind = 'mcp_error' as const;\n readonly tool_name: string | undefined;\n constructor(message: string, metadata: { tool_name?: string } = {}) {\n super(message)\n this.name = 'mcp_error'\n this.tool_name = metadata.tool_name\n }\n}\n","/**\n * Mapping between MCP `CallToolResult` payloads and Fascicle tool values, in\n * both directions: inbound results from `mcp_client` tools, outbound results\n * for `serve_flow`.\n */\n\nimport { as_record, is_record } from '#schema'\nimport { mcp_error } from './errors.js'\n\nexport type McpToolResult = {\n content: Array<{ type: 'text'; text: string }>\n structuredContent?: Record<string, unknown>\n}\n\n/**\n * Converts a remote tool's `CallToolResult` into the value a Fascicle\n * `Tool.execute` returns.\n *\n * `isError: true` marks a tool-level failure, so it throws `mcp_error` rather\n * than returning, letting the tool loop's error policy feed it back to the\n * model. `structuredContent` is preferred over joined text parts when present;\n * with neither, the raw `content` (or `null`) is returned.\n */\nexport function call_result_to_output(result: unknown, tool_name?: string): unknown {\n const record = as_record(result) ?? {}\n\n if (record['isError'] === true) {\n const detail = join_text(record['content']) ?? 'MCP tool returned an error'\n throw new mcp_error(detail, tool_name !== undefined ? { tool_name } : {})\n }\n\n if (is_record(record['structuredContent'])) return record['structuredContent']\n\n const text = join_text(record['content'])\n if (text !== undefined) return text\n\n return record['content'] ?? null\n}\n\n/**\n * Converts a Fascicle flow's output into a `CallToolResult` for `serve_flow`.\n *\n * A `to_result` override takes precedence over the default mapping. By\n * default, objects are emitted as both a JSON text part (every MCP host can\n * read text) and `structuredContent` (typed hosts get the object); everything\n * else becomes a single text part.\n */\nexport function output_to_call_result<o>(\n output: o,\n to_result?: (output: o) => { text: string; structured?: Record<string, unknown> },\n): McpToolResult {\n if (to_result !== undefined) {\n const shaped = to_result(output)\n return build_result(shaped.text, shaped.structured)\n }\n if (typeof output === 'string') return build_result(output)\n if (is_record(output)) return build_result(stringify(output), output)\n if (Array.isArray(output)) return build_result(stringify(output))\n return build_result(String(output))\n}\n\n/**\n * Assembles a `CallToolResult` with one text part and, when given, structured\n * content.\n */\nfunction build_result(text: string, structured?: Record<string, unknown>): McpToolResult {\n return structured !== undefined\n ? { content: [{ type: 'text', text }], structuredContent: structured }\n : { content: [{ type: 'text', text }] }\n}\n\n/**\n * Joins the `text` parts of an MCP content array with newlines, skipping\n * non-text parts; `undefined` when there is nothing to join.\n */\nfunction join_text(content: unknown): string | undefined {\n if (!Array.isArray(content)) return undefined\n const parts: string[] = []\n for (const part of content) {\n if (is_record(part) && part['type'] === 'text' && typeof part['text'] === 'string') {\n parts.push(part['text'])\n }\n }\n return parts.length > 0 ? parts.join('\\n') : undefined\n}\n\n/**\n * `JSON.stringify` that falls back to `String` instead of throwing on\n * unserializable values (circular references, BigInt).\n */\nfunction stringify(value: unknown): string {\n try {\n return JSON.stringify(value)\n } catch {\n return String(value)\n }\n}\n","/**\n * Lazy loader for the optional `@modelcontextprotocol/sdk` peer.\n *\n * `mcp_client` needs SDK values (the Client and transport constructors), so it\n * imports them dynamically rather than statically: a consumer can import\n * `fascicle/mcp` without the SDK installed and only pays the cost when they\n * actually connect. A missing peer surfaces as a typed `mcp_sdk_missing_error`\n * with install guidance, mirroring the engine's `load_optional_peer`.\n *\n * `serve_flow` is not covered here: it operates on a caller-constructed\n * `McpServer`, so it needs only a type-only import and no runtime SDK load.\n */\n\nimport { mcp_sdk_missing_error } from './errors.js'\n\nexport type McpClientSdk = Awaited<ReturnType<typeof load_client_sdk>>\n\n/**\n * Dynamically imports the `@modelcontextprotocol/sdk` client modules,\n * throwing a typed `mcp_sdk_missing_error` when the optional peer is not\n * installed.\n */\nexport async function load_client_sdk() {\n try {\n const [client_mod, stdio_mod, http_mod] = await Promise.all([\n import('@modelcontextprotocol/sdk/client/index.js'),\n import('@modelcontextprotocol/sdk/client/stdio.js'),\n import('@modelcontextprotocol/sdk/client/streamableHttp.js'),\n ])\n return {\n Client: client_mod.Client,\n StdioClientTransport: stdio_mod.StdioClientTransport,\n StreamableHTTPClientTransport: http_mod.StreamableHTTPClientTransport,\n }\n } catch (err: unknown) {\n const detail = err instanceof Error ? err.message : String(err)\n throw new mcp_sdk_missing_error(\n `@modelcontextprotocol/sdk is required for fascicle/mcp; install it: pnpm add @modelcontextprotocol/sdk (cause: ${detail})`,\n )\n }\n}\n","/**\n * Inbound MCP: connect to an external MCP server and surface its tools as plain\n * Fascicle `Tool[]`.\n */\n\nimport type { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'\nimport type { Tool, ToolExecContext } from '#engine'\nimport { is_record, json_schema_to_standard } from '#schema'\nimport { mcp_error } from './errors.js'\nimport { call_result_to_output } from './result_mapping.js'\nimport { load_client_sdk, type McpClientSdk } from './sdk_loader.js'\n\nconst DEFAULT_CLIENT_INFO = { name: 'fascicle', version: '0.0.0' }\n\nexport type McpStdioConfig = {\n transport: 'stdio'\n command: string\n args?: string[]\n env?: Record<string, string>\n cwd?: string\n}\n\nexport type McpStreamableHttpConfig = {\n transport: 'http'\n url: string\n headers?: Record<string, string>\n}\n\n// Escape hatch: hand in an already-connected Client (a transport the adapter\n// does not build, a test harness, a shared connection). Its lifecycle stays\n// with the caller, so the returned `close` is a no-op for this variant.\nexport type McpExistingClientConfig = {\n transport: 'client'\n client: Client\n}\n\nexport type McpClientConfig =\n | McpStdioConfig\n | McpStreamableHttpConfig\n | McpExistingClientConfig\n\nexport type McpClientOptions = {\n // Identity sent in the MCP handshake; defaults to Fascicle.\n client_info?: { name: string; version: string }\n // When set, only tools whose name is listed are surfaced.\n include?: ReadonlyArray<string>\n // Supplies a description for tools that advertise none.\n default_description?: (tool_name: string) => string\n // Prepended, as written, to each surfaced tool's name, so two servers'\n // tools can share a call without colliding. The server is still called by\n // its own name, and `include` and `default_description` see that name too.\n name_prefix?: string\n}\n\nexport type McpClientHandle = {\n readonly tools: ReadonlyArray<Tool>\n readonly close: () => Promise<void>\n}\n\n/**\n * Connects to an MCP server and surfaces its advertised tools as Fascicle\n * `Tool[]`, plus a `close` handle for the connection.\n *\n * Owns the connection lifecycle (config in, `{ tools, close }` out) so callers\n * do not have to import SDK transport classes themselves. Each advertised MCP\n * tool becomes an ordinary `Tool`: its JSON Schema is wrapped as a `ToolSchema`\n * the loop validates against and the provider receives back unchanged, and\n * `execute` forwards to `callTool`, propagating the run's abort signal. For the\n * `client` transport variant the caller keeps ownership of the connection, so\n * `close` is a no-op. A connection this call opened is closed again when\n * listing its tools fails.\n */\nexport async function mcp_client(\n config: McpClientConfig,\n options: McpClientOptions = {},\n): Promise<McpClientHandle> {\n const owns_client = config.transport !== 'client'\n const client = await connect_client(config, options)\n\n const include = options.include !== undefined ? new Set(options.include) : undefined\n const listed = await client.listTools().catch(async (err: unknown) => {\n // A client this call connected has no other owner yet, so it closes here,\n // taking a spawned stdio server with it. The listing failure is the one\n // the caller sees, even if the close fails too.\n if (owns_client) await client.close().catch(() => undefined)\n throw err\n })\n const tools: Tool[] = []\n for (const advertised of listed.tools) {\n if (include !== undefined && !include.has(advertised.name)) continue\n tools.push(to_fascicle_tool(client, advertised, options))\n }\n\n return {\n tools,\n close: async () => {\n if (owns_client) await client.close()\n },\n }\n}\n\n/**\n * Returns the caller's already-connected client as-is, or lazily loads the\n * SDK and connects a fresh client over the configured transport.\n */\nasync function connect_client(\n config: McpClientConfig,\n options: McpClientOptions,\n): Promise<Client> {\n if (config.transport === 'client') return config.client\n const sdk = await load_client_sdk()\n const client = new sdk.Client(options.client_info ?? DEFAULT_CLIENT_INFO)\n await client.connect(build_transport(sdk, config))\n return client\n}\n\n/**\n * Constructs the SDK transport matching the config: a spawned child process\n * for `stdio`, a Streamable HTTP connection for `http`.\n */\nfunction build_transport(\n sdk: McpClientSdk,\n config: McpStdioConfig | McpStreamableHttpConfig,\n): Transport {\n if (config.transport === 'stdio') {\n return new sdk.StdioClientTransport({\n command: config.command,\n ...(config.args !== undefined ? { args: config.args } : {}),\n ...(config.env !== undefined ? { env: config.env } : {}),\n ...(config.cwd !== undefined ? { cwd: config.cwd } : {}),\n })\n }\n const opts = config.headers !== undefined ? { requestInit: { headers: config.headers } } : {}\n // The SDK declares this class `implements Transport`, but its `onmessage`\n // overload is narrower than the interface's, which only strict mode flags.\n // eslint-disable-next-line typescript-eslint/no-unsafe-type-assertion\n return new sdk.StreamableHTTPClientTransport(new URL(config.url), opts) as Transport\n}\n\n/**\n * Wraps one advertised MCP tool as a Fascicle `Tool` whose `execute` forwards\n * to `callTool` on the shared client. Only the `Tool`'s name carries\n * `name_prefix`; the call, the fallback description, and the errors use the\n * server's own name.\n *\n * An already-aborted signal short-circuits before the wire call; otherwise the\n * signal is passed through so cancelling the run cancels the remote call.\n */\nfunction to_fascicle_tool(\n client: Client,\n advertised: { name: string; description?: string | undefined; inputSchema: unknown },\n options: McpClientOptions,\n): Tool {\n const name = advertised.name\n const description =\n advertised.description ?? options.default_description?.(name) ?? `MCP tool ${name}`\n return {\n name: `${options.name_prefix ?? ''}${name}`,\n description,\n input_schema: json_schema_to_standard(advertised.inputSchema),\n execute: async (input: unknown, ctx: ToolExecContext) => {\n if (ctx.abort.aborted) {\n throw ctx.abort.reason instanceof Error\n ? ctx.abort.reason\n : new mcp_error(`MCP tool ${name} aborted before invocation`, { tool_name: name })\n }\n const result = await client.callTool(\n { name, arguments: is_record(input) ? input : undefined },\n undefined,\n { signal: ctx.abort },\n )\n return call_result_to_output(result, name)\n },\n }\n}\n","/**\n * Outbound MCP: expose a composed Fascicle flow as an MCP tool.\n *\n * `serve_flow` registers onto a caller-constructed `McpServer` (the caller owns\n * the transport, identity, and lifecycle, and can host many flows on one\n * server), so it needs only a type-only SDK import. The registered handler\n * drives the existing `run`, threading the per-request abort signal so an MCP\n * client cancellation aborts the in-flight flow, and maps the result into a\n * `CallToolResult`. A thrown flow becomes an `isError` result rather than a\n * JSON-RPC protocol error.\n */\n\nimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport type { z } from 'zod'\nimport { run } from '#core'\nimport type { Step, TrajectoryLogger } from '#core'\nimport { output_to_call_result } from './result_mapping.js'\n\nexport type ServeFlowConfig<i, o> = {\n server: McpServer\n flow: Step<i, o>\n name: string\n description: string\n /**\n * Stays zod rather than joining the rest of the surface on `ToolSchema`.\n * `McpServer.registerTool` types `inputSchema` as a zod schema and offers no\n * JSON Schema entry point, and the SDK carries zod as a hard runtime\n * dependency, so a `serve_flow` caller already has zod resolved. Widening\n * this to a neutral schema would typecheck and then fail inside the SDK.\n */\n input_schema: z.ZodType<i>\n trajectory?: TrajectoryLogger\n // Overrides the default value-to-CallToolResult mapping.\n to_result?: (output: o) => { text: string; structured?: Record<string, unknown> }\n}\n\n/**\n * Registers a Fascicle flow as a tool on a caller-owned MCP server.\n *\n * Drives the flow with `run`, threading the per-request abort signal so an\n * MCP client cancellation aborts the in-flight flow, and maps the result\n * into a `CallToolResult`. A thrown flow becomes an `isError` result rather\n * than a JSON-RPC protocol error.\n */\nexport function serve_flow<i, o>(config: ServeFlowConfig<i, o>): void {\n const { server, flow, name, description, input_schema, trajectory, to_result } = config\n server.registerTool(\n name,\n { description, inputSchema: input_schema },\n async (input: i, extra) => {\n try {\n const output = await run(flow, input, {\n install_signal_handlers: false,\n abort: extra.signal,\n ...(trajectory !== undefined ? { trajectory } : {}),\n })\n return output_to_call_result(output, to_result)\n } catch (err: unknown) {\n return {\n isError: true,\n content: [{ type: 'text', text: err instanceof Error ? err.message : String(err) }],\n }\n }\n },\n )\n}\n"],"mappings":";;;;;;;;;;;AAQA,IAAa,wBAAb,cAA2C,MAAM;CAC/C,OAAgB;CAChB,YACE,UAAU,0GACV;EACA,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;AAEA,IAAa,YAAb,cAA+B,MAAM;CACnC,OAAgB;CAChB;CACA,YAAY,SAAiB,WAAmC,CAAC,GAAG;EAClE,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,YAAY,SAAS;CAC5B;AACF;;;;;;;;;;;;;;;;;ACHA,SAAgB,sBAAsB,QAAiB,WAA6B;CAClF,MAAM,SAAS,UAAU,MAAM,KAAK,CAAC;CAErC,IAAI,OAAO,eAAe,MAExB,MAAM,IAAI,UADK,UAAU,OAAO,UAAU,KAAK,8BACnB,cAAc,KAAA,IAAY,EAAE,UAAU,IAAI,CAAC,CAAC;CAG1E,IAAI,UAAU,OAAO,oBAAoB,GAAG,OAAO,OAAO;CAE1D,MAAM,OAAO,UAAU,OAAO,UAAU;CACxC,IAAI,SAAS,KAAA,GAAW,OAAO;CAE/B,OAAO,OAAO,cAAc;AAC9B;;;;;;;;;AAUA,SAAgB,sBACd,QACA,WACe;CACf,IAAI,cAAc,KAAA,GAAW;EAC3B,MAAM,SAAS,UAAU,MAAM;EAC/B,OAAO,aAAa,OAAO,MAAM,OAAO,UAAU;CACpD;CACA,IAAI,OAAO,WAAW,UAAU,OAAO,aAAa,MAAM;CAC1D,IAAI,UAAU,MAAM,GAAG,OAAO,aAAa,UAAU,MAAM,GAAG,MAAM;CACpE,IAAI,MAAM,QAAQ,MAAM,GAAG,OAAO,aAAa,UAAU,MAAM,CAAC;CAChE,OAAO,aAAa,OAAO,MAAM,CAAC;AACpC;;;;;AAMA,SAAS,aAAa,MAAc,YAAqD;CACvF,OAAO,eAAe,KAAA,IAClB;EAAE,SAAS,CAAC;GAAE,MAAM;GAAQ;EAAK,CAAC;EAAG,mBAAmB;CAAW,IACnE,EAAE,SAAS,CAAC;EAAE,MAAM;EAAQ;CAAK,CAAC,EAAE;AAC1C;;;;;AAMA,SAAS,UAAU,SAAsC;CACvD,IAAI,CAAC,MAAM,QAAQ,OAAO,GAAG,OAAO,KAAA;CACpC,MAAM,QAAkB,CAAC;CACzB,KAAK,MAAM,QAAQ,SACjB,IAAI,UAAU,IAAI,KAAK,KAAK,YAAY,UAAU,OAAO,KAAK,YAAY,UACxE,MAAM,KAAK,KAAK,OAAO;CAG3B,OAAO,MAAM,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,KAAA;AAC/C;;;;;AAMA,SAAS,UAAU,OAAwB;CACzC,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF;;;;;;;;;;;;;;;;;;;;AC1EA,eAAsB,kBAAkB;CACtC,IAAI;EACF,MAAM,CAAC,YAAY,WAAW,YAAY,MAAM,QAAQ,IAAI;GAC1D,OAAO;GACP,OAAO;GACP,OAAO;EACT,CAAC;EACD,OAAO;GACL,QAAQ,WAAW;GACnB,sBAAsB,UAAU;GAChC,+BAA+B,SAAS;EAC1C;CACF,SAAS,KAAc;EAErB,MAAM,IAAI,sBACR,kHAFa,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EAE6D,EAC3H;CACF;AACF;;;AC3BA,MAAM,sBAAsB;CAAE,MAAM;CAAY,SAAS;AAAQ;;;;;;;;;;;;;;AA4DjE,eAAsB,WACpB,QACA,UAA4B,CAAC,GACH;CAC1B,MAAM,cAAc,OAAO,cAAc;CACzC,MAAM,SAAS,MAAM,eAAe,QAAQ,OAAO;CAEnD,MAAM,UAAU,QAAQ,YAAY,KAAA,IAAY,IAAI,IAAI,QAAQ,OAAO,IAAI,KAAA;CAC3E,MAAM,SAAS,MAAM,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,QAAiB;EAIpE,IAAI,aAAa,MAAM,OAAO,MAAM,CAAC,CAAC,YAAY,KAAA,CAAS;EAC3D,MAAM;CACR,CAAC;CACD,MAAM,QAAgB,CAAC;CACvB,KAAK,MAAM,cAAc,OAAO,OAAO;EACrC,IAAI,YAAY,KAAA,KAAa,CAAC,QAAQ,IAAI,WAAW,IAAI,GAAG;EAC5D,MAAM,KAAK,iBAAiB,QAAQ,YAAY,OAAO,CAAC;CAC1D;CAEA,OAAO;EACL;EACA,OAAO,YAAY;GACjB,IAAI,aAAa,MAAM,OAAO,MAAM;EACtC;CACF;AACF;;;;;AAMA,eAAe,eACb,QACA,SACiB;CACjB,IAAI,OAAO,cAAc,UAAU,OAAO,OAAO;CACjD,MAAM,MAAM,MAAM,gBAAgB;CAClC,MAAM,SAAS,IAAI,IAAI,OAAO,QAAQ,eAAe,mBAAmB;CACxE,MAAM,OAAO,QAAQ,gBAAgB,KAAK,MAAM,CAAC;CACjD,OAAO;AACT;;;;;AAMA,SAAS,gBACP,KACA,QACW;CACX,IAAI,OAAO,cAAc,SACvB,OAAO,IAAI,IAAI,qBAAqB;EAClC,SAAS,OAAO;EAChB,GAAI,OAAO,SAAS,KAAA,IAAY,EAAE,MAAM,OAAO,KAAK,IAAI,CAAC;EACzD,GAAI,OAAO,QAAQ,KAAA,IAAY,EAAE,KAAK,OAAO,IAAI,IAAI,CAAC;EACtD,GAAI,OAAO,QAAQ,KAAA,IAAY,EAAE,KAAK,OAAO,IAAI,IAAI,CAAC;CACxD,CAAC;CAEH,MAAM,OAAO,OAAO,YAAY,KAAA,IAAY,EAAE,aAAa,EAAE,SAAS,OAAO,QAAQ,EAAE,IAAI,CAAC;CAI5F,OAAO,IAAI,IAAI,8BAA8B,IAAI,IAAI,OAAO,GAAG,GAAG,IAAI;AACxE;;;;;;;;;;AAWA,SAAS,iBACP,QACA,YACA,SACM;CACN,MAAM,OAAO,WAAW;CACxB,MAAM,cACJ,WAAW,eAAe,QAAQ,sBAAsB,IAAI,KAAK,YAAY;CAC/E,OAAO;EACL,MAAM,GAAG,QAAQ,eAAe,KAAK;EACrC;EACA,cAAc,wBAAwB,WAAW,WAAW;EAC5D,SAAS,OAAO,OAAgB,QAAyB;GACvD,IAAI,IAAI,MAAM,SACZ,MAAM,IAAI,MAAM,kBAAkB,QAC9B,IAAI,MAAM,SACV,IAAI,UAAU,YAAY,KAAK,6BAA6B,EAAE,WAAW,KAAK,CAAC;GAOrF,OAAO,sBAAsB,MALR,OAAO,SAC1B;IAAE;IAAM,WAAW,UAAU,KAAK,IAAI,QAAQ,KAAA;GAAU,GACxD,KAAA,GACA,EAAE,QAAQ,IAAI,MAAM,CACtB,GACqC,IAAI;EAC3C;CACF;AACF;;;;;;;;;;;ACnIA,SAAgB,WAAiB,QAAqC;CACpE,MAAM,EAAE,QAAQ,MAAM,MAAM,aAAa,cAAc,YAAY,cAAc;CACjF,OAAO,aACL,MACA;EAAE;EAAa,aAAa;CAAa,GACzC,OAAO,OAAU,UAAU;EACzB,IAAI;GAMF,OAAO,sBAAsB,MALR,IAAI,MAAM,OAAO;IACpC,yBAAyB;IACzB,OAAO,MAAM;IACb,GAAI,eAAe,KAAA,IAAY,EAAE,WAAW,IAAI,CAAC;GACnD,CAAC,GACoC,SAAS;EAChD,SAAS,KAAc;GACrB,OAAO;IACL,SAAS;IACT,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;IAAE,CAAC;GACpF;EACF;CACF,CACF;AACF"}
package/dist/otel.js CHANGED
@@ -8,12 +8,15 @@ import { SpanStatusCode, context, metrics, trace } from "@opentelemetry/api";
8
8
  * hour"), which want real OTel metric instruments rather than a
9
9
  * spans-to-metrics pipeline. This recorder listens to the same trajectory
10
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).
11
+ * client histograms, plus three Fascicle-named instruments for the data the
12
+ * conventions do not cover yet (cost, absorbed retries, cache traffic).
13
13
  *
14
14
  * Instruments and sources:
15
15
  * - `gen_ai.client.token.usage` ({token}) from `response_received`, one
16
16
  * point per direction via `gen_ai.token.type`.
17
+ * - `fascicle.client.cache.token.usage` ({token}) from `response_received`'s
18
+ * `cached_input_tokens` and `cache_write_tokens`, one point per direction
19
+ * above zero via `fascicle.cache.direction` (`read` or `write`).
17
20
  * - `gen_ai.client.operation.duration` (s) from `response_received`
18
21
  * `duration_ms`, the model-only round trip.
19
22
  * - `gen_ai.client.operation.time_to_first_chunk` (s) from
@@ -104,6 +107,11 @@ function create_metrics_recorder(options) {
104
107
  description: "Tool execution duration",
105
108
  advice: { explicitBucketBoundaries: DURATION_BOUNDARIES }
106
109
  });
110
+ const cache_token_usage = meter.createHistogram("fascicle.client.cache.token.usage", {
111
+ unit: "{token}",
112
+ description: "Number of input tokens read from or written to the prompt cache per model turn",
113
+ advice: { explicitBucketBoundaries: TOKEN_BOUNDARIES }
114
+ });
107
115
  const cost = meter.createHistogram("fascicle.client.operation.cost", {
108
116
  unit: "usd",
109
117
  description: "Estimated cost per model turn"
@@ -120,8 +128,21 @@ function create_metrics_recorder(options) {
120
128
  if (top?.model !== void 0) attrs["gen_ai.request.model"] = top.model;
121
129
  return attrs;
122
130
  };
131
+ const record_cache_tokens = (event, base) => {
132
+ const reads = event_number(event, "cached_input_tokens") ?? 0;
133
+ if (reads > 0) cache_token_usage.record(reads, {
134
+ ...base,
135
+ "fascicle.cache.direction": "read"
136
+ });
137
+ const writes = event_number(event, "cache_write_tokens") ?? 0;
138
+ if (writes > 0) cache_token_usage.record(writes, {
139
+ ...base,
140
+ "fascicle.cache.direction": "write"
141
+ });
142
+ };
123
143
  const on_response_received = (event) => {
124
144
  const base = base_attributes();
145
+ record_cache_tokens(event, base);
125
146
  const input = event_number(event, "input_tokens");
126
147
  if (input !== void 0) token_usage.record(input, {
127
148
  ...base,
@@ -293,6 +314,30 @@ function to_attributes(meta, prefix, flatten = false) {
293
314
  return attrs;
294
315
  }
295
316
  /**
317
+ * The engine events that carry a captured payload, and the field that holds
318
+ * it: a turn's request, the reply's parts, and the body that went on the
319
+ * wire. A `ctx.emit` event carries its own keys and isn't one of them.
320
+ */
321
+ const CAPTURED_FIELDS = /* @__PURE__ */ new Map([
322
+ ["request_sent", "request"],
323
+ ["response_received", "content"],
324
+ ["request_wire", "body"]
325
+ ]);
326
+ /**
327
+ * A recorded event's attributes. A captured payload, which grows with the
328
+ * conversation, is left out and recorded as `<prefix>capture.bytes`, the
329
+ * UTF-8 length of its JSON, since an attribute has to stay small.
330
+ */
331
+ function event_attributes(event, prefix) {
332
+ const field = CAPTURED_FIELDS.get(event.kind);
333
+ if (field === void 0 || !(field in event)) return to_attributes(event, prefix);
334
+ const { [field]: payload, ...rest } = event;
335
+ return {
336
+ ...to_attributes(rest, prefix),
337
+ [`${prefix}capture.bytes`]: Buffer.byteLength(safe_json(payload))
338
+ };
339
+ }
340
+ /**
296
341
  * Create a `TrajectoryLogger` that mirrors spans and events onto
297
342
  * OpenTelemetry, using `options.tracer` (or the global `fascicle` tracer).
298
343
  *
@@ -362,7 +407,7 @@ function create_otel_trajectory_logger(options = {}) {
362
407
  const span = target_for_event(event);
363
408
  if (span === void 0) return;
364
409
  const name = typeof event.kind === "string" ? event.kind : "event";
365
- span.addEvent(name, to_attributes(event, prefix));
410
+ span.addEvent(name, event_attributes(event, prefix));
366
411
  }
367
412
  };
368
413
  }
package/dist/otel.js.map CHANGED
@@ -1 +1 @@
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 GenAI semantic conventions are\n * experimental, so a revision of them may rename an instrument this module\n * records.\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 // Open engine.generate calls in the order they started, each with the\n // identity its metric attributes carry; the last one is the innermost.\n const context_stack: Array<{ readonly id: string; readonly provider?: string; readonly 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 const provider = meta?.['provider']\n const model = meta?.['model_id']\n context_stack.push({\n id,\n ...(typeof provider === 'string' ? { provider } : {}),\n ...(typeof model === 'string' ? { model } : {}),\n })\n },\n on_end_span(id) {\n // Removed by id, since interleaved generates need not end in the\n // reverse of the order they started.\n const idx = context_stack.findIndex((entry) => entry.id === id)\n if (idx !== -1) context_stack.splice(idx, 1)\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: engine code outside\n * `providers/` imports no npm package (rules/no-engine-npm-dep.yml), and an\n * app that never imports `fascicle/otel` pulls in zero OTel packages at\n * 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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"}
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 three Fascicle-named instruments for the data the\n * conventions do not cover yet (cost, absorbed retries, cache traffic).\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 * - `fascicle.client.cache.token.usage` ({token}) from `response_received`'s\n * `cached_input_tokens` and `cache_write_tokens`, one point per direction\n * above zero via `fascicle.cache.direction` (`read` or `write`).\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 GenAI semantic conventions are\n * experimental, so a revision of them may rename an instrument this module\n * records.\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 cache_token_usage: Histogram = meter.createHistogram('fascicle.client.cache.token.usage', {\n unit: '{token}',\n description: 'Number of input tokens read from or written to the prompt cache per model turn',\n advice: { explicitBucketBoundaries: TOKEN_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 // Open engine.generate calls in the order they started, each with the\n // identity its metric attributes carry; the last one is the innermost.\n const context_stack: Array<{ readonly id: string; readonly provider?: string; readonly 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 // A provider that caches reports zero counts on a turn that didn't, so a\n // direction records a point only above zero.\n const record_cache_tokens = (event: TrajectoryEvent, base: Attributes): void => {\n const reads = event_number(event, 'cached_input_tokens') ?? 0\n if (reads > 0) cache_token_usage.record(reads, { ...base, 'fascicle.cache.direction': 'read' })\n const writes = event_number(event, 'cache_write_tokens') ?? 0\n if (writes > 0) cache_token_usage.record(writes, { ...base, 'fascicle.cache.direction': 'write' })\n }\n\n const on_response_received = (event: TrajectoryEvent): void => {\n const base = base_attributes()\n record_cache_tokens(event, base)\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 const provider = meta?.['provider']\n const model = meta?.['model_id']\n context_stack.push({\n id,\n ...(typeof provider === 'string' ? { provider } : {}),\n ...(typeof model === 'string' ? { model } : {}),\n })\n },\n on_end_span(id) {\n // Removed by id, since interleaved generates need not end in the\n // reverse of the order they started.\n const idx = context_stack.findIndex((entry) => entry.id === id)\n if (idx !== -1) context_stack.splice(idx, 1)\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: engine code outside\n * `providers/` imports no npm package (rules/no-engine-npm-dep.yml), and an\n * app that never imports `fascicle/otel` pulls in zero OTel packages at\n * 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\n/**\n * The engine events that carry a captured payload, and the field that holds\n * it: a turn's request, the reply's parts, and the body that went on the\n * wire. A `ctx.emit` event carries its own keys and isn't one of them.\n */\nconst CAPTURED_FIELDS: ReadonlyMap<string, string> = new Map([\n ['request_sent', 'request'],\n ['response_received', 'content'],\n ['request_wire', 'body'],\n])\n\n/**\n * A recorded event's attributes. A captured payload, which grows with the\n * conversation, is left out and recorded as `<prefix>capture.bytes`, the\n * UTF-8 length of its JSON, since an attribute has to stay small.\n */\nfunction event_attributes(event: TrajectoryEvent, prefix: string): Attributes {\n const field = CAPTURED_FIELDS.get(event.kind)\n // Stryker disable next-line ConditionalExpression: with the first test gone, `undefined in event` looks for a key named \"undefined\", which no event of another kind carries, so it returns here all the same.\n if (field === undefined || !(field in event)) return to_attributes(event, prefix)\n const { [field]: payload, ...rest } = event\n return {\n ...to_attributes(rest, prefix),\n [`${prefix}capture.bytes`]: Buffer.byteLength(safe_json(payload)),\n }\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, event_attributes(event, prefix))\n },\n }\n}\n"],"mappings":"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"}
@@ -286,6 +286,7 @@ function read_file_tool(session, read_limit_lines) {
286
286
  required: ["path"],
287
287
  additionalProperties: false
288
288
  }),
289
+ read_only: true,
289
290
  execute: async (input) => {
290
291
  const request = read_request(input, read_limit_lines);
291
292
  const { real } = await contain(session, request.path);
@@ -386,6 +387,7 @@ function list_files_tool(session, ignore, limit) {
386
387
  },
387
388
  additionalProperties: false
388
389
  }),
390
+ read_only: true,
389
391
  execute: async (input, ctx) => {
390
392
  const request = list_request(input);
391
393
  const files = await matching_files(session, request, ignored, ctx.abort);
@@ -603,6 +605,7 @@ function search_tool(session, ignore, budget_ms) {
603
605
  required: ["pattern"],
604
606
  additionalProperties: false
605
607
  }),
608
+ read_only: true,
606
609
  execute: async (input, ctx) => {
607
610
  const request = search_request(input);
608
611
  const base = await contain(session, request.path);
@@ -623,4 +626,4 @@ function search_tool(session, ignore, budget_ms) {
623
626
  //#endregion
624
627
  export { read_file_tool as a, resolve_roots as c, is_binary as i, shown_path as l, search_tool as n, contain_writable as o, list_files_tool as r, error_code as s, search_files as t };
625
628
 
626
- //# sourceMappingURL=search-CpCJYMUm.js.map
629
+ //# sourceMappingURL=search-DjhdMsJ8.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"search-DjhdMsJ8.js","names":["LINE_WIDTH","ALL_FILES"],"sources":["../src/acp/tools/containment.ts","../src/acp/tools/read_file.ts","../src/acp/tools/list_files.ts","../src/acp/tools/search.ts"],"sourcesContent":["/**\n * Containment: the boundary the workspace file tools keep. A path, absolute\n * or relative to the session's `cwd`, is allowed only when its real path\n * lands under one of the session's roots, which are real paths themselves,\n * resolved once at `session/new`.\n *\n * Real paths on both sides are the point. A symlink inside the workspace\n * that points out of it is the classic escape, and checking the path as\n * written would let it through. A `cwd` behind a symlink (macOS's `/tmp` and\n * `/var` both are) would refuse every file in the project if the roots\n * stayed as the client sent them. A path that doesn't exist yet resolves\n * through its nearest existing ancestor, and a dangling symlink through its\n * target, so a path outside the roots is refused the same way whether or\n * not it exists.\n *\n * The writes keep a stricter boundary inside the roots: nothing under a\n * `.git` or a `node_modules`. Git runs what its directory holds (a hook,\n * `core.fsmonitor`), a package manager runs what `node_modules` holds\n * (`.bin`, an install script), and a change in either never shows in\n * `git diff`, so an edit there would be code that runs unseen. No mode lifts\n * it, since Accept edits and Auto write without asking.\n */\n\nimport { readlink, realpath, stat } from 'node:fs/promises'\nimport { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'\nimport type { AcpSession } from '../types.js'\n\n/** A path a tool may touch, both as the client names it and as the file system resolves it. */\nexport type ContainedPath = {\n /** Absolute, under the `cwd` the client sent: what the client and the model are shown. */\n readonly path: string\n /** Symlinks resolved: what the tool opens. */\n readonly real: string\n}\n\n/** The error codes that mean a path, or a directory on the way to it, doesn't exist. */\nconst MISSING: ReadonlySet<unknown> = new Set(['ENOENT', 'ENOTDIR'])\n\n/**\n * How many symlinks a missing path may pass through before resolving it\n * gives up. `path.resolve` folds `missing/..` away where the kernel would\n * fail on it, so a link such as `a -> missing/../a` would otherwise loop.\n */\nconst MAX_LINK_HOPS = 40\n\n/**\n * The names a write never reaches through, wherever under a root they sit:\n * a nested repository's `.git` counts, and so does a worktree's, which is a\n * file pointing git at its real directory.\n */\nconst GUARDED_NAMES: ReadonlySet<string> = new Set(['.git', 'node_modules'])\n\n/**\n * The code a Node file system error carries, such as `ENOENT`. Every\n * caller hands in an error from `node:fs`, which always has one.\n */\nexport function error_code(err: unknown): unknown {\n return Reflect.get(Object(err), 'code')\n}\n\n/**\n * Resolve one root the client sent to its real path, refusing a relative\n * path (which would resolve against wherever the agent was launched), a path\n * that doesn't exist, and a file.\n */\nasync function resolve_root(root: string): Promise<string> {\n if (!isAbsolute(root)) {\n throw new Error(`the workspace root ${root} is a relative path; send session/new with absolute paths`)\n }\n const real = await realpath(root).catch((err: unknown) => {\n throw new Error(\n `the workspace root ${root} can't be opened (${String(error_code(err))}); send session/new with a directory that exists`,\n )\n })\n if (!(await stat(real)).isDirectory()) {\n throw new Error(`the workspace root ${root} is a file; send session/new with a directory`)\n }\n return real\n}\n\n/**\n * Resolve a session's roots (its `cwd`, then each additional directory) to\n * their real paths, once, when the session starts. The error names the\n * first root that isn't an absolute path to an existing directory.\n */\nexport async function resolve_roots(roots: ReadonlyArray<string>): Promise<string[]> {\n return Promise.all(roots.map(resolve_root))\n}\n\n/**\n * Whether `target` is `root` or lies beneath it. Both are compared as they\n * are, so the caller hands in real paths for a containment check.\n */\nfunction is_within(root: string, target: string): boolean {\n return target === root || target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`)\n}\n\n/**\n * A symlink's target as written, or `undefined` when the path isn't a\n * symlink or isn't there.\n */\nasync function link_target(path: string): Promise<string | undefined> {\n return readlink(path).catch(() => undefined)\n}\n\n/**\n * The real path of `path`, existing or not. A path that exists is the file\n * system's own answer. A missing one is its parent's real path plus its\n * name, unless it's a dangling symlink, whose real path is its target's:\n * writing through it would land there.\n */\nasync function real_path(path: string, hops_left: number): Promise<string> {\n try {\n return await realpath(path)\n } catch (err: unknown) {\n if (!MISSING.has(error_code(err))) throw err\n }\n const parent = await real_path(dirname(path), hops_left)\n const target = await link_target(path)\n if (target === undefined) return join(parent, basename(path))\n if (hops_left === 0) throw new Error(`${path} passes through too many symbolic links to resolve`)\n return real_path(resolve(parent, target), hops_left - 1)\n}\n\n/**\n * Check that a path a tool was handed lands inside the session's workspace,\n * and return it both ways. The refusal is an ordinary error naming the roots\n * in the client's terms, since the model reads it as a tool result and can\n * try a path that fits.\n */\nexport async function contain(session: AcpSession, requested: string): Promise<ContainedPath> {\n const path = resolve(session.cwd, requested)\n const real = await real_path(path, MAX_LINK_HOPS)\n if (session.roots.some((root) => is_within(root, real))) return { path, real }\n const allowed = [session.cwd, ...session.additional_directories].join(', ')\n throw new Error(`${requested} is outside the workspace; the file tools only reach paths under ${allowed}`)\n}\n\n/**\n * A path segment as a file system that ignores case, or Windows, which also\n * drops trailing dots and spaces, compares it, so `.GIT` and `.git.` name\n * the same directory as `.git` wherever they do.\n */\nfunction folded(segment: string): string {\n return segment.toLowerCase().replace(/[. ]+$/u, '')\n}\n\n/**\n * The first of GUARDED_NAMES on the way down to `path` from any root it lies\n * under, or `undefined` when there is none.\n */\nfunction guarded_segment(roots: ReadonlyArray<string>, path: string): string | undefined {\n for (const root of roots) {\n if (!is_within(root, path)) continue\n const found = relative(root, path).split(sep).map(folded).find((name) => GUARDED_NAMES.has(name))\n if (found !== undefined) return found\n }\n return undefined\n}\n\n/**\n * Check a path a write was handed the way `contain` does, then refuse one\n * that reaches `.git` or `node_modules` under a root. The path is checked as\n * written, against the roots in the client's terms, and as its symlinks\n * resolve, against the real ones, so a `.git` that is a symlink and a\n * symlink into `.git` are both refused. `tool` names the tool asking, for\n * the refusal, which points the model at `run_command`, the tool that asks\n * before it acts in Manual and in Accept edits.\n */\nexport async function contain_writable(session: AcpSession, requested: string, tool: string): Promise<ContainedPath> {\n const target = await contain(session, requested)\n const roots = [...session.roots, ...[session.cwd, ...session.additional_directories].map((dir) => resolve(dir))]\n const segment = guarded_segment(roots, target.path) ?? guarded_segment(roots, target.real)\n if (segment === undefined) return target\n throw new Error(\n `${requested} reaches ${segment}, where ${tool} never writes, since what's there can run on the user's next command without showing in git diff; if it has to change, use run_command`,\n )\n}\n\n/**\n * A path as a tool shows it to the model: relative to `cwd` when it's under\n * it, and absolute otherwise, as for a file in an additional directory.\n * Either form reads back through `contain`.\n */\nexport function shown_path(session: AcpSession, path: string): string {\n return is_within(session.cwd, path) ? relative(session.cwd, path) || '.' : path\n}\n","/**\n * read_file: read a text file in the workspace with its lines numbered, a\n * window at a time.\n *\n * A window stops at `read_limit_lines` and says where the next one starts,\n * and a line past LINE_WIDTH characters is cut with a marker, because a\n * minified bundle or a source map can be one line of megabytes and nothing\n * else keeps it out of the model's context. A file with a NUL byte in its\n * first 8 KB is refused as binary. The file streams line by line, so a\n * window near the top of a huge file reads only as far as it shows.\n */\n\nimport { open, stat } from 'node:fs/promises'\nimport type { FileHandle } from 'node:fs/promises'\nimport type { Tool } from '#engine'\nimport { as_record, json_schema_to_standard } from '#schema'\nimport type { AcpSession } from '../types.js'\nimport { contain, error_code } from './containment.js'\n\n/** The longest line `read_file` returns whole, the width Claude Code's Read cuts at. */\nconst LINE_WIDTH = 2000\n\n/** How much of a file's head is checked for a NUL byte, the sign of a binary file. */\nconst BINARY_SNIFF_BYTES = 8192\n\n/** One read: the path as the model gave it, and the lines it covers. */\ntype ReadRequest = {\n readonly path: string\n readonly offset: number\n readonly limit: number\n}\n\n/**\n * Whether a value counts lines: a whole number of at least 1.\n */\nfunction is_count(value: unknown): value is number {\n return Number.isInteger(value) && Number(value) >= 1\n}\n\n/**\n * Read the call's window out of its input, with `limit` held to the cap.\n * The tool loop has already checked the types against the schema, but a\n * flow that wraps the tool can call `execute` directly, and the schema's\n * `minimum` is advice to the model rather than something the loop enforces.\n */\nfunction read_request(input: unknown, read_limit_lines: number): ReadRequest {\n const fields: Record<string, unknown> = as_record(input) ?? {}\n const { path, offset = 1, limit = read_limit_lines } = fields\n if (typeof path !== 'string') throw new Error('read_file needs a path, as a string')\n if (!is_count(offset) || !is_count(limit)) {\n throw new Error('read_file counts offset and limit in lines from 1, so each has to be a whole number of at least 1')\n }\n return { path, offset, limit: Math.min(limit, read_limit_lines) }\n}\n\n/**\n * Whether the file's first BINARY_SNIFF_BYTES hold a NUL byte. `search`\n * skips a file this calls binary, so the two tools agree on what is text.\n */\nexport async function is_binary(handle: FileHandle): Promise<boolean> {\n const head = Buffer.alloc(BINARY_SNIFF_BYTES)\n const { bytesRead } = await handle.read(head, 0, BINARY_SNIFF_BYTES, 0)\n return head.subarray(0, bytesRead).includes(0)\n}\n\n/**\n * One line as the model sees it: its number, a tab, and its text, cut at\n * LINE_WIDTH with a marker that says how long it was.\n */\nfunction numbered(line_number: number, line: string): string {\n const text =\n line.length > LINE_WIDTH ? `${line.slice(0, LINE_WIDTH)} [line cut at ${LINE_WIDTH} of ${line.length} characters]` : line\n return `${String(line_number).padStart(6)}\\t${text}`\n}\n\n/**\n * Number the window's lines, reading one line past it to learn whether the\n * file goes on, and say where to start the next read when it does.\n */\nasync function read_lines(handle: FileHandle, request: ReadRequest): Promise<string> {\n const last = request.offset + request.limit - 1\n const shown: string[] = []\n let count = 0\n let more = false\n // The binary check reads at an explicit position, which leaves the\n // handle's own position at the top, where these lines start.\n for await (const line of handle.readLines()) {\n count += 1\n if (count > last) {\n more = true\n break\n }\n if (count >= request.offset) shown.push(numbered(count, line))\n }\n if (count === 0) return `${request.path} is empty`\n if (shown.length === 0) {\n throw new Error(`offset ${request.offset} is past the end of ${request.path}, which has ${count} lines`)\n }\n const body = shown.join('\\n')\n if (!more) return body\n return `${body}\\n\\n[lines ${request.offset} to ${last} shown; the file goes on, so read on with offset ${last + 1}]`\n}\n\n/**\n * Read a contained file's window, refusing what isn't a regular text file.\n * The type is checked before the file opens, since opening a FIFO would\n * wait for a writer that never comes.\n */\nasync function read_contained(real: string, request: ReadRequest): Promise<string> {\n const info = await stat(real).catch((err: unknown) => {\n throw error_code(err) === 'ENOENT' ? new Error(`${request.path} doesn't exist`) : err\n })\n if (info.isDirectory()) throw new Error(`${request.path} is a directory; list_files shows what's in it`)\n if (!info.isFile()) throw new Error(`${request.path} isn't a regular file, so read_file can't read it`)\n const handle = await open(real)\n try {\n if (await is_binary(handle)) {\n throw new Error(`${request.path} is a binary file (it has a NUL byte in its first 8 KB), so read_file won't read it`)\n }\n return await read_lines(handle, request)\n } finally {\n await handle.close()\n }\n}\n\n/**\n * The `read_file` tool for one session: numbered lines from a file inside\n * its workspace, at most `read_limit_lines` per call.\n */\nexport function read_file_tool(session: AcpSession, read_limit_lines: number): Tool {\n return {\n name: 'read_file',\n description:\n `Read a text file in the workspace. Returns its lines numbered from 1, at most ${read_limit_lines} per call; ` +\n `pass offset (the first line to read) and limit to read part of a longer file. ` +\n `Lines over ${LINE_WIDTH} characters are cut. The path is absolute or relative to the workspace root.`,\n input_schema: json_schema_to_standard({\n type: 'object',\n properties: {\n path: { type: 'string', description: 'The file to read, absolute or relative to the workspace root' },\n offset: { type: 'integer', minimum: 1, description: 'The first line to read, counting from 1; default: 1' },\n limit: {\n type: 'integer',\n minimum: 1,\n description: `How many lines to read; default and most: ${read_limit_lines}`,\n },\n },\n required: ['path'],\n additionalProperties: false,\n }),\n read_only: true,\n execute: async (input) => {\n const request = read_request(input, read_limit_lines)\n const { real } = await contain(session, request.path)\n return read_contained(real, request)\n },\n }\n}\n","/**\n * list_files: list the workspace's files that match a glob.\n *\n * It walks the directory itself and matches each file with `path`'s\n * `matchesGlob`, rather than handing the walk to `fs/promises`' `glob`.\n * That `glob` steps through a symlinked directory whenever a pattern names\n * it, passes over its `exclude` callback for a pattern that names its\n * segments, swallows a directory it can't read, and, with an `exclude`\n * callback under Stryker's runner, can drop a whole directory it has already\n * listed. The walk here never follows a symlink and never enters an ignored\n * name, so every file it lists lies under the searched directory, which\n * `contain` has already placed inside a root, and its matches follow the\n * same glob rules as `glob`'s.\n */\n\nimport type { Dirent } from 'node:fs'\nimport { readdir, stat } from 'node:fs/promises'\nimport { isAbsolute, join, matchesGlob } from 'node:path'\nimport type { Tool } from '#engine'\nimport { as_record, json_schema_to_standard } from '#schema'\nimport type { AcpSession } from '../types.js'\nimport { contain, shown_path } from './containment.js'\n\n/** What `list_files` matches when the call names no pattern. */\nconst ALL_FILES = '**/*'\n\n/** One listing: the glob, and the directory it runs in, as the model gave them. */\ntype ListRequest = {\n readonly pattern: string\n readonly path: string\n}\n\n/** What one walk needs besides the directory it's in. */\nexport type Walk = {\n readonly pattern: string\n readonly ignored: ReadonlySet<string>\n readonly abort: AbortSignal\n readonly found: string[]\n}\n\n/**\n * Read the call's pattern and directory out of its input, refusing a\n * pattern that reaches past the directory: it could never match, and the\n * model is better told to pass the directory as `path`.\n */\nfunction list_request(input: unknown): ListRequest {\n const fields: Record<string, unknown> = as_record(input) ?? {}\n const { pattern = ALL_FILES, path = '.' } = fields\n if (typeof pattern !== 'string' || typeof path !== 'string') {\n throw new Error('list_files takes its pattern and path as strings')\n }\n if (isAbsolute(pattern) || pattern.split(/[\\\\/]/).includes('..')) {\n throw new Error(\n `list_files matches its pattern under path, so ${pattern} can't be absolute or climb with ..; pass the directory as path instead`,\n )\n }\n return { pattern, path }\n}\n\n/**\n * Walk one directory, depth first: descend into each subdirectory and keep\n * each regular file that matches, skipping ignored names. A symlink is\n * neither a directory nor a file to a `readdir` entry, so the walk never\n * follows one. `search` walks with it too, so both tools see the same files.\n */\nexport async function walk(directory: string, below: string, work: Walk): Promise<void> {\n work.abort.throwIfAborted()\n const entries: Dirent[] = await readdir(directory, { withFileTypes: true })\n for (const entry of entries) {\n if (work.ignored.has(entry.name)) continue\n const relative = join(below, entry.name)\n if (entry.isDirectory()) await walk(join(directory, entry.name), relative, work)\n else if (entry.isFile() && matchesGlob(relative, work.pattern)) work.found.push(relative)\n }\n}\n\n/**\n * The files under the request's directory that match its pattern, in the\n * model's terms and sorted.\n */\nasync function matching_files(\n session: AcpSession,\n request: ListRequest,\n ignored: ReadonlySet<string>,\n abort: AbortSignal,\n): Promise<string[]> {\n const base = await contain(session, request.path)\n if (!(await stat(base.real)).isDirectory()) {\n throw new Error(`${request.path} is a file; list_files lists a directory, and read_file reads a file`)\n }\n const found: string[] = []\n await walk(base.real, '', { pattern: request.pattern, ignored, abort, found })\n return found.map((relative) => shown_path(session, join(base.path, relative))).toSorted()\n}\n\n/**\n * The files as the model reads them, one to a line, and past `limit` the\n * first `limit` of them with a note giving the total. The walk has already\n * found every match to sort them, so the total costs nothing to count.\n */\nfunction listing(files: ReadonlyArray<string>, limit: number): string {\n if (files.length <= limit) return files.join('\\n')\n const note = `[the first ${limit} of ${files.length} files; narrow pattern or path to see the rest]`\n return [...files.slice(0, limit), '', note].join('\\n')\n}\n\n/**\n * The `list_files` tool for one session: the files under a directory in\n * its workspace that match a glob, skipping the `ignore` names, at most\n * `limit` per call.\n */\nexport function list_files_tool(session: AcpSession, ignore: ReadonlyArray<string>, limit: number): Tool {\n const ignored = new Set(ignore)\n return {\n name: 'list_files',\n description: [\n `List the files in the workspace that match a glob pattern, one per line and at most ${limit} per call; a path under the workspace root is shown relative to it.`,\n `The pattern matches under path (default: the workspace root) and defaults to ${ALL_FILES}.`,\n 'As in a shell, * and ** skip names that start with a dot, so name the dot to list hidden files (.github/**/*).',\n ...(ignore.length === 0 ? [] : [`Skips ${ignore.join(', ')}.`]),\n ].join(' '),\n input_schema: json_schema_to_standard({\n type: 'object',\n properties: {\n pattern: { type: 'string', description: `A glob such as src/**/*.ts; default: ${ALL_FILES}` },\n path: {\n type: 'string',\n description: 'The directory to search, absolute or relative to the workspace root; default: the root',\n },\n },\n additionalProperties: false,\n }),\n read_only: true,\n execute: async (input, ctx) => {\n const request = list_request(input)\n const files = await matching_files(session, request, ignored, ctx.abort)\n return files.length === 0 ? `no files match ${request.pattern} under ${request.path}` : listing(files, limit)\n },\n }\n}\n","/**\n * search: find the lines in the workspace's files that match a regular\n * expression.\n *\n * The pattern is the model's, and JavaScript's `RegExp` backtracks, so a\n * pattern such as `(a+)+$` against one long line can run for minutes. No\n * abort interrupts synchronous code, and one agent process serves every\n * session, so a search on the main thread could leave even `session/cancel`\n * unanswered. Each search runs in a worker thread instead, which the turn's\n * abort and a time budget can terminate mid-match. The worker is a thin\n * shell, `search_worker.ts`: what it runs is `search_files`, here, where\n * the tests call it on the main thread.\n *\n * The search walks the files itself, with `list_files`' walk, rather than\n * handing the work to `rg`, because the module keeps child processes to\n * `run_command`.\n */\n\nimport { open, stat } from 'node:fs/promises'\nimport { extname, join } from 'node:path'\nimport { Worker } from 'node:worker_threads'\nimport type { Tool } from '#engine'\nimport { as_record, json_schema_to_standard } from '#schema'\nimport type { AcpSession } from '../types.js'\nimport { contain, shown_path } from './containment.js'\nimport { walk } from './list_files.js'\nimport { is_binary } from './read_file.js'\n\n/** What `search` matches when the call names no glob. */\nconst ALL_FILES = '**/*'\n\n/** The most matches one call returns. */\nconst MATCH_LIMIT = 100\n\n/**\n * The longest matching line shown whole. A longer one is shown as a window\n * this wide around its match, since a minified bundle is one line of\n * megabytes and every match in it would otherwise carry the whole line.\n */\nconst LINE_WIDTH = 500\n\n/** How much of a long line its window shows before the match. */\nconst LINE_LEAD = 100\n\n/**\n * The search worker, beside this module with its extension: `.ts` in the\n * source tree, where vitest and Stryker run it, and `.js` once built.\n */\nconst SEARCH_WORKER = new URL(`./search_worker${extname(import.meta.url)}`, import.meta.url)\n\n/** One search as the model asked for it. */\ntype SearchRequest = {\n readonly pattern: string\n readonly path: string\n readonly glob: string\n}\n\n/** One search as the worker runs it: plain data, since it crosses to another thread. */\ntype SearchJob = {\n /** The real path of the directory to walk, or of the one file to search. */\n readonly base: string\n readonly directory: boolean\n readonly pattern: string\n /** The glob as the walk matches it, relative to `base`. */\n readonly glob: string\n readonly ignore: ReadonlyArray<string>\n readonly limit: number\n}\n\n/**\n * One matching line: its file relative to the job's base (empty when the\n * base is that file), its number counting from 1, and its text.\n */\ntype SearchMatch = {\n readonly file: string\n readonly line: number\n readonly text: string\n}\n\n/** The matches, and whether the search stopped at its limit with more to find. */\ntype SearchResult = {\n readonly matches: ReadonlyArray<SearchMatch>\n readonly more: boolean\n}\n\n/**\n * Read the call's pattern, path, and glob out of its input. The pattern\n * compiles in the worker, which reports one that isn't a regular expression\n * with the engine's own message.\n */\nfunction search_request(input: unknown): SearchRequest {\n const fields: Record<string, unknown> = as_record(input) ?? {}\n const { pattern, path = '.', glob = ALL_FILES } = fields\n if (typeof pattern !== 'string' || typeof path !== 'string' || typeof glob !== 'string') {\n throw new Error('search needs a pattern, and takes its pattern, path, and glob as strings')\n }\n return { pattern, path, glob }\n}\n\n/**\n * The glob as the walk matches it. Like `rg --glob`, a glob without a slash\n * names files at any depth, so `*.ts` reaches `src/a.ts`, while one with a\n * slash matches the path under the searched directory.\n */\nfunction walk_glob(glob: string): string {\n return glob.includes('/') ? glob : `**/${glob}`\n}\n\n/**\n * The files a job searches, relative to its base: the one file, or every\n * file the walk keeps, sorted so the same search stops at the same match\n * every time.\n */\nasync function files_of(job: SearchJob): Promise<string[]> {\n if (!job.directory) return ['']\n const found: string[] = []\n // Nothing inside the worker cancels the walk: the turn's abort and the\n // budget terminate the whole thread instead.\n const abort = new AbortController().signal\n await walk(job.base, '', { pattern: job.glob, ignored: new Set(job.ignore), abort, found })\n return found.toSorted()\n}\n\n/**\n * A file's text, or nothing for a binary file, which then has no lines to\n * search.\n */\nasync function file_text(path: string): Promise<string> {\n const handle = await open(path)\n try {\n // The binary check reads at an explicit position, which leaves the\n // handle's own position at the top, where readFile starts.\n return (await is_binary(handle)) ? '' : await handle.readFile('utf8')\n } finally {\n await handle.close()\n }\n}\n\n/**\n * A text's lines without their endings, and without the empty one after a\n * final newline, which isn't a line of the file.\n */\nfunction lines_of(text: string): string[] {\n const lines = text.split(/\\r?\\n/)\n if (lines.at(-1) === '') lines.pop()\n return lines\n}\n\n/**\n * A matching line as `search` shows it: whole up to LINE_WIDTH characters,\n * and past that, a window that wide starting LINE_LEAD characters before\n * the match, kept inside the line, with the columns it covers.\n */\nfunction excerpt(line: string, at: number): string {\n if (line.length <= LINE_WIDTH) return line\n const start = Math.max(0, Math.min(at - LINE_LEAD, line.length - LINE_WIDTH))\n return `${line.slice(start, start + LINE_WIDTH)} [columns ${start + 1} to ${start + LINE_WIDTH} of ${line.length}]`\n}\n\n/**\n * Search a job's files, in order, for the lines its pattern matches,\n * stopping at the first match past the limit, which says there are more.\n * The search worker runs this, and the tests call it on the main thread,\n * where Stryker can switch its mutants on.\n */\nexport async function search_files(job: SearchJob): Promise<SearchResult> {\n const regex = new RegExp(job.pattern)\n const matches: SearchMatch[] = []\n for (const file of await files_of(job)) {\n for (const [index, line] of lines_of(await file_text(join(job.base, file))).entries()) {\n const found = regex.exec(line)\n if (found === null) continue\n if (matches.length === job.limit) return { matches, more: true }\n matches.push({ file, line: index + 1, text: excerpt(line, found.index) })\n }\n }\n return { matches, more: false }\n}\n\n/**\n * Run one job in a search worker. The turn's abort and the budget each\n * terminate the thread, mid-match if need be, which nothing could do to a\n * pattern running on the main thread. However the search ends, the abort\n * listener and the budget's timer go with it.\n */\nasync function in_worker(job: SearchJob, budget_ms: number, abort: AbortSignal): Promise<SearchResult> {\n abort.throwIfAborted()\n const worker = new Worker(SEARCH_WORKER, { workerData: job })\n const { promise, resolve, reject } = Promise.withResolvers<SearchResult>()\n const stop = (reason: unknown): void => {\n void worker.terminate()\n reject(reason)\n }\n const on_abort = (): void => {\n stop(abort.reason)\n }\n const over_budget = new Error(\n `search stopped after ${budget_ms / 1000} s without finishing: the pattern may backtrack without end, ` +\n 'as nested quantifiers such as (a+)+ can, or there may be too much to search; ' +\n 'simplify the pattern, or narrow path or glob',\n )\n const budget = setTimeout(stop, budget_ms, over_budget)\n abort.addEventListener('abort', on_abort)\n worker.once('message', resolve)\n worker.once('error', reject)\n try {\n return await promise\n } finally {\n clearTimeout(budget)\n abort.removeEventListener('abort', on_abort)\n }\n}\n\n/**\n * The matches as the model reads them, one `path:line: text` to a line, and\n * a note when the search stopped at its limit.\n */\nfunction report(session: AcpSession, base: string, request: SearchRequest, result: SearchResult): string {\n if (result.matches.length === 0) {\n return `no lines match ${request.pattern} under ${request.path} in files matching ${request.glob}`\n }\n const lines = result.matches.map(\n (match) => `${shown_path(session, join(base, match.file))}:${match.line}: ${match.text}`,\n )\n if (result.more) {\n lines.push('', `[the first ${result.matches.length} matches; narrow the pattern, path, or glob to see the rest]`)\n }\n return lines.join('\\n')\n}\n\n/**\n * The `search` tool for one session: the lines under a path in its\n * workspace that match a regular expression, skipping binary files and the\n * `ignore` names, at most MATCH_LIMIT per call, each search in a worker\n * that the turn's abort and `budget_ms` can terminate.\n */\nexport function search_tool(session: AcpSession, ignore: ReadonlyArray<string>, budget_ms: number): Tool {\n return {\n name: 'search',\n description: [\n `Search the workspace's files for lines that match a regular expression, at most ${MATCH_LIMIT} per call,`,\n 'each shown as path:line: text; a path under the workspace root is shown relative to it.',\n 'The pattern is a JavaScript regular expression matched against one line at a time; write (?i:...) for a part that ignores case.',\n 'path (default: the workspace root) is the directory to search, or a single file.',\n 'glob picks the files: without a slash it matches a file name at any depth (*.ts, *.{ts,tsx}),',\n 'and with one it matches the path under path (src/**/*.ts).',\n 'As in a shell, * and ** skip names that start with a dot, so name the dot to search hidden files (.github/**/*).',\n ignore.length === 0 ? 'Skips binary files.' : `Skips binary files and ${ignore.join(', ')}.`,\n ].join(' '),\n input_schema: json_schema_to_standard({\n type: 'object',\n properties: {\n pattern: { type: 'string', description: 'A JavaScript regular expression, such as function\\\\s+\\\\w+' },\n path: {\n type: 'string',\n description: 'The directory or file to search, absolute or relative to the workspace root; default: the root',\n },\n glob: { type: 'string', description: `Which files to search, such as *.ts or src/**/*.ts; default: ${ALL_FILES}` },\n },\n required: ['pattern'],\n additionalProperties: false,\n }),\n read_only: true,\n execute: async (input, ctx) => {\n const request = search_request(input)\n const base = await contain(session, request.path)\n const info = await stat(base.real)\n if (!info.isDirectory() && !info.isFile()) {\n throw new Error(`${request.path} isn't a directory or a regular file, so search can't read it`)\n }\n const job: SearchJob = {\n base: base.real,\n directory: info.isDirectory(),\n pattern: request.pattern,\n glob: walk_glob(request.glob),\n ignore,\n limit: MATCH_LIMIT,\n }\n return report(session, base.path, request, await in_worker(job, budget_ms, ctx.abort))\n },\n }\n}\n"],"mappings":"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"}
@@ -1,4 +1,4 @@
1
- import { t as search_files } from "./search-CpCJYMUm.js";
1
+ import { t as search_files } from "./search-DjhdMsJ8.js";
2
2
  import { parentPort, workerData } from "node:worker_threads";
3
3
  //#region src/acp/tools/search_worker.ts
4
4
  /**
package/dist/testing.d.ts CHANGED
@@ -1,5 +1,20 @@
1
1
  import { n as CheckpointStore } from "./types-CPqLZOEr.js";
2
- import { I as UsageTotals, M as ToolCallRecord, d as GenerateOptions, f as GenerateResult, s as Engine, u as FinishReason } from "./types-Sw0oHW-_.js";
2
+ import { B as UsageTotals, F as ToolCallRecord, G as NativeProviderAdapter, R as TurnRequest, h as GenerateResult, m as GenerateOptions, n as AssistantContentPart, p as FinishReason, u as Engine } from "./types-C7pO0jLq.js";
3
+ //#region src/testing/assert_prefix_stable.d.ts
4
+ /**
5
+ * Check that every turn of every call in `requests` sends the turn before it
6
+ * unchanged: the same system prompt, the same tools in the same order
7
+ * (names, descriptions, and input schemas), and every earlier message again,
8
+ * as the same JSON text, before any new one.
9
+ *
10
+ * Throws a plain `Error` at the first difference, naming the call (counted
11
+ * from 1), the step (its `step_index`), and the difference, with message and
12
+ * tool positions as the request's arrays hold them, from 0. A new call
13
+ * starts wherever a `step_index` doesn't increase, so the check reads calls
14
+ * that ran one at a time, and a `parallel` flow takes one double per branch.
15
+ */
16
+ export declare function assert_prefix_stable(requests: ReadonlyArray<TurnRequest>): void;
17
+ //#endregion
3
18
  //#region src/testing/engine_from_generate.d.ts
4
19
  /**
5
20
  * Build an `Engine` whose only live member is the supplied `generate`.
@@ -62,6 +77,66 @@ type CaptureEngine = {
62
77
  */
63
78
  export declare function make_capture_engine(options?: CaptureEngineOptions): CaptureEngine;
64
79
  //#endregion
80
+ //#region src/testing/make_loop_engine.d.ts
81
+ /** One tool call a scripted turn makes. A call without an `id` gets `call_<turn>_<n>`. */
82
+ type LoopCall = {
83
+ readonly id?: string;
84
+ readonly name: string;
85
+ readonly input: unknown;
86
+ };
87
+ /** A turn spelled out field by field. */
88
+ type LoopTurnFields = {
89
+ /** The turn's text (default: its `content`'s text parts, joined). */
90
+ readonly text?: string;
91
+ /** The calls the turn makes (default: its `content`'s tool_call parts). */
92
+ readonly tool_calls?: ReadonlyArray<LoopCall>;
93
+ /** The turn's parts, which the loop sends back as the assistant message. */
94
+ readonly content?: ReadonlyArray<AssistantContentPart>;
95
+ /** Default: `'tool_calls'` when the turn makes calls, `'stop'` otherwise. */
96
+ readonly finish_reason?: FinishReason;
97
+ /** Default: the engine's `usage` option. */
98
+ readonly usage?: UsageTotals;
99
+ /**
100
+ * True to play a turn the provider paused partway through (Anthropic's
101
+ * `pause_turn`), which the loop sends back and continues with another turn.
102
+ */
103
+ readonly paused?: boolean;
104
+ /** An error to throw for this turn instead of answering. */
105
+ readonly throw?: Error;
106
+ };
107
+ /**
108
+ * One model turn: a string is a final answer, an array is the calls the turn
109
+ * makes, and an object spells the turn out field by field.
110
+ */
111
+ type LoopTurn = string | ReadonlyArray<LoopCall> | LoopTurnFields;
112
+ type LoopEngineOptions = {
113
+ /** The model every call resolves to unless it names one (default `'loop'`). */
114
+ readonly model_id?: string;
115
+ /** The usage a turn reports when it sets none (default `{ input_tokens: 40, output_tokens: 20 }`). */
116
+ readonly usage?: UsageTotals;
117
+ /**
118
+ * The caching the double's provider declares, which decides the `cache`
119
+ * each request carries (default: none, so no request carries one).
120
+ */
121
+ readonly prompt_cache?: NativeProviderAdapter['prompt_cache'];
122
+ };
123
+ type LoopEngine = {
124
+ readonly engine: Engine;
125
+ /** Every request the model was sent, in order, growing as the script plays. */
126
+ readonly requests: TurnRequest[];
127
+ };
128
+ /**
129
+ * Build an engine whose one provider, `'loop'`, plays `turns` in order, a
130
+ * turn each time any call through the engine asks the model for one, and
131
+ * the array that records every request it was sent.
132
+ *
133
+ * `options.model_id` sets the default model (default `'loop'`),
134
+ * `options.usage` the usage a turn reports when it sets none (default
135
+ * `{ input_tokens: 40, output_tokens: 20 }`), and `options.prompt_cache` the
136
+ * caching its provider declares (default: none).
137
+ */
138
+ export declare function make_loop_engine(turns: ReadonlyArray<LoopTurn>, options?: LoopEngineOptions): LoopEngine;
139
+ //#endregion
65
140
  //#region src/testing/make_script_engine.d.ts
66
141
  type ScriptResponse = {
67
142
  readonly content?: unknown;
@@ -134,5 +209,5 @@ export declare function make_stub_engine(canned: ReadonlyArray<StubResponse>, op
134
209
  */
135
210
  export declare function text_of<t = unknown>(opts: GenerateOptions<t>): string;
136
211
  //#endregion
137
- export type { CaptureEngine, CaptureEngineOptions, ScriptEngineOptions, ScriptResponse, StoreConformanceFailure, StoreConformanceOptions, StoreConformanceReport, StubContent, StubContentFn, StubEngineOptions, StubResponse };
212
+ export type { CaptureEngine, CaptureEngineOptions, LoopCall, LoopEngine, LoopEngineOptions, LoopTurn, ScriptEngineOptions, ScriptResponse, StoreConformanceFailure, StoreConformanceOptions, StoreConformanceReport, StubContent, StubContentFn, StubEngineOptions, StubResponse };
138
213
  //# sourceMappingURL=testing.d.ts.map