fascicle 0.12.3 → 0.12.7
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 +61 -6
- package/README.md +3 -2
- package/dist/agents.d.ts +1 -1
- package/dist/agents.js +1 -1
- package/dist/{core-DdJEhyQc.js → core-CFdEjtiT.js} +281 -270
- package/dist/core-CFdEjtiT.js.map +1 -0
- package/dist/{engine-J4lIxpw5.js → engine-DQiQHiy8.js} +182 -34
- package/dist/engine-DQiQHiy8.js.map +1 -0
- package/dist/index.d.ts +28 -2
- package/dist/index.js +48 -4
- package/dist/index.js.map +1 -1
- package/dist/{invoke-CH_eJZeS.js → invoke-eEYMZmWg.js} +3 -3
- package/dist/{invoke-CH_eJZeS.js.map → invoke-eEYMZmWg.js.map} +1 -1
- package/dist/{leading_system-BUCT-PwD.js → leading_system-DQmlA6Fs.js} +2 -2
- package/dist/{leading_system-BUCT-PwD.js.map → leading_system-DQmlA6Fs.js.map} +1 -1
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +1 -1
- package/dist/otel.d.ts +20 -2
- package/dist/otel.js +228 -8
- package/dist/otel.js.map +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/{types-DU6cvoA4.d.ts → types-CLigYA62.d.ts} +28 -2
- package/dist/viewer-app/assets/index-BGb1-MwM.js +2 -0
- package/dist/viewer-app/assets/index-D7kvKs40.css +1 -0
- package/dist/viewer-app/fonts/sora-OFL.txt +93 -0
- package/dist/viewer-app/fonts/sora-latin.woff2 +0 -0
- package/dist/viewer-app/fonts/spline-sans-mono-OFL.txt +93 -0
- package/dist/viewer-app/fonts/spline-sans-mono-latin.woff2 +0 -0
- package/dist/viewer-app/index.html +13 -0
- package/dist/viewer.d.ts +17 -3
- package/dist/viewer.js +210 -50
- package/dist/viewer.js.map +1 -1
- package/package.json +14 -3
- package/dist/core-DdJEhyQc.js.map +0 -1
- package/dist/engine-J4lIxpw5.js.map +0 -1
- package/dist/static/viewer.html +0 -375
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,60 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.12.7 — 2026-09-01
|
|
4
|
+
|
|
5
|
+
Everything in v0.12.6 ships here for the first time: that version was tagged but never reached npm, because its publish run failed on the gate described below. Upgrading from v0.12.5 picks up both sections.
|
|
6
|
+
|
|
7
|
+
### Internal
|
|
8
|
+
|
|
9
|
+
- **The release gate reads the release notes now.** The v0.12.6 changelog entry carried a sentence with two semicolons, which the `prose` slot rejects (vale's `Repo.Semicolon` rule). The narrow check the release skill runs before tagging covered `docs`, `links`, and `spell` only, so the sentence passed locally and then failed inside `publish.yaml`, stranding the tag on a commit that could never pass. The sentence is split in two, and the pre-tag gate now runs `prose` and `prose-health` as well, because vale reads `CHANGELOG.md` like any other markdown.
|
|
10
|
+
|
|
11
|
+
## v0.12.6 — 2026-09-01
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- **The viewer draws a run canvas now.** The one static HTML page is replaced by a compiled Solid app that ships prebuilt inside the package, so running the viewer is still one command with nothing to build. The canvas is structure first: it computes a metro-line layout from the flow's `describe.json` tree and draws the whole composition dim and dashed before a single step runs, then the run moves through that geometry as amber light. Retry draws as a loop in the line, fallback as a bypass basin that reroutes when the primary fails, a terminal failure as a scarred puck, and map instances as perpendicular ticks that become a ruler comb at scale, with suspended, emitting, and annotation states carrying their own card treatments. Two properties are load-bearing and gated by `pnpm check:all`: the runtime dependency list stays empty, and the bundle is offline (vendored fonts, no CDN, no telemetry).
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **Every run scrubs.** Canvas state is a pure fold of events up to a time, and live mode is that fold pinned to the newest event, so replay is the same fold stopped earlier rather than a second render path. A time spine along the bottom margin carries the playhead. Scrub off the live edge and the LIVE chip becomes REPLAY with a `RETURN TO LIVE` control. Arrow keys step one event, shifted arrows step one second, and Home and End jump to T+0 and the live edge. The server grew `GET /api/trajectory`, which streams the full run history as NDJSON so the client folds the whole run on load and follows SSE from the cursor that route names, never double-counting. An off-by-default DENSITY dial shades the spine where events crowd together, and the choice persists across sessions.
|
|
20
|
+
|
|
21
|
+
- **Play mode performs the run.** Press play at T+0 and the canvas replays the run on its real timestamp deltas: speeds of 1x, 2x, and 3x, a compression dial (on by default) that caps any single inter-event gap at about two seconds so a ten-minute run plays in a minute or two, a loop toggle for booth-style playback, and controls that fade while a performance runs with the cursor idle.
|
|
22
|
+
|
|
23
|
+
- **The trajectory records what a canvas needs.** Every observed run now opens with a `flow_structure` event, the `describe.json` tree embedded verbatim, recorded only when a logger or stream consumer is present so an unobserved run pays nothing for the walk. `suspend`'s gate records a `suspended` event before it throws, carrying `suspend_id` plus the step id that joins it back to its `flow_structure` node, so a consumer sees the pause as its own event ahead of the span-end error. And `cost`, `turn_retry`, and `response_received` carry the enclosing step's `span_id`, so a consumer attributes them to the exact turn rather than an open-span-stack guess, which mis-attributes under parallel. The field is additive and optional, so fixtures without it keep the old fallback.
|
|
24
|
+
|
|
25
|
+
### Internal
|
|
26
|
+
|
|
27
|
+
- Rewrote `docs/viewer.md` around the run canvas, and pinned the viewer server's heartbeat, close, error, and 500 paths plus the tailer's io-error, drain, stop, and coalescing paths in tests.
|
|
28
|
+
|
|
29
|
+
## v0.12.5 — 2026-08-21
|
|
30
|
+
|
|
31
|
+
Everything in v0.12.4 ships here for the first time: that version was tagged but never reached npm, because its publish run failed on the gate described below. Upgrading from v0.12.3 picks up both sections.
|
|
32
|
+
|
|
33
|
+
### Fixed
|
|
34
|
+
|
|
35
|
+
- **A type error only CI could see.** `examples/otel-grafana/main.ts` imports `fascicle/otel`, which had no `tsconfig` `paths` entry, so TypeScript fell through to the package `exports` map and resolved the subpath from `./dist/otel.d.ts`. That file is present on any machine that has built before, so the `types` slot passed locally and failed on CI's clean checkout, where `pnpm check` runs ahead of `pnpm build`. `fascicle/viewer` carried the same gap with no importer to expose it yet. Both point at source now, and the `deps` slot fails if a published `exports` subpath ever loses its mapping again.
|
|
36
|
+
|
|
37
|
+
### Internal
|
|
38
|
+
|
|
39
|
+
- **A failed check job keeps its evidence.** checkride prints one pass/fail line per slot and writes each tool's real output to `.check/`, so a red run named the failing slot without saying why. Every workflow that runs the suite now uploads that directory as an artifact on failure, minus the coverage and mutation report trees that account for most of its size.
|
|
40
|
+
- **The `claude_cli` spawn tests no longer race their own mock.** Both SIGTERM escalator tests slept 150ms to let the mock install its handler before signalling it, which is a bet on how long a cold Node start takes: measured spawn to handler ran from 42ms idle to 127ms under a process spawn storm against that budget. The mock now signals readiness through a file and the tests wait for it.
|
|
41
|
+
|
|
42
|
+
## v0.12.4 — 2026-08-21
|
|
43
|
+
|
|
44
|
+
### Added
|
|
45
|
+
|
|
46
|
+
- **Per-step model timing, and tokens per second derived from it.** Every step the tool loop produces carries a `StepTiming` block (`started_at`, `duration_ms`, and `first_chunk_ms` on streamed turns), stamped so only the successful attempt is measured: failed attempts, backoff waits, and tool execution never inflate the number. `throughput()` derives tokens per second from a `GenerateResult`, a step array, or a single step, and names its basis (`decode` when every turn streamed, `blended` when any window includes network and prefill). The ollama native adapter passes the daemon's own nanosecond durations through `provider_reported.ollama` verbatim.
|
|
47
|
+
|
|
48
|
+
- **The trajectory stream is dashboard-ready: retry events and opt-in OTel metrics.** `response_received` carries the full flat per-turn record, every absorbed retry becomes a `turn_retry` event (attempt, classified failure kind, HTTP status, and the honored backoff delay), and the closing `engine.generate` span reports step and tool-call counts. On the `fascicle/otel` side, span meta flattens one level so a dashboard can query `fascicle.usage.input_tokens`, and a new opt-in `metrics` option records the GenAI semconv client histograms plus cost and retry instruments, tagged with provider and model.
|
|
49
|
+
|
|
50
|
+
- **A Grafana walkthrough.** `docs/grafana.md` tells the end-to-end story for the `fascicle/otel` bridge: the mental model, a three-step keyless demo against the `grafana/otel-lgtm` container, wiring for a real app, what each metric means, and hand-built panel queries, with an importable dashboard JSON beside the example.
|
|
51
|
+
|
|
52
|
+
### Changed
|
|
53
|
+
|
|
54
|
+
- **Every example lives in its own folder now, with a README and a screenshot of a real run.** The 28 single-file demos moved to `examples/<name>/main.ts`, the seven app workspaces kept their layout and gained screenshots, and the shared agents library got a README. The screenshots are captures rather than mockups: keyless demos as terminal renders, local Ollama and `claude` sessions for the model-backed ones, the viewer UI, and Grafana dashboard and Tempo trace views fed by the demo. Every cross-reference in `docs/`, the README, and the site follows the new paths.
|
|
55
|
+
|
|
56
|
+
- **`structured-output` and `tool-loop` run on the `openrouter` provider.** The pair used to require `ANTHROPIC_API_KEY`; they now read `OPENROUTER_API_KEY`, matching `live-smoke`, and their hand-rolled key guards are gone because `create_engine` already rejects an empty `api_key` with a message that names the fix.
|
|
57
|
+
|
|
3
58
|
## v0.12.3 — 2026-08-19
|
|
4
59
|
|
|
5
60
|
### Changed
|
|
@@ -132,9 +187,9 @@
|
|
|
132
187
|
|
|
133
188
|
- **Compile-time joint checking for literal `sequence` tuples.** Each child of a literal tuple must accept its predecessor's output, and a mismatch errors on the offending element. Arrays built at runtime still degrade to unknown boundaries; annotate the outer `Step<In, Out>` to keep the flow's boundary checked.
|
|
134
189
|
|
|
135
|
-
- **Docs for the layering.** `docs/leaf-arm-spine.md` names the leaf / arm / spine shape and the decision rules at each layer, `docs/advanced-composition.md` covers the demoted tier (`scope`/`stash`/`use`, plain `ensemble`, `tournament`, `improve`/`learn`), and `examples/newsroom.ts` is the vocabulary tour that uses every primary primitive once.
|
|
190
|
+
- **Docs for the layering.** `docs/leaf-arm-spine.md` names the leaf / arm / spine shape and the decision rules at each layer, `docs/advanced-composition.md` covers the demoted tier (`scope`/`stash`/`use`, plain `ensemble`, `tournament`, `improve`/`learn`), and `examples/newsroom/main.ts` is the vocabulary tour that uses every primary primitive once.
|
|
136
191
|
|
|
137
|
-
- **A one-file style pair in the examples.** `examples/
|
|
192
|
+
- **A one-file style pair in the examples.** `examples/release-notes/main.ts` and `examples/release-notes-direct/main.ts` build the same release-notes flow two ways (composed through `chain` and arms, and written straight through as one function), so the cost and the benefit of composing are readable side by side rather than asserted. `docs/blueprint.md` is rebuilt around `chain` and points at the pair.
|
|
138
193
|
|
|
139
194
|
### Changed
|
|
140
195
|
|
|
@@ -392,14 +447,14 @@ work is in the docs surface, the example apps, and the check suite.
|
|
|
392
447
|
|
|
393
448
|
- Releases are now published from CI with npm Trusted Publishing (OIDC) and a signed provenance attestation, gated by a required-reviewer GitHub Environment (`.github/workflows/publish.yaml`). No long-lived npm token exists anywhere; verify a release with `npm audit signatures`. This makes v0.9.0 the first provenance-attested Fascicle publish (see `research/provenance-publish-spec.md`).
|
|
394
449
|
- Agent-layer boundary ADR: Fascicle stays on the single-turn seam (`generateText`/`streamText`) and declines the v7 agent layer (`ToolLoopAgent`, `WorkflowAgent`, `HarnessAgent`, `toolApproval`, `@ai-sdk/otel`), recorded in `research/explorations/2026-07-ai-sdk-agent-layer-boundary.md` and linked from `docs/providers.md`.
|
|
395
|
-
- `examples/
|
|
450
|
+
- `examples/live-smoke/main.ts`: a manual release smoke gate that runs one tool-loop flow streamed and non-streamed against OpenRouter and an OpenAI-compatible backend, checking the tool round trip, stream/record text parity, and usage/cost accounting. Live network, so it stays out of the test suite by design.
|
|
396
451
|
- Dev toolchain sweep: vitest 4.1.10, oxlint 1.73, oxlint-tsgolint 0.24, tsdown 0.22.3, zod 4.4.3, `@types/node` 26, fallow 3, and friends.
|
|
397
452
|
|
|
398
453
|
## v0.8.16 — 2026-07-07
|
|
399
454
|
|
|
400
455
|
### Added
|
|
401
456
|
|
|
402
|
-
- `fascicle/ui` subpath for streaming a run into an AI SDK `useChat` UI: `to_ui_message_response`, `pipe_ui_message_stream_to_response`, and `to_ui_message_chunks` translate trajectory `model_chunk` events onto the AI SDK UI message wire. Ships with `docs/human-in-the-loop.md` and `examples/
|
|
457
|
+
- `fascicle/ui` subpath for streaming a run into an AI SDK `useChat` UI: `to_ui_message_response`, `pipe_ui_message_stream_to_response`, and `to_ui_message_chunks` translate trajectory `model_chunk` events onto the AI SDK UI message wire. Ships with `docs/human-in-the-loop.md` and `examples/hitl-http/main.ts` covering suspend/confirm/resume over HTTP.
|
|
403
458
|
|
|
404
459
|
### Changed
|
|
405
460
|
|
|
@@ -691,7 +746,7 @@ work is in the docs surface, the example apps, and the check suite.
|
|
|
691
746
|
- `judge_equals`, `judge_with`, `judge_llm` in `@repo/composites`: stock judges over `{ input, output, meta }`. `judge_llm` takes a `Step<string, string>` model so composites stays engine-free; users wire their own `model_call({...})` into the judge.
|
|
692
747
|
- `regression_compare`, `read_baseline`, `write_baseline`: diff two `BenchReport`s against `pass_rate`, per-judge means, and a relative cost threshold (default 10%). Doesn't short-circuit; full delta + per-case report.
|
|
693
748
|
- `tee_logger` adapter in `@repo/observability`: fan one `TrajectoryLogger` contract out to N sinks. First sink's `start_span` id is canonical, and per-sink ids are translated back on `end_span`. Sinks that throw don't derail the others.
|
|
694
|
-
- `examples/
|
|
749
|
+
- `examples/bench-reviewer/main.ts` + `bench/reviewer/{cases.json,baseline.json}`: end-to-end driver against `@repo/agents`'s `reviewer`. `WRITE_BASELINE=1` records, subsequent runs compare and exit 1 on regression.
|
|
695
750
|
- Cost rendering in the viewer: per-span cost badges that roll up the tree, plus a header running total (`<n> events · <m> errors · $<total>`). Run filter narrows the total. Cost attribution uses an open-span stack per `run_id`; format is 4 decimals under $0.01, 2 decimals otherwise.
|
|
696
751
|
- `examples/amplify` opt-in viewer push via `AMPLIFY_VIEWER_URL`: tees the on-disk trajectory with `http_logger` when set; standalone runs without the env var keep the existing single-sink behaviour.
|
|
697
752
|
|
|
@@ -724,7 +779,7 @@ work is in the docs surface, the example apps, and the check suite.
|
|
|
724
779
|
## v0.3.3 — 2026-04-29
|
|
725
780
|
|
|
726
781
|
### Added
|
|
727
|
-
- `improve` composite in `@repo/composites`: bounded online self-improvement loop with parallel proposers, structured lessons accumulator, plateau detection, and configurable wall-clock + round budgets. Online counterpart to `learn`. Example at `examples/improve.ts`.
|
|
782
|
+
- `improve` composite in `@repo/composites`: bounded online self-improvement loop with parallel proposers, structured lessons accumulator, plateau detection, and configurable wall-clock + round budgets. Online counterpart to `learn`. Example at `examples/improve/main.ts`.
|
|
728
783
|
- `ensemble_step` composite: Step-based sibling of `ensemble` for cases where scoring is itself a `Step`. Returns `winner_id`, `winner`, structured `winner_scored`, and the full `scored` map.
|
|
729
784
|
|
|
730
785
|
## v0.3.2 — 2026-04-29
|
package/README.md
CHANGED
|
@@ -14,7 +14,7 @@ pnpm add fascicle
|
|
|
14
14
|
|
|
15
15
|
Fascicle is ESM-only and requires Node >= 24. `ai`, `zod`, and every provider SDK are optional peers — install only the ones you use. `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli`, with no AI SDK package and no schema library installed at all; schemas accept any [Standard Schema](https://standardschema.dev) — zod, ArkType, Valibot, whichever you already use. See [docs/providers.md](./docs/providers.md).
|
|
16
16
|
|
|
17
|
-
No API key on hand? Several runnable examples need zero keys: [examples/hello.ts](./examples/hello.ts), [examples/
|
|
17
|
+
No API key on hand? Several runnable examples need zero keys: [examples/hello/main.ts](./examples/hello/main.ts), [examples/suspend-resume/main.ts](./examples/suspend-resume/main.ts), and [examples/viewer-demo/main.ts](./examples/viewer-demo/main.ts) use no engine at all, and [examples/newsroom/main.ts](./examples/newsroom/main.ts) runs the full vocabulary against the bundled stub engine from `fascicle/testing`.
|
|
18
18
|
|
|
19
19
|
## A 60-second tour
|
|
20
20
|
|
|
@@ -221,8 +221,9 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
|
|
|
221
221
|
- [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
|
|
222
222
|
- [docs/adoption-decision.md](./docs/adoption-decision.md) weighs whether to adopt Fascicle: the honest case, the risks, and when to reach for something else
|
|
223
223
|
- [docs/roadmap.md](./docs/roadmap.md) — what has shipped, what is being considered, and what Fascicle deliberately will not do
|
|
224
|
-
- [examples/](./examples/) — runnable reference flows; start with [examples/newsroom.ts](./examples/newsroom.ts), the vocabulary tour
|
|
224
|
+
- [examples/](./examples/) — runnable reference flows; start with [examples/newsroom/main.ts](./examples/newsroom/main.ts), the vocabulary tour
|
|
225
225
|
- [docs/viewer.md](./docs/viewer.md) — viewer details and transport options
|
|
226
|
+
- [docs/grafana.md](./docs/grafana.md) — shipping a run's traces and metrics to a Grafana dashboard over OpenTelemetry
|
|
226
227
|
|
|
227
228
|
## Contributing
|
|
228
229
|
|
package/dist/agents.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as Step } from "./types-DBpU27sQ.js";
|
|
2
2
|
import { r as ToolSchema } from "./types-BK0UW28o.js";
|
|
3
|
-
import { a as Engine, i as EffortLevel } from "./types-
|
|
3
|
+
import { a as Engine, i as EffortLevel } from "./types-CLigYA62.js";
|
|
4
4
|
|
|
5
5
|
//#region src/agents/define_agent.d.ts
|
|
6
6
|
type AgentBuiltPrompt = string | {
|
package/dist/agents.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { S as assert_valid_step_id, k as aborted_error, x as step } from "./core-CFdEjtiT.js";
|
|
2
2
|
import { readFileSync } from "node:fs";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
//#region src/agents/define_agent.ts
|