fascicle 0.11.1 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,114 @@
1
+ //#region src/core/trajectory.d.ts
2
+ /**
3
+ * Wire-format guards for trajectory events.
4
+ *
5
+ * `TrajectoryEvent` (in `types.ts`) is the loose internal type — any code that
6
+ * calls `trajectory.record(event)` or `start_span(name, meta)` produces values
7
+ * conforming to it. This file defines the *narrower* shapes that the studio
8
+ * (and any other downstream consumer) can recognize in the wire stream:
9
+ *
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
+ *
20
+ * `parse_trajectory_event` is the wire gate, and it is deliberately permissive:
21
+ * a value is a trajectory event iff it is a non-array object carrying a string
22
+ * `kind`. The well-known guards layered on top are *recognizers*, not gates — a
23
+ * `{ kind: 'span_start' }` line missing its `span_id` is still a valid event on
24
+ * the wire, just not a `SpanStartEvent`. Anything stricter would have a viewer
25
+ * drop lines a newer producer emits, which is the opposite of what a
26
+ * forward-compatible wire format is for. `is_custom_trajectory_event` therefore
27
+ * answers `true` for well-known kinds too: it is the fallback shape, not a
28
+ * fifth disjoint case.
29
+ *
30
+ * Extra fields (`run_id`, `id`, provider-specific metadata) are neither
31
+ * required nor stripped: a successful parse hands the value straight back, so a
32
+ * parse / re-serialize round trip is lossless.
33
+ */
34
+ type SpanStartEvent = {
35
+ readonly kind: 'span_start';
36
+ readonly span_id: string;
37
+ readonly name: string;
38
+ } & {
39
+ readonly [key: string]: unknown;
40
+ };
41
+ type SpanEndEvent = {
42
+ readonly kind: 'span_end';
43
+ readonly span_id: string;
44
+ } & {
45
+ readonly [key: string]: unknown;
46
+ };
47
+ type EmitEvent = {
48
+ readonly kind: 'emit';
49
+ } & {
50
+ readonly [key: string]: unknown;
51
+ };
52
+ type RunEndStatus = 'done' | 'failed' | 'aborted' | 'suspended';
53
+ type RunEndEvent = {
54
+ readonly kind: 'run_end';
55
+ readonly status: RunEndStatus;
56
+ } & {
57
+ readonly [key: string]: unknown;
58
+ };
59
+ type CheckpointStatus = 'hit' | 'miss' | 'read_error';
60
+ type CheckpointEvent = {
61
+ readonly kind: 'checkpoint';
62
+ readonly status: CheckpointStatus;
63
+ readonly key: string;
64
+ } & {
65
+ readonly [key: string]: unknown;
66
+ };
67
+ type CustomTrajectoryEvent = {
68
+ readonly kind: string;
69
+ } & {
70
+ readonly [key: string]: unknown;
71
+ };
72
+ type ParsedTrajectoryEvent = SpanStartEvent | SpanEndEvent | EmitEvent | RunEndEvent | CheckpointEvent | CustomTrajectoryEvent;
73
+ type TrajectoryParseResult = {
74
+ readonly success: true;
75
+ readonly data: ParsedTrajectoryEvent;
76
+ } | {
77
+ readonly success: false;
78
+ readonly error: Error;
79
+ };
80
+ /**
81
+ * The wire gate: a non-array object carrying a string `kind`.
82
+ *
83
+ * True for every well-known kind as well, since `custom` is the fallback shape
84
+ * rather than a disjoint case.
85
+ */
86
+ declare function is_custom_trajectory_event(value: unknown): value is CustomTrajectoryEvent;
87
+ /** A composer span open: both `span_id` and `name` must be present as strings. */
88
+ declare function is_span_start_event(value: unknown): value is SpanStartEvent;
89
+ /** A composer span close: `span_id` must be present as a string, `name` need not be. */
90
+ declare function is_span_end_event(value: unknown): value is SpanEndEvent;
91
+ /** A `ctx.emit` event: the kind alone identifies it, the payload is the caller's. */
92
+ declare function is_emit_event(value: unknown): value is EmitEvent;
93
+ /**
94
+ * A terminal run event: `status` must be one of the known run outcomes, so the
95
+ * narrowed type's `status` union is truthful. An unknown future status still
96
+ * passes the wire gate as a custom event.
97
+ */
98
+ declare function is_run_end_event(value: unknown): value is RunEndEvent;
99
+ /**
100
+ * A checkpoint lookup event: `status` must be a known lookup outcome and `key`
101
+ * the store key that was consulted, for the same truthful-narrowing reason as
102
+ * `is_run_end_event`.
103
+ */
104
+ declare function is_checkpoint_event(value: unknown): value is CheckpointEvent;
105
+ /**
106
+ * Parse one wire value into a trajectory event, `safeParse`-shaped.
107
+ *
108
+ * On success `data` is the value itself, not a copy, so nothing on the line is
109
+ * dropped or reordered on the way through.
110
+ */
111
+ declare function parse_trajectory_event(value: unknown): TrajectoryParseResult;
112
+ //#endregion
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-cSLNlHzh.d.ts.map
@@ -36,6 +36,7 @@ type RunContext = {
36
36
  readonly abort: AbortSignal;
37
37
  readonly emit: (event: Record<string, unknown>) => void;
38
38
  readonly on_cleanup: (fn: CleanupFn) => void;
39
+ readonly call: <ci, co>(this: RunContext, s: Step<ci, co>, input: ci) => Promise<co>;
39
40
  readonly checkpoint_store?: CheckpointStore | undefined;
40
41
  readonly resume_data?: Readonly<Record<string, unknown>> | undefined;
41
42
  readonly streaming: boolean;
@@ -52,12 +53,32 @@ type StepMetadata = {
52
53
  type Step<i, o> = {
53
54
  readonly id: string;
54
55
  readonly kind: string;
55
- run(input: i, ctx: RunContext): Promise<o> | o;
56
+ readonly run: StepFn<i, o>;
56
57
  readonly config?: Readonly<Record<string, unknown>>;
57
- readonly children?: ReadonlyArray<Step<unknown, unknown>>;
58
+ readonly children?: ReadonlyArray<AnyStep>;
58
59
  readonly anonymous?: boolean;
59
60
  readonly meta?: StepMetadata;
60
61
  };
62
+ /**
63
+ * The supertype of every Step: `never` input (contravariant, so any concrete
64
+ * input type is admitted) and `unknown` output (covariant). Use this for
65
+ * heterogeneous step collections and type-erased plumbing; `AnyStep` cannot
66
+ * be run directly, which is the point: pairing an erased step with an input
67
+ * it accepts is the runner's job, not the type system's.
68
+ */
69
+ type AnyStep = Step<never, unknown>;
70
+ /**
71
+ * Extract a Step's input type. The fallback is `never`, not `unknown`, so a
72
+ * non-step can never satisfy an input-position check by accident; sequence's
73
+ * joint checking depends on that. This is the canonical extractor the
74
+ * composers' internal type machinery builds on.
75
+ */
76
+ type StepInput<s> = s extends Step<infer i, unknown> ? i : never;
77
+ /**
78
+ * Extract a Step's output type. Falls back to `unknown` so type-erased
79
+ * plumbing over `AnyStep` degrades to the safe top type instead of lying.
80
+ */
81
+ type StepOutput<s> = s extends Step<never, infer o> ? o : unknown;
61
82
  //#endregion
62
- export { StepMetadata as a, StepFn as i, RunContext as n, TrajectoryEvent as o, Step as r, TrajectoryLogger as s, CheckpointStore as t };
63
- //# sourceMappingURL=types-BDSbSUAO.d.ts.map
83
+ 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-BqUY6nRX.d.ts.map
@@ -1,4 +1,4 @@
1
- import { s as TrajectoryLogger } from "./types-BDSbSUAO.js";
1
+ import { d as TrajectoryLogger } from "./types-BqUY6nRX.js";
2
2
  import { r as ToolSchema } from "./types-BCtKsxrX.js";
3
3
 
4
4
  //#region src/engine/providers/claude_cli/types.d.ts
@@ -531,9 +531,10 @@ type AiSdkTelemetrySettings = {
531
531
  *
532
532
  * | Field | Rule |
533
533
  * | --------------------------------------------------------------------- | ----------------------------------------- |
534
- * | `model` | per-call wins; else default; else `sonnet` |
535
- * | `provider` | per-call wins; else default; else sole configured provider; else `anthropic` |
534
+ * | `model` | per-call wins; else default; else model_required_error is thrown |
535
+ * | `provider` | per-call wins; else default; else sole configured provider; else provider_required_error is thrown |
536
536
  * | `system`, `effort`, `max_steps`, `turn_timeout_ms`, `tool_error_policy`, `schema_repair_attempts`, `tool_call_repair_attempts`, `max_tool_calls_per_step` | per-call wins (nullish coalesce) |
537
+ * | `temperature`, `max_tokens`, `top_p` | per-call wins (nullish coalesce) |
537
538
  * | `retry_policy` | per-call replaces wholesale |
538
539
  * | `provider_options` | two-level: per-provider-key shallow merge |
539
540
  * | `prompt`, `tools`, `schema`, `abort`, `trajectory`, `on_chunk` | not defaultable; always call-supplied |
@@ -543,6 +544,9 @@ type EngineDefaults = {
543
544
  readonly provider?: string;
544
545
  readonly system?: string;
545
546
  readonly effort?: EffortLevel;
547
+ readonly temperature?: number;
548
+ readonly max_tokens?: number;
549
+ readonly top_p?: number;
546
550
  readonly max_steps?: number;
547
551
  readonly turn_timeout_ms?: number;
548
552
  readonly retry_policy?: RetryPolicy;
@@ -598,4 +602,4 @@ type Engine = {
598
602
  };
599
603
  //#endregion
600
604
  export { TurnResult as A, ProviderTransport as B, StreamChunk as C, ToolCallRecord as D, ToolApprovalRequest as E, ExternalAgentAdapter as F, default_normalize_usage as H, NativeProviderAdapter as I, ProviderAdapter as L, UserContentPart as M, AiSdkProviderAdapter as N, ToolExecContext as O, EffortTranslation as P, ProviderCapability as R, StepRecord as S, ToolApprovalHandler as T, RawProviderUsage as V, ProviderConfigMap as _, Engine as a, RetryFailureKind as b, FinishReason as c, Message as d, PrepareStepContext as f, PricingTable as g, Pricing as h, EffortLevel as i, UsageTotals as j, TurnRequest as k, GenerateOptions as l, PrepareStepResult as m, AssistantContentPart as n, EngineConfig as o, PrepareStepHook as p, CostBreakdown as r, EngineDefaults as s, AiSdkTelemetrySettings as t, GenerateResult as u, ProviderInit as v, Tool as w, RetryPolicy as x, ResolvedModel as y, ProviderFactory as z };
601
- //# sourceMappingURL=types-B3HIsBBD.d.ts.map
605
+ //# sourceMappingURL=types-CXBB4aIM.d.ts.map
package/dist/ui.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { o as TrajectoryEvent } from "./types-BDSbSUAO.js";
2
- import { ServerResponse } from "node:http";
1
+ import { u as TrajectoryEvent } from "./types-BqUY6nRX.js";
3
2
  import { UIMessageChunk } from "ai";
3
+ import { ServerResponse } from "node:http";
4
4
 
5
5
  //#region src/ui/to_ui_message_stream.d.ts
6
6
  /**
@@ -0,0 +1,117 @@
1
+ import { a as ParsedTrajectoryEvent } from "./trajectory-cSLNlHzh.js";
2
+
3
+ //#region src/viewer/start_viewer.d.ts
4
+ /**
5
+ * `start_viewer` programmatic embed implementation.
6
+ *
7
+ * Spin up the server, optionally start tailing a JSONL file, and return a
8
+ * handle that can stop both. `start_viewer` only depends on core's wire-format
9
+ * schema; it never reaches into the engine, composites, or any provider.
10
+ */
11
+ type StartViewerOptions = {
12
+ readonly path?: string;
13
+ readonly host?: string;
14
+ readonly port?: number;
15
+ readonly buffer?: number;
16
+ readonly on_parse_error?: (err: unknown, line: string) => void;
17
+ readonly on_io_error?: (err: unknown) => void;
18
+ readonly on_subscriber_error?: (err: unknown) => void;
19
+ };
20
+ type ViewerHandle = {
21
+ readonly url: string;
22
+ readonly host: string;
23
+ readonly port: number;
24
+ readonly close: () => Promise<void>;
25
+ };
26
+ /**
27
+ * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`
28
+ * is set, a file tail that feeds the same broadcaster.
29
+ *
30
+ * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest
31
+ * and SSE are always available; tailing is opt-in via `path`.
32
+ */
33
+ declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandle>;
34
+ //#endregion
35
+ //#region src/viewer/broadcast.d.ts
36
+ type BroadcastEvent = {
37
+ readonly id: number;
38
+ readonly event: ParsedTrajectoryEvent;
39
+ };
40
+ type Subscriber = (entry: BroadcastEvent) => void;
41
+ type Broadcaster = {
42
+ readonly emit: (event: ParsedTrajectoryEvent) => BroadcastEvent;
43
+ readonly subscribe: (fn: Subscriber) => () => void;
44
+ readonly snapshot: () => readonly BroadcastEvent[];
45
+ readonly snapshot_after: (last_id: number) => readonly BroadcastEvent[];
46
+ readonly size: () => number;
47
+ };
48
+ type BroadcasterOptions = {
49
+ readonly buffer: number;
50
+ readonly on_subscriber_error?: (err: unknown) => void;
51
+ };
52
+ /**
53
+ * Creates a broadcaster: a bounded ring buffer plus subscriber fan-out.
54
+ *
55
+ * Each event gets a monotonic `id` so SSE clients can replay from a known
56
+ * cursor on reconnect (`snapshot_after`). `emit` does not await delivery, so
57
+ * slow-client backpressure is the subscriber's responsibility. A subscriber
58
+ * that throws is unsubscribed, and the `on_subscriber_error` callback fires
59
+ * once with the captured error so the server can log it.
60
+ */
61
+ declare function create_broadcaster(options: BroadcasterOptions): Broadcaster;
62
+ //#endregion
63
+ //#region src/viewer/server.d.ts
64
+ type ServerOptions = {
65
+ readonly broadcaster: Broadcaster;
66
+ readonly host: string;
67
+ readonly port: number;
68
+ readonly on_parse_error?: (err: unknown, line: string) => void;
69
+ };
70
+ type ViewerServer = {
71
+ readonly url: string;
72
+ readonly close: () => Promise<void>;
73
+ };
74
+ /**
75
+ * Starts the HTTP server and resolves once it is listening.
76
+ *
77
+ * Wires the five routes (static HTML, health, snapshot, SSE, ingest) to a
78
+ * single request handler and resolves with the bound URL and a `close`
79
+ * that shuts the socket down.
80
+ */
81
+ declare function start_server(options: ServerOptions): Promise<ViewerServer>;
82
+ //#endregion
83
+ //#region src/viewer/tail.d.ts
84
+ type TailOptions = {
85
+ readonly path: string;
86
+ readonly on_event: (event: ParsedTrajectoryEvent) => void;
87
+ readonly on_parse_error?: (err: unknown, line: string) => void;
88
+ readonly on_io_error?: (err: unknown) => void;
89
+ };
90
+ type Tail = {
91
+ readonly stop: () => void;
92
+ readonly drain: () => Promise<void>;
93
+ };
94
+ /**
95
+ * Starts tailing `path` and returns a handle to stop or drain it.
96
+ *
97
+ * Watches the file with `fs.watch` and re-reads from the last known offset
98
+ * on every change, buffering an incomplete trailing line until the rest
99
+ * arrives. Overlapping change events are coalesced: a read already in
100
+ * flight absorbs any events that fire while it runs instead of starting a
101
+ * second concurrent read.
102
+ */
103
+ declare function start_tail(options: TailOptions): Tail;
104
+ //#endregion
105
+ //#region src/viewer/cli.d.ts
106
+ /**
107
+ * CLI entry point: parses argv, starts the viewer, and wires shutdown.
108
+ *
109
+ * Warns but proceeds when the tailed path does not exist yet or when the
110
+ * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the
111
+ * browser, then installs SIGINT/SIGTERM handlers that close the viewer
112
+ * before exiting.
113
+ */
114
+ declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
115
+ //#endregion
116
+ export { type BroadcastEvent, type Broadcaster, type BroadcasterOptions, type ServerOptions, type StartViewerOptions, type Subscriber, type Tail, type TailOptions, type ViewerHandle, type ViewerServer, create_broadcaster, run_viewer_cli, start_server, start_tail, start_viewer };
117
+ //# sourceMappingURL=viewer.d.ts.map