fascicle 0.5.0 → 0.6.3
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 +31 -0
- package/README.md +16 -8
- package/dist/adapters.d.ts +38 -0
- package/dist/adapters.js +78 -0
- package/dist/adapters.js.map +1 -0
- package/dist/index-BiuCs04Z.d.ts +710 -0
- package/dist/index.d.ts +35 -709
- package/dist/index.js +287 -460
- package/dist/index.js.map +1 -1
- package/dist/tee-D_Qh_vfY.js +169 -0
- package/dist/tee-D_Qh_vfY.js.map +1 -0
- package/package.json +7 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,36 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.6.3 — 2026-06-11
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
- CI `pnpm install --frozen-lockfile` no longer fails with `ERR_PNPM_IGNORED_BUILDS`; the `esbuild` build script is now approved in the `allowBuilds` map, classifying a transitive dependency that a recent toolchain bump introduced.
|
|
7
|
+
|
|
8
|
+
## v0.6.2 — 2026-06-11
|
|
9
|
+
|
|
10
|
+
### Internal
|
|
11
|
+
- Stopped tracking the local `.codegraph` tooling config (`config.json` and its `.gitignore`). These are per-machine artifacts and no longer belong in version control.
|
|
12
|
+
|
|
13
|
+
## v0.6.1 — 2026-06-11
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
- AI-SDK adapter: the caller's `system` prompt is now delivered through the AI SDK's top-level `system` option instead of as a `role: "system"` entry in the `messages` array. This removes the SDK's "System messages in the prompt or messages fields can be a security risk..." warning that fired on every `generateText`/`streamText` call (most visibly on non-Claude providers, flooding build logs), without changing what the model receives. A leading run of system messages is joined into the single `system` option; the `claude_cli` subprocess transport is unaffected.
|
|
17
|
+
|
|
18
|
+
## v0.6.0 — 2026-06-10
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
- 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.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
- **Security.** The sandbox now isolates the network entirely when the allowlist is empty, instead of leaving it open.
|
|
25
|
+
- Packaging: the `./adapters` subpath is now published and the package front door (main export) resolves correctly.
|
|
26
|
+
- Engine: `provider_options` are threaded through to the provider and reasoning-effort translation is corrected.
|
|
27
|
+
- Core: composers no longer swallow control-flow signals.
|
|
28
|
+
- Addressed adversarial-review and publish-audit findings across the library and the examples.
|
|
29
|
+
|
|
30
|
+
### Internal
|
|
31
|
+
- Docs reconciled with the shipped API, plus a snippet typecheck harness and CI step that validate doc snippets against the built types.
|
|
32
|
+
- Added the release workflow, base CI workflow, opt-in live-provider smoke tests, roadmap, a Stryker baseline note, and the committed `pnpm-lock`.
|
|
33
|
+
|
|
3
34
|
## v0.5.0 — 2026-06-03
|
|
4
35
|
|
|
5
36
|
### 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
|
-
|
|
42
|
-
|
|
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
|
|
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 (`'
|
|
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
|

|
|
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
|
-
|
|
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-BiuCs04Z.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
|
package/dist/adapters.js
ADDED
|
@@ -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"}
|