fascicle 0.5.0 → 0.6.0

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,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.6.0 — 2026-06-10
4
+
5
+ ### Added
6
+ - Observability now produces correct span trees: `parent_span_id` is populated so nested spans nest, events carry timestamps, tool results are recorded, and `claude_cli` errors are surfaced instead of being dropped.
7
+
8
+ ### Fixed
9
+ - **Security.** The sandbox now isolates the network entirely when the allowlist is empty, instead of leaving it open.
10
+ - Packaging: the `./adapters` subpath is now published and the package front door (main export) resolves correctly.
11
+ - Engine: `provider_options` are threaded through to the provider and reasoning-effort translation is corrected.
12
+ - Core: composers no longer swallow control-flow signals.
13
+ - Addressed adversarial-review and publish-audit findings across the library and the examples.
14
+
15
+ ### Internal
16
+ - Docs reconciled with the shipped API, plus a snippet typecheck harness and CI step that validate doc snippets against the built types.
17
+ - Added the release workflow, base CI workflow, opt-in live-provider smoke tests, roadmap, a Stryker baseline note, and the committed `pnpm-lock`.
18
+
3
19
  ## v0.5.0 — 2026-06-03
4
20
 
5
21
  ### Added
package/README.md CHANGED
@@ -12,10 +12,11 @@ No framework lifecycle. No ambient state. No decorators. Adapters are passed in
12
12
  pnpm add fascicle zod
13
13
  ```
14
14
 
15
- Provider SDKs are optional peers — install only the ones you use. See [docs/providers.md](./docs/providers.md).
15
+ fascicle is ESM-only and requires Node >= 24. Provider SDKs are optional peers — install only the ones you use. See [docs/providers.md](./docs/providers.md).
16
16
 
17
17
  ## A 60-second tour
18
18
 
19
+ <!-- snippet: check -->
19
20
  ```typescript
20
21
  import { run, sequence, step } from 'fascicle';
21
22
 
@@ -29,8 +30,9 @@ await run(flow, 1); // 4
29
30
 
30
31
  Add a model call:
31
32
 
33
+ <!-- snippet: check -->
32
34
  ```typescript
33
- import { create_engine, model_call, run, sequence, step } from 'fascicle';
35
+ import { create_engine, model_call, pipe, run, sequence, step } from 'fascicle';
34
36
 
35
37
  const engine = create_engine({
36
38
  providers: { anthropic: { api_key: process.env.ANTHROPIC_API_KEY! } },
@@ -38,8 +40,10 @@ const engine = create_engine({
38
40
 
39
41
  const flow = sequence([
40
42
  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),
43
+ pipe(
44
+ model_call({ engine, model: 'sonnet', system: 'No preamble.' }),
45
+ (r) => r.content,
46
+ ),
43
47
  ]);
44
48
 
45
49
  try {
@@ -71,14 +75,14 @@ try {
71
75
  | `adversarial` | build, critique, repeat until accept or `max_rounds` |
72
76
  | `ensemble` | run N members, pick the highest-scoring result |
73
77
  | `tournament` | single-elimination bracket |
74
- | `consensus` | run N concurrently, accept only if `>= quorum` agree |
78
+ | `consensus` | run N concurrently, accept when an `agree` predicate holds |
75
79
  | `checkpoint` | memoize an inner step by key in a `CheckpointStore` |
76
80
  | `suspend` | pause for external input; resume later with `resume_data` |
77
81
  | `scope` / `stash` / `use` | named state across non-adjacent steps |
78
82
 
79
83
  Plus `run`, `run.stream`, and `describe`.
80
84
 
81
- **AI engine.** `create_engine(config)` returns one `generate` surface across seven providers. Two axes: `model` names a family (`sonnet`, `opus`, `gpt` — latest of that family) or a specific id (`claude-opus-4-8`), and `provider` names the transport (`anthropic`, `claude_cli`, `openrouter`, …) — so the same `model: 'opus'` runs anywhere. Reasoning effort (`'low' | 'medium' | 'high'`) is translated per provider. Cost estimation uses a pricing table with per-engine overrides.
85
+ **AI engine.** `create_engine(config)` returns one `generate` surface across seven providers. Two axes: `model` names a family (`sonnet`, `opus`, `gpt` — latest of that family) or a specific id (`claude-opus-4-8`), and `provider` names the transport (`anthropic`, `claude_cli`, `openrouter`, …) — so the same `model: 'opus'` runs anywhere. Reasoning effort (`'none'` through `'max'`) is translated per provider. Cost estimation uses a pricing table with per-engine overrides.
82
86
 
83
87
  **Adapters injected per run.** Trajectory loggers and checkpoint stores ship under the `fascicle/adapters` subpath:
84
88
 
@@ -113,14 +117,18 @@ Full details: [docs/providers.md](./docs/providers.md). The `claude_cli` adapter
113
117
 
114
118
  ![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)
115
119
 
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:
120
+ The `fascicle-viewer` bin ships with the umbrella package (there is no separate `fascicle-viewer` package). Point it at a trajectory file and it opens a browser tree of spans, errors, and emits as the run executes:
117
121
 
118
122
  ```bash
