fascicle 0.8.13 → 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,25 @@
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
+
3
23
  ## v0.8.13 — 2026-07-07
4
24
 
5
25
  ### Added
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
@@ -164,6 +164,14 @@ type Tool<i = unknown, o = unknown> = {
164
164
  input_schema: z.ZodType<i>;
165
165
  execute: (input: i, ctx: ToolExecContext) => Promise<o> | o;
166
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;
167
175
  };
168
176
  type ToolApprovalRequest = {
169
177
  tool_name: string;
@@ -450,4 +458,4 @@ declare class provider_auth_error extends Error {
450
458
  }
451
459
  //#endregion
452
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 };
453
- //# sourceMappingURL=index-C3NcdaSY.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-C3NcdaSY.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
package/dist/index.js CHANGED
@@ -4116,12 +4116,13 @@ async function run_tool_loop(config) {
4116
4116
  }
4117
4117
  const would_exceed_after = step_index + 1 >= config.max_steps;
4118
4118
  const tool_results_to_feed = [];
4119
+ let terminal_fired = false;
4119
4120
  for (const raw_call of effective_calls) {
4120
4121
  throw_if_aborted_in_flight(config.abort, step_index, {
4121
4122
  id: raw_call.id,
4122
4123
  name: raw_call.name
4123
4124
  });
4124
- if (would_exceed_after) {
4125
+ if (would_exceed_after && tool_map.get(raw_call.name)?.ends_turn !== true) {
4125
4126
  const record = {
4126
4127
  id: raw_call.id,
4127
4128
  name: raw_call.name,
@@ -4311,6 +4312,7 @@ async function run_tool_loop(config) {
4311
4312
  };
4312
4313
  step_tool_records.push(record);
4313
4314
  tool_calls_all.push(record);
4315
+ if (tool.ends_turn === true) terminal_fired = true;
4314
4316
  tool_results_to_feed.push(build_tool_result_message(raw_call.id, tool.name, output ?? ""));
4315
4317
  record_tool_call(config.trajectory, {
4316
4318
  step_index,
@@ -4349,7 +4351,7 @@ async function run_tool_loop(config) {
4349
4351
  ...r.error !== void 0 ? { error: r.error } : { output: r.output }
4350
4352
  });
4351
4353
  for (const m of tool_results_to_feed) config.messages.push(m);
4352
- const turn_finish_reason = would_exceed_after ? "max_steps" : salvage !== void 0 ? "tool_calls" : turn.finish_reason;
4354
+ const turn_finish_reason = terminal_fired ? "tool_calls" : would_exceed_after ? "max_steps" : salvage !== void 0 ? "tool_calls" : turn.finish_reason;
4353
4355
  const step_record = {
4354
4356
  index: step_index,
4355
4357
  text: turn.text,
@@ -4365,6 +4367,11 @@ async function run_tool_loop(config) {
4365
4367
  usage: turn.usage,
4366
4368
  finish_reason: turn_finish_reason
4367
4369
  });
4370
+ if (terminal_fired) {
4371
+ finish_reason = "stop";
4372
+ text = turn.text;
4373
+ break;
4374
+ }
4368
4375
  if (would_exceed_after) {
4369
4376
  max_steps_reached = true;
4370
4377
  finish_reason = "max_steps";
@@ -4833,7 +4840,8 @@ async function generate(opts_in, engine) {
4833
4840
  model,
4834
4841
  messages: sdk_messages,
4835
4842
  abortSignal: internal_controller.signal,
4836
- stopWhen: stepCountIs(1)
4843
+ stopWhen: stepCountIs(1),
4844
+ maxRetries: 0
4837
4845
  };
4838
4846
  if (hoisted_system !== void 0) base_params.system = hoisted_system;
4839
4847
  if (sdk_tools !== void 0) base_params.tools = sdk_tools;
@@ -5181,7 +5189,7 @@ function model_call(cfg) {
5181
5189
  if (cfg.max_tool_calls_per_step !== void 0) opts.max_tool_calls_per_step = cfg.max_tool_calls_per_step;
5182
5190
  if (cfg.on_tool_approval !== void 0) opts.on_tool_approval = cfg.on_tool_approval;
5183
5191
  if (ctx.streaming) opts.on_chunk = (chunk) => {
5184
- ctx.emit({
5192
+ ctx.trajectory.record({
5185
5193
  kind: "model_chunk",
5186
5194
  step_id,
5187
5195
  chunk