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.
- package/CHANGELOG.md +102 -0
- package/README.md +40 -31
- package/dist/adapters.d.ts +1 -1
- package/dist/agents.d.ts +11 -2
- package/dist/agents.js +63 -20
- package/dist/agents.js.map +1 -1
- package/dist/bin/fascicle-viewer.js +2 -2
- package/dist/{core-DgH4mDbK.js → core-DDRhHu5P.js} +458 -38
- package/dist/core-DDRhHu5P.js.map +1 -0
- package/dist/engine-b4ZH8esY.js +7317 -0
- package/dist/engine-b4ZH8esY.js.map +1 -0
- package/dist/index.d.ts +388 -224
- package/dist/index.js +331 -7795
- package/dist/index.js.map +1 -1
- package/dist/{invoke-BjrbCBSV.js → invoke-CyKNhvBw.js} +3 -3
- package/dist/{invoke-BjrbCBSV.js.map → invoke-CyKNhvBw.js.map} +1 -1
- package/dist/mcp.d.ts +2 -2
- package/dist/mcp.js +1 -1
- package/dist/otel.d.ts +1 -1
- package/dist/static/viewer.html +2 -1
- package/dist/stdio.d.ts +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +90 -0
- package/dist/testing.js +255 -0
- package/dist/testing.js.map +1 -0
- package/dist/trajectory-cSLNlHzh.d.ts +114 -0
- package/dist/{types-BDSbSUAO.d.ts → types-BqUY6nRX.d.ts} +25 -4
- package/dist/{types-B3HIsBBD.d.ts → types-CXBB4aIM.d.ts} +8 -4
- package/dist/ui.d.ts +2 -2
- package/dist/viewer.d.ts +117 -0
- package/dist/viewer.js +658 -0
- package/dist/viewer.js.map +1 -0
- package/package.json +27 -9
- package/dist/core-DgH4mDbK.js.map +0 -1
- package/dist/leading_system-CpkjHoCQ.js +0 -307
- package/dist/leading_system-CpkjHoCQ.js.map +0 -1
|
@@ -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
|
|
56
|
+
readonly run: StepFn<i, o>;
|
|
56
57
|
readonly config?: Readonly<Record<string, unknown>>;
|
|
57
|
-
readonly children?: ReadonlyArray<
|
|
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 {
|
|
63
|
-
//# sourceMappingURL=types-
|
|
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 {
|
|
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
|
|
535
|
-
* | `provider` | per-call wins; else default; else sole configured provider; else
|
|
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-
|
|
605
|
+
//# sourceMappingURL=types-CXBB4aIM.d.ts.map
|
package/dist/ui.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import {
|
|
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
|
/**
|
package/dist/viewer.d.ts
ADDED
|
@@ -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
|