119
- pnpm dlx fascicle-viewer .trajectory.jsonl
123
+ # installed locally:
124
+ pnpm exec fascicle-viewer .trajectory.jsonl
125
+ # or one-off via the umbrella package:
126
+ pnpm dlx --package=fascicle fascicle-viewer .trajectory.jsonl
120
127
  ```
121
128
 
122
129
  Or embed it programmatically:
123
130
 
131
+ <!-- snippet: check -->
124
132
  ```typescript
125
133
  import { start_viewer } from 'fascicle';
126
134
 
@@ -0,0 +1,38 @@
1
+ import { G as CheckpointStore, X as TrajectoryLogger } from "./index-CCFSc--s.js";
2
+
3
+ //#region packages/observability/src/noop.d.ts
4
+ declare function noop_logger(): TrajectoryLogger;
5
+ //#endregion
6
+ //#region packages/observability/src/filesystem.d.ts
7
+ type FilesystemLoggerOptions = {
8
+ readonly output_path: string;
9
+ };
10
+ declare function filesystem_logger(options: FilesystemLoggerOptions): TrajectoryLogger;
11
+ //#endregion
12
+ //#region packages/observability/src/http.d.ts
13
+ type HttpLoggerFetch = (url: string, init: {
14
+ method: 'POST';
15
+ headers: Record<string, string>;
16
+ body: string;
17
+ }) => Promise<{
18
+ ok: boolean;
19
+ status: number;
20
+ }>;
21
+ type HttpLoggerOptions = {
22
+ readonly url: string;
23
+ readonly fetch?: HttpLoggerFetch;
24
+ readonly on_error?: (err: unknown) => void;
25
+ };
26
+ declare function http_logger(options: HttpLoggerOptions): TrajectoryLogger;
27
+ //#endregion
28
+ //#region packages/observability/src/tee.d.ts
29
+ declare function tee_logger(...loggers: ReadonlyArray<TrajectoryLogger>): TrajectoryLogger;
30
+ //#endregion
31
+ //#region packages/stores/src/filesystem.d.ts
32
+ type FilesystemStoreOptions = {
33
+ readonly root_dir: string;
34
+ };
35
+ declare function filesystem_store(options: FilesystemStoreOptions): CheckpointStore;
36
+ //#endregion
37
+ export { type FilesystemLoggerOptions, type FilesystemStoreOptions, type HttpLoggerFetch, type HttpLoggerOptions, filesystem_logger, filesystem_store, http_logger, noop_logger, tee_logger };
38
+ //# sourceMappingURL=adapters.d.ts.map
@@ -0,0 +1,78 @@
1
+ import { n as http_logger, r as filesystem_logger, t as tee_logger } from "./tee-D_Qh_vfY.js";
2
+ import { createHash, randomUUID } from "node:crypto";
3
+ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
4
+ import { join } from "node:path";
5
+ //#region packages/observability/src/noop.ts
6
+ /**
7
+ * No-op trajectory logger.
8
+ *
9
+ * Satisfies `TrajectoryLogger` from `@repo/core` without emitting any
10
+ * output. Used as the default when no logger is supplied to `run(...)` and as
11
+ * a cheap fallback in tests that do not care about trajectory output.
12
+ */
13
+ function noop_logger() {
14
+ return {
15
+ record: () => {},
16
+ start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,
17
+ end_span: () => {}
18
+ };
19
+ }
20
+ //#endregion
21
+ //#region packages/stores/src/filesystem.ts
22
+ /**
23
+ * Filesystem-backed checkpoint store.
24
+ *
25
+ * Satisfies `CheckpointStore` from `@repo/core`. Each key is stored as
26
+ * a JSON file under the configured root directory. Writes are all-or-nothing:
27
+ * values are written to a temporary sibling file and then atomically renamed
28
+ * into place, so an interrupted write never leaves a partially-written file
29
+ * at the target key (spec.md §6.3, §6.8). On `get`, a missing file, a partial
30
+ * temp file that is not atomically renamed, or a JSON parse failure each read
31
+ * as a cache miss (returning `null`) rather than an error.
32
+ *
33
+ * Paths are accepted at construction; the store never reads `process.env`.
34
+ */
35
+ function safe_filename(key) {
36
+ const hash = createHash("sha256").update(key).digest("hex").slice(0, 12);
37
+ return `${key.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64)}.${hash}.json`;
38
+ }
39
+ function filesystem_store(options) {
40
+ const { root_dir } = options;
41
+ const ensure_root = async () => {
42
+ await mkdir(root_dir, { recursive: true });
43
+ };
44
+ const path_for = (key) => join(root_dir, safe_filename(key));
45
+ const get = async (key) => {
46
+ const path = path_for(key);
47
+ let raw;
48
+ try {
49
+ raw = await readFile(path, "utf8");
50
+ } catch {
51
+ return null;
52
+ }
53
+ try {
54
+ return JSON.parse(raw);
55
+ } catch {
56
+ return null;
57
+ }
58
+ };
59
+ const set = async (key, value) => {
60
+ await ensure_root();
61
+ const target = path_for(key);
62
+ const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`;
63
+ await writeFile(tmp, JSON.stringify(value), "utf8");
64
+ await rename(tmp, target);
65
+ };
66
+ const delete_key = async (key) => {
67
+ await rm(path_for(key), { force: true });
68
+ };
69
+ return {
70
+ get,
71
+ set,
72
+ delete: delete_key
73
+ };
74
+ }
75
+ //#endregion
76
+ export { filesystem_logger, filesystem_store, http_logger, noop_logger, tee_logger };
77
+
78
+ //# sourceMappingURL=adapters.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapters.js","names":[],"sources":["../packages/observability/src/noop.ts","../packages/stores/src/filesystem.ts"],"sourcesContent":["/**\n * No-op trajectory logger.\n *\n * Satisfies `TrajectoryLogger` from `@repo/core` without emitting any\n * output. Used as the default when no logger is supplied to `run(...)` and as\n * a cheap fallback in tests that do not care about trajectory output.\n */\n\nimport { randomUUID } from 'node:crypto'\nimport type { TrajectoryLogger } from '@repo/core'\n\nexport function noop_logger(): TrajectoryLogger {\n return {\n record: () => {},\n start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,\n end_span: () => {},\n }\n}\n","/**\n * Filesystem-backed checkpoint store.\n *\n * Satisfies `CheckpointStore` from `@repo/core`. Each key is stored as\n * a JSON file under the configured root directory. Writes are all-or-nothing:\n * values are written to a temporary sibling file and then atomically renamed\n * into place, so an interrupted write never leaves a partially-written file\n * at the target key (spec.md §6.3, §6.8). On `get`, a missing file, a partial\n * temp file that is not atomically renamed, or a JSON parse failure each read\n * as a cache miss (returning `null`) rather than an error.\n *\n * Paths are accepted at construction; the store never reads `process.env`.\n */\n\nimport { createHash, randomUUID } from 'node:crypto'\nimport { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport type { CheckpointStore } from '@repo/core'\n\nexport type FilesystemStoreOptions = {\n readonly root_dir: string\n}\n\nfunction safe_filename(key: string): string {\n const hash = createHash('sha256').update(key).digest('hex').slice(0, 12)\n const slug = key.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64)\n return `${slug}.${hash}.json`\n}\n\nexport function filesystem_store(options: FilesystemStoreOptions): CheckpointStore {\n const { root_dir } = options\n\n const ensure_root = async (): Promise<void> => {\n await mkdir(root_dir, { recursive: true })\n }\n\n const path_for = (key: string): string => join(root_dir, safe_filename(key))\n\n const get = async (key: string): Promise<unknown> => {\n const path = path_for(key)\n let raw: string\n try {\n raw = await readFile(path, 'utf8')\n } catch {\n return null\n }\n try {\n return JSON.parse(raw) as unknown\n } catch {\n return null\n }\n }\n\n const set = async (key: string, value: unknown): Promise<void> => {\n await ensure_root()\n const target = path_for(key)\n const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`\n await writeFile(tmp, JSON.stringify(value), 'utf8')\n await rename(tmp, target)\n }\n\n const delete_key = async (key: string): Promise<void> => {\n const target = path_for(key)\n await rm(target, { force: true })\n }\n\n return { get, set, delete: delete_key }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,cAAgC;AAC9C,QAAO;EACL,cAAc;EACd,aAAa,SAAS,GAAG,KAAK,GAAG,YAAY,CAAC,MAAM,GAAG,EAAE;EACzD,gBAAgB;EACjB;;;;;;;;;;;;;;;;;ACOH,SAAS,cAAc,KAAqB;CAC1C,MAAM,OAAO,WAAW,SAAS,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM,CAAC,MAAM,GAAG,GAAG;AAExE,QAAO,GADM,IAAI,QAAQ,oBAAoB,IAAI,CAAC,MAAM,GAAG,GAAG,CAC/C,GAAG,KAAK;;AAGzB,SAAgB,iBAAiB,SAAkD;CACjF,MAAM,EAAE,aAAa;CAErB,MAAM,cAAc,YAA2B;AAC7C,QAAM,MAAM,UAAU,EAAE,WAAW,MAAM,CAAC;;CAG5C,MAAM,YAAY,QAAwB,KAAK,UAAU,cAAc,IAAI,CAAC;CAE5E,MAAM,MAAM,OAAO,QAAkC;EACnD,MAAM,OAAO,SAAS,IAAI;EAC1B,IAAI;AACJ,MAAI;AACF,SAAM,MAAM,SAAS,MAAM,OAAO;UAC5B;AACN,UAAO;;AAET,MAAI;AACF,UAAO,KAAK,MAAM,IAAI;UAChB;AACN,UAAO;;;CAIX,MAAM,MAAM,OAAO,KAAa,UAAkC;AAChE,QAAM,aAAa;EACnB,MAAM,SAAS,SAAS,IAAI;EAC5B,MAAM,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC,MAAM,GAAG,EAAE,CAAC;AAClD,QAAM,UAAU,KAAK,KAAK,UAAU,MAAM,EAAE,OAAO;AACnD,QAAM,OAAO,KAAK,OAAO;;CAG3B,MAAM,aAAa,OAAO,QAA+B;AAEvD,QAAM,GADS,SAAS,IAAI,EACX,EAAE,OAAO,MAAM,CAAC;;AAGnC,QAAO;EAAE;EAAK;EAAK,QAAQ;EAAY"}