fascicle 0.9.6 → 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 CHANGED
@@ -1,5 +1,33 @@
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
+
3
31
  ## v0.9.6 — 2026-07-17
4
32
 
5
33
  ### Added
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
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
- 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 eight provider adapters: Anthropic, OpenAI, Google, OpenRouter, AWS Bedrock, Ollama, LM Studio, and a `claude_cli` subprocess that drives the Claude Code CLI.
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 (18).** Every composer takes `Step<i, o>` and returns `Step<i, o>`. Anything that fits a step fits any composition of steps.
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 18 primitives, run/stream, checkpointing
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
@@ -179,7 +208,6 @@ For zero-latency streaming from inside a long-running flow, pair it with `http_l
179
208
  - [docs/cookbook.md](./docs/cookbook.md) — retries, fan-out, judges, HITL, tool loops
180
209
  - [docs/human-in-the-loop.md](./docs/human-in-the-loop.md) — suspend/resume approval over HTTP and streaming to a `useChat` UI via `fascicle/ui`
181
210
  - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
182
- - [docs/blueprint.md](./docs/blueprint.md) is the agent blueprint: the standard app architecture (one composition layer, markdown prompts, normalized module shapes)
183
211
  - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a fascicle agent as somebody's child process
184
212
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
185
213
  - [docs/comparison.md](./docs/comparison.md) — how fascicle compares to LangChain, Mastra, and others
@@ -198,7 +226,7 @@ This repo is a **single package**. The code is organized as deep modules under `
198
226
  ```bash
199
227
  pnpm install
200
228
  pnpm check # types, lint, structural rules, dead-code, tests, docs, spell
201
- pnpm check:all # adds Stryker mutation testing (slow; final gate)
229
+ pnpm check:all # adds Stryker mutation testing + the packaging gate (final gate)
202
230
  ```
203
231
 
204
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.
@@ -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.6",
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"