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 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-Cy7EUeiP.d.ts.map
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-Cy7EUeiP.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-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>>;