fascicle 0.12.1 → 0.12.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +113 -38
- package/README.md +16 -15
- package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
- package/dist/adapters-CutexJd3.js.map +1 -0
- package/dist/adapters.d.ts +10 -10
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +13 -3
- package/dist/agents.js +12 -5
- package/dist/agents.js.map +1 -1
- package/dist/{core-DDRhHu5P.js → core-DdJEhyQc.js} +122 -488
- package/dist/core-DdJEhyQc.js.map +1 -0
- package/dist/{engine-b4ZH8esY.js → engine-CdXegeqC.js} +201 -380
- package/dist/engine-CdXegeqC.js.map +1 -0
- package/dist/index.d.ts +111 -25
- package/dist/index.js +446 -48
- package/dist/index.js.map +1 -1
- package/dist/{invoke-CyKNhvBw.js → invoke-CH_eJZeS.js} +8 -8
- package/dist/{invoke-CyKNhvBw.js.map → invoke-CH_eJZeS.js.map} +1 -1
- package/dist/leading_system-BUCT-PwD.js +330 -0
- package/dist/leading_system-BUCT-PwD.js.map +1 -0
- package/dist/mcp.d.ts +5 -5
- package/dist/mcp.js +10 -9
- package/dist/mcp.js.map +1 -1
- package/dist/otel.d.ts +21 -3
- package/dist/otel.js +232 -12
- package/dist/otel.js.map +1 -1
- package/dist/stdio.d.ts +2 -2
- package/dist/stdio.js +2 -2
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -2
- package/dist/testing.js.map +1 -1
- package/dist/{trajectory-cSLNlHzh.d.ts → trajectory-ByoOQZ6T.d.ts} +10 -10
- package/dist/trajectory-D1eq9eue.js +81 -0
- package/dist/trajectory-D1eq9eue.js.map +1 -0
- package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
- package/dist/{types-CXBB4aIM.d.ts → types-CLigYA62.d.ts} +30 -4
- package/dist/{types-BqUY6nRX.d.ts → types-DBpU27sQ.d.ts} +7 -2
- package/dist/ui.d.ts +1 -1
- package/dist/ui.js +1 -1
- package/dist/ui.js.map +1 -1
- package/dist/viewer.d.ts +8 -8
- package/dist/viewer.js +16 -15
- package/dist/viewer.js.map +1 -1
- package/package.json +10 -5
- package/dist/adapters-hmnJOOgf.js.map +0 -1
- package/dist/core-DDRhHu5P.js.map +0 -1
- package/dist/engine-b4ZH8esY.js.map +0 -1
package/dist/otel.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"otel.js","names":["otel_context"],"sources":["../src/otel/trajectory_logger.ts"],"sourcesContent":["/**\n * OpenTelemetry bridge for fascicle trajectory events.\n *\n * `create_otel_trajectory_logger` returns a plain TrajectoryLogger that turns\n * the engine's own span + event stream into OpenTelemetry spans: the\n * `engine.generate` span becomes an OTel root span, each `engine.generate.step`\n * a child span, and every `record`ed event (tool_call, tool_result, cost, ...)\n * an OTel span event on the currently-open span. It is transport-neutral: the\n * spans come from events the engine already emits, so native and external\n * transports get traces without any AI-SDK involvement.\n *\n * This module is the ONLY place `@opentelemetry/api` is imported, and it lives\n * outside `src/engine/` on purpose: the engine's `ai + zod` npm-dep invariant\n * holds unmodified, and an app that never imports `fascicle/otel` pulls in\n * zero OTel packages at runtime.\n *\n * Nesting is resolved two ways, in order: an explicit `parent_span_id` on the\n * start meta (how the composition runner threads composer-span parenthood) wins;\n * otherwise the currently-open span (top of the open stack) is the parent. This\n * is exact for the sequential engine flow (generate → step → step) and for\n * runner-nested spans; genuinely interleaved sibling spans that carry no\n * `parent_span_id` (concurrent branches sharing one logger) fall back to stack\n * order, which is this bridge's one documented approximation.\n */\n\nimport {\n context as otel_context,\n trace,\n SpanStatusCode,\n type AttributeValue,\n type Attributes,\n type Context,\n type Span,\n type Tracer,\n} from '@opentelemetry/api'\nimport type { TrajectoryEvent, TrajectoryLogger } from '#core'\n\nexport type OtelTrajectoryLoggerOptions = {\n /**\n * Tracer to open spans on. Defaults to `trace.getTracer('fascicle')`, which\n * resolves against whatever global TracerProvider the host has registered.\n */\n readonly tracer?: Tracer\n /**\n * Prefix for span + event attributes derived from event metadata, keeping\n * them out of the OTel semantic-convention namespace. Defaults to `fascicle.`.\n */\n readonly attribute_prefix?: string\n}\n\n// Event/meta keys that are bridge plumbing, not span attributes.\nconst INTERNAL_KEYS: ReadonlySet<string> = new Set(['kind', 'span_id', 'parent_span_id'])\n\n/**\n * JSON-stringify `value`, falling back to `String(value)` when `stringify`\n * throws or returns `undefined` (e.g. for functions or symbols).\n */\nfunction safe_json(value: unknown): string {\n try {\n return JSON.stringify(value) ?? String(value)\n } catch {\n return String(value)\n }\n}\n\n/**\n * Convert a JS value into an OTel-compatible attribute value.\n *\n * Primitives and homogeneous primitive arrays pass through unchanged;\n * anything else falls back to `safe_json`; `null`/`undefined` drop out\n * entirely (returning `undefined`) so the caller can omit the attribute.\n */\nfunction to_attribute_value(value: unknown): AttributeValue | undefined {\n if (value === null || value === undefined) return undefined\n const kind = typeof value\n if (kind === 'string' || kind === 'number' || kind === 'boolean') {\n // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion\n return value as AttributeValue\n }\n if (Array.isArray(value)) {\n if (value.every((v) => typeof v === 'string')) return value\n if (value.every((v) => typeof v === 'number')) return value\n if (value.every((v) => typeof v === 'boolean')) return value\n return safe_json(value)\n }\n return safe_json(value)\n}\n\n/**\n * Build an OTel `Attributes` object from event/meta fields.\n *\n * Skips the bridge's internal plumbing keys (`kind`, `span_id`,\n * `parent_span_id`) and prefixes the rest with `prefix` so they stay out of\n * OTel's semantic-convention namespace.\n */\nfunction to_attributes(\n meta: Readonly<Record<string, unknown>> | undefined,\n prefix: string,\n): Attributes {\n const attrs: Attributes = {}\n if (meta === undefined) return attrs\n for (const [key, value] of Object.entries(meta)) {\n if (INTERNAL_KEYS.has(key)) continue\n const attr = to_attribute_value(value)\n if (attr !== undefined) attrs[`${prefix}${key}`] = attr\n }\n return attrs\n}\n\ntype OpenSpan = { readonly span: Span; readonly context: Context }\n\n/**\n * Create a `TrajectoryLogger` that mirrors spans and events onto\n * OpenTelemetry, using `options.tracer` (or the global `fascicle` tracer).\n *\n * Parent resolution favors an explicit `parent_span_id` on the start meta;\n * otherwise it falls back to the currently open span on an internal stack.\n */\nexport function create_otel_trajectory_logger(\n options: OtelTrajectoryLoggerOptions = {},\n): TrajectoryLogger {\n const tracer = options.tracer ?? trace.getTracer('fascicle')\n const prefix = options.attribute_prefix ?? 'fascicle.'\n const open = new Map<string, OpenSpan>()\n const stack: string[] = []\n let counter = 0\n\n const top_context = (): Context | undefined => {\n const top = stack[stack.length - 1]\n if (top === undefined) return undefined\n return open.get(top)?.context\n }\n\n const parent_context = (meta: Record<string, unknown> | undefined): Context => {\n const explicit = meta?.['parent_span_id']\n if (typeof explicit === 'string') {\n const parent = open.get(explicit)\n if (parent !== undefined) return parent.context\n }\n return top_context() ?? otel_context.active()\n }\n\n const target_for_event = (event: TrajectoryEvent): Span | undefined => {\n if (typeof event.span_id === 'string') {\n const target = open.get(event.span_id)\n if (target !== undefined) return target.span\n }\n const top = stack[stack.length - 1]\n return top !== undefined ? open.get(top)?.span : undefined\n }\n\n return {\n start_span(name, meta) {\n const parent = parent_context(meta)\n const span = tracer.startSpan(name, { attributes: to_attributes(meta, prefix) }, parent)\n counter += 1\n const id = `fascicle-otel-${counter}`\n open.set(id, { span, context: trace.setSpan(parent, span) })\n stack.push(id)\n return id\n },\n end_span(id, meta) {\n const entry = open.get(id)\n if (entry === undefined) return\n const { span } = entry\n span.setAttributes(to_attributes(meta, prefix))\n const error = meta?.['error']\n if (typeof error === 'string' && error.length > 0) {\n span.setStatus({ code: SpanStatusCode.ERROR, message: error })\n }\n span.end()\n open.delete(id)\n const idx = stack.lastIndexOf(id)\n if (idx !== -1) stack.splice(idx, 1)\n },\n record(event) {\n const span = target_for_event(event)\n if (span === undefined) return\n const name = typeof event.kind === 'string' ? event.kind : 'event'\n span.addEvent(name, to_attributes(event, prefix))\n },\n }\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"otel.js","names":["otel_metrics","otel_context"],"sources":["../src/otel/metrics.ts","../src/otel/trajectory_logger.ts"],"sourcesContent":["/**\n * Opt-in OpenTelemetry metrics derived from the trajectory stream.\n *\n * The bridge's spans answer \"what happened on this run\"; SRE dashboards ask\n * aggregate questions (\"p95 latency by model\", \"429s per minute\", \"tokens per\n * hour\"), which want real OTel metric instruments rather than a\n * spans-to-metrics pipeline. This recorder listens to the same trajectory\n * events the span bridge mirrors and records the GenAI semantic-convention\n * client histograms, plus two Fascicle-named instruments for the data the\n * conventions do not cover yet (cost, absorbed retries).\n *\n * Instruments and sources:\n * - `gen_ai.client.token.usage` ({token}) from `response_received`, one\n * point per direction via `gen_ai.token.type`.\n * - `gen_ai.client.operation.duration` (s) from `response_received`\n * `duration_ms`, the model-only round trip.\n * - `gen_ai.client.operation.time_to_first_chunk` (s) from\n * `first_chunk_ms` on streamed turns.\n * - `gen_ai.execute_tool.duration` (s) from `tool_result`, tagged\n * `gen_ai.tool.name`.\n * - `fascicle.client.operation.cost` (usd) from the `cost` event's\n * `total_usd`.\n * - `fascicle.client.turn_retries` ({retry}) counter from `turn_retry`,\n * tagged `error.type` with the classified failure kind.\n *\n * Provider and model attributes come from the enclosing `engine.generate`\n * span's start meta, tracked on a stack with the same documented\n * approximation as the span bridge: concurrent generates sharing one logger\n * attribute to the innermost open call. The semantic conventions are still\n * experimental (mid-2026), so a semconv revision may rename instruments;\n * this module tracks the names at implementation time.\n */\n\nimport {\n metrics as otel_metrics,\n type Attributes,\n type Counter,\n type Histogram,\n type Meter,\n} from '@opentelemetry/api'\nimport type { TrajectoryEvent } from '#core'\n\nexport type OtelMetricsOptions = {\n /**\n * Meter to create instruments on. Defaults to\n * `metrics.getMeter('fascicle')`, which resolves against the global\n * MeterProvider the host has registered.\n */\n readonly meter?: Meter\n}\n\n/**\n * The span-lifecycle + event listener the trajectory logger drives when\n * metrics are enabled.\n */\nexport type MetricsRecorder = {\n readonly on_start_span: (\n id: string,\n name: string,\n meta: Record<string, unknown> | undefined,\n ) => void\n readonly on_end_span: (id: string) => void\n readonly on_record: (event: TrajectoryEvent) => void\n}\n\n/** Semconv-suggested boundaries for the duration histograms, in seconds. */\nconst DURATION_BOUNDARIES = [\n 0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48,\n 40.96, 81.92,\n]\n\n/** Semconv-suggested boundaries for the token-usage histogram. */\nconst TOKEN_BOUNDARIES = [\n 1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304,\n]\n\n/**\n * Read `key` off the loose event and return it only when it is a number.\n */\nfunction event_number(event: TrajectoryEvent, key: string): number | undefined {\n const value = event[key]\n return typeof value === 'number' ? value : undefined\n}\n\n/**\n * Read `key` off the loose event and return it only when it is a string.\n */\nfunction event_string(event: TrajectoryEvent, key: string): string | undefined {\n const value = event[key]\n return typeof value === 'string' ? value : undefined\n}\n\n/**\n * Create the metrics recorder: instruments are created once here, and every\n * recording stamps the provider/model of the innermost open generate call.\n */\nexport function create_metrics_recorder(options: OtelMetricsOptions): MetricsRecorder {\n const meter = options.meter ?? otel_metrics.getMeter('fascicle')\n\n const token_usage: Histogram = meter.createHistogram('gen_ai.client.token.usage', {\n unit: '{token}',\n description: 'Number of input and output tokens used per model turn',\n advice: { explicitBucketBoundaries: TOKEN_BOUNDARIES },\n })\n const operation_duration: Histogram = meter.createHistogram(\n 'gen_ai.client.operation.duration',\n {\n unit: 's',\n description: 'Model round-trip duration of the successful turn attempt',\n advice: { explicitBucketBoundaries: DURATION_BOUNDARIES },\n },\n )\n const time_to_first_chunk: Histogram = meter.createHistogram(\n 'gen_ai.client.operation.time_to_first_chunk',\n {\n unit: 's',\n description: 'Time from turn start to the first streamed chunk',\n advice: { explicitBucketBoundaries: DURATION_BOUNDARIES },\n },\n )\n const tool_duration: Histogram = meter.createHistogram('gen_ai.execute_tool.duration', {\n unit: 's',\n description: 'Tool execution duration',\n advice: { explicitBucketBoundaries: DURATION_BOUNDARIES },\n })\n const cost: Histogram = meter.createHistogram('fascicle.client.operation.cost', {\n unit: 'usd',\n description: 'Estimated cost per model turn',\n })\n const retries: Counter = meter.createCounter('fascicle.client.turn_retries', {\n unit: '{retry}',\n description: 'Provider turn attempts that failed and were retried',\n })\n\n // Innermost open engine.generate call's identity, for metric attributes.\n const generate_ids = new Set<string>()\n const context_stack: Array<{ provider?: string; model?: string }> = []\n\n const base_attributes = (): Attributes => {\n const attrs: Attributes = { 'gen_ai.operation.name': 'chat' }\n const top = context_stack[context_stack.length - 1]\n if (top?.provider !== undefined) attrs['gen_ai.provider.name'] = top.provider\n if (top?.model !== undefined) attrs['gen_ai.request.model'] = top.model\n return attrs\n }\n\n const on_response_received = (event: TrajectoryEvent): void => {\n const base = base_attributes()\n const input = event_number(event, 'input_tokens')\n if (input !== undefined) {\n token_usage.record(input, { ...base, 'gen_ai.token.type': 'input' })\n }\n const output = event_number(event, 'output_tokens')\n if (output !== undefined) {\n token_usage.record(output, { ...base, 'gen_ai.token.type': 'output' })\n }\n const duration_ms = event_number(event, 'duration_ms')\n if (duration_ms !== undefined) operation_duration.record(duration_ms / 1000, base)\n const first_chunk_ms = event_number(event, 'first_chunk_ms')\n if (first_chunk_ms !== undefined) {\n time_to_first_chunk.record(first_chunk_ms / 1000, base)\n }\n }\n\n return {\n on_start_span(id, name, meta) {\n if (name !== 'engine.generate') return\n generate_ids.add(id)\n const provider = meta?.['provider']\n const model = meta?.['model_id']\n context_stack.push({\n ...(typeof provider === 'string' ? { provider } : {}),\n ...(typeof model === 'string' ? { model } : {}),\n })\n },\n on_end_span(id) {\n if (!generate_ids.delete(id)) return\n context_stack.pop()\n },\n on_record(event) {\n if (event.kind === 'response_received') {\n on_response_received(event)\n return\n }\n if (event.kind === 'tool_result') {\n const duration_ms = event_number(event, 'duration_ms')\n if (duration_ms === undefined) return\n const name = event_string(event, 'name')\n tool_duration.record(duration_ms / 1000, {\n ...base_attributes(),\n ...(name !== undefined ? { 'gen_ai.tool.name': name } : {}),\n })\n return\n }\n if (event.kind === 'cost') {\n const total_usd = event_number(event, 'total_usd')\n if (total_usd !== undefined) cost.record(total_usd, base_attributes())\n return\n }\n if (event.kind === 'turn_retry') {\n const failure_kind = event_string(event, 'failure_kind')\n retries.add(1, {\n ...base_attributes(),\n ...(failure_kind !== undefined ? { 'error.type': failure_kind } : {}),\n })\n }\n },\n }\n}\n","/**\n * OpenTelemetry bridge for Fascicle trajectory events.\n *\n * `create_otel_trajectory_logger` returns a plain TrajectoryLogger that turns\n * the engine's own span + event stream into OpenTelemetry spans: the\n * `engine.generate` span becomes an OTel root span, each `engine.generate.step`\n * a child span, and every `record`ed event (tool_call, tool_result, cost, ...)\n * an OTel span event on the currently open span. It is transport-neutral: the\n * spans come from events the engine already emits, so native and external\n * transports get traces without any AI-SDK involvement.\n *\n * `@opentelemetry/api` is imported ONLY under `src/otel/` (this module and\n * metrics.ts), outside `src/engine/` on purpose: the engine's `ai + zod`\n * npm-dep invariant holds unmodified, and an app that never imports\n * `fascicle/otel` pulls in zero OTel packages at runtime.\n *\n * Nesting is resolved two ways, in order: an explicit `parent_span_id` on the\n * start meta (how the composition runner threads composer-span parenthood) wins;\n * otherwise the currently open span (top of the open stack) is the parent. This\n * is exact for the sequential engine flow (generate → step → step) and for\n * runner-nested spans; genuinely interleaved sibling spans that carry no\n * `parent_span_id` (concurrent branches sharing one logger) fall back to stack\n * order, which is this bridge's one documented approximation.\n */\n\nimport {\n context as otel_context,\n trace,\n SpanStatusCode,\n type AttributeValue,\n type Attributes,\n type Context,\n type Span,\n type Tracer,\n} from '@opentelemetry/api'\nimport type { TrajectoryEvent, TrajectoryLogger } from '#core'\nimport { create_metrics_recorder, type OtelMetricsOptions } from './metrics.js'\n\nexport type OtelTrajectoryLoggerOptions = {\n /**\n * Tracer to open spans on. Defaults to `trace.getTracer('fascicle')`, which\n * resolves against whatever global TracerProvider the host has registered.\n */\n readonly tracer?: Tracer\n /**\n * Prefix for span + event attributes derived from event metadata, keeping\n * them out of the OTel semantic-convention namespace. Defaults to `fascicle.`.\n */\n readonly attribute_prefix?: string\n /**\n * Opt-in metric instruments recorded from the same trajectory stream the\n * spans mirror (GenAI semconv client histograms plus Fascicle's cost and\n * retry instruments; see metrics.ts). `true` uses the global MeterProvider's\n * `fascicle` meter; an object supplies a custom Meter. Off by default so the\n * bridge stays a pure tracer for hosts without a metrics pipeline.\n */\n readonly metrics?: boolean | OtelMetricsOptions\n}\n\n// Event/meta keys that are bridge plumbing, not span attributes.\nconst INTERNAL_KEYS: ReadonlySet<string> = new Set(['kind', 'span_id', 'parent_span_id'])\n\n/**\n * JSON-stringify `value`, falling back to `String(value)` when `stringify`\n * throws or returns `undefined`, as it does for functions and symbols.\n */\nfunction safe_json(value: unknown): string {\n try {\n return JSON.stringify(value) ?? String(value)\n } catch {\n return String(value)\n }\n}\n\n/**\n * Convert a JS value into an OTel-compatible attribute value.\n *\n * Primitives and homogeneous primitive arrays pass through unchanged;\n * anything else falls back to `safe_json`; `null`/`undefined` drop out\n * entirely (returning `undefined`) so the caller can omit the attribute.\n */\nfunction to_attribute_value(value: unknown): AttributeValue | undefined {\n if (value === null || value === undefined) return undefined\n const kind = typeof value\n if (kind === 'string' || kind === 'number' || kind === 'boolean') {\n // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion\n return value as AttributeValue\n }\n if (Array.isArray(value)) {\n if (value.every((v) => typeof v === 'string')) return value\n if (value.every((v) => typeof v === 'number')) return value\n if (value.every((v) => typeof v === 'boolean')) return value\n return safe_json(value)\n }\n return safe_json(value)\n}\n\n/**\n * True for a plain object value (not null, not an array): the shape span-meta\n * flattening applies to.\n */\nfunction is_plain_object(value: unknown): value is Record<string, unknown> {\n return value !== null && typeof value === 'object' && !Array.isArray(value)\n}\n\n/**\n * Spread one object-valued span-meta field into dotted attribute keys\n * (`usage` + `input_tokens` becomes `<prefix>usage.input_tokens`), with\n * deeper nesting falling back to `to_attribute_value`'s JSON form.\n */\nfunction flatten_into(\n attrs: Attributes,\n key: string,\n value: Record<string, unknown>,\n prefix: string,\n): void {\n for (const [inner_key, inner_value] of Object.entries(value)) {\n const attr = to_attribute_value(inner_value)\n if (attr !== undefined) attrs[`${prefix}${key}.${inner_key}`] = attr\n }\n}\n\n/**\n * Build an OTel `Attributes` object from event/meta fields.\n *\n * Skips the bridge's internal plumbing keys (`kind`, `span_id`,\n * `parent_span_id`) and prefixes the rest with `prefix` so they stay out of\n * OTel's semantic-convention namespace.\n *\n * With `flatten`, an object-valued field spreads one level into dotted keys\n * (`usage: { input_tokens: 5 }` becomes `<prefix>usage.input_tokens = 5`), so\n * span metadata like usage and model_resolved lands as numeric attributes a\n * dashboard can aggregate rather than a JSON string it cannot query. Flattening\n * applies to span meta only, never to `record`ed events: an event may carry\n * arbitrary payloads (a tool call's input, a salvage blob) where\n * attribute-per-key would explode cardinality and leak structure, so those\n * keep the JSON-string fallback.\n */\nfunction to_attributes(\n meta: Readonly<Record<string, unknown>> | undefined,\n prefix: string,\n flatten = false,\n): Attributes {\n const attrs: Attributes = {}\n if (meta === undefined) return attrs\n for (const [key, value] of Object.entries(meta)) {\n if (INTERNAL_KEYS.has(key)) continue\n if (flatten && is_plain_object(value)) {\n flatten_into(attrs, key, value, prefix)\n continue\n }\n const attr = to_attribute_value(value)\n if (attr !== undefined) attrs[`${prefix}${key}`] = attr\n }\n return attrs\n}\n\ntype OpenSpan = { readonly span: Span; readonly context: Context }\n\n/**\n * Create a `TrajectoryLogger` that mirrors spans and events onto\n * OpenTelemetry, using `options.tracer` (or the global `fascicle` tracer).\n *\n * Parent resolution favors an explicit `parent_span_id` on the start meta;\n * otherwise it falls back to the currently open span on an internal stack.\n */\nexport function create_otel_trajectory_logger(\n options: OtelTrajectoryLoggerOptions = {},\n): TrajectoryLogger {\n const tracer = options.tracer ?? trace.getTracer('fascicle')\n const prefix = options.attribute_prefix ?? 'fascicle.'\n const metrics_recorder =\n options.metrics === undefined || options.metrics === false\n ? undefined\n : create_metrics_recorder(options.metrics === true ? {} : options.metrics)\n const open = new Map<string, OpenSpan>()\n const stack: string[] = []\n let counter = 0\n\n const top_context = (): Context | undefined => {\n const top = stack[stack.length - 1]\n if (top === undefined) return undefined\n return open.get(top)?.context\n }\n\n const parent_context = (meta: Record<string, unknown> | undefined): Context => {\n const explicit = meta?.['parent_span_id']\n if (typeof explicit === 'string') {\n const parent = open.get(explicit)\n if (parent !== undefined) return parent.context\n }\n return top_context() ?? otel_context.active()\n }\n\n const target_for_event = (event: TrajectoryEvent): Span | undefined => {\n if (typeof event.span_id === 'string') {\n const target = open.get(event.span_id)\n if (target !== undefined) return target.span\n }\n const top = stack[stack.length - 1]\n return top !== undefined ? open.get(top)?.span : undefined\n }\n\n return {\n start_span(name, meta) {\n const parent = parent_context(meta)\n const span = tracer.startSpan(\n name,\n { attributes: to_attributes(meta, prefix, true) },\n parent,\n )\n counter += 1\n const id = `fascicle-otel-${counter}`\n open.set(id, { span, context: trace.setSpan(parent, span) })\n stack.push(id)\n metrics_recorder?.on_start_span(id, name, meta)\n return id\n },\n end_span(id, meta) {\n metrics_recorder?.on_end_span(id)\n const entry = open.get(id)\n if (entry === undefined) return\n const { span } = entry\n span.setAttributes(to_attributes(meta, prefix, true))\n const error = meta?.['error']\n if (typeof error === 'string' && error.length > 0) {\n span.setStatus({ code: SpanStatusCode.ERROR, message: error })\n }\n span.end()\n open.delete(id)\n const idx = stack.lastIndexOf(id)\n if (idx !== -1) stack.splice(idx, 1)\n },\n record(event) {\n metrics_recorder?.on_record(event)\n const span = target_for_event(event)\n if (span === undefined) return\n const name = typeof event.kind === 'string' ? event.kind : 'event'\n span.addEvent(name, to_attributes(event, prefix))\n },\n }\n}\n"],"mappings":"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"}
|
package/dist/stdio.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { a as Step, d as TrajectoryLogger } from "./types-
|
|
2
|
-
import { t as AnySchema } from "./types-
|
|
1
|
+
import { a as Step, d as TrajectoryLogger } from "./types-DBpU27sQ.js";
|
|
2
|
+
import { t as AnySchema } from "./types-BK0UW28o.js";
|
|
3
3
|
|
|
4
4
|
//#region src/stdio/execute_stdio.d.ts
|
|
5
5
|
type RunStdioOptions<i, o> = {
|
package/dist/stdio.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { r as stderr_logger } from "./adapters-
|
|
1
|
+
import { D as run, s as validate_schema } from "./core-DdJEhyQc.js";
|
|
2
|
+
import { r as stderr_logger } from "./adapters-CutexJd3.js";
|
|
3
3
|
import { text } from "node:stream/consumers";
|
|
4
4
|
//#region src/stdio/execute_stdio.ts
|
|
5
5
|
/**
|
package/dist/testing.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { M as UsageTotals, O as ToolCallRecord, a as Engine, c as FinishReason, l as GenerateOptions, u as GenerateResult } from "./types-CLigYA62.js";
|
|
2
2
|
|
|
3
3
|
//#region src/testing/engine_from_generate.d.ts
|
|
4
4
|
/**
|
package/dist/testing.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import
|
|
1
|
+
import { O as aborted_error } from "./core-DdJEhyQc.js";
|
|
2
|
+
import "./engine-CdXegeqC.js";
|
|
3
|
+
import { y as schema_validation_error } from "./leading_system-BUCT-PwD.js";
|
|
3
4
|
//#region src/testing/engine_from_generate.ts
|
|
4
5
|
/**
|
|
5
6
|
* Build an `Engine` whose only live member is the supplied `generate`.
|
package/dist/testing.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"testing.js","names":[],"sources":["../src/testing/engine_from_generate.ts","../src/testing/make_capture_engine.ts","../src/testing/canned.ts","../src/testing/make_script_engine.ts","../src/testing/make_stub_engine.ts","../src/testing/text_of.ts"],"sourcesContent":["/**\n * Wrap a canned `generate` function in a complete `Engine`.\n *\n * The remaining members are inert: pricing calls are no-ops that resolve\n * nothing, `dispose` resolves immediately, and `with_providers` throws\n * because a canned engine has no provider registry to derive from. Both\n * testing factories share this shell so a test double differs from a real\n * engine only in how `generate` answers.\n */\n\nimport type { Engine } from '#engine'\n\n/**\n * Build an `Engine` whose only live member is the supplied `generate`.\n *\n * A custom double MUST implement only `generate`: accept `GenerateOptions`\n * and resolve a complete `GenerateResult` (content, tool_calls, steps,\n * usage, finish_reason, model_resolved). Honoring `opts.abort`,\n * `opts.on_chunk`, and `opts.schema` is optional; honor whichever the code\n * under test exercises. It need NOT implement pricing, `with_providers`, or\n * `dispose`: this shell supplies the inert versions.\n */\nexport function engine_from_generate(generate: Engine['generate']): Engine {\n return {\n generate,\n register_price: () => {},\n resolve_price: () => undefined,\n list_prices: () => ({}),\n with_providers: () => {\n throw new Error('testing engines do not support with_providers')\n },\n dispose: async () => {},\n }\n}\n","/**\n * make_capture_engine: an `Engine` that records every generate call.\n *\n * Returns the engine together with the live `calls` array, which receives\n * the `GenerateOptions` of each call in order. Every call resolves with the\n * same canned result (`options.result`, or a minimal `'ok'` result), so the\n * double is for asserting what reached the engine, not for scripting\n * multi-role conversations: that is `make_stub_engine`'s job.\n *\n * `options.on_generate` runs after the call is recorded and is awaited\n * before the result resolves, which is the hook for driving streaming\n * chunks, spans, or aborts against the captured options.\n */\n\nimport type { Engine, GenerateOptions, GenerateResult } from '#engine'\nimport { engine_from_generate } from './engine_from_generate.js'\n\nexport type CaptureEngineOptions = {\n readonly result?: GenerateResult<unknown>\n readonly on_generate?: (opts: GenerateOptions) => Promise<void> | void\n}\n\nexport type CaptureEngine = {\n readonly engine: Engine\n readonly calls: GenerateOptions[]\n}\n\nconst DEFAULT_RESULT: GenerateResult<unknown> = {\n content: 'ok',\n tool_calls: [],\n steps: [],\n usage: { input_tokens: 1, output_tokens: 1 },\n finish_reason: 'stop',\n model_resolved: { provider: 'stub', model_id: 'capture' },\n}\n\n/**\n * Build an `Engine` that records each call's `GenerateOptions` into the\n * returned `calls` array and answers with the canned result.\n */\nexport function make_capture_engine(options: CaptureEngineOptions = {}): CaptureEngine {\n const calls: GenerateOptions[] = []\n const result = options.result ?? DEFAULT_RESULT\n\n const engine = engine_from_generate(\n async <t = string>(opts: GenerateOptions<t>): Promise<GenerateResult<t>> => {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const loose = opts as GenerateOptions\n calls.push(loose)\n if (options.on_generate) await options.on_generate(loose)\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return result as GenerateResult<t>\n },\n )\n return { engine, calls }\n}\n","/**\n * Shared plumbing for the canned engine doubles.\n *\n * make_stub_engine and make_script_engine answer calls from fixtures rather\n * than a provider, but the surrounding contract stays the engine's: a call\n * under an already-aborted signal throws `aborted_error`, a streaming caller\n * sees chunks before the result resolves, and content that fails the\n * caller's schema surfaces as `schema_validation_error` carrying the issues.\n * Keeping that contract here keeps every double interchangeable with a real\n * engine at the seams tests exercise.\n */\n\nimport { aborted_error, schema_validation_error } from '#engine'\nimport type { FinishReason, GenerateOptions, UsageTotals } from '#engine'\n\nexport const DEFAULT_USAGE: UsageTotals = { input_tokens: 40, output_tokens: 20 }\n\n/**\n * Mirror the engine's entry guard: a generate call under an already-aborted\n * signal never reaches a provider, so a double must refuse it the same way\n * for cancellation tests to be trustworthy.\n */\nexport function throw_if_aborted(abort: AbortSignal | undefined): void {\n if (abort?.aborted === true) {\n throw new aborted_error('aborted', { reason: abort.reason })\n }\n}\n\n/**\n * Render canned content as the text a provider would have put on the wire:\n * strings pass through, everything else is serialized as JSON (which is what\n * a schema-bearing call would have streamed).\n */\nfunction render_text(content: unknown): string {\n if (typeof content === 'string') return content\n return JSON.stringify(content) ?? ''\n}\n\n/**\n * Emit the minimal chunk sequence a streaming caller expects: the whole\n * content as one text chunk, then the finish marker. Enough for model_chunk\n * trajectory events and stream-consuming UIs to fire without a network.\n */\nexport async function emit_chunks(\n on_chunk: GenerateOptions['on_chunk'],\n content: unknown,\n finish_reason: FinishReason,\n usage: UsageTotals,\n): Promise<void> {\n if (on_chunk === undefined) return\n await on_chunk({ kind: 'text', text: render_text(content), step_index: 0 })\n await on_chunk({ kind: 'finish', finish_reason, usage })\n}\n\ntype CannedIssue = {\n readonly message: string\n readonly path?: ReadonlyArray<PropertyKey>\n}\n\n/**\n * Render issues as one `path: message` line per issue, dotted the same way\n * the engine's own repair prompts and error messages format them.\n */\nfunction format_issues(issues: ReadonlyArray<CannedIssue>): string {\n return issues\n .map((issue) =>\n issue.path === undefined || issue.path.length === 0\n ? issue.message\n : `${issue.path.map(String).join('.')}: ${issue.message}`,\n )\n .join('; ')\n}\n\n/**\n * Validate canned content through the caller's schema, throwing the engine's\n * own `schema_validation_error` on failure so `instanceof` handling in the\n * code under test sees exactly what a real engine throws when its repair\n * attempts run out. Absent a schema, the content passes through untouched.\n */\nexport async function validate_canned(\n schema: GenerateOptions<unknown>['schema'],\n content: unknown,\n described: string,\n): Promise<unknown> {\n if (schema === undefined) return content\n const checked = await schema['~standard'].validate(content)\n if (checked.issues !== undefined) {\n // The spec allows a path segment to be a bare key or a `{ key }` wrapper;\n // normalize to bare keys so schema_issues reads one shape, as the real\n // engine's validator does.\n const issues: CannedIssue[] = checked.issues.map((issue) =>\n issue.path === undefined\n ? { message: issue.message }\n : {\n message: issue.message,\n path: issue.path.map((segment) =>\n typeof segment === 'object' ? segment.key : segment,\n ),\n },\n )\n throw new schema_validation_error(\n `${described} failed the caller's schema: ${format_issues(issues)}`,\n issues,\n render_text(content),\n )\n }\n return checked.value\n}\n","/**\n * make_script_engine: a queue of canned responses consumed in call order.\n *\n * Where make_stub_engine routes by system-prompt prefix and cannot tell\n * call 3 from call 1, a script cares only about order: the first generate\n * call gets the first entry, the second the next, and a call past the end\n * throws naming how many responses were scripted versus received, so a flow\n * that makes an unexpected extra model call fails loudly. That makes it the\n * double for loops that must converge, retry paths, and flows whose calls a\n * prefix cannot distinguish (a markdown-only define_agent sends no system\n * prompt at all, so every call looks alike to a stub).\n *\n * An entry is plain content, or a `ScriptResponse` object when the call\n * should carry tool calls, report a different finish reason or usage, or\n * throw a scripted error (a rate_limit_error, a provider_error) instead of\n * answering. Only an object whose keys ALL belong to the ScriptResponse\n * shape is treated as scripted; any other value, `{ verdict: 'ship' }`\n * included, becomes content as-is. Wrap literal content that collides with\n * the shape in `{ content }`.\n *\n * Scripted content is validated through the caller's schema, and the abort\n * and on_chunk contracts match make_stub_engine's; see ./canned.ts.\n */\n\nimport type {\n Engine,\n FinishReason,\n GenerateOptions,\n GenerateResult,\n ToolCallRecord,\n UsageTotals,\n} from '#engine'\nimport { DEFAULT_USAGE, emit_chunks, throw_if_aborted, validate_canned } from './canned.js'\nimport { engine_from_generate } from './engine_from_generate.js'\n\nexport type ScriptResponse = {\n readonly content?: unknown\n readonly tool_calls?: ReadonlyArray<ToolCallRecord>\n readonly finish_reason?: FinishReason\n readonly usage?: UsageTotals\n /** An error to throw for this call instead of answering. */\n readonly throw?: Error\n}\n\nexport type ScriptEngineOptions = {\n readonly usage?: UsageTotals\n readonly model_id?: string\n}\n\nconst SCRIPT_KEYS = new Set(['content', 'tool_calls', 'finish_reason', 'usage', 'throw'])\n\n/**\n * Decide whether a queue entry is a ScriptResponse or plain content. Only a\n * non-null, non-array object whose keys all belong to the ScriptResponse\n * shape is scripted, so an arbitrary content fixture with its own keys\n * passes through untouched rather than being half-read as a script entry.\n */\nfunction is_script_response(entry: unknown): entry is ScriptResponse {\n if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return false\n const keys = Object.keys(entry)\n return keys.length > 0 && keys.every((key) => SCRIPT_KEYS.has(key))\n}\n\n/**\n * Build an `Engine` that answers generate calls strictly in call order from\n * `responses`, throwing once the queue is exhausted.\n *\n * `options` mirrors make_stub_engine's: `usage` is the default usage for\n * entries that do not set their own (default `{ input_tokens: 40,\n * output_tokens: 20 }`) and `model_id` sets `model_resolved.model_id`\n * (default `'script'`). The provider always reports as `'stub'`.\n */\nexport function make_script_engine(\n responses: ReadonlyArray<unknown>,\n options: ScriptEngineOptions = {},\n): Engine {\n const default_usage = options.usage ?? DEFAULT_USAGE\n const model_id = options.model_id ?? 'script'\n let call_count = 0\n\n return engine_from_generate(\n async <t = string>(opts: GenerateOptions<t>): Promise<GenerateResult<t>> => {\n throw_if_aborted(opts.abort)\n call_count += 1\n const index = call_count - 1\n if (index >= responses.length) {\n throw new Error(\n `make_script_engine: script exhausted: ${responses.length} response(s) scripted, call ${call_count} received`,\n )\n }\n const entry = responses[index]\n const scripted: ScriptResponse = is_script_response(entry) ? entry : { content: entry }\n if (scripted.throw !== undefined) throw scripted.throw\n const usage = scripted.usage ?? default_usage\n const finish_reason = scripted.finish_reason ?? 'stop'\n // Chunks carry the raw scripted content, before validation, mirroring a\n // real stream where text flows and only then gets validated.\n await emit_chunks(opts.on_chunk, scripted.content, finish_reason, usage)\n const content = await validate_canned(\n opts.schema,\n scripted.content,\n `make_script_engine: scripted response ${index}`,\n )\n return {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n content: content as t,\n tool_calls: scripted.tool_calls === undefined ? [] : [...scripted.tool_calls],\n steps: [],\n usage,\n finish_reason,\n model_resolved: { provider: 'stub', model_id },\n }\n },\n )\n}\n","/**\n * make_stub_engine: a canned, network-free `Engine` for tests and demos.\n *\n * Each generate call is routed by the system prompt's stable first line:\n * the first canned response whose `prefix` the system prompt starts with\n * answers the call, and an unmatched system throws, so a flow that grows a\n * new model boundary fails loudly instead of silently reusing a fixture.\n * A response with the empty-string prefix matches every call, which is the\n * single-model-boundary case.\n *\n * A response's `content` may be a function of `(opts, call_index)` for\n * routes a flow hits more than once (a converging loop, a judged retry):\n * `call_index` counts how many times that route has matched before,\n * starting at 0, so each pass can answer differently.\n *\n * Canned content is validated through the caller's own schema\n * (`opts.schema['~standard'].validate`), so fixtures cannot drift from the\n * contracts they stand in for. A failure throws the engine's own\n * `schema_validation_error` carrying the issues and the canned content as\n * `raw_text`, exactly what a real engine throws when repair attempts run\n * out, so `instanceof` handling in the code under test stays testable.\n *\n * The engine's streaming and cancellation contract holds too: an\n * already-aborted `opts.abort` throws `aborted_error`, and a provided\n * `opts.on_chunk` receives the canned content as a text chunk plus a finish\n * chunk before the result resolves.\n */\n\nimport type { Engine, GenerateOptions, GenerateResult, UsageTotals } from '#engine'\nimport { DEFAULT_USAGE, emit_chunks, throw_if_aborted, validate_canned } from './canned.js'\nimport { engine_from_generate } from './engine_from_generate.js'\n\n/**\n * The function form of canned content: called with the routed call's options\n * and how many times this prefix route has matched before (starting 0). May\n * be async; the returned value is validated and answered like static content.\n */\nexport type StubContentFn = (opts: GenerateOptions, call_index: number) => unknown\n\nexport type StubResponse = {\n readonly prefix: string\n /** Static content, or a `StubContentFn` invoked per matched call. */\n readonly content: unknown\n}\n\nexport type StubEngineOptions = {\n readonly usage?: UsageTotals\n readonly model_id?: string\n}\n\n/**\n * Build an `Engine` that answers every generate call from `canned`,\n * routed by system-prompt prefix.\n *\n * `options.usage` sets the usage totals reported on every result (default\n * `{ input_tokens: 40, output_tokens: 20 }`, so cost lines render non-zero\n * numbers); `options.model_id` sets `model_resolved.model_id` (default\n * `'stub'`). The provider always reports as `'stub'`.\n */\nexport function make_stub_engine(\n canned: ReadonlyArray<StubResponse>,\n options: StubEngineOptions = {},\n): Engine {\n const usage = options.usage ?? DEFAULT_USAGE\n const model_id = options.model_id ?? 'stub'\n const match_counts = new Map<StubResponse, number>()\n\n return engine_from_generate(\n async <t = string>(opts: GenerateOptions<t>): Promise<GenerateResult<t>> => {\n throw_if_aborted(opts.abort)\n const system = opts.system ?? ''\n const match = canned.find((c) => system.startsWith(c.prefix))\n if (match === undefined) {\n throw new Error(`make_stub_engine: no canned response for system: ${system || '(none)'}`)\n }\n const call_index = match_counts.get(match) ?? 0\n match_counts.set(match, call_index + 1)\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const loose = opts as GenerateOptions\n const produced =\n typeof match.content === 'function'\n ? // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n await (match.content as StubContentFn)(loose, call_index)\n : match.content\n // Chunks carry the raw canned content, before validation, mirroring a\n // real stream where text flows and only then gets validated.\n await emit_chunks(opts.on_chunk, produced, 'stop', usage)\n const content = await validate_canned(\n opts.schema,\n produced,\n `make_stub_engine: canned response for prefix '${match.prefix}'`,\n )\n return {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n content: content as t,\n tool_calls: [],\n steps: [],\n usage,\n finish_reason: 'stop',\n model_resolved: { provider: 'stub', model_id },\n }\n },\n )\n}\n","/**\n * text_of: the user-visible prompt text of a captured GenerateOptions.\n *\n * Capture assertions care about what the model was asked, not how the prompt\n * was encoded. A prompt is a bare string or a Message[] whose user turns\n * carry either a string or typed content parts; navigating\n * `calls[0].prompt[0].content[0].text` by hand couples every assertion to\n * one encoding. System and assistant text are excluded on purpose: assert\n * those through `opts.system` and the raw messages.\n */\n\nimport type { GenerateOptions } from '#engine'\n\n/**\n * Flatten the prompt's user-facing text into one string: a string prompt\n * verbatim, otherwise every user turn's text (string content, or the `text`\n * parts of a content-part array) joined with newlines. Total: absent or\n * non-text content yields ''.\n */\nexport function text_of<t = unknown>(opts: GenerateOptions<t>): string {\n if (typeof opts.prompt === 'string') return opts.prompt\n const texts: string[] = []\n for (const message of opts.prompt) {\n if (message.role !== 'user') continue\n if (typeof message.content === 'string') {\n texts.push(message.content)\n continue\n }\n for (const part of message.content) {\n if (part.type === 'text') texts.push(part.text)\n }\n }\n return texts.join('\\n')\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"testing.js","names":[],"sources":["../src/testing/engine_from_generate.ts","../src/testing/make_capture_engine.ts","../src/testing/canned.ts","../src/testing/make_script_engine.ts","../src/testing/make_stub_engine.ts","../src/testing/text_of.ts"],"sourcesContent":["/**\n * Wrap a canned `generate` function in a complete `Engine`.\n *\n * The remaining members are inert: pricing calls are no-ops that resolve\n * nothing, `dispose` resolves immediately, and `with_providers` throws\n * because a canned engine has no provider registry to derive from. Both\n * testing factories share this shell so a test double differs from a real\n * engine only in how `generate` answers.\n */\n\nimport type { Engine } from '#engine'\n\n/**\n * Build an `Engine` whose only live member is the supplied `generate`.\n *\n * A custom double MUST implement only `generate`: accept `GenerateOptions`\n * and resolve a complete `GenerateResult` (content, tool_calls, steps,\n * usage, finish_reason, model_resolved). Honoring `opts.abort`,\n * `opts.on_chunk`, and `opts.schema` is optional; honor whichever the code\n * under test exercises. It need NOT implement pricing, `with_providers`, or\n * `dispose`: this shell supplies the inert versions.\n */\nexport function engine_from_generate(generate: Engine['generate']): Engine {\n return {\n generate,\n register_price: () => {},\n resolve_price: () => undefined,\n list_prices: () => ({}),\n with_providers: () => {\n throw new Error('testing engines do not support with_providers')\n },\n dispose: async () => {},\n }\n}\n","/**\n * make_capture_engine: an `Engine` that records every generate call.\n *\n * Returns the engine together with the live `calls` array, which receives\n * the `GenerateOptions` of each call in order. Every call resolves with the\n * same canned result (`options.result`, or a minimal `'ok'` result), so the\n * double is for asserting what reached the engine, not for scripting\n * multi-role conversations: that is `make_stub_engine`'s job.\n *\n * `options.on_generate` runs after the call is recorded and is awaited\n * before the result resolves, which is the hook for driving streaming\n * chunks, spans, or aborts against the captured options.\n */\n\nimport type { Engine, GenerateOptions, GenerateResult } from '#engine'\nimport { engine_from_generate } from './engine_from_generate.js'\n\nexport type CaptureEngineOptions = {\n readonly result?: GenerateResult<unknown>\n readonly on_generate?: (opts: GenerateOptions) => Promise<void> | void\n}\n\nexport type CaptureEngine = {\n readonly engine: Engine\n readonly calls: GenerateOptions[]\n}\n\nconst DEFAULT_RESULT: GenerateResult<unknown> = {\n content: 'ok',\n tool_calls: [],\n steps: [],\n usage: { input_tokens: 1, output_tokens: 1 },\n finish_reason: 'stop',\n model_resolved: { provider: 'stub', model_id: 'capture' },\n}\n\n/**\n * Build an `Engine` that records each call's `GenerateOptions` into the\n * returned `calls` array and answers with the canned result.\n */\nexport function make_capture_engine(options: CaptureEngineOptions = {}): CaptureEngine {\n const calls: GenerateOptions[] = []\n const result = options.result ?? DEFAULT_RESULT\n\n const engine = engine_from_generate(\n async <t = string>(opts: GenerateOptions<t>): Promise<GenerateResult<t>> => {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const loose = opts as GenerateOptions\n calls.push(loose)\n if (options.on_generate) await options.on_generate(loose)\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return result as GenerateResult<t>\n },\n )\n return { engine, calls }\n}\n","/**\n * Shared plumbing for the canned engine doubles.\n *\n * make_stub_engine and make_script_engine answer calls from fixtures rather\n * than a provider, but the surrounding contract stays the engine's: a call\n * under an already-aborted signal throws `aborted_error`, a streaming caller\n * sees chunks before the result resolves, and content that fails the\n * caller's schema surfaces as `schema_validation_error` carrying the issues.\n * Keeping that contract here keeps every double interchangeable with a real\n * engine at the seams tests exercise.\n */\n\nimport { aborted_error, schema_validation_error } from '#engine'\nimport type { FinishReason, GenerateOptions, UsageTotals } from '#engine'\n\nexport const DEFAULT_USAGE: UsageTotals = { input_tokens: 40, output_tokens: 20 }\n\n/**\n * Mirror the engine's entry guard: a generate call under an already-aborted\n * signal never reaches a provider, so a double must refuse it the same way\n * for cancellation tests to be trustworthy.\n */\nexport function throw_if_aborted(abort: AbortSignal | undefined): void {\n if (abort?.aborted === true) {\n throw new aborted_error('aborted', { reason: abort.reason })\n }\n}\n\n/**\n * Render canned content as the text a provider would have put on the wire:\n * strings pass through, everything else is serialized as JSON (which is what\n * a schema-bearing call would have streamed).\n */\nfunction render_text(content: unknown): string {\n if (typeof content === 'string') return content\n return JSON.stringify(content) ?? ''\n}\n\n/**\n * Emit the minimal chunk sequence a streaming caller expects: the whole\n * content as one text chunk, then the finish marker. Enough for model_chunk\n * trajectory events and stream-consuming UIs to fire without a network.\n */\nexport async function emit_chunks(\n on_chunk: GenerateOptions['on_chunk'],\n content: unknown,\n finish_reason: FinishReason,\n usage: UsageTotals,\n): Promise<void> {\n if (on_chunk === undefined) return\n await on_chunk({ kind: 'text', text: render_text(content), step_index: 0 })\n await on_chunk({ kind: 'finish', finish_reason, usage })\n}\n\ntype CannedIssue = {\n readonly message: string\n readonly path?: ReadonlyArray<PropertyKey>\n}\n\n/**\n * Render issues as one `path: message` line per issue, dotted the same way\n * the engine's own repair prompts and error messages format them.\n */\nfunction format_issues(issues: ReadonlyArray<CannedIssue>): string {\n return issues\n .map((issue) =>\n issue.path === undefined || issue.path.length === 0\n ? issue.message\n : `${issue.path.map(String).join('.')}: ${issue.message}`,\n )\n .join('; ')\n}\n\n/**\n * Validate canned content through the caller's schema, throwing the engine's\n * own `schema_validation_error` on failure so `instanceof` handling in the\n * code under test sees exactly what a real engine throws when its repair\n * attempts run out. Absent a schema, the content passes through untouched.\n */\nexport async function validate_canned(\n schema: GenerateOptions<unknown>['schema'],\n content: unknown,\n described: string,\n): Promise<unknown> {\n if (schema === undefined) return content\n const checked = await schema['~standard'].validate(content)\n if (checked.issues !== undefined) {\n // The spec allows a path segment to be a bare key or a `{ key }` wrapper;\n // normalize to bare keys so schema_issues reads one shape, as the real\n // engine's validator does.\n const issues: CannedIssue[] = checked.issues.map((issue) =>\n issue.path === undefined\n ? { message: issue.message }\n : {\n message: issue.message,\n path: issue.path.map((segment) =>\n typeof segment === 'object' ? segment.key : segment,\n ),\n },\n )\n throw new schema_validation_error(\n `${described} failed the caller's schema: ${format_issues(issues)}`,\n issues,\n render_text(content),\n )\n }\n return checked.value\n}\n","/**\n * make_script_engine: a queue of canned responses consumed in call order.\n *\n * Where make_stub_engine routes by system-prompt prefix and cannot tell\n * call 3 from call 1, a script cares only about order: the first generate\n * call gets the first entry, the second the next, and a call past the end\n * throws naming how many responses were scripted versus received, so a flow\n * that makes an unexpected extra model call fails loudly. That makes it the\n * double for loops that must converge, retry paths, and flows whose calls a\n * prefix cannot distinguish (a markdown-only define_agent sends no system\n * prompt at all, so every call looks alike to a stub).\n *\n * An entry is plain content, or a `ScriptResponse` object when the call\n * should carry tool calls, report a different finish reason or usage, or\n * throw a scripted error (a rate_limit_error, a provider_error) instead of\n * answering. Only an object whose keys ALL belong to the ScriptResponse\n * shape is treated as scripted; any other value, `{ verdict: 'ship' }`\n * included, becomes content as-is. Wrap literal content that collides with\n * the shape in `{ content }`.\n *\n * Scripted content is validated through the caller's schema, and the abort\n * and on_chunk contracts match make_stub_engine's; see ./canned.ts.\n */\n\nimport type {\n Engine,\n FinishReason,\n GenerateOptions,\n GenerateResult,\n ToolCallRecord,\n UsageTotals,\n} from '#engine'\nimport { DEFAULT_USAGE, emit_chunks, throw_if_aborted, validate_canned } from './canned.js'\nimport { engine_from_generate } from './engine_from_generate.js'\n\nexport type ScriptResponse = {\n readonly content?: unknown\n readonly tool_calls?: ReadonlyArray<ToolCallRecord>\n readonly finish_reason?: FinishReason\n readonly usage?: UsageTotals\n /** An error to throw for this call instead of answering. */\n readonly throw?: Error\n}\n\nexport type ScriptEngineOptions = {\n readonly usage?: UsageTotals\n readonly model_id?: string\n}\n\nconst SCRIPT_KEYS = new Set(['content', 'tool_calls', 'finish_reason', 'usage', 'throw'])\n\n/**\n * Decide whether a queue entry is a ScriptResponse or plain content. Only a\n * non-null, non-array object whose keys all belong to the ScriptResponse\n * shape is scripted, so an arbitrary content fixture with its own keys\n * passes through untouched rather than being half-read as a script entry.\n */\nfunction is_script_response(entry: unknown): entry is ScriptResponse {\n if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return false\n const keys = Object.keys(entry)\n return keys.length > 0 && keys.every((key) => SCRIPT_KEYS.has(key))\n}\n\n/**\n * Build an `Engine` that answers generate calls strictly in call order from\n * `responses`, throwing once the queue is exhausted.\n *\n * `options` mirrors make_stub_engine's: `usage` is the default usage for\n * entries that do not set their own (default `{ input_tokens: 40,\n * output_tokens: 20 }`) and `model_id` sets `model_resolved.model_id`\n * (default `'script'`). The provider always reports as `'stub'`.\n */\nexport function make_script_engine(\n responses: ReadonlyArray<unknown>,\n options: ScriptEngineOptions = {},\n): Engine {\n const default_usage = options.usage ?? DEFAULT_USAGE\n const model_id = options.model_id ?? 'script'\n let call_count = 0\n\n return engine_from_generate(\n async <t = string>(opts: GenerateOptions<t>): Promise<GenerateResult<t>> => {\n throw_if_aborted(opts.abort)\n call_count += 1\n const index = call_count - 1\n if (index >= responses.length) {\n throw new Error(\n `make_script_engine: script exhausted: ${responses.length} response(s) scripted, call ${call_count} received`,\n )\n }\n const entry = responses[index]\n const scripted: ScriptResponse = is_script_response(entry) ? entry : { content: entry }\n if (scripted.throw !== undefined) throw scripted.throw\n const usage = scripted.usage ?? default_usage\n const finish_reason = scripted.finish_reason ?? 'stop'\n // Chunks carry the raw scripted content, before validation, mirroring a\n // real stream where text flows and only then gets validated.\n await emit_chunks(opts.on_chunk, scripted.content, finish_reason, usage)\n const content = await validate_canned(\n opts.schema,\n scripted.content,\n `make_script_engine: scripted response ${index}`,\n )\n return {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n content: content as t,\n tool_calls: scripted.tool_calls === undefined ? [] : [...scripted.tool_calls],\n steps: [],\n usage,\n finish_reason,\n model_resolved: { provider: 'stub', model_id },\n }\n },\n )\n}\n","/**\n * make_stub_engine: a canned, network-free `Engine` for tests and demos.\n *\n * Each generate call is routed by the system prompt's stable first line:\n * the first canned response whose `prefix` the system prompt starts with\n * answers the call, and an unmatched system throws, so a flow that grows a\n * new model boundary fails loudly instead of silently reusing a fixture.\n * A response with the empty-string prefix matches every call, which is the\n * single-model-boundary case.\n *\n * A response's `content` may be a function of `(opts, call_index)` for\n * routes a flow hits more than once (a converging loop, a judged retry):\n * `call_index` counts how many times that route has matched before,\n * starting at 0, so each pass can answer differently.\n *\n * Canned content is validated through the caller's own schema\n * (`opts.schema['~standard'].validate`), so fixtures cannot drift from the\n * contracts they stand in for. A failure throws the engine's own\n * `schema_validation_error` carrying the issues and the canned content as\n * `raw_text`, exactly what a real engine throws when repair attempts run\n * out, so `instanceof` handling in the code under test stays testable.\n *\n * The engine's streaming and cancellation contract holds too: an\n * already-aborted `opts.abort` throws `aborted_error`, and a provided\n * `opts.on_chunk` receives the canned content as a text chunk plus a finish\n * chunk before the result resolves.\n */\n\nimport type { Engine, GenerateOptions, GenerateResult, UsageTotals } from '#engine'\nimport { DEFAULT_USAGE, emit_chunks, throw_if_aborted, validate_canned } from './canned.js'\nimport { engine_from_generate } from './engine_from_generate.js'\n\n/**\n * The function form of canned content: called with the routed call's options\n * and how many times this prefix route has matched before (starting 0). May\n * be async; the returned value is validated and answered like static content.\n */\nexport type StubContentFn = (opts: GenerateOptions, call_index: number) => unknown\n\nexport type StubResponse = {\n readonly prefix: string\n /** Static content, or a `StubContentFn` invoked per matched call. */\n readonly content: unknown\n}\n\nexport type StubEngineOptions = {\n readonly usage?: UsageTotals\n readonly model_id?: string\n}\n\n/**\n * Build an `Engine` that answers every generate call from `canned`,\n * routed by system-prompt prefix.\n *\n * `options.usage` sets the usage totals reported on every result (default\n * `{ input_tokens: 40, output_tokens: 20 }`, so cost lines render non-zero\n * numbers); `options.model_id` sets `model_resolved.model_id` (default\n * `'stub'`). The provider always reports as `'stub'`.\n */\nexport function make_stub_engine(\n canned: ReadonlyArray<StubResponse>,\n options: StubEngineOptions = {},\n): Engine {\n const usage = options.usage ?? DEFAULT_USAGE\n const model_id = options.model_id ?? 'stub'\n const match_counts = new Map<StubResponse, number>()\n\n return engine_from_generate(\n async <t = string>(opts: GenerateOptions<t>): Promise<GenerateResult<t>> => {\n throw_if_aborted(opts.abort)\n const system = opts.system ?? ''\n const match = canned.find((c) => system.startsWith(c.prefix))\n if (match === undefined) {\n throw new Error(`make_stub_engine: no canned response for system: ${system || '(none)'}`)\n }\n const call_index = match_counts.get(match) ?? 0\n match_counts.set(match, call_index + 1)\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const loose = opts as GenerateOptions\n const produced =\n typeof match.content === 'function'\n ? // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n await (match.content as StubContentFn)(loose, call_index)\n : match.content\n // Chunks carry the raw canned content, before validation, mirroring a\n // real stream where text flows and only then gets validated.\n await emit_chunks(opts.on_chunk, produced, 'stop', usage)\n const content = await validate_canned(\n opts.schema,\n produced,\n `make_stub_engine: canned response for prefix '${match.prefix}'`,\n )\n return {\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n content: content as t,\n tool_calls: [],\n steps: [],\n usage,\n finish_reason: 'stop',\n model_resolved: { provider: 'stub', model_id },\n }\n },\n )\n}\n","/**\n * text_of: the user-visible prompt text of a captured GenerateOptions.\n *\n * Capture assertions care about what the model was asked, not how the prompt\n * was encoded. A prompt is a bare string or a Message[] whose user turns\n * carry either a string or typed content parts; navigating\n * `calls[0].prompt[0].content[0].text` by hand couples every assertion to\n * one encoding. System and assistant text are excluded on purpose: assert\n * those through `opts.system` and the raw messages.\n */\n\nimport type { GenerateOptions } from '#engine'\n\n/**\n * Flatten the prompt's user-facing text into one string: a string prompt\n * verbatim, otherwise every user turn's text (string content, or the `text`\n * parts of a content-part array) joined with newlines. Total: absent or\n * non-text content yields ''.\n */\nexport function text_of<t = unknown>(opts: GenerateOptions<t>): string {\n if (typeof opts.prompt === 'string') return opts.prompt\n const texts: string[] = []\n for (const message of opts.prompt) {\n if (message.role !== 'user') continue\n if (typeof message.content === 'string') {\n texts.push(message.content)\n continue\n }\n for (const part of message.content) {\n if (part.type === 'text') texts.push(part.text)\n }\n }\n return texts.join('\\n')\n}\n"],"mappings":"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"}
|
|
@@ -7,15 +7,15 @@
|
|
|
7
7
|
* conforming to it. This file defines the *narrower* shapes that the studio
|
|
8
8
|
* (and any other downstream consumer) can recognize in the wire stream:
|
|
9
9
|
*
|
|
10
|
-
* span_start
|
|
11
|
-
* span_end
|
|
12
|
-
* emit
|
|
13
|
-
* run_end
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* checkpoint
|
|
17
|
-
* <other
|
|
18
|
-
*
|
|
10
|
+
* span_start: composer span open
|
|
11
|
+
* span_end: composer span close
|
|
12
|
+
* emit: user-emitted event from inside a step (ctx.emit)
|
|
13
|
+
* run_end: terminal run event carrying the run's status, so a consumer
|
|
14
|
+
* distinguishes done / failed / aborted / suspended without
|
|
15
|
+
* inferring from silence
|
|
16
|
+
* checkpoint: checkpoint store lookup outcome (hit / miss / read_error)
|
|
17
|
+
* <other>: anything else, recognized by `is_custom_trajectory_event`,
|
|
18
|
+
* which only requires a string `kind`
|
|
19
19
|
*
|
|
20
20
|
* `parse_trajectory_event` is the wire gate, and it is deliberately permissive:
|
|
21
21
|
* a value is a trajectory event iff it is a non-array object carrying a string
|
|
@@ -111,4 +111,4 @@ declare function is_checkpoint_event(value: unknown): value is CheckpointEvent;
|
|
|
111
111
|
declare function parse_trajectory_event(value: unknown): TrajectoryParseResult;
|
|
112
112
|
//#endregion
|
|
113
113
|
export { parse_trajectory_event as _, ParsedTrajectoryEvent as a, SpanEndEvent as c, is_checkpoint_event as d, is_custom_trajectory_event as f, is_span_start_event as g, is_span_end_event as h, EmitEvent as i, SpanStartEvent as l, is_run_end_event as m, CheckpointStatus as n, RunEndEvent as o, is_emit_event as p, CustomTrajectoryEvent as r, RunEndStatus as s, CheckpointEvent as t, TrajectoryParseResult as u };
|
|
114
|
-
//# sourceMappingURL=trajectory-
|
|
114
|
+
//# sourceMappingURL=trajectory-ByoOQZ6T.d.ts.map
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
//#region src/core/trajectory.ts
|
|
2
|
+
/**
|
|
3
|
+
* The wire gate: a non-array object carrying a string `kind`.
|
|
4
|
+
*
|
|
5
|
+
* True for every well-known kind as well, since `custom` is the fallback shape
|
|
6
|
+
* rather than a disjoint case.
|
|
7
|
+
*/
|
|
8
|
+
function is_custom_trajectory_event(value) {
|
|
9
|
+
if (typeof value !== "object" || value === null) return false;
|
|
10
|
+
if (Array.isArray(value)) return false;
|
|
11
|
+
return typeof value.kind === "string";
|
|
12
|
+
}
|
|
13
|
+
/** A composer span open: both `span_id` and `name` must be present as strings. */
|
|
14
|
+
function is_span_start_event(value) {
|
|
15
|
+
if (!is_custom_trajectory_event(value)) return false;
|
|
16
|
+
if (value.kind !== "span_start") return false;
|
|
17
|
+
return typeof value["span_id"] === "string" && typeof value["name"] === "string";
|
|
18
|
+
}
|
|
19
|
+
/** A composer span close: `span_id` must be present as a string, `name` need not be. */
|
|
20
|
+
function is_span_end_event(value) {
|
|
21
|
+
if (!is_custom_trajectory_event(value)) return false;
|
|
22
|
+
return value.kind === "span_end" && typeof value["span_id"] === "string";
|
|
23
|
+
}
|
|
24
|
+
/** A `ctx.emit` event: the kind alone identifies it, the payload is the caller's. */
|
|
25
|
+
function is_emit_event(value) {
|
|
26
|
+
return is_custom_trajectory_event(value) && value.kind === "emit";
|
|
27
|
+
}
|
|
28
|
+
const RUN_END_STATUSES = /* @__PURE__ */ new Set([
|
|
29
|
+
"done",
|
|
30
|
+
"failed",
|
|
31
|
+
"aborted",
|
|
32
|
+
"suspended"
|
|
33
|
+
]);
|
|
34
|
+
/**
|
|
35
|
+
* A terminal run event: `status` must be one of the known run outcomes, so the
|
|
36
|
+
* narrowed type's `status` union is truthful. An unknown future status still
|
|
37
|
+
* passes the wire gate as a custom event.
|
|
38
|
+
*/
|
|
39
|
+
function is_run_end_event(value) {
|
|
40
|
+
if (!is_custom_trajectory_event(value)) return false;
|
|
41
|
+
if (value.kind !== "run_end") return false;
|
|
42
|
+
const status = value["status"];
|
|
43
|
+
return typeof status === "string" && RUN_END_STATUSES.has(status);
|
|
44
|
+
}
|
|
45
|
+
const CHECKPOINT_STATUSES = /* @__PURE__ */ new Set([
|
|
46
|
+
"hit",
|
|
47
|
+
"miss",
|
|
48
|
+
"read_error"
|
|
49
|
+
]);
|
|
50
|
+
/**
|
|
51
|
+
* A checkpoint lookup event: `status` must be a known lookup outcome and `key`
|
|
52
|
+
* the store key that was consulted, for the same truthful-narrowing reason as
|
|
53
|
+
* `is_run_end_event`.
|
|
54
|
+
*/
|
|
55
|
+
function is_checkpoint_event(value) {
|
|
56
|
+
if (!is_custom_trajectory_event(value)) return false;
|
|
57
|
+
if (value.kind !== "checkpoint") return false;
|
|
58
|
+
const status = value["status"];
|
|
59
|
+
if (typeof status !== "string" || !CHECKPOINT_STATUSES.has(status)) return false;
|
|
60
|
+
return typeof value["key"] === "string";
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Parse one wire value into a trajectory event, `safeParse`-shaped.
|
|
64
|
+
*
|
|
65
|
+
* On success `data` is the value itself, not a copy, so nothing on the line is
|
|
66
|
+
* dropped or reordered on the way through.
|
|
67
|
+
*/
|
|
68
|
+
function parse_trajectory_event(value) {
|
|
69
|
+
if (!is_custom_trajectory_event(value)) return {
|
|
70
|
+
success: false,
|
|
71
|
+
error: /* @__PURE__ */ new Error("not a trajectory event: expected an object with a string 'kind'")
|
|
72
|
+
};
|
|
73
|
+
return {
|
|
74
|
+
success: true,
|
|
75
|
+
data: value
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
//#endregion
|
|
79
|
+
export { is_span_end_event as a, is_run_end_event as i, is_custom_trajectory_event as n, is_span_start_event as o, is_emit_event as r, parse_trajectory_event as s, is_checkpoint_event as t };
|
|
80
|
+
|
|
81
|
+
//# sourceMappingURL=trajectory-D1eq9eue.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"trajectory-D1eq9eue.js","names":[],"sources":["../src/core/trajectory.ts"],"sourcesContent":["/**\n * Wire-format guards for trajectory events.\n *\n * `TrajectoryEvent` (in `types.ts`) is the loose internal type — any code that\n * calls `trajectory.record(event)` or `start_span(name, meta)` produces values\n * conforming to it. This file defines the *narrower* shapes that the studio\n * (and any other downstream consumer) can recognize in the wire stream:\n *\n * span_start: composer span open\n * span_end: composer span close\n * emit: user-emitted event from inside a step (ctx.emit)\n * run_end: terminal run event carrying the run's status, so a consumer\n * distinguishes done / failed / aborted / suspended without\n * inferring from silence\n * checkpoint: checkpoint store lookup outcome (hit / miss / read_error)\n * <other>: anything else, recognized by `is_custom_trajectory_event`,\n * which only requires a string `kind`\n *\n * `parse_trajectory_event` is the wire gate, and it is deliberately permissive:\n * a value is a trajectory event iff it is a non-array object carrying a string\n * `kind`. The well-known guards layered on top are *recognizers*, not gates — a\n * `{ kind: 'span_start' }` line missing its `span_id` is still a valid event on\n * the wire, just not a `SpanStartEvent`. Anything stricter would have a viewer\n * drop lines a newer producer emits, which is the opposite of what a\n * forward-compatible wire format is for. `is_custom_trajectory_event` therefore\n * answers `true` for well-known kinds too: it is the fallback shape, not a\n * fifth disjoint case.\n *\n * Extra fields (`run_id`, `id`, provider-specific metadata) are neither\n * required nor stripped: a successful parse hands the value straight back, so a\n * parse / re-serialize round trip is lossless.\n */\n\nexport type SpanStartEvent = {\n readonly kind: 'span_start'\n readonly span_id: string\n readonly name: string\n} & { readonly [key: string]: unknown }\n\nexport type SpanEndEvent = {\n readonly kind: 'span_end'\n readonly span_id: string\n} & { readonly [key: string]: unknown }\n\nexport type EmitEvent = {\n readonly kind: 'emit'\n} & { readonly [key: string]: unknown }\n\nexport type RunEndStatus = 'done' | 'failed' | 'aborted' | 'suspended'\n\nexport type RunEndEvent = {\n readonly kind: 'run_end'\n readonly status: RunEndStatus\n} & { readonly [key: string]: unknown }\n\nexport type CheckpointStatus = 'hit' | 'miss' | 'read_error'\n\nexport type CheckpointEvent = {\n readonly kind: 'checkpoint'\n readonly status: CheckpointStatus\n readonly key: string\n} & { readonly [key: string]: unknown }\n\nexport type CustomTrajectoryEvent = {\n readonly kind: string\n} & { readonly [key: string]: unknown }\n\nexport type ParsedTrajectoryEvent =\n | SpanStartEvent\n | SpanEndEvent\n | EmitEvent\n | RunEndEvent\n | CheckpointEvent\n | CustomTrajectoryEvent\n\nexport type TrajectoryParseResult =\n | { readonly success: true; readonly data: ParsedTrajectoryEvent }\n | { readonly success: false; readonly error: Error }\n\n/**\n * The wire gate: a non-array object carrying a string `kind`.\n *\n * True for every well-known kind as well, since `custom` is the fallback shape\n * rather than a disjoint case.\n */\nexport function is_custom_trajectory_event(value: unknown): value is CustomTrajectoryEvent {\n if (typeof value !== 'object' || value === null) return false\n if (Array.isArray(value)) return false\n return typeof (value as { kind?: unknown }).kind === 'string'\n}\n\n/** A composer span open: both `span_id` and `name` must be present as strings. */\nexport function is_span_start_event(value: unknown): value is SpanStartEvent {\n if (!is_custom_trajectory_event(value)) return false\n if (value.kind !== 'span_start') return false\n return typeof value['span_id'] === 'string' && typeof value['name'] === 'string'\n}\n\n/** A composer span close: `span_id` must be present as a string, `name` need not be. */\nexport function is_span_end_event(value: unknown): value is SpanEndEvent {\n if (!is_custom_trajectory_event(value)) return false\n return value.kind === 'span_end' && typeof value['span_id'] === 'string'\n}\n\n/** A `ctx.emit` event: the kind alone identifies it, the payload is the caller's. */\nexport function is_emit_event(value: unknown): value is EmitEvent {\n return is_custom_trajectory_event(value) && value.kind === 'emit'\n}\n\nconst RUN_END_STATUSES: ReadonlySet<string> = new Set(['done', 'failed', 'aborted', 'suspended'])\n\n/**\n * A terminal run event: `status` must be one of the known run outcomes, so the\n * narrowed type's `status` union is truthful. An unknown future status still\n * passes the wire gate as a custom event.\n */\nexport function is_run_end_event(value: unknown): value is RunEndEvent {\n if (!is_custom_trajectory_event(value)) return false\n if (value.kind !== 'run_end') return false\n const status = value['status']\n return typeof status === 'string' && RUN_END_STATUSES.has(status)\n}\n\nconst CHECKPOINT_STATUSES: ReadonlySet<string> = new Set(['hit', 'miss', 'read_error'])\n\n/**\n * A checkpoint lookup event: `status` must be a known lookup outcome and `key`\n * the store key that was consulted, for the same truthful-narrowing reason as\n * `is_run_end_event`.\n */\nexport function is_checkpoint_event(value: unknown): value is CheckpointEvent {\n if (!is_custom_trajectory_event(value)) return false\n if (value.kind !== 'checkpoint') return false\n const status = value['status']\n if (typeof status !== 'string' || !CHECKPOINT_STATUSES.has(status)) return false\n return typeof value['key'] === 'string'\n}\n\n/**\n * Parse one wire value into a trajectory event, `safeParse`-shaped.\n *\n * On success `data` is the value itself, not a copy, so nothing on the line is\n * dropped or reordered on the way through.\n */\nexport function parse_trajectory_event(value: unknown): TrajectoryParseResult {\n if (!is_custom_trajectory_event(value)) {\n return {\n success: false,\n error: new Error(\"not a trajectory event: expected an object with a string 'kind'\"),\n }\n }\n return { success: true, data: value }\n}\n"],"mappings":";;;;;;;AAqFA,SAAgB,2BAA2B,OAAgD;CACzF,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;CACjC,OAAO,OAAQ,MAA6B,SAAS;AACvD;;AAGA,SAAgB,oBAAoB,OAAyC;CAC3E,IAAI,CAAC,2BAA2B,KAAK,GAAG,OAAO;CAC/C,IAAI,MAAM,SAAS,cAAc,OAAO;CACxC,OAAO,OAAO,MAAM,eAAe,YAAY,OAAO,MAAM,YAAY;AAC1E;;AAGA,SAAgB,kBAAkB,OAAuC;CACvE,IAAI,CAAC,2BAA2B,KAAK,GAAG,OAAO;CAC/C,OAAO,MAAM,SAAS,cAAc,OAAO,MAAM,eAAe;AAClE;;AAGA,SAAgB,cAAc,OAAoC;CAChE,OAAO,2BAA2B,KAAK,KAAK,MAAM,SAAS;AAC7D;AAEA,MAAM,mCAAwC,IAAI,IAAI;CAAC;CAAQ;CAAU;CAAW;AAAW,CAAC;;;;;;AAOhG,SAAgB,iBAAiB,OAAsC;CACrE,IAAI,CAAC,2BAA2B,KAAK,GAAG,OAAO;CAC/C,IAAI,MAAM,SAAS,WAAW,OAAO;CACrC,MAAM,SAAS,MAAM;CACrB,OAAO,OAAO,WAAW,YAAY,iBAAiB,IAAI,MAAM;AAClE;AAEA,MAAM,sCAA2C,IAAI,IAAI;CAAC;CAAO;CAAQ;AAAY,CAAC;;;;;;AAOtF,SAAgB,oBAAoB,OAA0C;CAC5E,IAAI,CAAC,2BAA2B,KAAK,GAAG,OAAO;CAC/C,IAAI,MAAM,SAAS,cAAc,OAAO;CACxC,MAAM,SAAS,MAAM;CACrB,IAAI,OAAO,WAAW,YAAY,CAAC,oBAAoB,IAAI,MAAM,GAAG,OAAO;CAC3E,OAAO,OAAO,MAAM,WAAW;AACjC;;;;;;;AAQA,SAAgB,uBAAuB,OAAuC;CAC5E,IAAI,CAAC,2BAA2B,KAAK,GACnC,OAAO;EACL,SAAS;EACT,uBAAO,IAAI,MAAM,iEAAiE;CACpF;CAEF,OAAO;EAAE,SAAS;EAAM,MAAM;CAAM;AACtC"}
|
|
@@ -117,10 +117,10 @@ declare namespace StandardJSONSchemaV1 {
|
|
|
117
117
|
//#endregion
|
|
118
118
|
//#region src/schema/types.d.ts
|
|
119
119
|
/**
|
|
120
|
-
* Any Standard Schema implementation, used where
|
|
120
|
+
* Any Standard Schema implementation, used where Fascicle only ever validates.
|
|
121
121
|
*
|
|
122
122
|
* `t` is the validated output type, which is what callers care about; the input
|
|
123
|
-
* side stays `unknown` because
|
|
123
|
+
* side stays `unknown` because Fascicle validates values arriving from a model,
|
|
124
124
|
* a resume payload, or stdin, none of which are typed at the boundary.
|
|
125
125
|
*/
|
|
126
126
|
type AnySchema<t = unknown> = StandardSchemaV1<unknown, t>;
|
|
@@ -146,4 +146,4 @@ type SchemaIssue = {
|
|
|
146
146
|
};
|
|
147
147
|
//#endregion
|
|
148
148
|
export { SchemaIssue as n, ToolSchema as r, AnySchema as t };
|
|
149
|
-
//# sourceMappingURL=types-
|
|
149
|
+
//# sourceMappingURL=types-BK0UW28o.d.ts.map
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { d as TrajectoryLogger } from "./types-
|
|
2
|
-
import { r as ToolSchema } from "./types-
|
|
1
|
+
import { d as TrajectoryLogger } from "./types-DBpU27sQ.js";
|
|
2
|
+
import { r as ToolSchema } from "./types-BK0UW28o.js";
|
|
3
3
|
|
|
4
4
|
//#region src/engine/providers/claude_cli/types.d.ts
|
|
5
5
|
/**
|
|
@@ -164,6 +164,20 @@ type CostBreakdown = {
|
|
|
164
164
|
is_estimate: true;
|
|
165
165
|
};
|
|
166
166
|
type SalvageFormat = 'hermes' | 'json' | 'qwen_xml';
|
|
167
|
+
/**
|
|
168
|
+
* Wall-clock timing of one step's provider round-trip, measured by the engine
|
|
169
|
+
* around the successful turn attempt: failed attempts and retry backoff are
|
|
170
|
+
* excluded, as is tool execution (that is ToolCallRecord.duration_ms).
|
|
171
|
+
* `first_chunk_ms` is present only on streamed turns: milliseconds from the
|
|
172
|
+
* attempt start to the first chunk, so `duration_ms - first_chunk_ms` is the
|
|
173
|
+
* window the model spent emitting output. See `throughput()` for the derived
|
|
174
|
+
* tokens-per-second view.
|
|
175
|
+
*/
|
|
176
|
+
type StepTiming = {
|
|
177
|
+
/** Epoch ms when the successful provider attempt started. */started_at: number; /** Wall-clock ms from attempt start to the turn result. */
|
|
178
|
+
duration_ms: number; /** Streamed turns only: ms from attempt start to the first chunk. */
|
|
179
|
+
first_chunk_ms?: number;
|
|
180
|
+
};
|
|
167
181
|
type ToolCallRecord = {
|
|
168
182
|
id: string;
|
|
169
183
|
name: string;
|
|
@@ -188,6 +202,12 @@ type StepRecord = {
|
|
|
188
202
|
tool_calls: ToolCallRecord[];
|
|
189
203
|
usage: UsageTotals;
|
|
190
204
|
cost?: CostBreakdown;
|
|
205
|
+
/**
|
|
206
|
+
* Present on every step the engine's tool loop produced (both transports),
|
|
207
|
+
* absent on steps built by external adapters (claude_cli) and injected test
|
|
208
|
+
* seams that return a TurnResult without one.
|
|
209
|
+
*/
|
|
210
|
+
timing?: StepTiming;
|
|
191
211
|
finish_reason: FinishReason;
|
|
192
212
|
/**
|
|
193
213
|
* This turn's provider-reported detail, keyed by provider name. See
|
|
@@ -313,6 +333,12 @@ type TurnResult = {
|
|
|
313
333
|
}>;
|
|
314
334
|
readonly finish_reason: FinishReason;
|
|
315
335
|
readonly usage: UsageTotals;
|
|
336
|
+
/**
|
|
337
|
+
* Stamped by the engine's retry wrapper around the successful attempt, not
|
|
338
|
+
* by adapters: an adapter-returned TurnResult never carries one, and the
|
|
339
|
+
* wrapper's value would overwrite it if it did. See StepTiming.
|
|
340
|
+
*/
|
|
341
|
+
readonly timing?: StepTiming;
|
|
316
342
|
/**
|
|
317
343
|
* Opaque detail the provider reported about this turn, keyed by provider
|
|
318
344
|
* name: Bedrock's guardrail trace, Anthropic's cache breakdown, whatever a
|
|
@@ -601,5 +627,5 @@ type Engine = {
|
|
|
601
627
|
dispose: () => Promise<void>;
|
|
602
628
|
};
|
|
603
629
|
//#endregion
|
|
604
|
-
export {
|
|
605
|
-
//# sourceMappingURL=types-
|
|
630
|
+
export { TurnRequest as A, ProviderFactory as B, StepTiming as C, ToolApprovalRequest as D, ToolApprovalHandler as E, EffortTranslation as F, RawProviderUsage as H, ExternalAgentAdapter as I, NativeProviderAdapter as L, UsageTotals as M, UserContentPart as N, ToolCallRecord as O, AiSdkProviderAdapter as P, ProviderAdapter as R, StepRecord as S, Tool as T, default_normalize_usage as U, ProviderTransport as V, ProviderConfigMap as _, Engine as a, RetryFailureKind as b, FinishReason as c, Message as d, PrepareStepContext as f, PricingTable as g, Pricing as h, EffortLevel as i, TurnResult as j, ToolExecContext as k, GenerateOptions as l, PrepareStepResult as m, AssistantContentPart as n, EngineConfig as o, PrepareStepHook as p, CostBreakdown as r, EngineDefaults as s, AiSdkTelemetrySettings as t, GenerateResult as u, ProviderInit as v, StreamChunk as w, RetryPolicy as x, ResolvedModel as y, ProviderCapability as z };
|
|
631
|
+
//# sourceMappingURL=types-CLigYA62.d.ts.map
|
|
@@ -42,8 +42,13 @@ type RunContext = {
|
|
|
42
42
|
readonly streaming: boolean;
|
|
43
43
|
};
|
|
44
44
|
type StepFn<i, o> = (input: i, ctx: RunContext) => Promise<o> | o;
|
|
45
|
+
/**
|
|
46
|
+
* Descriptive metadata for a step. `name` is the display channel: it labels
|
|
47
|
+
* trajectory spans and `describe` output, and changing it is always safe
|
|
48
|
+
* because nothing keys off it. The step's `id` stays the identity channel.
|
|
49
|
+
*/
|
|
45
50
|
type StepMetadata = {
|
|
46
|
-
readonly
|
|
51
|
+
readonly name?: string;
|
|
47
52
|
readonly description?: string;
|
|
48
53
|
readonly port_labels?: Readonly<{
|
|
49
54
|
readonly in?: string;
|
|
@@ -81,4 +86,4 @@ type StepInput<s> = s extends Step<infer i, unknown> ? i : never;
|
|
|
81
86
|
type StepOutput<s> = s extends Step<never, infer o> ? o : unknown;
|
|
82
87
|
//#endregion
|
|
83
88
|
export { Step as a, StepMetadata as c, TrajectoryLogger as d, RunContext as i, StepOutput as l, CheckpointStore as n, StepFn as o, CleanupFn as r, StepInput as s, AnyStep as t, TrajectoryEvent as u };
|
|
84
|
-
//# sourceMappingURL=types-
|
|
89
|
+
//# sourceMappingURL=types-DBpU27sQ.d.ts.map
|
package/dist/ui.d.ts
CHANGED
package/dist/ui.js
CHANGED
|
@@ -6,7 +6,7 @@ import { createUIMessageStream, createUIMessageStreamResponse, pipeUIMessageStre
|
|
|
6
6
|
* `run.stream(flow, input)` yields `TrajectoryEvent`s; under streaming,
|
|
7
7
|
* `model_call` records `model_chunk` events carrying an engine `StreamChunk`.
|
|
8
8
|
* This module maps those chunks onto the AI SDK `UIMessageChunk` protocol so a
|
|
9
|
-
*
|
|
9
|
+
* Fascicle flow can back a `useChat` endpoint rendered by AI Elements /
|
|
10
10
|
* Streamdown, with zero bespoke glue.
|
|
11
11
|
*
|
|
12
12
|
* It is the outbound inverse of the engine's inbound provider->StreamChunk
|
package/dist/ui.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ui.js","names":[],"sources":["../src/ui/to_ui_message_stream.ts"],"sourcesContent":["/**\n * fascicle/ui: bridge a run's event stream to the AI SDK \"UI message stream\".\n *\n * `run.stream(flow, input)` yields `TrajectoryEvent`s; under streaming,\n * `model_call` records `model_chunk` events carrying an engine `StreamChunk`.\n * This module maps those chunks onto the AI SDK `UIMessageChunk` protocol so a\n * fascicle flow can back a `useChat` endpoint rendered by AI Elements /\n * Streamdown, with zero bespoke glue.\n *\n * It is the outbound inverse of the engine's inbound provider->StreamChunk\n * mapping. The wire framing (SSE, `data:` lines, terminal `[DONE]`, the\n * `x-vercel-ai-ui-message-stream` header) is owned by the `ai` builders; this\n * file only translates chunk shapes and manages open text/reasoning blocks.\n *\n * v7's `file`/`reasoning-file` UI parts are never emitted: the engine chunk\n * vocabulary has no generated-file kind (those provider parts drop at the\n * inbound mapping), so there is nothing here to translate them from.\n */\n\nimport {\n createUIMessageStream,\n createUIMessageStreamResponse,\n pipeUIMessageStreamToResponse,\n} from 'ai'\nimport type { UIMessageChunk } from 'ai'\nimport type { ServerResponse } from 'node:http'\nimport type { TrajectoryEvent } from '#core'\nimport type { StreamChunk } from '#engine'\n\n/**\n * The structural shape of a `run.stream(...)` handle. Typed structurally rather\n * than importing the core `StreamingRunHandle` so this module depends on no\n * core value and a caller can pass `run.stream(...)` directly.\n */\nexport type RunStreamLike = {\n readonly events: AsyncIterable<TrajectoryEvent>\n readonly result: Promise<unknown>\n}\n\nexport type ToUiStreamOptions = {\n /** Map a thrown run error to the text of an `error` part. */\n readonly on_error?: (error: unknown) => string\n}\n\n/**\n * Per-stream state: which text/reasoning blocks are open (so `*-start` fires\n * once and `*-end` closes them) and the tool name for each in-flight call (so\n * `tool-input-available` can echo it after only the id arrives at close).\n */\nexport type UiMapperState = {\n readonly open_text: Set<number>\n readonly open_reasoning: Set<number>\n readonly tool_names: Map<string, string>\n}\n\n/**\n * Create an empty `UiMapperState` for a new stream.\n */\nexport function create_ui_mapper_state(): UiMapperState {\n return { open_text: new Set(), open_reasoning: new Set(), tool_names: new Map() }\n}\n\n/**\n * Build the UI message chunk id for a step's text block.\n */\nfunction text_id(step_index: number): string {\n return `text-${step_index}`\n}\n\n/**\n * Build the UI message chunk id for a step's reasoning block.\n */\nfunction reasoning_id(step_index: number): string {\n return `reasoning-${step_index}`\n}\n\n/**\n * Close the text/reasoning blocks open for one step, returning the\n * `*-end` chunks needed and updating `state` in place.\n *\n * Called on a `step_finish` chunk, so only that step's blocks close; blocks\n * open for other steps are untouched.\n */\nfunction close_step_blocks(step_index: number, state: UiMapperState): UIMessageChunk[] {\n const parts: UIMessageChunk[] = []\n if (state.open_text.delete(step_index)) {\n parts.push({ type: 'text-end', id: text_id(step_index) })\n }\n if (state.open_reasoning.delete(step_index)) {\n parts.push({ type: 'reasoning-end', id: reasoning_id(step_index) })\n }\n return parts\n}\n\n/**\n * Close every text/reasoning block still open in `state`, returning the\n * `*-end` chunks needed.\n *\n * Used on stream `finish` and to flush any blocks still open when the\n * underlying event iterable ends.\n */\nexport function close_open_blocks(state: UiMapperState): UIMessageChunk[] {\n const parts: UIMessageChunk[] = []\n for (const step_index of state.open_text) {\n parts.push({ type: 'text-end', id: text_id(step_index) })\n }\n for (const step_index of state.open_reasoning) {\n parts.push({ type: 'reasoning-end', id: reasoning_id(step_index) })\n }\n state.open_text.clear()\n state.open_reasoning.clear()\n return parts\n}\n\n/**\n * Map a single engine `StreamChunk` to the `UIMessageChunk`s it produces,\n * opening and closing text/reasoning blocks in `state` as needed.\n */\nfunction map_chunk(chunk: StreamChunk, state: UiMapperState): UIMessageChunk[] {\n switch (chunk.kind) {\n case 'text': {\n const id = text_id(chunk.step_index)\n const parts: UIMessageChunk[] = []\n if (!state.open_text.has(chunk.step_index)) {\n state.open_text.add(chunk.step_index)\n parts.push({ type: 'text-start', id })\n }\n parts.push({ type: 'text-delta', id, delta: chunk.text })\n return parts\n }\n case 'reasoning': {\n const id = reasoning_id(chunk.step_index)\n const parts: UIMessageChunk[] = []\n if (!state.open_reasoning.has(chunk.step_index)) {\n state.open_reasoning.add(chunk.step_index)\n parts.push({ type: 'reasoning-start', id })\n }\n parts.push({ type: 'reasoning-delta', id, delta: chunk.text })\n return parts\n }\n case 'tool_call_start': {\n state.tool_names.set(chunk.id, chunk.name)\n return [{ type: 'tool-input-start', toolCallId: chunk.id, toolName: chunk.name }]\n }\n case 'tool_call_input_delta':\n return [{ type: 'tool-input-delta', toolCallId: chunk.id, inputTextDelta: chunk.delta }]\n case 'tool_call_end':\n return [\n {\n type: 'tool-input-available',\n toolCallId: chunk.id,\n toolName: state.tool_names.get(chunk.id) ?? '',\n input: chunk.input,\n },\n ]\n case 'tool_result':\n return chunk.error !== undefined\n ? [{ type: 'tool-output-error', toolCallId: chunk.id, errorText: chunk.error.message }]\n : [{ type: 'tool-output-available', toolCallId: chunk.id, output: chunk.output }]\n case 'step_finish':\n return close_step_blocks(chunk.step_index, state)\n case 'finish':\n return close_open_blocks(state)\n default:\n return []\n }\n}\n\n/**\n * Narrow an untyped `TrajectoryEvent['chunk']` payload to a `StreamChunk`\n * when it looks like one (an object with a string `kind`), otherwise\n * return `undefined`.\n */\nfunction as_stream_chunk(value: unknown): StreamChunk | undefined {\n if (typeof value !== 'object' || value === null) return undefined\n const kind = Reflect.get(value, 'kind')\n if (typeof kind !== 'string') return undefined\n // The value rode a loose TrajectoryEvent bag; model_call only records real\n // StreamChunks under `chunk`, and map_chunk narrows on `kind`, so treating it\n // as a StreamChunk is sound. Unknown kinds fall through to `[]`.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return value as StreamChunk\n}\n\n/**\n * Map one run event to zero or more UI message chunks, advancing `state`.\n * Non-`model_chunk` events (spans, cost, user emits) yield nothing.\n */\nexport function to_ui_message_chunks(\n event: TrajectoryEvent,\n state: UiMapperState,\n): UIMessageChunk[] {\n if (event.kind !== 'model_chunk') return []\n const chunk = as_stream_chunk(event['chunk'])\n return chunk === undefined ? [] : map_chunk(chunk, state)\n}\n\n/**\n * Build the `ReadableStream<UIMessageChunk>` that drives a `run.stream(...)`\n * handle through `to_ui_message_chunks`, used by both the `Response` and\n * Node `ServerResponse` entry points below.\n */\nfunction build_stream(\n handle: RunStreamLike,\n options: ToUiStreamOptions,\n): ReadableStream<UIMessageChunk> {\n const on_error = options.on_error\n return createUIMessageStream({\n execute: async ({ writer }) => {\n const state = create_ui_mapper_state()\n for await (const event of handle.events) {\n for (const part of to_ui_message_chunks(event, state)) writer.write(part)\n }\n for (const part of close_open_blocks(state)) writer.write(part)\n await handle.result\n },\n ...(on_error !== undefined ? { onError: on_error } : {}),\n })\n}\n\n/**\n * Turn a `run.stream(...)` handle into an SSE `Response` a `useChat` endpoint\n * can return directly.\n */\nexport function to_ui_message_response(\n handle: RunStreamLike,\n options: ToUiStreamOptions = {},\n): Response {\n return createUIMessageStreamResponse({ stream: build_stream(handle, options) })\n}\n\n/**\n * Pipe a `run.stream(...)` handle to a Node `http.ServerResponse` as SSE, for\n * `node:http` servers that hold a `ServerResponse` rather than returning a\n * web `Response`.\n */\nexport function pipe_ui_message_stream_to_response(\n handle: RunStreamLike,\n response: ServerResponse,\n options: ToUiStreamOptions = {},\n): void {\n pipeUIMessageStreamToResponse({ response, stream: build_stream(handle, options) })\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"ui.js","names":[],"sources":["../src/ui/to_ui_message_stream.ts"],"sourcesContent":["/**\n * fascicle/ui: bridge a run's event stream to the AI SDK \"UI message stream\".\n *\n * `run.stream(flow, input)` yields `TrajectoryEvent`s; under streaming,\n * `model_call` records `model_chunk` events carrying an engine `StreamChunk`.\n * This module maps those chunks onto the AI SDK `UIMessageChunk` protocol so a\n * Fascicle flow can back a `useChat` endpoint rendered by AI Elements /\n * Streamdown, with zero bespoke glue.\n *\n * It is the outbound inverse of the engine's inbound provider->StreamChunk\n * mapping. The wire framing (SSE, `data:` lines, terminal `[DONE]`, the\n * `x-vercel-ai-ui-message-stream` header) is owned by the `ai` builders; this\n * file only translates chunk shapes and manages open text/reasoning blocks.\n *\n * v7's `file`/`reasoning-file` UI parts are never emitted: the engine chunk\n * vocabulary has no generated-file kind (those provider parts drop at the\n * inbound mapping), so there is nothing here to translate them from.\n */\n\nimport {\n createUIMessageStream,\n createUIMessageStreamResponse,\n pipeUIMessageStreamToResponse,\n} from 'ai'\nimport type { UIMessageChunk } from 'ai'\nimport type { ServerResponse } from 'node:http'\nimport type { TrajectoryEvent } from '#core'\nimport type { StreamChunk } from '#engine'\n\n/**\n * The structural shape of a `run.stream(...)` handle. Typed structurally rather\n * than importing the core `StreamingRunHandle` so this module depends on no\n * core value and a caller can pass `run.stream(...)` directly.\n */\nexport type RunStreamLike = {\n readonly events: AsyncIterable<TrajectoryEvent>\n readonly result: Promise<unknown>\n}\n\nexport type ToUiStreamOptions = {\n /** Map a thrown run error to the text of an `error` part. */\n readonly on_error?: (error: unknown) => string\n}\n\n/**\n * Per-stream state: which text/reasoning blocks are open (so `*-start` fires\n * once and `*-end` closes them) and the tool name for each in-flight call (so\n * `tool-input-available` can echo it after only the id arrives at close).\n */\nexport type UiMapperState = {\n readonly open_text: Set<number>\n readonly open_reasoning: Set<number>\n readonly tool_names: Map<string, string>\n}\n\n/**\n * Create an empty `UiMapperState` for a new stream.\n */\nexport function create_ui_mapper_state(): UiMapperState {\n return { open_text: new Set(), open_reasoning: new Set(), tool_names: new Map() }\n}\n\n/**\n * Build the UI message chunk id for a step's text block.\n */\nfunction text_id(step_index: number): string {\n return `text-${step_index}`\n}\n\n/**\n * Build the UI message chunk id for a step's reasoning block.\n */\nfunction reasoning_id(step_index: number): string {\n return `reasoning-${step_index}`\n}\n\n/**\n * Close the text/reasoning blocks open for one step, returning the\n * `*-end` chunks needed and updating `state` in place.\n *\n * Called on a `step_finish` chunk, so only that step's blocks close; blocks\n * open for other steps are untouched.\n */\nfunction close_step_blocks(step_index: number, state: UiMapperState): UIMessageChunk[] {\n const parts: UIMessageChunk[] = []\n if (state.open_text.delete(step_index)) {\n parts.push({ type: 'text-end', id: text_id(step_index) })\n }\n if (state.open_reasoning.delete(step_index)) {\n parts.push({ type: 'reasoning-end', id: reasoning_id(step_index) })\n }\n return parts\n}\n\n/**\n * Close every text/reasoning block still open in `state`, returning the\n * `*-end` chunks needed.\n *\n * Used on stream `finish` and to flush any blocks still open when the\n * underlying event iterable ends.\n */\nexport function close_open_blocks(state: UiMapperState): UIMessageChunk[] {\n const parts: UIMessageChunk[] = []\n for (const step_index of state.open_text) {\n parts.push({ type: 'text-end', id: text_id(step_index) })\n }\n for (const step_index of state.open_reasoning) {\n parts.push({ type: 'reasoning-end', id: reasoning_id(step_index) })\n }\n state.open_text.clear()\n state.open_reasoning.clear()\n return parts\n}\n\n/**\n * Map a single engine `StreamChunk` to the `UIMessageChunk`s it produces,\n * opening and closing text/reasoning blocks in `state` as needed.\n */\nfunction map_chunk(chunk: StreamChunk, state: UiMapperState): UIMessageChunk[] {\n switch (chunk.kind) {\n case 'text': {\n const id = text_id(chunk.step_index)\n const parts: UIMessageChunk[] = []\n if (!state.open_text.has(chunk.step_index)) {\n state.open_text.add(chunk.step_index)\n parts.push({ type: 'text-start', id })\n }\n parts.push({ type: 'text-delta', id, delta: chunk.text })\n return parts\n }\n case 'reasoning': {\n const id = reasoning_id(chunk.step_index)\n const parts: UIMessageChunk[] = []\n if (!state.open_reasoning.has(chunk.step_index)) {\n state.open_reasoning.add(chunk.step_index)\n parts.push({ type: 'reasoning-start', id })\n }\n parts.push({ type: 'reasoning-delta', id, delta: chunk.text })\n return parts\n }\n case 'tool_call_start': {\n state.tool_names.set(chunk.id, chunk.name)\n return [{ type: 'tool-input-start', toolCallId: chunk.id, toolName: chunk.name }]\n }\n case 'tool_call_input_delta':\n return [{ type: 'tool-input-delta', toolCallId: chunk.id, inputTextDelta: chunk.delta }]\n case 'tool_call_end':\n return [\n {\n type: 'tool-input-available',\n toolCallId: chunk.id,\n toolName: state.tool_names.get(chunk.id) ?? '',\n input: chunk.input,\n },\n ]\n case 'tool_result':\n return chunk.error !== undefined\n ? [{ type: 'tool-output-error', toolCallId: chunk.id, errorText: chunk.error.message }]\n : [{ type: 'tool-output-available', toolCallId: chunk.id, output: chunk.output }]\n case 'step_finish':\n return close_step_blocks(chunk.step_index, state)\n case 'finish':\n return close_open_blocks(state)\n default:\n return []\n }\n}\n\n/**\n * Narrow an untyped `TrajectoryEvent['chunk']` payload to a `StreamChunk`\n * when it looks like one (an object with a string `kind`), otherwise\n * return `undefined`.\n */\nfunction as_stream_chunk(value: unknown): StreamChunk | undefined {\n if (typeof value !== 'object' || value === null) return undefined\n const kind = Reflect.get(value, 'kind')\n if (typeof kind !== 'string') return undefined\n // The value rode a loose TrajectoryEvent bag; model_call only records real\n // StreamChunks under `chunk`, and map_chunk narrows on `kind`, so treating it\n // as a StreamChunk is sound. Unknown kinds fall through to `[]`.\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n return value as StreamChunk\n}\n\n/**\n * Map one run event to zero or more UI message chunks, advancing `state`.\n * Non-`model_chunk` events (spans, cost, user emits) yield nothing.\n */\nexport function to_ui_message_chunks(\n event: TrajectoryEvent,\n state: UiMapperState,\n): UIMessageChunk[] {\n if (event.kind !== 'model_chunk') return []\n const chunk = as_stream_chunk(event['chunk'])\n return chunk === undefined ? [] : map_chunk(chunk, state)\n}\n\n/**\n * Build the `ReadableStream<UIMessageChunk>` that drives a `run.stream(...)`\n * handle through `to_ui_message_chunks`, used by both the `Response` and\n * Node `ServerResponse` entry points below.\n */\nfunction build_stream(\n handle: RunStreamLike,\n options: ToUiStreamOptions,\n): ReadableStream<UIMessageChunk> {\n const on_error = options.on_error\n return createUIMessageStream({\n execute: async ({ writer }) => {\n const state = create_ui_mapper_state()\n for await (const event of handle.events) {\n for (const part of to_ui_message_chunks(event, state)) writer.write(part)\n }\n for (const part of close_open_blocks(state)) writer.write(part)\n await handle.result\n },\n ...(on_error !== undefined ? { onError: on_error } : {}),\n })\n}\n\n/**\n * Turn a `run.stream(...)` handle into an SSE `Response` a `useChat` endpoint\n * can return directly.\n */\nexport function to_ui_message_response(\n handle: RunStreamLike,\n options: ToUiStreamOptions = {},\n): Response {\n return createUIMessageStreamResponse({ stream: build_stream(handle, options) })\n}\n\n/**\n * Pipe a `run.stream(...)` handle to a Node `http.ServerResponse` as SSE, for\n * `node:http` servers that hold a `ServerResponse` rather than returning a\n * web `Response`.\n */\nexport function pipe_ui_message_stream_to_response(\n handle: RunStreamLike,\n response: ServerResponse,\n options: ToUiStreamOptions = {},\n): void {\n pipeUIMessageStreamToResponse({ response, stream: build_stream(handle, options) })\n}\n"],"mappings":"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"}
|
package/dist/viewer.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { a as ParsedTrajectoryEvent } from "./trajectory-
|
|
1
|
+
import { a as ParsedTrajectoryEvent } from "./trajectory-ByoOQZ6T.js";
|
|
2
2
|
|
|
3
3
|
//#region src/viewer/start_viewer.d.ts
|
|
4
4
|
/**
|
|
@@ -45,7 +45,7 @@ type Broadcaster = {
|
|
|
45
45
|
readonly snapshot_after: (last_id: number) => readonly BroadcastEvent[];
|
|
46
46
|
readonly size: () => number;
|
|
47
47
|
};
|
|
48
|
-
type
|
|
48
|
+
type BroadcasterConfig = {
|
|
49
49
|
readonly buffer: number;
|
|
50
50
|
readonly on_subscriber_error?: (err: unknown) => void;
|
|
51
51
|
};
|
|
@@ -58,10 +58,10 @@ type BroadcasterOptions = {
|
|
|
58
58
|
* that throws is unsubscribed, and the `on_subscriber_error` callback fires
|
|
59
59
|
* once with the captured error so the server can log it.
|
|
60
60
|
*/
|
|
61
|
-
declare function create_broadcaster(
|
|
61
|
+
declare function create_broadcaster(config: BroadcasterConfig): Broadcaster;
|
|
62
62
|
//#endregion
|
|
63
63
|
//#region src/viewer/server.d.ts
|
|
64
|
-
type
|
|
64
|
+
type ServerConfig = {
|
|
65
65
|
readonly broadcaster: Broadcaster;
|
|
66
66
|
readonly host: string;
|
|
67
67
|
readonly port: number;
|
|
@@ -78,10 +78,10 @@ type ViewerServer = {
|
|
|
78
78
|
* single request handler and resolves with the bound URL and a `close`
|
|
79
79
|
* that shuts the socket down.
|
|
80
80
|
*/
|
|
81
|
-
declare function start_server(
|
|
81
|
+
declare function start_server(config: ServerConfig): Promise<ViewerServer>;
|
|
82
82
|
//#endregion
|
|
83
83
|
//#region src/viewer/tail.d.ts
|
|
84
|
-
type
|
|
84
|
+
type TailConfig = {
|
|
85
85
|
readonly path: string;
|
|
86
86
|
readonly on_event: (event: ParsedTrajectoryEvent) => void;
|
|
87
87
|
readonly on_parse_error?: (err: unknown, line: string) => void;
|
|
@@ -100,7 +100,7 @@ type Tail = {
|
|
|
100
100
|
* flight absorbs any events that fire while it runs instead of starting a
|
|
101
101
|
* second concurrent read.
|
|
102
102
|
*/
|
|
103
|
-
declare function start_tail(
|
|
103
|
+
declare function start_tail(config: TailConfig): Tail;
|
|
104
104
|
//#endregion
|
|
105
105
|
//#region src/viewer/cli.d.ts
|
|
106
106
|
/**
|
|
@@ -113,5 +113,5 @@ declare function start_tail(options: TailOptions): Tail;
|
|
|
113
113
|
*/
|
|
114
114
|
declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
|
|
115
115
|
//#endregion
|
|
116
|
-
export { type BroadcastEvent, type Broadcaster, type
|
|
116
|
+
export { type BroadcastEvent, type Broadcaster, type BroadcasterConfig, type ServerConfig, type StartViewerOptions, type Subscriber, type Tail, type TailConfig, type ViewerHandle, type ViewerServer, create_broadcaster, run_viewer_cli, start_server, start_tail, start_viewer };
|
|
117
117
|
//# sourceMappingURL=viewer.d.ts.map
|