fascicle 0.9.5 → 0.9.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 +35 -0
- package/README.md +33 -4
- package/dist/agents.d.ts +31 -0
- package/dist/agents.js +142 -0
- package/dist/agents.js.map +1 -0
- package/package.json +5 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,40 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.9.8 — 2026-07-19
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`define_agent` call-shaping config.** `DefineAgentConfig` accepts `model` and `schema_repair_attempts`, closing the gap where the blueprint's "models are threaded as data" rule could not be followed on the `fascicle/agents` surface (and where schema repair — set on every model call observed in production consumers — required dropping to a stage factory). Precedence: `config.model` > frontmatter `model` > engine default; the blueprint's stage-factory section now states the same rule.
|
|
8
|
+
- Two blueprint reference apps translated from production consumers, workspace-wired with stub-engine tests and the blueprint's ast-grep rules: `examples/change-triage/` (deterministic detectors + one schema-mode model call, a score floor the model cannot undercut, a privacy screen on the model's view) and `examples/docs-concierge/` (grounded Q&A with number-based citations, a `define_agent` stage, and a one-way gate that prefers abstaining over confidently wrong).
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- `docs/blueprint.md` and `site/blueprint.html` now state model precedence consistently (threaded model wins, frontmatter is the role default, engine default is the last resort), and the stage-factory snippet no longer implies frontmatter overrides a threaded model.
|
|
13
|
+
|
|
14
|
+
## v0.9.7 — 2026-07-17
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **`fascicle/agents` subpath.** `define_agent` — the markdown-plus-schema agent loader the blueprint recommends for simple one-prompt agents — is now importable by consumers via `import { define_agent } from 'fascicle/agents'`. It was previously reachable only inside the repo. Ships as its own bundle entry (`dist/agents.js`), smoke-verified at build time.
|
|
19
|
+
- A dedicated architecture page on the site (`site/blueprint.html`): the agent blueprint's one rule, adoption tiers, module contracts, anti-patterns, and ast-grep enforcement story, linked from both existing pages. `AGENTS.md` and the README now route agents and humans building *on* fascicle to `docs/blueprint.md` first, and a new `examples/README.md` indexes the example apps around it.
|
|
20
|
+
- Opt-in `build` + `publish` steps in the check runner, included by `pnpm check:all`: the tsdown bundle with export smoke imports, and the npm pack manifest + `@arethetypeswrong/cli` validation. Packaging regressions now fail the done-gate instead of surfacing at release time.
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- Documentation synced with the implementation across `docs/` and the site. The composition surface is documented as 21 primitives (adding `ensemble_step`, `improve`, and `learn` to every list and to the site's interactive tour); site code samples now show the real config-object APIs (`branch` / `map` / `ensemble` / `tournament` / `consensus`, `adversarial`'s required `accept`, `suspend`'s required `on`, `retry`'s `backoff_ms`); engine docs corrected for `claude_cli` reasoning-effort forwarding (`CLAUDE_CODE_EFFORT_LEVEL`), the `'timeout'` member of `DEFAULT_RETRY.retry_on`, the real missing-peer error message, `inherit_env` semantics, the full `EngineConfig` shape, and the complete error and Engine-method lists.
|
|
25
|
+
- The reference agents (reviewer, documenter, researcher) moved from `src/agents/` to `examples/agents/` as copy-pasteable demo code — they were never published (their markdown prompts do not ship in `dist/`), and their own docstring called them canonical examples. Their behavior tests still run in the default suite. `src/agents` now contains exactly the published surface: `define_agent`.
|
|
26
|
+
|
|
27
|
+
### Internal
|
|
28
|
+
|
|
29
|
+
- Hardened `define_agent` mutation coverage from 91.8% to 98.2% ahead of publication (frontmatter quoting and key-trim edges, primitive-input placeholder substitution, system-key omission, the pre-call abort guard); the three residual survivors are documented equivalent mutants.
|
|
30
|
+
|
|
31
|
+
## v0.9.6 — 2026-07-17
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- `docs/blueprint.md`: a standard app architecture for building on fascicle — one composition layer, three adoption tiers, markdown prompts, normalized module shapes, stub-engine testing, and field-observed anti-patterns distilled from the example apps and production consumers.
|
|
36
|
+
- Three ast-grep boundary rules wired into `examples/pr-improve` (runnable via `check:rules`): `create_engine` confined to `engine.ts`, no imperative loops in `flow.ts`, and fascicle value imports confined to the files allowed to know about it.
|
|
37
|
+
|
|
3
38
|
## v0.9.5 — 2026-07-12
|
|
4
39
|
|
|
5
40
|
### Fixed
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|

