fascicle 0.17.0 → 0.17.2
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 +25 -0
- package/dist/AGENTS.md +8 -8
- package/dist/acp.d.ts +1 -1
- package/dist/acp.js +2 -2
- package/dist/agents.d.ts +1 -1
- package/dist/agents.js +1 -1
- package/dist/{core-BOFcG3tp.js → core-Dwir3pkb.js} +231 -15
- package/dist/core-Dwir3pkb.js.map +1 -0
- package/dist/diagram_bin.js +1 -1
- package/dist/{engine-BMdRqWL2.js → engine-DPPqAVdZ.js} +224 -38
- package/dist/engine-DPPqAVdZ.js.map +1 -0
- package/dist/index.d.ts +61 -6
- package/dist/index.js +132 -18
- package/dist/index.js.map +1 -1
- package/dist/{invoke-BbJLQcLl.js → invoke-DF7YLovL.js} +3 -3
- package/dist/{invoke-BbJLQcLl.js.map → invoke-DF7YLovL.js.map} +1 -1
- package/dist/{leading_system-DmNxhvzL.js → leading_system-DJvuhESU.js} +2 -2
- package/dist/{leading_system-DmNxhvzL.js.map → leading_system-DJvuhESU.js.map} +1 -1
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +1 -1
- package/dist/{search-CpCJYMUm.js → search-DjhdMsJ8.js} +4 -1
- package/dist/search-DjhdMsJ8.js.map +1 -0
- package/dist/search_worker.js +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/{types-BNgAUQP1.d.ts → types-C7pO0jLq.d.ts} +51 -7
- package/dist/viewer.d.ts +27 -0
- package/dist/viewer.js +165 -19
- package/dist/viewer.js.map +1 -1
- package/package.json +1 -1
- package/dist/core-BOFcG3tp.js.map +0 -1
- package/dist/engine-BMdRqWL2.js.map +0 -1
- package/dist/search-CpCJYMUm.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,30 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.17.2 — 2026-10-28
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- **A `gate` with no store fails its resume instead of running its step again.** A gate without one suspended and then, on the resume, ran `inner` again and passed the new result through, so a gate around a model call bought a second answer that the approver never saw. The resume fails now with `gate_result_error`, whose `reason` is `no_store`. Give the gate a `store`, or the run a `checkpoint_store`, or use a plain `suspend` when the step is cheap and deterministic. A gate handed its datum before it ever suspended, through `resume_data` on a first run, is resuming too, so with nothing stored it fails with `missing`, or with `no_store` when it has no store, since an approval given before anything was shown covers nothing.
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- **A resumed `gate` serves the result it showed, or fails the run.** A gate's resume read its result back from the store, and a read that threw, or a store that no longer held the result, counted as a miss, so the gate ran `inner` again, paid for it again, wrote the new result over the old one, and passed it through an approval that covered the old one. A resume never runs `inner` now. It serves the stored result, or it fails with `gate_result_error`, which names the gate and carries a `reason`: `read_error`, with the store's error as its `cause`, or `missing`. The trajectory records the lookup's `checkpoint` event as before. A durable run that a failed read stopped resumes from the next event with nothing new, since the approval stays in its resume data. A first run's failed read is still a miss, since nobody has approved anything yet.
|
|
12
|
+
- **A flow that uses one suspend id in two places is refused before it runs.** Resume data is keyed by suspend id, so a second `suspend` or `gate` with the same id found the first one's datum and passed without pausing, on an approval that was given for something else. `run`, `run.stream`, and `run.until_suspended`, and so `durable`, now walk the flow before any step runs and throw `duplicate_suspend_id_error` with `reason: 'declared_twice'`, whose `paths` hold each place's step ids from the root and whose message names each place. A `gate` counts through its `suspend`, one `suspend` placed twice counts twice, and two arms of a `branch` count too, since a resume replays the branch's condition. The run ends `failed`. A flow that ran before and is refused now needs an id of its own for each `suspend` and `gate`, and a durable run that the refusal failed has to be deleted and started again on the fixed flow, since renaming an id changes the flow's fingerprint. A run that reaches one `suspend` again fails there too, with `reason: 'reached_twice'`, when the input differs from the one its datum was taken for: a later round of a `loop`, the next item of a `map`, or a call through `ctx.call` that the tree doesn't show. The input is the same when its JSON, with the keys sorted, reads the same as it did when the datum was taken, so an object changed in place since counts as another input, and one that JSON can't hold has to be the same value. A `retry` that runs the step again on the same input still passes. A `map` with `settle: true` settles the second item as the error, and a flow that wants a decision per round or per item approves a map's batch at a gate before the map, or a loop's result at a gate after it. A `gate` checks its own input the same way, on a first run as well as a resume, before it reads or writes its store, since its key is fixed and its `suspend` always sees a view of the one stored result. A `map` whose items each reach one gate used to show the approver one item's result and hand every item another's, and now its second item fails with `reached_twice` before it runs `inner`, so the store keeps the first item's result. Core exports the comparison as `same_input_as`.
|
|
13
|
+
- **A provider failure that `retry_on` leaves out throws a typed error.** `retry_with_policy` threw such a failure again as it caught it, and for a 429, a 5xx, or a network failure that was the plain record that the classifier built, so it reached the caller as something like `{ kind: 'provider_5xx', status: 503 }`, and the run's `run_end` read `[object Object]`. It throws what exhaustion would have thrown now: `rate_limit_error` for a rate limit, with `attempts` counting every failure so far, and `provider_error` for the rest, with `cause_kind` set to `provider_5xx` or `network`, and the status and body of a 5xx. The message is the provider's own, or else says that `retry_on` leaves the kind out. A failure that was already an `Error`, such as `turn_timeout_error` or a native adapter's network failure, comes back as itself.
|
|
14
|
+
- **`checkpoint` can fail the run on a read that failed, with `on_read_error: 'fail'`.** A `store.get` that threw counted as a miss, so `checkpoint` ran `inner` again and wrote the new result over the old one, and a hand-built `checkpoint` before a `suspend` that showed its result passed an approval through to something the approver never saw. `on_read_error: 'fail'` records the same `read_error` event and then throws the store's error, without running `inner` or writing anything, the read-side twin of `on_write_error: 'fail'`. A checkpoint whose result a `suspend` shows should pass `'fail'` for both. `'miss'` is the default and keeps the old behavior, and the option stays out of the step's `config`, so `describe` and a durable run's fingerprint don't change.
|
|
15
|
+
|
|
16
|
+
### Internal
|
|
17
|
+
|
|
18
|
+
- **The publish workflow keeps its OIDC identity away from the job that runs dependencies.** `publish.yaml` held `id-token: write` in the same job that installed, ran the gate, and built, so a compromised dev dependency could have minted the workflow's identity and published under it. It runs three jobs now: `unpublished` looks the version up on npm, `build` installs, runs the gate, builds, and packs the tarball with only `contents: read`, and `publish` holds `id-token: write` and the `npm-publish` gate, runs nothing from the repo, and publishes the packed tarball with `--ignore-scripts`. The gate runs before the approval, so the reviewer approves a green build, and [SECURITY.md](./SECURITY.md) describes the split.
|
|
19
|
+
|
|
20
|
+
## v0.17.1 — 2026-10-26
|
|
21
|
+
|
|
22
|
+
### Added
|
|
23
|
+
|
|
24
|
+
- **The viewer can read a trajectory without following a link.** A host that checked a run's `trajectory.jsonl` before it started a viewer couldn't keep that check true, because the tail and `/api/trajectory` opened the path again on every read and followed a link there, so a link that was swapped in afterwards, such as one that points at `~/.ssh/id_ed25519`, was read and served to whoever held the viewer's URL. `follow_links: false` on `start_viewer`, `start_tail`, and `create_viewer_handler` opens the trajectory with `O_NOFOLLOW` and checks the handle that it opened rather than the path, so the viewer reads only a regular file with no other name, and a FIFO at the path is refused without waiting for a writer. The tail reports a refusal to `on_io_error` and waits for a file that it can read, as it does for a missing one, and `/api/trajectory` serves the ring, as it does when there's no file. A directory above the file is still followed, so a host keeps checking those itself, and the option throws on a platform that has no `O_NOFOLLOW`. Following links stays the default. See [viewer.md](./docs/viewer.md#security).
|
|
25
|
+
- **The tool loop tells the model which calls `max_tool_calls_per_step` dropped, and a read-only tool doesn't count toward the cap.** Calls past the cap were left out of history with no result, so that no provider saw a call without one, but the model never learned that they hadn't run, and whether it made them again was left to chance. When the loop goes on, one user message after the step's tool results now names each dropped call with its input, clipped to 120 characters, as in `1 call didn't run, because max_tool_calls_per_step allows 1 per turn: write_file({"path":"a.ts"}). Make it again, no more than 1 per turn.` A `Tool` gains `read_only`, and a call to a tool that sets it doesn't count, so a turn can make several reads and still make only one write or command. The first counted call past the cap is dropped, and so is every call after it, so what runs is always the start of what the model asked for. The ACP `read_file`, `list_files`, and `search` tools set it. MCP tools don't, since `readOnlyHint` is a hint from the server that nothing checks. The dropped calls' `ToolCallRecord`s and the `tool_calls_dropped` event are unchanged. See [configuration.md](./docs/configuration.md#local-runtime-tool-reliability).
|
|
26
|
+
- **`truncated_turn_policy: 'continue'` keeps a tool loop going past a turn that reached its output limit before it made a call.** The loop ended on any turn that made no tool call, whatever its finish reason, so a turn that reached `max_tokens` while a thinking model was still reasoning ended the whole session, which made `max_tokens` useless as a per-turn cap. Under `'continue'`, on a call with tools and with a step left, the loop sends back whatever text the turn showed and leaves out its reasoning, which a provider wouldn't take back without the signature that it never got. Then it adds a user message that says the turn was cut off at the limit and asks for the next tool call or the final answer, and asks for another turn, which counts toward `max_steps`. The turn's `StepRecord` says `truncated: true`, and a `turn_truncated` event records its `output_tokens` and the call's `max_tokens`. The option goes on a call, on `defaults`, or on a `model_call` or `model_step` config, any other value throws `engine_config_error`, and `claude_cli` records `option_ignored`. `'stop'` stays the default. Ollama counts a model's thinking against `num_predict`, on its MLX runner as on llama.cpp, so the cap does stop a long reasoning turn there. See [configuration.md](./docs/configuration.md#local-runtime-tool-reliability).
|
|
27
|
+
|
|
3
28
|
## v0.17.0 — 2026-10-24
|
|
4
29
|
|
|
5
30
|
### Added
|
package/dist/AGENTS.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
This file is for a coding agent (Claude Code, Codex, Cursor, or another) that's
|
|
4
4
|
working in a project which uses the published `fascicle` package. A person who
|
|
5
5
|
is learning Fascicle will usually import it from their `CLAUDE.md`, as
|
|
6
|
-
[lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
6
|
+
[lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
|
|
7
7
|
was checked against `fascicle` 0.16.3, and against 0.15.0 where the two differ,
|
|
8
8
|
except what's marked 0.17.0 and later, which was checked against 0.17.0. A rule
|
|
9
9
|
that a later release changes says what changed.
|
|
@@ -298,7 +298,7 @@ messages are the real ones.
|
|
|
298
298
|
| "check its work and redo it" | a `loop` with a code guard, or `adversarial` |
|
|
299
299
|
| "pick the best of" | `ensemble_step` |
|
|
300
300
|
| "only if they agree" | `consensus` |
|
|
301
|
-
| "ask me first," "wait for approval" | `suspend` or `gate`, with `run.until_suspended` |
|
|
301
|
+
| "ask me first," "wait for approval" | `suspend` or `gate`, with `run.until_suspended`, and a `gate` needs a `store` or a `checkpoint_store` to resume |
|
|
302
302
|
| "let it look things up," "give it a tool" | `define_tool`, and `tools` with `max_steps` on the `model_step` |
|
|
303
303
|
| "ask me before it runs that tool" | `needs_approval` on the tool, and `on_tool_approval` on the model step |
|
|
304
304
|
| "don't redo the expensive part" | `checkpoint`, with a `checkpoint_store` |
|
|
@@ -396,11 +396,11 @@ describe('the calculator', () => {
|
|
|
396
396
|
|
|
397
397
|
## Where to Look Next
|
|
398
398
|
|
|
399
|
-
- [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
400
|
-
- [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
399
|
+
- [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/blueprint.md) for the layout of a growing app.
|
|
400
|
+
- [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/leaf-arm-spine.md) for choosing a primitive at each
|
|
401
401
|
layer.
|
|
402
|
-
- [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
403
|
-
- [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
402
|
+
- [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/composition.md) for one line on every composer.
|
|
403
|
+
- [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/cookbook.md) for worked patterns, including tool loops with
|
|
404
404
|
`define_tool`.
|
|
405
|
-
- [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
406
|
-
- [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.
|
|
405
|
+
- [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/testing.md) for the stand-in engines.
|
|
406
|
+
- [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/troubleshooting.md) for errors and their causes.
|
package/dist/acp.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
|
|
2
|
-
import { M as Tool, N as ToolApprovalHandler } from "./types-
|
|
2
|
+
import { M as Tool, N as ToolApprovalHandler } from "./types-C7pO0jLq.js";
|
|
3
3
|
import { AgentApp, ClientCapabilities, ContentBlock, SessionUpdate } from "@agentclientprotocol/sdk";
|
|
4
4
|
//#region src/acp/types.d.ts
|
|
5
5
|
/**
|
package/dist/acp.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { A as aborted_error, E as run } from "./core-Dwir3pkb.js";
|
|
2
2
|
import { n as is_record, t as as_record } from "./records-1HU7mWXf.js";
|
|
3
3
|
import { t as json_schema_to_standard } from "./json_schema_to_standard-C4F4lXHE.js";
|
|
4
|
-
import { a as read_file_tool, c as resolve_roots, i as is_binary, l as shown_path, n as search_tool, o as contain_writable, r as list_files_tool, s as error_code } from "./search-
|
|
4
|
+
import { a as read_file_tool, c as resolve_roots, i as is_binary, l as shown_path, n as search_tool, o as contain_writable, r as list_files_tool, s as error_code } from "./search-DjhdMsJ8.js";
|
|
5
5
|
import { t as route_console_to_stderr } from "./console-CdB4pcFO.js";
|
|
6
6
|
import { randomUUID } from "node:crypto";
|
|
7
7
|
import { mkdir, open, stat, writeFile } from "node:fs/promises";
|
package/dist/agents.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { c as Step } from "./types-CPqLZOEr.js";
|
|
2
2
|
import { r as ToolSchema } from "./types-BK0UW28o.js";
|
|
3
|
-
import { l as EffortLevel, u as Engine } from "./types-
|
|
3
|
+
import { l as EffortLevel, u as Engine } from "./types-C7pO0jLq.js";
|
|
4
4
|
//#region src/agents/define_agent.d.ts
|
|
5
5
|
type AgentBuiltPrompt = string | {
|
|
6
6
|
readonly user: string;
|
package/dist/agents.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { A as aborted_error, b as assert_valid_step_id, y as step } from "./core-Dwir3pkb.js";
|
|
2
2
|
import { readFileSync } from "node:fs";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
//#region src/agents/define_agent.ts
|
|
@@ -146,7 +146,7 @@ const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
|
|
|
146
146
|
* Pick a node's label: its display name, else an id its author chose, else
|
|
147
147
|
* its kind. `by_kind` reports the last case, where the kind already shows.
|
|
148
148
|
*/
|
|
149
|
-
function label_of(node) {
|
|
149
|
+
function label_of$1(node) {
|
|
150
150
|
const display = resolve_display_name(node, "");
|
|
151
151
|
if (display !== "") return {
|
|
152
152
|
label: display,
|
|
@@ -273,7 +273,7 @@ function find_replays(root) {
|
|
|
273
273
|
const seen = by_id.get(node.id);
|
|
274
274
|
by_id.set(node.id, {
|
|
275
275
|
id: node.id,
|
|
276
|
-
label: label_of(node).label,
|
|
276
|
+
label: label_of$1(node).label,
|
|
277
277
|
gates: seen === void 0 ? gates : [.../* @__PURE__ */ new Set([...seen.gates, ...gates])]
|
|
278
278
|
});
|
|
279
279
|
}
|
|
@@ -362,7 +362,7 @@ function wrap(words, limit) {
|
|
|
362
362
|
* parent gives this child, and it is dropped when it only repeats the label.
|
|
363
363
|
*/
|
|
364
364
|
function to_item(node, role, draw) {
|
|
365
|
-
const { label, by_kind } = label_of(node);
|
|
365
|
+
const { label, by_kind } = label_of$1(node);
|
|
366
366
|
return {
|
|
367
367
|
head: role === void 0 || role === label ? label : `${role} ${label}`,
|
|
368
368
|
note: [...note_of(node, by_kind), ...replay_note(draw.marks.get(node))],
|
|
@@ -529,6 +529,51 @@ var flow_changed_error = class extends Error {
|
|
|
529
529
|
this.continued_on = continued_on;
|
|
530
530
|
}
|
|
531
531
|
};
|
|
532
|
+
/**
|
|
533
|
+
* What a `gate_result_error` says for `reason`: which gate resumed, why the
|
|
534
|
+
* result it showed can't be served, and what to do about it.
|
|
535
|
+
*/
|
|
536
|
+
function gate_result_message(suspend_id, reason, cause) {
|
|
537
|
+
if (reason === "read_error") return `gate ${suspend_id} resumed, and its store failed to read the result that it showed (${cause instanceof Error ? cause.message : String(cause)}): resume the run again once the store reads, since the approval is still in its resume data`;
|
|
538
|
+
if (reason === "missing") return `gate ${suspend_id} resumed, and its store no longer holds the result that it showed: delete the run and start it again`;
|
|
539
|
+
return `gate ${suspend_id} resumed with no store to serve the result that it showed: give the gate a store or the run a checkpoint_store, or use a plain suspend when the step is cheap and deterministic`;
|
|
540
|
+
}
|
|
541
|
+
var gate_result_error = class extends Error {
|
|
542
|
+
kind = "gate_result_error";
|
|
543
|
+
suspend_id;
|
|
544
|
+
reason;
|
|
545
|
+
constructor(suspend_id, reason, cause) {
|
|
546
|
+
super(gate_result_message(suspend_id, reason, cause), cause === void 0 ? void 0 : { cause });
|
|
547
|
+
this.name = "gate_result_error";
|
|
548
|
+
this.suspend_id = suspend_id;
|
|
549
|
+
this.reason = reason;
|
|
550
|
+
}
|
|
551
|
+
};
|
|
552
|
+
/**
|
|
553
|
+
* What a `duplicate_suspend_id_error` says: where the id sits more than
|
|
554
|
+
* once, or that a run reached it again on another input, and what to do
|
|
555
|
+
* about it.
|
|
556
|
+
*/
|
|
557
|
+
function duplicate_suspend_id_message(suspend_id, reason, paths, detail) {
|
|
558
|
+
if (reason === "reached_twice") return `suspend ${suspend_id} was reached again in this run with another input, and its resume data answered the first one: a suspend takes one decision per run, so approve a map's batch at a gate before the map, or a loop's result at a gate after it`;
|
|
559
|
+
const places = detail.labels ?? paths.map((path) => path.join(" > "));
|
|
560
|
+
const arms = detail.at_branch === true ? "; only one arm of a branch runs, but a resume replays its condition, so each arm's gate needs an id of its own" : "";
|
|
561
|
+
return `suspend id ${JSON.stringify(suspend_id)} is used in ${places.length} places (${places.join(", ")}): resume data is keyed by id, so give each suspend and gate an id of its own${arms}`;
|
|
562
|
+
}
|
|
563
|
+
var duplicate_suspend_id_error = class extends Error {
|
|
564
|
+
kind = "duplicate_suspend_id_error";
|
|
565
|
+
suspend_id;
|
|
566
|
+
reason;
|
|
567
|
+
paths;
|
|
568
|
+
constructor(suspend_id, reason, detail = {}) {
|
|
569
|
+
const paths = detail.paths ?? [];
|
|
570
|
+
super(duplicate_suspend_id_message(suspend_id, reason, paths, detail));
|
|
571
|
+
this.name = "duplicate_suspend_id_error";
|
|
572
|
+
this.suspend_id = suspend_id;
|
|
573
|
+
this.reason = reason;
|
|
574
|
+
this.paths = paths;
|
|
575
|
+
}
|
|
576
|
+
};
|
|
532
577
|
var run_not_found_error = class extends Error {
|
|
533
578
|
kind = "run_not_found_error";
|
|
534
579
|
run_id;
|
|
@@ -992,6 +1037,144 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
|
|
|
992
1037
|
};
|
|
993
1038
|
}
|
|
994
1039
|
//#endregion
|
|
1040
|
+
//#region src/core/suspend_ids.ts
|
|
1041
|
+
/**
|
|
1042
|
+
* suspend_ids: one suspend id, one place in the flow.
|
|
1043
|
+
*
|
|
1044
|
+
* Resume data is keyed by suspend id, so a `suspend` finds its datum by id
|
|
1045
|
+
* alone, and a second `suspend` or `gate` with the same id would pass on the
|
|
1046
|
+
* first one's datum without pausing. `check_suspend_ids(flow)` walks the
|
|
1047
|
+
* declared tree before a run starts and throws `duplicate_suspend_id_error`
|
|
1048
|
+
* with `reason: 'declared_twice'` for the first id, in flow order, that sits
|
|
1049
|
+
* in two or more places. A `gate` counts through the `suspend` inside it, and
|
|
1050
|
+
* one `suspend` value placed twice counts in each place.
|
|
1051
|
+
*
|
|
1052
|
+
* The walk refuses an id in two arms of a `branch` as well. Only one arm runs
|
|
1053
|
+
* per pass, but a resume replays the branch's condition, and a condition that
|
|
1054
|
+
* comes out the other way would hand one arm's approval to the other.
|
|
1055
|
+
*
|
|
1056
|
+
* The walk reads `children` and guards against a cycle with the steps on the
|
|
1057
|
+
* current path from the root, the way `describe` does, so a step that two
|
|
1058
|
+
* paths reach counts once per path, and a step that is its own ancestor is
|
|
1059
|
+
* skipped where it comes back. A step never changes once it's built, so the
|
|
1060
|
+
* answer is kept per root step and each root is walked once.
|
|
1061
|
+
*
|
|
1062
|
+
* What the walk can't see, a run can: a `suspend` that a `loop` reaches in a
|
|
1063
|
+
* later round, or a `map` for its next item. `same_input_as(first)` is the
|
|
1064
|
+
* test the runner holds each later reach to, so a run takes each id's datum
|
|
1065
|
+
* once, or again on the same input, the way a `retry` runs a step again.
|
|
1066
|
+
*/
|
|
1067
|
+
const refusals = /* @__PURE__ */ new WeakMap();
|
|
1068
|
+
/**
|
|
1069
|
+
* Add the place of every `suspend` at or under `step` to `found`, by id, in
|
|
1070
|
+
* the order the walk meets them. `on_path` holds the steps between the root
|
|
1071
|
+
* and `step`, so a step met again among its own descendants is skipped.
|
|
1072
|
+
*/
|
|
1073
|
+
function collect(step, trail, on_path, found) {
|
|
1074
|
+
if (on_path.has(step)) return;
|
|
1075
|
+
if (step.kind === "suspend") found.set(step.id, [...found.get(step.id) ?? [], trail]);
|
|
1076
|
+
on_path.add(step);
|
|
1077
|
+
for (const [index, child] of (step.children ?? []).entries()) collect(child, [...trail, {
|
|
1078
|
+
step: child,
|
|
1079
|
+
position: index + 1
|
|
1080
|
+
}], on_path, found);
|
|
1081
|
+
on_path.delete(step);
|
|
1082
|
+
}
|
|
1083
|
+
/**
|
|
1084
|
+
* The depth at which two places first go separate ways. Both start at the
|
|
1085
|
+
* root, and two children of one parent at one position are the same step,
|
|
1086
|
+
* so the first position that differs is where they part, and -1 means one
|
|
1087
|
+
* place holds the other.
|
|
1088
|
+
*/
|
|
1089
|
+
function parting_depth(a, b) {
|
|
1090
|
+
return a.findIndex((frame, depth) => frame.position !== b[depth]?.position);
|
|
1091
|
+
}
|
|
1092
|
+
/**
|
|
1093
|
+
* How the refusal names `place`: its step ids from the root, with a step's
|
|
1094
|
+
* position under its parent added at each depth where the place parts from
|
|
1095
|
+
* a twin, another place whose ids read the same. A place among its own
|
|
1096
|
+
* twins parts from itself at -1, which marks no step.
|
|
1097
|
+
*/
|
|
1098
|
+
function label_of(place, twins) {
|
|
1099
|
+
const marked = new Set(twins.map((twin) => parting_depth(place, twin)));
|
|
1100
|
+
return place.map((frame, depth) => marked.has(depth) ? `${frame.step.id} (step ${frame.position})` : frame.step.id).join(" > ");
|
|
1101
|
+
}
|
|
1102
|
+
/**
|
|
1103
|
+
* The refusal for `suspend_id`, which sits at each of `places`.
|
|
1104
|
+
*/
|
|
1105
|
+
function refusal_for(suspend_id, places) {
|
|
1106
|
+
const paths = places.map((place) => place.map((frame) => frame.step.id));
|
|
1107
|
+
const keys = paths.map((path) => JSON.stringify(path));
|
|
1108
|
+
return {
|
|
1109
|
+
suspend_id,
|
|
1110
|
+
paths,
|
|
1111
|
+
labels: places.map((place, i) => label_of(place, places.filter((_, j) => keys[j] === keys[i]))),
|
|
1112
|
+
at_branch: places.some((a) => places.some((b) => a[parting_depth(a, b) - 1]?.step.kind === "branch"))
|
|
1113
|
+
};
|
|
1114
|
+
}
|
|
1115
|
+
/**
|
|
1116
|
+
* The refusal for the first id in flow order that sits in two or more places
|
|
1117
|
+
* under `root`, or `null` when every id sits in one.
|
|
1118
|
+
*/
|
|
1119
|
+
function find_refusal(root) {
|
|
1120
|
+
const found = /* @__PURE__ */ new Map();
|
|
1121
|
+
collect(root, [{
|
|
1122
|
+
step: root,
|
|
1123
|
+
position: 0
|
|
1124
|
+
}], /* @__PURE__ */ new Set(), found);
|
|
1125
|
+
for (const [suspend_id, places] of found) if (places.length > 1) return refusal_for(suspend_id, places);
|
|
1126
|
+
return null;
|
|
1127
|
+
}
|
|
1128
|
+
/**
|
|
1129
|
+
* Throw `duplicate_suspend_id_error` when `root` holds one suspend id in two
|
|
1130
|
+
* or more places. The runner calls this before the first step of every run,
|
|
1131
|
+
* and the answer is kept per root, so a flow is walked once however often it
|
|
1132
|
+
* runs.
|
|
1133
|
+
*/
|
|
1134
|
+
function check_suspend_ids(root) {
|
|
1135
|
+
let refusal = refusals.get(root);
|
|
1136
|
+
if (refusal === void 0) {
|
|
1137
|
+
refusal = find_refusal(root);
|
|
1138
|
+
refusals.set(root, refusal);
|
|
1139
|
+
}
|
|
1140
|
+
if (refusal !== null) throw new duplicate_suspend_id_error(refusal.suspend_id, "declared_twice", refusal);
|
|
1141
|
+
}
|
|
1142
|
+
/**
|
|
1143
|
+
* Sort an object's keys as `JSON.stringify` meets it, so two objects that
|
|
1144
|
+
* hold the same entries in another order write the same JSON. An array keeps
|
|
1145
|
+
* its order, since its order is its content.
|
|
1146
|
+
*/
|
|
1147
|
+
function sort_keys(_, value) {
|
|
1148
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
|
|
1149
|
+
return Object.fromEntries(Object.keys(value).toSorted().map((key) => [key, Reflect.get(value, key)]));
|
|
1150
|
+
}
|
|
1151
|
+
/**
|
|
1152
|
+
* The stable JSON of `value`, its keys sorted, or `undefined` when JSON
|
|
1153
|
+
* can't hold it: `JSON.stringify` throws (a `BigInt`, a cycle) or writes
|
|
1154
|
+
* nothing (`undefined`, a function).
|
|
1155
|
+
*/
|
|
1156
|
+
function stable_json(value) {
|
|
1157
|
+
try {
|
|
1158
|
+
return JSON.stringify(value, sort_keys);
|
|
1159
|
+
} catch {}
|
|
1160
|
+
}
|
|
1161
|
+
/**
|
|
1162
|
+
* A test of whether a later input is the same as `first`, which a resume
|
|
1163
|
+
* datum taken for `first` answers as well.
|
|
1164
|
+
*
|
|
1165
|
+
* `first` is snapshotted now, as stable JSON with its keys sorted, and a
|
|
1166
|
+
* later input matches when its stable JSON is the same, so a `retry` that
|
|
1167
|
+
* reaches a step again on a copy of its input passes, while an object that
|
|
1168
|
+
* a `loop` changed in place since doesn't, since the datum answered what the
|
|
1169
|
+
* object held then. When JSON can't hold `first`, a later input matches
|
|
1170
|
+
* only when it's the same value by `Object.is`.
|
|
1171
|
+
*/
|
|
1172
|
+
function same_input_as(first) {
|
|
1173
|
+
const snapshot = stable_json(first);
|
|
1174
|
+
if (snapshot === void 0) return (next) => Object.is(next, first);
|
|
1175
|
+
return (next) => stable_json(next) === snapshot;
|
|
1176
|
+
}
|
|
1177
|
+
//#endregion
|
|
995
1178
|
//#region src/core/runner.ts
|
|
996
1179
|
/**
|
|
997
1180
|
* Runner.
|
|
@@ -1016,6 +1199,7 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
|
|
|
1016
1199
|
*/
|
|
1017
1200
|
const dispatch = /* @__PURE__ */ new Map();
|
|
1018
1201
|
const unreached_gates = /* @__PURE__ */ new Map();
|
|
1202
|
+
const taken_data = /* @__PURE__ */ new Map();
|
|
1019
1203
|
/**
|
|
1020
1204
|
* Register the dispatch handler for a step kind.
|
|
1021
1205
|
*
|
|
@@ -1086,6 +1270,20 @@ function mark_gates_reached(ctx, suspend_ids) {
|
|
|
1086
1270
|
if (unreached.size === 0) unreached_gates.delete(ctx.run_id);
|
|
1087
1271
|
}
|
|
1088
1272
|
/**
|
|
1273
|
+
* Note that a `suspend` took its resume datum for `input`. The first take of
|
|
1274
|
+
* `suspend_id` in a run keeps a test of its input. A later take on the same
|
|
1275
|
+
* input passes, since a `retry` ran the step again, and one on another input
|
|
1276
|
+
* throws `duplicate_suspend_id_error` with `reason: 'reached_twice'`, since
|
|
1277
|
+
* the run's one datum for the id answered the first.
|
|
1278
|
+
*/
|
|
1279
|
+
function note_datum_taken(ctx, suspend_id, input) {
|
|
1280
|
+
const taken = taken_data.get(ctx.run_id) ?? /* @__PURE__ */ new Map();
|
|
1281
|
+
taken_data.set(ctx.run_id, taken);
|
|
1282
|
+
const same = taken.get(suspend_id);
|
|
1283
|
+
if (same === void 0) taken.set(suspend_id, same_input_as(input));
|
|
1284
|
+
else if (!same(input)) throw new duplicate_suspend_id_error(suspend_id, "reached_twice");
|
|
1285
|
+
}
|
|
1286
|
+
/**
|
|
1089
1287
|
* Start tracking the gates a run was resumed with, the ones `resume_data`
|
|
1090
1288
|
* holds a value for. A run started without any is never replaying.
|
|
1091
1289
|
*/
|
|
@@ -1346,6 +1544,7 @@ function start_run$1(flow, input, options, high_water_mark) {
|
|
|
1346
1544
|
};
|
|
1347
1545
|
try {
|
|
1348
1546
|
throw_if_aborted(ctx);
|
|
1547
|
+
check_suspend_ids(flow);
|
|
1349
1548
|
return await dispatch_step(flow, input, ctx);
|
|
1350
1549
|
} catch (err) {
|
|
1351
1550
|
let thrown = err;
|
|
@@ -1362,6 +1561,7 @@ function start_run$1(flow, input, options, high_water_mark) {
|
|
|
1362
1561
|
} finally {
|
|
1363
1562
|
logger.record(terminal);
|
|
1364
1563
|
unreached_gates.delete(run_id);
|
|
1564
|
+
taken_data.delete(run_id);
|
|
1365
1565
|
unlink_abort();
|
|
1366
1566
|
signal_runs.delete(controller);
|
|
1367
1567
|
release_signal_handlers();
|
|
@@ -3160,8 +3360,8 @@ register_traced_kind("compose");
|
|
|
3160
3360
|
* `checkpoint(inner, { key })` checks a persistent store for a completed
|
|
3161
3361
|
* result at `key` before running `inner`. On a hit, returns the stored
|
|
3162
3362
|
* value. On a miss, runs `inner`, persists its result at `key`, and returns
|
|
3163
|
-
* it.
|
|
3164
|
-
* lookup records a `checkpoint` trajectory event with
|
|
3363
|
+
* it. A corrupted read (the store throws on `get`) is a miss by default.
|
|
3364
|
+
* Every lookup records a `checkpoint` trajectory event with
|
|
3165
3365
|
* `status: 'hit' | 'miss' | 'read_error'`.
|
|
3166
3366
|
*
|
|
3167
3367
|
* A failed write (store throws on `set`) doesn't fail the run either. It
|
|
@@ -3172,6 +3372,12 @@ register_traced_kind("compose");
|
|
|
3172
3372
|
* event and then throws the store's error, for a result that a `suspend`
|
|
3173
3373
|
* hands to an approver, which has to be the one the store kept.
|
|
3174
3374
|
*
|
|
3375
|
+
* `on_read_error: 'fail'` does the same for a failed read: it records the
|
|
3376
|
+
* `read_error` event and then throws the store's error rather than run
|
|
3377
|
+
* `inner`. A checkpoint whose result a `suspend` shows wants both, since a
|
|
3378
|
+
* resume that runs `inner` again would pass a new result through an approval
|
|
3379
|
+
* that covered the old one.
|
|
3380
|
+
*
|
|
3175
3381
|
* Wrapping an anonymous inner step throws synchronously at construction time
|
|
3176
3382
|
* with the message `checkpoint requires a named step, got anonymous`, because
|
|
3177
3383
|
* a cached result must map back to a stable, identifiable step.
|
|
@@ -3224,13 +3430,14 @@ function store_failure(status, err, meta) {
|
|
|
3224
3430
|
}
|
|
3225
3431
|
/**
|
|
3226
3432
|
* The value stored at `key` in `store`, or `undefined` on a miss, recording
|
|
3227
|
-
* exactly one `checkpoint` event so hits, misses, and
|
|
3228
|
-
*
|
|
3229
|
-
*
|
|
3230
|
-
* `
|
|
3231
|
-
*
|
|
3232
|
-
|
|
3233
|
-
|
|
3433
|
+
* exactly one `checkpoint` event so hits, misses, and read errors are all
|
|
3434
|
+
* visible in the trajectory. A stored `null` or `undefined` is a miss, which
|
|
3435
|
+
* is what lets `undefined` stand for one. A throwing `store.get` records
|
|
3436
|
+
* `status: 'read_error'` and behaves as a miss, so a broken store doesn't
|
|
3437
|
+
* fail the run, unless `fail_on_read` says to throw the store's error once
|
|
3438
|
+
* the event is recorded.
|
|
3439
|
+
*/
|
|
3440
|
+
async function look_up(store, key, meta, ctx, fail_on_read) {
|
|
3234
3441
|
try {
|
|
3235
3442
|
const value = await store.get(key);
|
|
3236
3443
|
const hit = value !== null && value !== void 0;
|
|
@@ -3242,6 +3449,7 @@ async function look_up(store, key, meta, ctx) {
|
|
|
3242
3449
|
return hit ? value : void 0;
|
|
3243
3450
|
} catch (err) {
|
|
3244
3451
|
ctx.trajectory.record(store_failure("read_error", err, meta));
|
|
3452
|
+
if (fail_on_read) throw err;
|
|
3245
3453
|
return;
|
|
3246
3454
|
}
|
|
3247
3455
|
}
|
|
@@ -3273,13 +3481,14 @@ function checkpoint(inner, config) {
|
|
|
3273
3481
|
const id = next_id();
|
|
3274
3482
|
const key_spec = config.key;
|
|
3275
3483
|
const fail_on_write = config.on_write_error === "fail";
|
|
3484
|
+
const fail_on_read = config.on_read_error === "fail";
|
|
3276
3485
|
const gates = gates_within(inner);
|
|
3277
3486
|
const run_fn = async (input, ctx) => {
|
|
3278
3487
|
const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
|
|
3279
3488
|
const store = ctx.checkpoint_store;
|
|
3280
3489
|
if (!store) return dispatch_step(inner, input, ctx);
|
|
3281
3490
|
const meta = event_meta(id, key, ctx);
|
|
3282
|
-
const cached = await look_up(store, key, meta, ctx);
|
|
3491
|
+
const cached = await look_up(store, key, meta, ctx, fail_on_read);
|
|
3283
3492
|
if (cached !== void 0) {
|
|
3284
3493
|
mark_gates_reached(ctx, gates);
|
|
3285
3494
|
return cached;
|
|
@@ -3315,6 +3524,12 @@ register_traced_kind("checkpoint");
|
|
|
3315
3524
|
* ctx)`; the result is returned. Invalid resume data throws
|
|
3316
3525
|
* `resume_validation_error` carrying the vendor-neutral issue list.
|
|
3317
3526
|
*
|
|
3527
|
+
* A run takes each id's datum once. A run that reaches the suspend again on
|
|
3528
|
+
* the same input takes it again, the way a `retry` runs a step again, and
|
|
3529
|
+
* one that reaches it on another input, in a later round of a `loop` or for
|
|
3530
|
+
* the next item of a `map`, throws `duplicate_suspend_id_error` with
|
|
3531
|
+
* `reason: 'reached_twice'`, since the datum answered the first input.
|
|
3532
|
+
*
|
|
3318
3533
|
* `deadline_ms` says how long the gate waits for its resume. The run can't
|
|
3319
3534
|
* keep a clock of its own, since it unwinds as soon as it suspends, so the
|
|
3320
3535
|
* value rides out on the `suspended_error` (and the outcome
|
|
@@ -3358,6 +3573,7 @@ function suspend(config) {
|
|
|
3358
3573
|
});
|
|
3359
3574
|
throw new suspended_error(suspend_id, { input }, void 0, deadline_ms);
|
|
3360
3575
|
}
|
|
3576
|
+
note_datum_taken(ctx, suspend_id, input);
|
|
3361
3577
|
mark_gates_reached(ctx, [suspend_id]);
|
|
3362
3578
|
const parsed = await validate_schema(resume_schema, resume_value);
|
|
3363
3579
|
if (!parsed.ok) throw new resume_validation_error(`resume data for ${suspend_id} failed validation`, parsed.issues, suspend_id);
|
|
@@ -3704,6 +3920,6 @@ function chain(input_name) {
|
|
|
3704
3920
|
}
|
|
3705
3921
|
register_traced_kind("chain");
|
|
3706
3922
|
//#endregion
|
|
3707
|
-
export {
|
|
3923
|
+
export { aborted_error as A, STEP_KINDS as B, durable as C, same_input_as as D, run as E, gate_result_error as F, resolve_display_name as H, resume_validation_error as I, run_not_found_error as L, duplicate_suspend_id_error as M, error_path as N, describe as O, flow_changed_error as P, suspended_error as R, suggest_step_id as S, validate_schema as T, is_step_kind as V, parallel as _, suspend as a, assert_valid_step_id as b, loop as c, retry as d, compute_backoff as f, branch as g, map as h, use as i, describe_cycle_error as j, is_step as k, timeout as l, pipe as m, scope as n, checkpoint as o, wait_with_abort as p, stash as r, compose as s, chain as t, fallback as u, sequence as v, format_schema_issues as w, is_valid_step_id as x, step as y, timeout_error as z };
|
|
3708
3924
|
|
|
3709
|
-
//# sourceMappingURL=core-
|
|
3925
|
+
//# sourceMappingURL=core-Dwir3pkb.js.map
|