fascicle 0.8.12 → 0.8.16
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 +29 -0
- package/README.md +1 -0
- package/dist/{index-Cy7EUeiP.d.ts → index-ORrmFF1x.d.ts} +33 -2
- package/dist/index.d.ts +3 -1
- package/dist/index.js +410 -10
- package/dist/index.js.map +1 -1
- package/dist/mcp.d.ts +1 -1
- package/dist/ui.d.ts +48 -0
- package/dist/ui.js +171 -0
- package/dist/ui.js.map +1 -0
- package/package.json +7 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,34 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.8.16 — 2026-07-07
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- `fascicle/ui` subpath for streaming a run into an AI SDK `useChat` UI: `to_ui_message_response`, `pipe_ui_message_stream_to_response`, and `to_ui_message_chunks` translate trajectory `model_chunk` events onto the AI SDK UI message wire. Ships with `docs/human-in-the-loop.md` and `examples/hitl_http.ts` covering suspend/confirm/resume over HTTP.
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- `model_call` now records `model_chunk` on the trajectory (via `trajectory.record`) instead of routing it through `ctx.emit`, so consumers see a clean top-level `model_chunk` event carrying the `StreamChunk` rather than one wrapped in a generic `emit`.
|
|
12
|
+
|
|
13
|
+
### Fixed
|
|
14
|
+
|
|
15
|
+
- Disabled the AI SDK's built-in retry (`maxRetries: 0`) on the generate and stream calls. The engine already owns retry via its retry policy; the SDK's default of 2 nested a second retry loop inside every attempt, inflating provider round-trips and distorting backoff.
|
|
16
|
+
|
|
17
|
+
## v0.8.15 — 2026-07-07
|
|
18
|
+
|
|
19
|
+
### Added
|
|
20
|
+
|
|
21
|
+
- `Tool.ends_turn` (default off): mark a tool terminal so a successful call ends the tool loop deterministically instead of feeding the result back for another model turn. The call executes normally (its output is recorded on the `ToolCallRecord`, fed to history as a tool result, and emitted as `tool_call`/`tool_result` trajectory events and a `tool_result` chunk), then the loop stops with `finish_reason: 'stop'`. Only a successful execution ends the loop: a denied, invalid, dropped, or throwing terminal call is fed back like any other tool error and the loop continues. A terminal finish wins over a coincident `max_steps` cap (a clean `stop`, with `max_steps_reached` still false), and a salvaged terminal call (`tool_call_repair_attempts`) ends the loop identically. Existing loops are unaffected: `ends_turn` undefined preserves prior behavior exactly.
|
|
22
|
+
|
|
23
|
+
## v0.8.13 — 2026-07-07
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- Two opt-in, provider-agnostic reliability options for `generate` that make local-model tool loops survivable. Both default to off, so existing behavior is unchanged.
|
|
28
|
+
- `tool_call_repair_attempts` (default `0`): when a step returns text with no structured tool calls, salvage a call the model emitted as assistant text in Hermes (`<tool_call>{...}</tool_call>`), bare/`json`-fenced, or Qwen3-Coder XML form. A candidate runs only if its name resolves and its arguments validate against the tool's `input_schema`, so plain JSON-in-prose never false-positives. Salvaged calls run the normal execute path and are marked `salvaged` (with `salvaged_format`) on their `ToolCallRecord`, plus a `tool_call_salvaged` trajectory event. The budget is shared across the whole call, including schema-repair passes.
|
|
29
|
+
- `max_tool_calls_per_step` (default unlimited, must be `>= 1`): execute only the first N tool calls of a step and drop the rest for that turn (the model can re-issue them next turn). Dropped calls surface as `ToolCallRecord`s with `error.message: 'dropped_max_tool_calls_per_step'` and a `tool_calls_dropped` event. Set to `1` for runtimes that mishandle parallel tool calls.
|
|
30
|
+
- Both options are threaded through `EngineDefaults` (same per-call-wins merge rule) and `model_call`. The subprocess `claude_cli` provider records `option_ignored` for each, since it does not run the shared tool loop.
|
|
31
|
+
|
|
3
32
|
## v0.8.12 — 2026-07-04
|
|
4
33
|
|
|
5
34
|
### Fixed
|
package/README.md
CHANGED
|
@@ -175,6 +175,7 @@ For zero-latency streaming from inside a long-running flow, pair it with `http_l
|
|
|
175
175
|
- [docs/providers.md](./docs/providers.md) — per-provider adapter notes
|
|
176
176
|
- [docs/cli.md](./docs/cli.md) — the `claude_cli` subprocess adapter
|
|
177
177
|
- [docs/cookbook.md](./docs/cookbook.md) — retries, fan-out, judges, HITL, tool loops
|
|
178
|
+
- [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`
|
|
178
179
|
- [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
|
|
179
180
|
- [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a fascicle agent as somebody's child process
|
|
180
181
|
- [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
|
|
@@ -93,6 +93,7 @@ type CostBreakdown = {
|
|
|
93
93
|
currency: 'USD';
|
|
94
94
|
is_estimate: true;
|
|
95
95
|
};
|
|
96
|
+
type SalvageFormat = 'hermes' | 'json' | 'qwen_xml';
|
|
96
97
|
type ToolCallRecord = {
|
|
97
98
|
id: string;
|
|
98
99
|
name: string;
|
|
@@ -104,6 +105,12 @@ type ToolCallRecord = {
|
|
|
104
105
|
};
|
|
105
106
|
duration_ms: number;
|
|
106
107
|
started_at: number;
|
|
108
|
+
/**
|
|
109
|
+
* Present only when the call was recovered from assistant text rather than
|
|
110
|
+
* returned structurally by the provider (tool_call_repair_attempts > 0).
|
|
111
|
+
*/
|
|
112
|
+
salvaged?: true;
|
|
113
|
+
salvaged_format?: SalvageFormat;
|
|
107
114
|
};
|
|
108
115
|
type StepRecord = {
|
|
109
116
|
index: number;
|
|
@@ -157,6 +164,14 @@ type Tool<i = unknown, o = unknown> = {
|
|
|
157
164
|
input_schema: z.ZodType<i>;
|
|
158
165
|
execute: (input: i, ctx: ToolExecContext) => Promise<o> | o;
|
|
159
166
|
needs_approval?: boolean | ((input: i) => boolean | Promise<boolean>);
|
|
167
|
+
/**
|
|
168
|
+
* When true, a SUCCESSFUL execution of this tool ends the tool loop
|
|
169
|
+
* deterministically: the loop executes the call (recording its output and
|
|
170
|
+
* trajectory events like any tool), then stops instead of running another
|
|
171
|
+
* model turn. A denied, invalid, dropped, or throwing terminal call does NOT
|
|
172
|
+
* end the loop. undefined (the default) preserves the prior loop exactly.
|
|
173
|
+
*/
|
|
174
|
+
ends_turn?: boolean;
|
|
160
175
|
};
|
|
161
176
|
type ToolApprovalRequest = {
|
|
162
177
|
tool_name: string;
|
|
@@ -224,6 +239,20 @@ type GenerateOptions<t = string> = {
|
|
|
224
239
|
retry?: RetryPolicy;
|
|
225
240
|
tool_error_policy?: 'feed_back' | 'throw';
|
|
226
241
|
schema_repair_attempts?: number;
|
|
242
|
+
/**
|
|
243
|
+
* Budget for salvaging tool calls the model emitted as assistant text
|
|
244
|
+
* instead of structured tool_calls (a common local-runtime failure).
|
|
245
|
+
* 0 (the default) disables salvage entirely. The budget is shared across
|
|
246
|
+
* the whole generate call, including schema-repair re-invocations.
|
|
247
|
+
*/
|
|
248
|
+
tool_call_repair_attempts?: number;
|
|
249
|
+
/**
|
|
250
|
+
* Cap on tool calls executed per step. Calls beyond the cap are dropped
|
|
251
|
+
* for that step (the model can re-issue them next turn) and surfaced via
|
|
252
|
+
* ToolCallRecord errors and a tool_calls_dropped trajectory event.
|
|
253
|
+
* undefined (the default) leaves the count unlimited.
|
|
254
|
+
*/
|
|
255
|
+
max_tool_calls_per_step?: number;
|
|
227
256
|
on_tool_approval?: ToolApprovalHandler;
|
|
228
257
|
provider_options?: Record<string, unknown>;
|
|
229
258
|
};
|
|
@@ -291,7 +320,7 @@ type ProviderConfigMap = {
|
|
|
291
320
|
* | --------------------------------------------------------------------- | ----------------------------------------- |
|
|
292
321
|
* | `model` | per-call wins; else default; else `sonnet` |
|
|
293
322
|
* | `provider` | per-call wins; else default; else sole configured provider; else `anthropic` |
|
|
294
|
-
* | `system`, `effort`, `max_steps`, `tool_error_policy`, `schema_repair_attempts` | per-call wins (nullish coalesce) |
|
|
323
|
+
* | `system`, `effort`, `max_steps`, `tool_error_policy`, `schema_repair_attempts`, `tool_call_repair_attempts`, `max_tool_calls_per_step` | per-call wins (nullish coalesce) |
|
|
295
324
|
* | `retry_policy` | per-call replaces wholesale |
|
|
296
325
|
* | `provider_options` | two-level: per-provider-key shallow merge |
|
|
297
326
|
* | `prompt`, `tools`, `schema`, `abort`, `trajectory`, `on_chunk` | not defaultable; always call-supplied |
|
|
@@ -305,6 +334,8 @@ type EngineDefaults = {
|
|
|
305
334
|
readonly retry_policy?: RetryPolicy;
|
|
306
335
|
readonly tool_error_policy?: 'feed_back' | 'throw';
|
|
307
336
|
readonly schema_repair_attempts?: number;
|
|
337
|
+
readonly tool_call_repair_attempts?: number;
|
|
338
|
+
readonly max_tool_calls_per_step?: number;
|
|
308
339
|
readonly provider_options?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
|
|
309
340
|
};
|
|
310
341
|
type EngineConfig = {
|
|
@@ -427,4 +458,4 @@ declare class provider_auth_error extends Error {
|
|
|
427
458
|
}
|
|
428
459
|
//#endregion
|
|
429
460
|
export { RetryFailureKind as A, UserContentPart as B, GenerateResult as C, ProviderConfigMap as D, PricingTable as E, ToolApprovalHandler as F, ToolApprovalRequest as I, ToolCallRecord as L, StepRecord as M, StreamChunk as N, ProviderInit as O, Tool as P, ToolExecContext as R, GenerateOptions as S, Pricing as T, EffortLevel as _, on_chunk_error as a, EngineDefaults as b, provider_error as c, schema_validation_error as d, tool_approval_denied_error as f, CostBreakdown as g, AssistantContentPart as h, model_required_error as i, RetryPolicy as j, ResolvedModel as k, provider_not_configured_error as l, create_engine as m, engine_config_error as n, provider_auth_error as o, tool_error as p, engine_disposed_error as r, provider_capability_error as s, claude_cli_error as t, rate_limit_error as u, Engine as v, Message as w, FinishReason as x, EngineConfig as y, UsageTotals as z };
|
|
430
|
-
//# sourceMappingURL=index-
|
|
461
|
+
//# sourceMappingURL=index-ORrmFF1x.d.ts.map
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { A as fallback, B as describe, C as checkpoint, D as LoopResult, E as LoopGuardResult, F as parallel, G as Step, H as run, I as sequence, J as TrajectoryLogger, K as StepMetadata, L as DescribeOptions, M as pipe, N as map, O as loop, P as branch, R as FlowNode, S as suspend, T as LoopConfig, U as CheckpointStore, V as step, W as RunContext, Y as __json_default_export, _ as suspended_error, a as SpanStartEvent, b as stash, c as span_end_event_schema, d as STEP_KINDS, f as StepKind, g as resume_validation_error, h as describe_cycle_error, i as SpanEndEvent, j as retry, k as timeout, l as span_start_event_schema, m as aborted_error, n as EmitEvent, o as custom_event_schema, p as is_step_kind, q as TrajectoryEvent, r as ParsedTrajectoryEvent, s as emit_event_schema, t as CustomTrajectoryEvent, u as trajectory_event_schema, v as timeout_error, w as compose, x as use, y as scope, z as FlowValue } from "./index-CEj6hY9z.js";
|
|
2
|
-
import { A as RetryFailureKind, B as UserContentPart, C as GenerateResult, D as ProviderConfigMap, E as PricingTable, F as ToolApprovalHandler, I as ToolApprovalRequest, L as ToolCallRecord, M as StepRecord, N as StreamChunk, O as ProviderInit, P as Tool, R as ToolExecContext, S as GenerateOptions, T as Pricing, _ as EffortLevel, a as on_chunk_error, b as EngineDefaults, c as provider_error, d as schema_validation_error, f as tool_approval_denied_error, g as CostBreakdown, h as AssistantContentPart, i as model_required_error, j as RetryPolicy, k as ResolvedModel, l as provider_not_configured_error, m as create_engine, n as engine_config_error, o as provider_auth_error, p as tool_error, r as engine_disposed_error, s as provider_capability_error, t as claude_cli_error, u as rate_limit_error, v as Engine, w as Message, x as FinishReason, y as EngineConfig, z as UsageTotals } from "./index-
|
|
2
|
+
import { A as RetryFailureKind, B as UserContentPart, C as GenerateResult, D as ProviderConfigMap, E as PricingTable, F as ToolApprovalHandler, I as ToolApprovalRequest, L as ToolCallRecord, M as StepRecord, N as StreamChunk, O as ProviderInit, P as Tool, R as ToolExecContext, S as GenerateOptions, T as Pricing, _ as EffortLevel, a as on_chunk_error, b as EngineDefaults, c as provider_error, d as schema_validation_error, f as tool_approval_denied_error, g as CostBreakdown, h as AssistantContentPart, i as model_required_error, j as RetryPolicy, k as ResolvedModel, l as provider_not_configured_error, m as create_engine, n as engine_config_error, o as provider_auth_error, p as tool_error, r as engine_disposed_error, s as provider_capability_error, t as claude_cli_error, u as rate_limit_error, v as Engine, w as Message, x as FinishReason, y as EngineConfig, z as UsageTotals } from "./index-ORrmFF1x.js";
|
|
3
3
|
import { z } from "zod";
|
|
4
4
|
|
|
5
5
|
//#region src/composites/adversarial.d.ts
|
|
@@ -298,6 +298,8 @@ type ModelCallConfig<T = string> = {
|
|
|
298
298
|
readonly retry_policy?: RetryPolicy;
|
|
299
299
|
readonly tool_error_policy?: 'feed_back' | 'throw';
|
|
300
300
|
readonly schema_repair_attempts?: number;
|
|
301
|
+
readonly tool_call_repair_attempts?: number;
|
|
302
|
+
readonly max_tool_calls_per_step?: number;
|
|
301
303
|
readonly on_tool_approval?: ToolApprovalHandler;
|
|
302
304
|
};
|
|
303
305
|
declare function model_call<T = string>(cfg: ModelCallConfig<T>): Step<ModelCallInput, GenerateResult<T>>;
|