|
|
4
4
|
|
|
5
|
-
Compose agents out of LLM calls, tool calls, and plain functions. Everything is a `Step<i, o>`. Wire steps together with
|
|
5
|
+
Compose agents out of LLM calls, tool calls, and plain functions. Everything is a `Step<i, o>`. Wire steps together with 21 primitives (`sequence`, `parallel`, `branch`, `retry`, `loop`, `ensemble`, `checkpoint`, …) and run them as plain values. One `generate` surface fronts eight provider adapters: Anthropic, OpenAI, Google, OpenRouter, AWS Bedrock, 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
|
|
|
@@ -57,7 +57,7 @@ try {
|
|
|
57
57
|
|
|
58
58
|
## What's in the box
|
|
59
59
|
|
|
60
|
-
**Composition primitives (
|
|
60
|
+
**Composition primitives (21).** Every composer takes `Step<i, o>` and returns `Step<i, o>`. Anything that fits a step fits any composition of steps.
|
|
61
61
|
|
|
62
62
|
| Primitive | Shape |
|
|
63
63
|
| --- | --- |
|
|
@@ -74,11 +74,14 @@ try {
|
|
|
74
74
|
| `compose` | label a composite so it shows up by intent in trajectories |
|
|
75
75
|
| `adversarial` | build, critique, repeat until accept or `max_rounds` |
|
|
76
76
|
| `ensemble` | run N members, pick the highest-scoring result |
|
|
77
|
+
| `ensemble_step` | pick-best where the scorer is itself a `Step` (a model judge with its own span) |
|
|
77
78
|
| `tournament` | single-elimination bracket |
|
|
78
79
|
| `consensus` | run N concurrently, accept when an `agree` predicate holds |
|
|
79
80
|
| `checkpoint` | memoize an inner step by key in a `CheckpointStore` |
|
|
80
81
|
| `suspend` | pause for external input; resume later with `resume_data` |
|
|
81
82
|
| `scope` / `stash` / `use` | named state across non-adjacent steps |
|
|
83
|
+
| `improve` | bounded online propose → score → accept/reject self-improvement loop |
|
|
84
|
+
| `learn` | offline reflection over recorded trajectories |
|
|
82
85
|
|
|
83
86
|
Plus `run`, `run.stream`, and `describe`.
|
|
84
87
|
|
|
@@ -101,6 +104,25 @@ await run(flow, input, {
|
|
|
101
104
|
|
|
102
105
|
`run.stream(flow, input)` returns `{ events, result }` for incremental observation.
|
|
103
106
|
|
|
107
|
+
**Markdown-defined agents.** When an agent is just a prompt plus an output schema, `define_agent` (the `fascicle/agents` subpath) folds a markdown file — frontmatter `name` / `model` / `temperature`, body as the prompt — and a zod schema into a `Step<i, o>`:
|
|
108
|
+
|
|
109
|
+
<!-- snippet: check -->
|
|
110
|
+
```typescript
|
|
111
|
+
import { z } from 'zod';
|
|
112
|
+
import { create_engine } from 'fascicle';
|
|
113
|
+
import { define_agent } from 'fascicle/agents';
|
|
114
|
+
|
|
115
|
+
const engine = create_engine({ providers: { claude_cli: { auth_mode: 'oauth' } } });
|
|
116
|
+
|
|
117
|
+
const reviewer = define_agent({
|
|
118
|
+
md_path: new URL('./prompts/reviewer.md', import.meta.url),
|
|
119
|
+
schema: z.object({ findings: z.array(z.string()), summary: z.string() }),
|
|
120
|
+
engine,
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
This is the [blueprint's](./docs/blueprint.md) recommended shape for simple one-prompt agents; reference agents built on it (reviewer, documenter, researcher) live in [examples/agents/](./examples/agents/).
|
|
125
|
+
|
|
104
126
|
**MCP bridge.** The `fascicle/mcp` subpath connects flows to the Model Context Protocol both ways. `mcp_client` turns an external MCP server's tools into plain `Tool[]`; `serve_flow` exposes a composed flow as an MCP tool to hosts like Claude Desktop or Cursor. It is pure adapter glue over the existing `Tool` and `run` contracts, and `@modelcontextprotocol/sdk` is an optional peer you only install when you use it.
|
|
105
127
|
|
|
106
128
|
<!-- snippet: check -->
|
|
@@ -167,11 +189,18 @@ await handle.close();
|
|
|
167
189
|
|
|
168
190
|
For zero-latency streaming from inside a long-running flow, pair it with `http_logger` from `fascicle/adapters`. See [docs/viewer.md](./docs/viewer.md) for the full transport story.
|
|
169
191
|
|
|
192
|
+
## Building an app on fascicle
|
|
193
|
+
|
|
194
|
+
**[docs/blueprint.md](./docs/blueprint.md) is the recommended architecture for apps built on fascicle** — distilled from the reference apps and production consumers. One composition layer (`flow.ts`) that holds the whole topology, `create_engine` confined to one file, prompts as markdown with frontmatter, zod schemas as the stage contracts, stub-engine testing, and [ast-grep rules](./examples/pr-improve/rules/) that turn each boundary into a build failure. If you are a coding agent scaffolding a new fascicle app, follow the blueprint and its checklist.
|
|
195
|
+
|
|
196
|
+
The canonical worked example is [examples/pr-improve/](./examples/pr-improve/), with its design rationale in [examples/pr-improve/docs/architecture.md](./examples/pr-improve/docs/architecture.md).
|
|
197
|
+
|
|
170
198
|
## Where to go next
|
|
171
199
|
|
|
200
|
+
- [docs/blueprint.md](./docs/blueprint.md) — **the agent blueprint**: the standard app architecture (start here when building an app)
|
|
172
201
|
- [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
|
|
173
202
|
- [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
|
|
174
|
-
- [docs/composition.md](./docs/composition.md) — full composition surface: the
|
|
203
|
+
- [docs/composition.md](./docs/composition.md) — full composition surface: the 21 primitives, run/stream, checkpointing
|
|
175
204
|
- [docs/api-reference.md](./docs/api-reference.md) — the public surface at a glance
|
|
176
205
|
- [docs/configuration.md](./docs/configuration.md) — engine config, defaults, pricing, retries
|
|
177
206
|
- [docs/providers.md](./docs/providers.md) — per-provider adapter notes
|
|
@@ -197,7 +226,7 @@ This repo is a **single package**. The code is organized as deep modules under `
|
|
|
197
226
|
```bash
|
|
198
227
|
pnpm install
|
|
199
228
|
pnpm check # types, lint, structural rules, dead-code, tests, docs, spell
|
|
200
|
-
pnpm check:all # adds Stryker mutation testing (
|
|
229
|
+
pnpm check:all # adds Stryker mutation testing + the packaging gate (final gate)
|
|
201
230
|
```
|
|
202
231
|
|
|
203
232
|
`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.
|
package/dist/agents.d.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { G as Step } from "./index-JhJahQNi.js";
|
|
2
|
+
import { y as Engine } from "./index-DyjXGal_.js";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
|
|
5
|
+
//#region src/agents/define_agent.d.ts
|
|
6
|
+
type AgentBuiltPrompt = string | {
|
|
7
|
+
readonly user: string;
|
|
8
|
+
readonly system?: string;
|
|
9
|
+
};
|
|
10
|
+
type DefineAgentConfig<i, o> = {
|
|
11
|
+
readonly md_path: string | URL;
|
|
12
|
+
readonly schema: z.ZodType<o>;
|
|
13
|
+
readonly engine: Engine;
|
|
14
|
+
readonly name?: string;
|
|
15
|
+
readonly build_prompt?: (input: i) => AgentBuiltPrompt;
|
|
16
|
+
/**
|
|
17
|
+
* Model for this agent's calls, typically threaded from the app's resolved
|
|
18
|
+
* role-to-model table. Wins over frontmatter `model`; when both are absent
|
|
19
|
+
* the engine default applies.
|
|
20
|
+
*/
|
|
21
|
+
readonly model?: string;
|
|
22
|
+
/**
|
|
23
|
+
* Forwarded to `engine.generate`: how many times the engine may re-prompt
|
|
24
|
+
* the model to repair schema-invalid output before failing the call.
|
|
25
|
+
*/
|
|
26
|
+
readonly schema_repair_attempts?: number;
|
|
27
|
+
};
|
|
28
|
+
declare function define_agent<i, o>(config: DefineAgentConfig<i, o>): Step<i, o>;
|
|
29
|
+
//#endregion
|
|
30
|
+
export { type AgentBuiltPrompt, type DefineAgentConfig, define_agent };
|
|
31
|
+
//# sourceMappingURL=agents.d.ts.map
|
package/dist/agents.js
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import { E as aborted_error, w as step } from "./core-CYpxskeT.js";
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
//#region src/agents/define_agent.ts
|
|
5
|
+
/**
|
|
6
|
+
* define_agent: markdown-driven loader for simple agents.
|
|
7
|
+
*
|
|
8
|
+
* Most "agents" in practice are a system prompt and an output schema with a
|
|
9
|
+
* thin wrapper. `define_agent({ md_path, schema, engine, build_prompt? })`
|
|
10
|
+
* folds those into a `Step<i, o>`:
|
|
11
|
+
*
|
|
12
|
+
* - The markdown file is read once at factory time. Its YAML-style frontmatter
|
|
13
|
+
* (`name`, `description`, `model`, `temperature`) is parsed into the agent's
|
|
14
|
+
* step name and engine call defaults; the body is the system prompt.
|
|
15
|
+
* - Without `build_prompt`, the body (after `{{key}}` substitution against
|
|
16
|
+
* top-level string fields of the input) is the user prompt and no system is
|
|
17
|
+
* sent — the markdown carries the full instruction.
|
|
18
|
+
* - With `build_prompt`, the body is the system prompt and `build_prompt(input)`
|
|
19
|
+
* produces the user message (string, or `{ user, system? }` to override).
|
|
20
|
+
* - `config.model` and `config.schema_repair_attempts` shape the call from
|
|
21
|
+
* code. An explicit `model` wins over frontmatter `model` (frontmatter stays
|
|
22
|
+
* the role default when the app threads nothing; the engine default is the
|
|
23
|
+
* last resort), so a resolved role-to-model table and env overrides actually
|
|
24
|
+
* reach the call.
|
|
25
|
+
*
|
|
26
|
+
* The factory keeps no engine state. Each call delegates to `engine.generate`
|
|
27
|
+
* with the resolved prompts, the schema, and `ctx.abort` / `ctx.trajectory`
|
|
28
|
+
* threaded through. An `agent.call` trajectory event carries the agent name,
|
|
29
|
+
* resolved model id, and engine-reported usage. No retry or fallback is baked
|
|
30
|
+
* in — wrap with `retry()` from core if you need it.
|
|
31
|
+
*
|
|
32
|
+
* Frontmatter parser is intentionally tiny (no gray-matter): bare `key: value`
|
|
33
|
+
* lines, optional `'`/`"` quotes, `temperature` coerced to number. Anything
|
|
34
|
+
* richer should go through `build_prompt`.
|
|
35
|
+
*/
|
|
36
|
+
const FRONTMATTER_OPEN = /^---\s*\r?\n/;
|
|
37
|
+
const FRONTMATTER_CLOSE = /^---\s*$/m;
|
|
38
|
+
const PLACEHOLDER_RE = /\{\{(\w+)\}\}/g;
|
|
39
|
+
function unquote(raw) {
|
|
40
|
+
if (raw.length >= 2) {
|
|
41
|
+
const first = raw[0];
|
|
42
|
+
const last = raw[raw.length - 1];
|
|
43
|
+
if (first === "\"" && last === "\"" || first === "'" && last === "'") return raw.slice(1, -1);
|
|
44
|
+
}
|
|
45
|
+
return raw;
|
|
46
|
+
}
|
|
47
|
+
function parse_frontmatter(content) {
|
|
48
|
+
const open_match = content.match(FRONTMATTER_OPEN);
|
|
49
|
+
if (!open_match) return {
|
|
50
|
+
frontmatter: {},
|
|
51
|
+
body: content
|
|
52
|
+
};
|
|
53
|
+
const after_open = content.slice(open_match[0].length);
|
|
54
|
+
const close_match = FRONTMATTER_CLOSE.exec(after_open);
|
|
55
|
+
if (close_match?.index === void 0) throw new Error("define_agent: malformed frontmatter (missing closing `---`)");
|
|
56
|
+
const yaml_block = after_open.slice(0, close_match.index);
|
|
57
|
+
const body = after_open.slice(close_match.index + close_match[0].length).replace(/^\r?\n/, "");
|
|
58
|
+
const out = {};
|
|
59
|
+
const lines = yaml_block.split(/\r?\n/);
|
|
60
|
+
for (const raw of lines) {
|
|
61
|
+
const line = raw.trim();
|
|
62
|
+
if (line === "" || line.startsWith("#")) continue;
|
|
63
|
+
const colon_idx = line.indexOf(":");
|
|
64
|
+
if (colon_idx === -1) throw new Error(`define_agent: malformed frontmatter line: ${raw}`);
|
|
65
|
+
const key = line.slice(0, colon_idx).trim();
|
|
66
|
+
const value_raw = line.slice(colon_idx + 1).trim();
|
|
67
|
+
const value = unquote(value_raw);
|
|
68
|
+
if (key === "name" || key === "description" || key === "model") {
|
|
69
|
+
out[key] = value;
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
if (key === "temperature") {
|
|
73
|
+
const n = Number(value);
|
|
74
|
+
if (!Number.isFinite(n)) throw new Error(`define_agent: temperature must be a number, got: ${value_raw}`);
|
|
75
|
+
out.temperature = n;
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
return {
|
|
80
|
+
frontmatter: out,
|
|
81
|
+
body
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
function read_md_sync(path) {
|
|
85
|
+
if (path instanceof URL) return readFileSync(fileURLToPath(path), "utf8");
|
|
86
|
+
if (path.startsWith("file://")) return readFileSync(fileURLToPath(path), "utf8");
|
|
87
|
+
return readFileSync(path, "utf8");
|
|
88
|
+
}
|
|
89
|
+
function substitute(template, input) {
|
|
90
|
+
if (input === null || typeof input !== "object") return template;
|
|
91
|
+
const obj = input;
|
|
92
|
+
return template.replace(PLACEHOLDER_RE, (match, key) => {
|
|
93
|
+
const v = obj[key];
|
|
94
|
+
return typeof v === "string" ? v : match;
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
function define_agent(config) {
|
|
98
|
+
const { frontmatter, body } = parse_frontmatter(read_md_sync(config.md_path));
|
|
99
|
+
const display_name = config.name ?? frontmatter.name ?? "agent";
|
|
100
|
+
return step(display_name, async (input, ctx) => {
|
|
101
|
+
if (ctx.abort.aborted) throw new aborted_error("aborted before agent call");
|
|
102
|
+
let user_prompt;
|
|
103
|
+
let system_prompt;
|
|
104
|
+
if (config.build_prompt) {
|
|
105
|
+
const built = config.build_prompt(input);
|
|
106
|
+
if (typeof built === "string") {
|
|
107
|
+
user_prompt = built;
|
|
108
|
+
system_prompt = body;
|
|
109
|
+
} else {
|
|
110
|
+
user_prompt = built.user;
|
|
111
|
+
system_prompt = built.system ?? body;
|
|
112
|
+
}
|
|
113
|
+
} else {
|
|
114
|
+
user_prompt = substitute(body, input);
|
|
115
|
+
system_prompt = void 0;
|
|
116
|
+
}
|
|
117
|
+
const opts = {
|
|
118
|
+
prompt: user_prompt,
|
|
119
|
+
schema: config.schema,
|
|
120
|
+
abort: ctx.abort,
|
|
121
|
+
trajectory: ctx.trajectory
|
|
122
|
+
};
|
|
123
|
+
if (system_prompt !== void 0 && system_prompt !== "") opts.system = system_prompt;
|
|
124
|
+
const model = config.model ?? frontmatter.model;
|
|
125
|
+
if (model !== void 0) opts.model = model;
|
|
126
|
+
if (frontmatter.temperature !== void 0) opts.temperature = frontmatter.temperature;
|
|
127
|
+
if (config.schema_repair_attempts !== void 0) opts.schema_repair_attempts = config.schema_repair_attempts;
|
|
128
|
+
const result = await config.engine.generate(opts);
|
|
129
|
+
const resolved_model = `${result.model_resolved.provider}:${result.model_resolved.model_id}`;
|
|
130
|
+
ctx.trajectory.record({
|
|
131
|
+
kind: "agent.call",
|
|
132
|
+
name: display_name,
|
|
133
|
+
model: resolved_model,
|
|
134
|
+
usage: result.usage
|
|
135
|
+
});
|
|
136
|
+
return result.content;
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
//#endregion
|
|
140
|
+
export { define_agent };
|
|
141
|
+
|
|
142
|
+
//# sourceMappingURL=agents.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agents.js","names":[],"sources":["../src/agents/define_agent.ts"],"sourcesContent":["/**\n * define_agent: markdown-driven loader for simple agents.\n *\n * Most \"agents\" in practice are a system prompt and an output schema with a\n * thin wrapper. `define_agent({ md_path, schema, engine, build_prompt? })`\n * folds those into a `Step<i, o>`:\n *\n * - The markdown file is read once at factory time. Its YAML-style frontmatter\n * (`name`, `description`, `model`, `temperature`) is parsed into the agent's\n * step name and engine call defaults; the body is the system prompt.\n * - Without `build_prompt`, the body (after `{{key}}` substitution against\n * top-level string fields of the input) is the user prompt and no system is\n * sent — the markdown carries the full instruction.\n * - With `build_prompt`, the body is the system prompt and `build_prompt(input)`\n * produces the user message (string, or `{ user, system? }` to override).\n * - `config.model` and `config.schema_repair_attempts` shape the call from\n * code. An explicit `model` wins over frontmatter `model` (frontmatter stays\n * the role default when the app threads nothing; the engine default is the\n * last resort), so a resolved role-to-model table and env overrides actually\n * reach the call.\n *\n * The factory keeps no engine state. Each call delegates to `engine.generate`\n * with the resolved prompts, the schema, and `ctx.abort` / `ctx.trajectory`\n * threaded through. An `agent.call` trajectory event carries the agent name,\n * resolved model id, and engine-reported usage. No retry or fallback is baked\n * in — wrap with `retry()` from core if you need it.\n *\n * Frontmatter parser is intentionally tiny (no gray-matter): bare `key: value`\n * lines, optional `'`/`\"` quotes, `temperature` coerced to number. Anything\n * richer should go through `build_prompt`.\n */\n\nimport { readFileSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nimport { aborted_error, step } from '#core'\nimport type { RunContext, Step } from '#core'\nimport type { Engine, GenerateOptions } from '#engine'\nimport type { z } from 'zod'\n\nexport type AgentBuiltPrompt =\n | string\n | { readonly user: string; readonly system?: string }\n\nexport type DefineAgentConfig<i, o> = {\n readonly md_path: string | URL\n readonly schema: z.ZodType<o>\n readonly engine: Engine\n readonly name?: string\n readonly build_prompt?: (input: i) => AgentBuiltPrompt\n /**\n * Model for this agent's calls, typically threaded from the app's resolved\n * role-to-model table. Wins over frontmatter `model`; when both are absent\n * the engine default applies.\n */\n readonly model?: string\n /**\n * Forwarded to `engine.generate`: how many times the engine may re-prompt\n * the model to repair schema-invalid output before failing the call.\n */\n readonly schema_repair_attempts?: number\n}\n\ntype Frontmatter = {\n readonly name?: string\n readonly description?: string\n readonly model?: string\n readonly temperature?: number\n}\n\ntype ParsedPrompt = {\n readonly frontmatter: Frontmatter\n readonly body: string\n}\n\nconst FRONTMATTER_OPEN = /^---\\s*\\r?\\n/\nconst FRONTMATTER_CLOSE = /^---\\s*$/m\nconst PLACEHOLDER_RE = /\\{\\{(\\w+)\\}\\}/g\n\nfunction unquote(raw: string): string {\n if (raw.length >= 2) {\n const first = raw[0]\n const last = raw[raw.length - 1]\n if ((first === '\"' && last === '\"') || (first === \"'\" && last === \"'\")) {\n return raw.slice(1, -1)\n }\n }\n return raw\n}\n\nfunction parse_frontmatter(content: string): ParsedPrompt {\n const open_match = content.match(FRONTMATTER_OPEN)\n if (!open_match) return { frontmatter: {}, body: content }\n const after_open = content.slice(open_match[0].length)\n const close_match = FRONTMATTER_CLOSE.exec(after_open)\n if (close_match?.index === undefined) {\n throw new Error('define_agent: malformed frontmatter (missing closing `---`)')\n }\n const yaml_block = after_open.slice(0, close_match.index)\n const body = after_open.slice(close_match.index + close_match[0].length).replace(/^\\r?\\n/, '')\n\n const out: { -readonly [K in keyof Frontmatter]: Frontmatter[K] } = {}\n const lines = yaml_block.split(/\\r?\\n/)\n for (const raw of lines) {\n const line = raw.trim()\n if (line === '' || line.startsWith('#')) continue\n const colon_idx = line.indexOf(':')\n if (colon_idx === -1) {\n throw new Error(`define_agent: malformed frontmatter line: ${raw}`)\n }\n const key = line.slice(0, colon_idx).trim()\n const value_raw = line.slice(colon_idx + 1).trim()\n const value = unquote(value_raw)\n if (key === 'name' || key === 'description' || key === 'model') {\n out[key] = value\n continue\n }\n if (key === 'temperature') {\n const n = Number(value)\n if (!Number.isFinite(n)) {\n throw new Error(`define_agent: temperature must be a number, got: ${value_raw}`)\n }\n out.temperature = n\n continue\n }\n }\n return { frontmatter: out, body }\n}\n\nfunction read_md_sync(path: string | URL): string {\n if (path instanceof URL) {\n return readFileSync(fileURLToPath(path), 'utf8')\n }\n if (path.startsWith('file://')) {\n return readFileSync(fileURLToPath(path), 'utf8')\n }\n return readFileSync(path, 'utf8')\n}\n\nfunction substitute(template: string, input: unknown): string {\n if (input === null || typeof input !== 'object') return template\n // oxlint-disable-next-line typescript/no-unsafe-type-assertion\n const obj = input as Record<string, unknown>\n return template.replace(PLACEHOLDER_RE, (match, key: string) => {\n const v = obj[key]\n return typeof v === 'string' ? v : match\n })\n}\n\nexport function define_agent<i, o>(config: DefineAgentConfig<i, o>): Step<i, o> {\n const text = read_md_sync(config.md_path)\n const { frontmatter, body } = parse_frontmatter(text)\n\n const display_name = config.name ?? frontmatter.name ?? 'agent'\n\n return step<i, o>(display_name, async (input, ctx: RunContext): Promise<o> => {\n if (ctx.abort.aborted) {\n throw new aborted_error('aborted before agent call')\n }\n \n let user_prompt: string\n let system_prompt: string | undefined\n if (config.build_prompt) {\n const built = config.build_prompt(input)\n if (typeof built === 'string') {\n user_prompt = built\n system_prompt = body\n } else {\n user_prompt = built.user\n system_prompt = built.system ?? body\n }\n } else {\n user_prompt = substitute(body, input)\n system_prompt = undefined\n }\n \n const opts: GenerateOptions<o> = {\n prompt: user_prompt,\n schema: config.schema,\n abort: ctx.abort,\n trajectory: ctx.trajectory,\n }\n if (system_prompt !== undefined && system_prompt !== '') {\n opts.system = system_prompt\n }\n const model = config.model ?? frontmatter.model\n if (model !== undefined) opts.model = model\n if (frontmatter.temperature !== undefined) opts.temperature = frontmatter.temperature\n if (config.schema_repair_attempts !== undefined) {\n opts.schema_repair_attempts = config.schema_repair_attempts\n }\n \n const result = await config.engine.generate<o>(opts)\n \n const resolved_model = `${result.model_resolved.provider}:${result.model_resolved.model_id}`\n ctx.trajectory.record({\n kind: 'agent.call',\n name: display_name,\n model: resolved_model,\n usage: result.usage,\n })\n \n return result.content\n })\n}\n"],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fascicle",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.8",
|
|
4
4
|
"description": "Compose agents like plain values. A TypeScript toolkit that wires LLM calls, tools, and functions into typed steps over eight providers. No framework, no ambient state.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -51,6 +51,10 @@
|
|
|
51
51
|
"types": "./dist/adapters.d.ts",
|
|
52
52
|
"import": "./dist/adapters.js"
|
|
53
53
|
},
|
|
54
|
+
"./agents": {
|
|
55
|
+
"types": "./dist/agents.d.ts",
|
|
56
|
+
"import": "./dist/agents.js"
|
|
57
|
+
},
|
|
54
58
|
"./mcp": {
|
|
55
59
|
"types": "./dist/mcp.d.ts",
|
|
56
60
|
"import": "./dist/mcp.js"
|