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 +119 -1
- package/README.md +107 -167
- package/dist/bin/fascicle-viewer.js +9 -0
- package/dist/index.d.ts +474 -69
- package/dist/index.js +2263 -548
- package/dist/index.js.map +1 -1
- package/dist/static/viewer.html +374 -0
- package/package.json +9 -3
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 (
|
|
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
|
-
|
|
3
|
+

|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
No framework lifecycle. No ambient state. No decorators. Adapters are passed in per run.
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
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
|
-
|
|
15
|
+
Provider SDKs are optional peers — install only the ones you use. See [docs/providers.md](./docs/providers.md).
|
|
45
16
|
|
|
46
|
-
##
|
|
17
|
+
## A 60-second tour
|
|
47
18
|
|
|
48
|
-
|
|
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
|
-
|
|
22
|
+
const flow = sequence([
|
|
23
|
+
step('add', (n: number) => n + 1),
|
|
24
|
+
step('double', (n: number) => n * 2),
|
|
25
|
+
]);
|
|
70
26
|
|
|
71
|
-
|
|
72
|
-
pnpm install
|
|
73
|
-
pnpm check
|
|
27
|
+
await run(flow, 1); // 4
|
|
74
28
|
```
|
|
75
29
|
|
|
76
|
-
|
|
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 '
|
|
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('
|
|
89
|
-
|
|
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
|
-
|
|
45
|
+
try {
|
|
46
|
+
console.log(await run(flow, 'Rust ownership'));
|
|
47
|
+
} finally {
|
|
48
|
+
await engine.dispose();
|
|
49
|
+
}
|
|
93
50
|
```
|
|
94
51
|
|
|
95
|
-
|
|
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
|
-
|
|
98
|
-
import { filesystem_logger } from '@repo/observability';
|
|
99
|
-
import { filesystem_store } from '@repo/stores';
|
|
54
|
+
## What's in the box
|
|
100
55
|
|
|
101
|
-
|
|
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
|
-
|
|
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
|
-
|
|
79
|
+
Plus `run`, `run.stream`, and `describe`.
|
|
110
80
|
|
|
111
|
-
|
|
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
|
-
|
|
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
|
-
|
|
119
|
-
|
|
120
|
-
messages: [{ role: 'user', content: 'hello' }],
|
|
121
|
-
});
|
|
85
|
+
```typescript
|
|
86
|
+
import { filesystem_logger, filesystem_store } from 'fascicle/adapters';
|
|
122
87
|
|
|
123
|
-
await
|
|
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
|
-
|
|
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
|
-
|
|
96
|
+
`run.stream(flow, input)` returns `{ events, result }` for incremental observation.
|
|
129
97
|
|
|
130
|
-
|
|
98
|
+
## Provider matrix
|
|
131
99
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
114
|
+

|
|
153
115
|
|
|
154
|
-
|
|
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
|
|
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
|
-
|
|
163
|
-
|
|
164
|
-
```bash
|
|
165
|
-
pnpm --filter @repo/fascicle add @repo/core --workspace
|
|
166
|
-
```
|
|
122
|
+
Or embed it programmatically:
|
|
167
123
|
|
|
168
|
-
|
|
124
|
+
```typescript
|
|
125
|
+
import { start_viewer } from 'fascicle';
|
|
169
126
|
|
|
170
|
-
|
|
127
|
+
const handle = await start_viewer({ port: 4242 });
|
|
128
|
+
// later
|
|
129
|
+
await handle.close();
|
|
130
|
+
```
|
|
171
131
|
|
|
172
|
-
-
|
|
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
|
-
|
|
134
|
+
## Where to go next
|
|
176
135
|
|
|
177
|
-
|
|
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
|
-
|
|
146
|
+
## Contributing
|
|
180
147
|
|
|
181
|
-
|
|
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
|
-
|
|
150
|
+
## Development
|
|
192
151
|
|
|
193
|
-
|
|
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
|
-
```
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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));
|