fascicle 0.1.13 → 0.3.8

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 CHANGED
@@ -1,12 +1,130 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.3.8 — 2026-05-06
4
+
5
+ ### Fixed
6
+ - `examples/mcp-server/` lint failures that blocked `prepublishOnly`: rewrote the `reverse_text` tool to use `Intl.Segmenter` + `Array#toReversed()` (grapheme-correct, lint-clean), and replaced the chained `as` casts in `client.ts:text_of` with a small `is_record` user-defined type guard. Smoke test output unchanged.
7
+
8
+ ## v0.3.7 — 2026-05-05
9
+
10
+ ### Added
11
+ - Public `fascicle/adapters` subpath exposing `filesystem_logger`, `filesystem_store`, `http_logger`, `tee_logger`, and `noop_logger`. Previously these adapters lived in workspace-private packages and were unreachable by `npm install fascicle` consumers despite being referenced throughout the docs.
12
+ - Minimal stdio MCP server example under `examples/mcp-server/`, demonstrating how to expose a `Step<i, o>` as an MCP tool.
13
+ - `CONTRIBUTING.md` with contribution guidelines, linked from the README.
14
+
15
+ ### Changed
16
+ - README hero illustration is now an animated mycelium diagram showing model_call, step, and tool fruiting from a shared substrate; viewer screenshot moved into the live-dashboard section.
17
+ - Documented two adapter limits in `docs/concepts.md`: `filesystem_logger` writes synchronously via `appendFileSync`, and the in-memory span stack in `filesystem_logger`/`http_logger` is not async-context-aware. README, getting-started, cookbook, and writing-a-harness all cross-reference the new "Adapter limits" section.
18
+ - README primitives count corrected to 18, with `loop` and `compose` listed in the table.
19
+
20
+ ### Internal
21
+ - Added `docs/plans/menu.md` cataloguing considered-but-unshipped work.
22
+
23
+ ## v0.3.6 — 2026-04-30
24
+
25
+ ### Added
26
+ - `bench` primitive in `@repo/composites`: online counterpart to `learn`. `bench(flow, cases, judges, options?)` runs a flow against a fixture set, scores each output via judges, and returns a structured `BenchReport` with per-case results and summary (pass_rate, mean_scores per judge, total/mean cost). Per-case observability via `trajectory_dir` (one JSONL per case) and `live_url` (push to a viewer); both can be combined. Cost is tracked in-process by intercepting `cost` events on the trajectory pipeline.
27
+ - `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.
28
+ - `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.
29
+ - `tee_logger` adapter in `@repo/observability`: fan one `TrajectoryLogger` contract out to N sinks. First sink's `start_span` id is canonical; per-sink ids are translated back on `end_span`; sinks that throw don't derail the others.
30
+ - `examples/bench_reviewer.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.
31
+ - 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.
32
+ - `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.
33
+
34
+ ### Changed
35
+ - The viewer ships as part of the `fascicle` umbrella. `start_viewer` is importable from `'fascicle'`; the `fascicle-viewer` bin ships with the published tarball at `dist/bin/fascicle-viewer.js` (with `dist/static/viewer.html` copied alongside). `scripts/check-deps.mjs` now asserts inclusion (was: isolation). Runtime install graph stays free of HTTP-server deps because the viewer only uses `node:*` + `zod` + `@repo/core`.
36
+ - README promotes the viewer to a headline surface section with `pnpm dlx fascicle-viewer` and the programmatic `start_viewer` shape.
37
+
38
+ ### Internal
39
+ - `scripts/build.mjs` copies `viewer.html` into `dist/static/` and writes a tiny `dist/bin/fascicle-viewer.js` shim that drives `run_viewer_cli` from the bundled umbrella; smoke test asserts `start_viewer` and `run_viewer_cli` are exported.
40
+ - `spec/eval.md` records the four-wedge plan and seven open questions surfaced during execution (judge_llm wiring, judge abstention encoding, bench parallelism, baseline `run_id` non-determinism, two viewer UI papercuts, and the live-amplify dogfood result: 51 events, $0.1725 cost, both transports verified end-to-end).
41
+ - `spec/viewer.md` reframed packaging and §12 done-def items 2–3 marked verified.
42
+
43
+ ## v0.3.5 — 2026-04-30
44
+
45
+ ### Added
46
+ - `@repo/viewer` package and `fascicle-viewer` CLI: minimal in-repo dev dashboard for visualizing a fascicle run as it executes. Single static HTML page (vanilla JS, no build step), an SSE-fed span tree with active/error/emit highlighting, and a click-to-expand event log. Two transports feed one in-process broadcaster: file-tail (`fascicle-viewer .trajectory.jsonl`) for the primary case and HTTP push (`fascicle-viewer --listen` plus the new `http_logger`) for low-latency or remote attach. Localhost-only by default. Programmatic embed via `start_viewer({...})`. See `packages/viewer/README.md`.
47
+ - `http_logger` adapter in `@repo/observability`: a `TrajectoryLogger` that POSTs each event as one line of NDJSON to a configured URL. Drops on transport error, never blocks the user flow. Wire format mirrors `filesystem_logger` byte-for-byte and parses back via `trajectory_event_schema`.
48
+
49
+ ### Internal
50
+ - New ast-grep boundary rule (`rules/no-engine-import-from-viewer.yml`) keeps the viewer dev tool isolated from `@repo/engine`, composites, agents, the umbrella, stores, observability, and any provider SDK.
51
+ - `scripts/check-deps.mjs` gains a `check_viewer_isolation` invariant: `@repo/viewer` must not appear in `@repo/fascicle`'s dependency graph, so the published `fascicle` install graph stays free of HTTP-server deps.
52
+ - `spec/viewer.md` documents the v1 plan, scope boundaries, and the explicit non-goals that separate this dev tool from the larger `spec/studio.md` PDR.
53
+
54
+ ## v0.3.4 — 2026-04-30
55
+
56
+ ### Internal
57
+ - Switch to ASI-only style: trailing statement semicolons and multi-line interface/type-member separators removed across all TS sources.
58
+ - Add ast-grep rules (`no-semicolons`, `no-semicolons-types`) and a small orchestrator script (`scripts/strip-semicolons.mjs`) wired into `check:fix` to enforce the style going forward.
59
+
60
+ ## v0.3.3 — 2026-04-29
61
+
62
+ ### Added
63
+ - `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`.
64
+ - `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.
65
+
66
+ ## v0.3.2 — 2026-04-29
67
+
68
+ ### Added
69
+ - `@repo/agents` package: markdown-driven `define_agent` loader plus `reviewer`, `documenter`, and `researcher` agents. `reviewer` and `documenter` are markdown-defined; `researcher` is bespoke TypeScript that drives `loop` from core over injected `search`/`fetch` callables, with a per-round summarizer that itself uses `define_agent`.
70
+ - Examples wiring each new agent against an in-process stub engine, plus an end-to-end `learn_reviewer` demo that runs the reviewer over three diffs (writing JSONL via `filesystem_logger`) and feeds the directory to `learn` to derive prompt-tightening proposals.
71
+
72
+ ### Internal
73
+ - Tightened `learn` tests in `@repo/composites` around truncation events and `flow_description` equality.
74
+
75
+ ## v0.3.1 — 2026-04-29
76
+
77
+ ### Internal
78
+ - Colocated unit tests under `__tests__/` subfolders (e.g. `packages/core/src/branch.ts` ↔ `packages/core/src/__tests__/branch.test.ts`); cross-cutting tests under `packages/<name>/test/` are unchanged.
79
+
80
+ ## v0.3.0 — 2026-04-29
81
+
82
+ ### Added
83
+
84
+ - New core primitives `loop` and `compose`, plus a universal `name?` option on every composer.
85
+ - New `learn` composer in `@repo/composites` for offline self-improvement, with file-path and directory sources, exported from the package index.
86
+ - `amplify` self-improvement loop example with a demo helper providing chart, measure, and reset utilities.
87
+ - `learn` example with smoke test.
88
+ - `EffortLevel` extended with `xhigh` and `max`, and reasoning support added to the `claude_cli` adapter.
89
+ - `spec/plans/ideas.md` capturing possible directions to build on fascicle.
90
+
91
+ ### Changed
92
+
93
+ - `adversarial`, `ensemble`, `tournament`, and `consensus` extracted from `@repo/core` into a new `@repo/composites` package.
94
+
95
+ ### Fixed
96
+
97
+ - `loop` type parameter renamed from `out` to `o` so tsx can parse the source.
98
+
99
+ ### Internal
100
+
101
+ - Codegraph config plus ignore rules for db/cache files.
102
+ - Gitignored the rgr example trajectory output (per-run telemetry).
103
+ - Repaired the amplify cascade under tsc 6.x and `pnpm exec`.
104
+ - Imported adversarial types directly in the rgr harness; drive-by lint fixes for `pnpm check:all`.
105
+
106
+ ## v0.2.0 — 2026-04-26
107
+
108
+ ### Added
109
+
110
+ - Phase 0 library surfaces preparing for an upcoming `fascicle-studio` web UI: a `STEP_KINDS` const string union (plus `is_step_kind` and `StepKind`), structured Zod schemas for the trajectory wire format (`span_start_event_schema`, `span_end_event_schema`, `emit_event_schema`, `custom_event_schema`, and the combined `trajectory_event_schema`) configured to allow unknown fields so additional metadata survives a parse / re-serialize round-trip, an optional third-form `step(id, fn, meta?)` overload with `StepMetadata` (display name, description, port labels) echoed on `FlowNode` by `describe.json`, and automatic `run_id` stamping on every emitted trajectory event (a caller-supplied `run_id` is preserved). All re-exported through the `fascicle` umbrella.
111
+ - Contract tests locking the studio-facing invariants: `describe.json` is stable per `Step` instance, every emitted event id matches a node id in the flow tree, every event carries `run_id`, and every primitive's `kind` is in `STEP_KINDS`.
112
+ - Studio design doc plus parallel research notes at `spec/studio.md` and `spec/research/` capturing decisions for the sibling `fascicle-studio` repo.
113
+ - A red/green/refactor TDD harness example at `examples/red-green-refactor/`.
114
+ - `docs/til.md` with extracted snippets from pre-squash history.
115
+
116
+ ### Changed
117
+
118
+ - Dropped the npm scope from the published name (now `fascicle`). README streamlined.
119
+ - `prepublishOnly` no longer runs the Stryker mutation check; it stays available via `pnpm check:all`.
120
+
3
121
  ## v0.1.13 — 2026-04-25
4
122
 
5
123
  Initial public release. Fresh git baseline — prior internal commit history is intentionally not carried forward.
6
124
 
7
125
  The v0.1.13 surface:
8
126
 
9
- - Composition layer (`@robmclarty/fascicle` / internal `@repo/core`) — 16 primitives (`step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `retry`, `fallback`, `timeout`, `adversarial`, `ensemble`, `tournament`, `consensus`, `checkpoint`, `suspend`, `scope`/`stash`/`use`), `run`, `run.stream`, `describe`.
127
+ - Composition layer (`fascicle` / internal `@repo/core`) — 16 primitives (`step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `retry`, `fallback`, `timeout`, `adversarial`, `ensemble`, `tournament`, `consensus`, `checkpoint`, `suspend`, `scope`/`stash`/`use`), `run`, `run.stream`, `describe`.
10
128
  - AI engine layer (`@repo/engine`) — `create_engine(config)` returning a unified `generate` surface over seven Vercel AI SDK provider adapters: Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess adapter that drives the Claude Code CLI.
11
129
  - Adapter packages — `@repo/observability` (trajectory loggers), `@repo/stores` (checkpoint stores).
12
130
  - Check pipeline — `pnpm check` / `pnpm check:all` orchestrate types, lint, struct (ast-grep), dead-code (fallow), tests, docs, spell, and opt-in mutation testing (Stryker).
package/README.md CHANGED
@@ -1,224 +1,164 @@
1
1
  # Fascicle
2
2
 
3
- **`@robmclarty/fascicle` is a TypeScript library for composing agents out of LLM calls, tool calls, and plain functions.** Everything is a `Step<i, o>`; you wire steps together with 16 primitives (`sequence`, `parallel`, `branch`, `retry`, `ensemble`, `checkpoint`, …) and run them as plain values. One `generate` surface fronts seven provider adapters (Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess that drives Claude Code itself).
3
+ ![A substrate for agents — three mushrooms (model_call, step, tool) fruit from a shared mycelium network; every mushroom is a Step<i, o>, every thread is a composition](./mycelium.svg)
4
4
 
5
- No framework lifecycle, no ambient state, no decorators. Adapters get passed in per run, not configured globally. `npm install @robmclarty/fascicle` and you have the whole surface.
5
+ Compose agents out of LLM calls, tool calls, and plain functions. Everything is a `Step<i, o>`. Wire steps together with 18 primitives (`sequence`, `parallel`, `branch`, `retry`, `loop`, `ensemble`, `checkpoint`, …) and run them as plain values. One `generate` surface fronts seven provider adapters: Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess that drives the Claude Code CLI.
6
6
 
7
- Two layers:
7
+ No framework lifecycle. No ambient state. No decorators. Adapters are passed in per run.
8
8
 
9
- - **Composition (`@repo/core` internal / `@robmclarty/fascicle` public)** — 16 primitives (`step`, `sequence`, `parallel`, `branch`, `map`, `pipe`, `retry`, `fallback`, `timeout`, `adversarial`, `ensemble`, `tournament`, `consensus`, `checkpoint`, `suspend`, `scope`/`stash`/`use`) plus `run`, `run.stream`, and `describe`. Every composable unit is a `Step<i, o>`; every composer returns a `Step<i, o>`. Anywhere a step fits, any composition of steps fits.
10
- - **AI engine (`@repo/engine`)** — `create_engine(config)` returning a unified `generate` surface over seven AI SDK provider adapters: Anthropic, OpenAI, Google, OpenRouter, Ollama, LM Studio, and a `claude_cli` subprocess adapter that drives the Claude Code CLI.
9
+ ## Install
11
10
 
12
- `@robmclarty/fascicle` is a thin umbrella package that re-exports both layers so downstream apps can install one thing. Internally, workspace packages use the `@repo/*` prefix; the published name stays `@robmclarty/fascicle`.
13
-
14
- ## Names
15
-
16
- - **`@robmclarty/fascicle`** — the one thing you install from npm. Bundles the composition primitives and the engine.
17
- - **`@repo/core`, `@repo/engine`, `@repo/observability`, `@repo/stores`, `@repo/fascicle`** — workspace-only. Contributors see these internally; they are never published.
18
-
19
- Only `@robmclarty/fascicle` reaches npm. Contributors work against `@repo/*` symlinks inside this pnpm workspace.
20
-
21
- The monorepo split is an **architectural boundary enforcement mechanism**, not a distribution strategy. `@repo/core` cannot import from adapter packages; `@repo/engine` cannot reach outside its providers; `packages/config/` is the only place allowed to read `process.env`. Keeping those boundaries as separate workspace packages lets the dependency graph, fallow, and the ast-grep rules in `rules/` police them directly. Consumers still see one package.
22
-
23
- ## Layout
24
-
25
- ```text
26
- ├── packages/
27
- │ ├── fascicle/ umbrella: re-exports core + engine
28
- │ ├── core/ composition layer (16 primitives, run, describe)
29
- │ ├── engine/ AI engine layer (create_engine, generate)
30
- │ │ └── src/providers/ anthropic, openai, google, openrouter, ollama, lmstudio, claude_cli
31
- │ ├── config/ zod-validated env loader; only package that reads process.env
32
- │ ├── observability/ TrajectoryLogger adapters (noop, filesystem JSONL)
33
- │ └── stores/ CheckpointStore adapters (filesystem)
34
- ├── examples/ runnable reference harnesses (hello, streaming, ensemble, suspend, ollama)
35
- ├── rules/ ast-grep structural rules
36
- ├── scripts/check.mjs the check orchestrator
37
- ├── .ridgeline/ ridgeline project constraints, taste, and build dirs
38
- ├── docs/ concepts, providers, configuration, cookbook, CLI, harness guide
39
- ├── fallow.toml vitest.config.ts stryker.config.mjs cspell.json sgconfig.yml
40
- ├── AGENTS.md CLAUDE.md agent contracts
41
- └── package.json scripts + all devDependencies live here
11
+ ```bash
12
+ pnpm add fascicle zod
42
13
  ```
43
14
 
44
- Runtime dependencies live in the package that imports them; devDependencies live at the root. Cross-package imports go through workspace names (`@repo/core`), not relative paths.
15
+ Provider SDKs are optional peers — install only the ones you use. See [docs/providers.md](./docs/providers.md).
45
16
 
46
- ## The check contract
17
+ ## A 60-second tour
47
18
 
48
- `pnpm check:all` is the single source of truth for "is this done?". `pnpm check` runs the same pipeline minus the opt-in `mutation` step and is the command to use during iteration.
49
-
50
- | Check | Tool | Catches |
51
- | ---------- | -------------------------------- | ------------------------------------------------------------ |
52
- | `types` | `tsc` | Type errors (ground truth) |
53
- | `lint` | `oxlint` + `oxlint-tsgolint` | Syntax rules, floating promises, unsafe any, 50+ type-aware rules |
54
- | `struct` | `ast-grep` | Project-specific structural rules (see `rules/`) |
55
- | `dead` | `fallow` | Unused exports/files/deps, circular deps, duplication, complexity, boundary violations |
56
- | `test` | `vitest` + `@vitest/coverage-v8` | Unit test failures and coverage below thresholds |
57
- | `docs` | `markdownlint-cli2` | Broken markdown |
58
- | `spell` | `cspell` | Misspellings in source and docs |
59
- | `mutation` | `stryker` (opt-in) | Tests that pass trivially (run via `pnpm check:all` or `--include mutation`) |
60
-
61
- Deeper passes on demand:
62
-
63
- - `pnpm check:all` — full pipeline including Stryker mutation testing
64
- - `pnpm check --include mutation` — same as `check:all` but via the flag
65
- - `pnpm check:mutation` — Stryker only (bypasses the orchestrator)
66
- - `pnpm check:security` — `pnpm audit --audit-level=high`
67
- - `pnpm check:fix` — auto-fix oxlint and fallow issues where possible
19
+ ```typescript
20
+ import { run, sequence, step } from 'fascicle';
68
21
 
69
- ## Quick start
22
+ const flow = sequence([
23
+ step('add', (n: number) => n + 1),
24
+ step('double', (n: number) => n * 2),
25
+ ]);
70
26
 
71
- ```bash
72
- pnpm install
73
- pnpm check
27
+ await run(flow, 1); // 4
74
28
  ```
75
29
 
76
- Output lands in `.check/`:
77
-
78
- - `.check/summary.json` — aggregate result for agents
79
- - `.check/lint.json`, `.check/dead.json`, `.check/struct.json`, `.check/test.json` — raw per-tool JSON
80
- - `.check/coverage/` — vitest coverage report
81
-
82
- ## Using the composition layer
30
+ Add a model call:
83
31
 
84
32
  ```typescript
85
- import { run, sequence, step } from '@robmclarty/fascicle';
33
+ import { create_engine, model_call, run, sequence, step } from 'fascicle';
34
+
35
+ const engine = create_engine({
36
+ providers: { anthropic: { api_key: process.env.ANTHROPIC_API_KEY! } },
37
+ });
86
38
 
87
39
  const flow = sequence([
88
- step('a', (n: number) => n + 1),
89
- step('b', (n: number) => n * 2),
40
+ step('brief', (topic: string) => `Write a 2-sentence brief on: ${topic}`),
41
+ model_call({ engine, model: 'sonnet', system: 'No preamble.' }),
42
+ step('extract', (r) => r.content),
90
43
  ]);
91
44
 
92
- const result = await run(flow, 1); // 4
45
+ try {
46
+ console.log(await run(flow, 'Rust ownership'));
47
+ } finally {
48
+ await engine.dispose();
49
+ }
93
50
  ```
94
51
 
95
- Inject adapters per run:
52
+ `model_call` is the only sanctioned bridge between composition and the engine. It threads `ctx.abort`, `ctx.trajectory`, and streaming chunks for you.
96
53
 
97
- ```typescript
98
- import { filesystem_logger } from '@repo/observability';
99
- import { filesystem_store } from '@repo/stores';
54
+ ## What's in the box
100
55
 
101
- await run(flow, input, {
102
- trajectory: filesystem_logger({ output_path: '/tmp/run.jsonl' }),
103
- checkpoint_store: filesystem_store({ root_dir: '/tmp/checkpoints' }),
104
- });
105
- ```
56
+ **Composition primitives (18).** Every composer takes `Step<i, o>` and returns `Step<i, o>`. Anything that fits a step fits any composition of steps.
106
57
 
107
- `run.stream(flow, input)` returns `{ events, result }` for observation. See [`packages/core/README.md`](./packages/core/README.md) for the full surface and [`examples/`](./examples/) for runnable references.
58
+ | Primitive | Shape |
59
+ | --- | --- |
60
+ | `step` | lift a plain function into `Step<i, o>` |
61
+ | `sequence` | run A then B then C, threading the value |
62
+ | `parallel` | run a named map of steps concurrently |
63
+ | `branch` | route on a predicate of the input |
64
+ | `map` | run a step per array element, optional concurrency cap |
65
+ | `pipe` | post-process an inner step's output with a plain function |
66
+ | `retry` | re-run on failure with exponential backoff |
67
+ | `fallback` | run a backup if the primary throws |
68
+ | `timeout` | cancel an inner step after N ms |
69
+ | `loop` | bounded iteration with carry-state and an optional convergence guard |
70
+ | `compose` | label a composite so it shows up by intent in trajectories |
71
+ | `adversarial` | build, critique, repeat until accept or `max_rounds` |
72
+ | `ensemble` | run N members, pick the highest-scoring result |
73
+ | `tournament` | single-elimination bracket |
74
+ | `consensus` | run N concurrently, accept only if `>= quorum` agree |
75
+ | `checkpoint` | memoize an inner step by key in a `CheckpointStore` |
76
+ | `suspend` | pause for external input; resume later with `resume_data` |
77
+ | `scope` / `stash` / `use` | named state across non-adjacent steps |
108
78
 
109
- ## Using the engine layer
79
+ Plus `run`, `run.stream`, and `describe`.
110
80
 
111
- ```typescript
112
- import { create_engine } from '@robmclarty/fascicle';
81
+ **AI engine.** `create_engine(config)` returns one `generate` surface across seven providers. Aliases (`sonnet`, `opus`, `gpt-4o`, `cli-sonnet`, …) resolve to `provider:model_id`. Reasoning effort (`'low' | 'medium' | 'high'`) is translated per provider. Cost estimation uses a pricing table with per-engine overrides.
113
82
 
114
- const engine = create_engine({
115
- providers: { anthropic: { api_key: process.env.ANTHROPIC_API_KEY! } },
116
- });
83
+ **Adapters injected per run.** Trajectory loggers and checkpoint stores ship under the `fascicle/adapters` subpath:
117
84
 
118
- const result = await engine.generate({
119
- model: 'claude-sonnet-4-5',
120
- messages: [{ role: 'user', content: 'hello' }],
121
- });
85
+ ```typescript
86
+ import { filesystem_logger, filesystem_store } from 'fascicle/adapters';
122
87
 
123
- await engine.dispose();
88
+ await run(flow, input, {
89
+ trajectory: filesystem_logger({ output_path: '.trajectory.jsonl' }),
90
+ checkpoint_store: filesystem_store({ root_dir: '.checkpoints' }),
91
+ });
124
92
  ```
125
93
 
126
- Provider adapters are wired behind optional peer dependencies; install only the ones you use. See [`docs/providers.md`](./docs/providers.md) for the full provider matrix, [`docs/configuration.md`](./docs/configuration.md) for engine config, and [`docs/cli.md`](./docs/cli.md) for the `claude_cli` adapter.
94
+ `filesystem_logger` writes synchronously and the bundled span stacks aren't async-context-aware — fine for dev tools and short-lived runs, see [docs/concepts.md](./docs/concepts.md#adapter-limits) before wiring it into a long-running server. The `TrajectoryLogger` and `CheckpointStore` contracts (exported from `fascicle`) are tiny — roll your own to push events to Honeycomb, S3, etc.
127
95
 
128
- ## Agent use
96
+ `run.stream(flow, input)` returns `{ events, result }` for incremental observation.
129
97
 
130
- The contract: **if `pnpm check` exits 0, the work is done. If it exits non-zero, read `.check/summary.json` for which checks failed, then the corresponding tool JSON for diagnostics.**
98
+ ## Provider matrix
131
99
 
132
- ```jsonc
133
- // .check/summary.json
134
- {
135
- "timestamp": "2026-04-20T...",
136
- "ok": false,
137
- "total_duration_ms": 4821,
138
- "checks": [
139
- { "name": "types", "ok": true, "exit_code": 0, "duration_ms": 1200, "output_file": null },
140
- { "name": "lint", "ok": false, "exit_code": 1, "duration_ms": 340, "output_file": "lint.json" }
141
- ]
142
- }
143
- ```
100
+ | Provider | Peer dep | Auth |
101
+ | ------------ | ----------------------------- | ------------------- |
102
+ | `anthropic` | `@ai-sdk/anthropic` | API key |
103
+ | `openai` | `@ai-sdk/openai` | API key |
104
+ | `google` | `@ai-sdk/google` | API key |
105
+ | `openrouter` | `@openrouter/ai-sdk-provider` | API key |
106
+ | `ollama` | `ai-sdk-ollama` | local `base_url` |
107
+ | `lmstudio` | `@ai-sdk/openai-compatible` | local `base_url` |
108
+ | `claude_cli` | none (spawns `claude`) | OAuth or API key |
144
109
 
145
- Flags:
110
+ Full details: [docs/providers.md](./docs/providers.md). The `claude_cli` adapter has its own guide: [docs/cli.md](./docs/cli.md).
146
111
 
147
- - `pnpm check --json` — machine-readable to stdout, no human decoration
148
- - `pnpm check --bail` — stop at the first failure
149
- - `pnpm check --only types,lint` — run a subset during iteration
150
- - `pnpm check --skip spell,docs` — skip slow or noisy checks
112
+ ## Live dev dashboard
151
113
 
152
- ## Working across packages
114
+ ![fascicle-viewer running against an amplify trajectory: span tree on the left, event log on the right, $2.55 cost rolled up in the header](./screenshot.png)
153
115
 
154
- `pnpm check` always runs over the whole workspace — that's the shipping gate. For tighter per-package loops:
116
+ The `fascicle-viewer` bin ships with the umbrella package. Point it at a trajectory file and it opens a browser tree of spans, errors, and emits as the run executes:
155
117
 
156
118
  ```bash
157
- pnpm --filter @repo/core test # run one package's tests
158
- pnpm --filter @repo/engine add zod # add a runtime dep to one package
159
- pnpm add -w -D typescript@latest # upgrade a root devDependency
119
+ pnpm dlx fascicle-viewer .trajectory.jsonl
160
120
  ```
161
121
 
162
- Inter-package deps use the workspace protocol:
163
-
164
- ```bash
165
- pnpm --filter @repo/fascicle add @repo/core --workspace
166
- ```
122
+ Or embed it programmatically:
167
123
 
168
- ## MCP servers
124
+ ```typescript
125
+ import { start_viewer } from 'fascicle';
169
126
 
170
- `.mcp.json` wires two servers for agent clients (Claude Code / Cursor / Windsurf):
127
+ const handle = await start_viewer({ port: 4242 });
128
+ // later
129
+ await handle.close();
130
+ ```
171
131
 
172
- - **`fallow`** — structured codebase analysis (`analyze`, `check_changed`, `find_dupes`, `check_health`, `fix_preview`, `fix_apply`, `project_info`). Use during implementation for real-time dead-code and boundary feedback instead of waiting for the final `pnpm check`.
173
- - **`ast-grep`** — structural code search and rule testing against the YAML rules in `rules/`.
132
+ For zero-latency streaming from inside a long-running flow, pair it with `http_logger` from `fascicle/adapters`. See [packages/viewer/README.md](./packages/viewer/README.md) for the full transport story.
174
133
 
175
- Confirm with `claude mcp list`.
134
+ ## Where to go next
176
135
 
177
- ## Extending
136
+ - [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
137
+ - [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
138
+ - [docs/configuration.md](./docs/configuration.md) — engine config, aliases, pricing, retries
139
+ - [docs/providers.md](./docs/providers.md) — per-provider adapter notes
140
+ - [docs/cli.md](./docs/cli.md) — the `claude_cli` subprocess adapter
141
+ - [docs/cookbook.md](./docs/cookbook.md) — retries, fan-out, judges, HITL, tool loops
142
+ - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
143
+ - [examples/](./examples/) — runnable reference flows
144
+ - [packages/viewer/README.md](./packages/viewer/README.md) — viewer details and transport options
178
145
 
179
- **Add a check.** Edit `scripts/check.mjs` and append to `CHECKS`:
146
+ ## Contributing
180
147
 
181
- ```js
182
- {
183
- name: 'agent',
184
- description: 'agnix: AI config linting',
185
- command: 'pnpm',
186
- args: ['exec', 'agnix', '--format', 'json', '.'],
187
- output_file: 'agent.json',
188
- }
189
- ```
148
+ Fascicle is early and not accepting outside pull requests yet. Bug reports and feature ideas via GitHub Issues are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
190
149
 
191
- **Add a structural rule.** Drop a YAML file into `rules/`. Existing rules enforce no classes, no default exports, snake_case exports, no `process.env` outside `@repo/config`, no provider SDK imports outside `packages/engine/src/providers`, no `child_process` outside the `claude_cli` adapter, and several cross-package import boundaries. ast-grep picks new rules up automatically.
150
+ ## Development
192
151
 
193
- **Add an architecture boundary.** Edit `fallow.toml`:
152
+ This repo is a pnpm workspace. Internally the code is split into `@repo/core`, `@repo/engine`, `@repo/observability`, `@repo/stores`, and `@repo/fascicle` (umbrella). Only the umbrella reaches npm as `fascicle`. The split exists to enforce architectural boundaries (e.g. `@repo/core` cannot import adapters; only `@repo/config` reads `process.env`); fallow and the ast-grep rules in `rules/` police them.
194
153
 
195
- ```toml
196
- [[boundaries.rules]]
197
- from = "packages/*/src/**"
198
- cannotImport = ["../*/src/**"] # no cross-package relative imports; use workspace names
154
+ ```bash
155
+ pnpm install
156
+ pnpm check # types, lint, structural rules, dead-code, tests, docs, spell
157
+ pnpm check:all # adds Stryker mutation testing (slow; final gate)
199
158
  ```
200
159
 
201
- **Add a package.** Create `packages/<name>/package.json` (name `@repo/<name>`, `type: module`, `private: true`, `exports`) and `packages/<name>/src/index.ts`. Run `pnpm install` to wire the symlink. Root `tsconfig.json`, `vitest.config.ts`, `fallow.toml`, `cspell.json`, `stryker.config.mjs`, and `rules/` already glob across `packages/*/src/**`.
202
-
203
- ## Philosophy
160
+ `pnpm check` is the single source of truth for "is this done?". Output lands in `.check/` (one JSON per check). See [AGENTS.md](./AGENTS.md) for the full contract and [CLAUDE.md](./CLAUDE.md) for Claude-specific notes.
204
161
 
205
- 1. **The check is the contract.** A single command the agent can trust. No hidden CI gates.
206
- 2. **Structured output over stderr chatter.** Every JSON-capable tool is configured to emit JSON. Agents parse structured data, not colorized text.
207
- 3. **The orchestrator is dumb.** It shells out, captures exit codes, and writes files. It does not parse diagnostics.
208
- 4. **Tools, not frameworks.** Each tool is independently swappable. If something better than oxlint ships next year, you change one line in `CHECKS`.
209
- 5. **Step-as-value.** In the composition layer, every unit is a `Step<i, o>` and every composer returns one. Substitutability, introspectability, and no coupling fall out of that one invariant.
162
+ ## License
210
163
 
211
- ## Related docs
212
-
213
- - [AGENTS.md](./AGENTS.md) — universal contract for any coding agent
214
- - [CLAUDE.md](./CLAUDE.md) — Claude-specific workflow notes
215
- - [CHANGELOG.md](./CHANGELOG.md) — version history
216
- - [docs/getting-started.md](./docs/getting-started.md) — install + first flow
217
- - [docs/concepts.md](./docs/concepts.md) — step-as-value, composition, trajectories
218
- - [docs/configuration.md](./docs/configuration.md) — engine config, aliases, provider setup
219
- - [docs/providers.md](./docs/providers.md) — per-provider adapter notes
220
- - [docs/cli.md](./docs/cli.md) — `claude_cli` subprocess adapter
221
- - [docs/cookbook.md](./docs/cookbook.md) — worked patterns (retries, fan-out, judges, HITL)
222
- - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
223
- - [packages/core/README.md](./packages/core/README.md) — composition layer surface
224
- - [.ridgeline/](./.ridgeline/) — project constraints, taste, and ridgeline build history
164
+ [Apache 2.0](./LICENSE)
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ import { pathToFileURL } from 'node:url';
3
+ import { dirname, resolve } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+
6
+ const here = dirname(fileURLToPath(import.meta.url));
7
+ const dist_index = resolve(here, '..', 'index.js');
8
+ const mod = await import(pathToFileURL(dist_index).href);
9
+ await mod.run_viewer_cli(process.argv.slice(2));