Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -555,8 +555,8 @@ budgets before every model call. The OpenAI-compatible adapter also refreshes
finite time-budget reminders before each request. The core supplies optional
`request.deadlines` on the `performance.now()` clock for adapters to calculate
remaining node and shared graph time. Reminders do not extend hard limits or
interrupt a model response already in progress. The core API's default timeouts
remain 60 seconds per node and 5 minutes per graph.
interrupt a model response already in progress. The core API sets no node or
graph timeout unless you pass one.

## Results, timeouts, and accounting

Expand Down Expand Up @@ -585,9 +585,12 @@ its successors wait until it is resumed, with a new time budget, or cancelled wi
`cancelExecutions`. See [pausing on node timeout](docs/execution-control.md#pausing-on-node-timeout).
Otherwise, and always with `braid()` or `onNodeTimeout: "fail"`, a node timeout
marks the running node `failed: NODE_TIMEOUT`; unconditional successors can
consume its error and partial workspace. A graph timeout marks running nodes `failed: GRAPH_TIMEOUT`,
skips queued/pending nodes with `graph_timeout`, and retains already completed
terminal outputs. Timers are cleared when no longer needed.
consume its error and partial workspace. A graph timeout pauses a `startBraid`
run and its running executions until `setLimits` raises it (see
[limits](docs/execution-control.md#limits)). With `braid()` or `onLimit: "fail"`,
it marks running nodes `failed: GRAPH_TIMEOUT`, skips queued/pending nodes with
`graph_timeout`, and retains already completed terminal outputs. Timers are
cleared when no longer needed.

Timeouts abort the invocation signal and stop waiting for the model even if it
ignores cancellation. Workspace setup, tracked writes, and cleanup are awaited
Expand Down Expand Up @@ -649,14 +652,16 @@ scheduler event bus.

Out of scope: cycles not closed by a decision's choice edge, nested/overlapping cycles, arbitrary
code nodes, durable workflow recovery, saved templates, a graphical editing UI,
and recursive Braid calls from model nodes.
and recursive Braid calls from model nodes. The RSI Mode and Zen Mode milestones
revisit some of these boundaries; see [ROADMAP.md](ROADMAP.md#milestones).

## Releases and upgrades

The 0.5 API is experimental. See [GitHub releases](https://github.com/Epsirom/braid/releases)
for release and upgrade notes.

- Upgrading from 0.4: read the [0.4 → 0.5 migration guide](docs/compatibility.md#migrating-from-04-to-05).
- Upgrading from 0.5: read the [0.5 → 0.6 migration guide](docs/compatibility.md#migrating-from-05-to-06).
- Upgrading from 0.4: also follow the [0.4 → 0.5 migration guide](docs/compatibility.md#migrating-from-04-to-05).
- Upgrading from 0.3: also follow the [0.3 → 0.4 migration guide](docs/compatibility.md#migrating-from-03-to-04).
- Upgrading from 0.2: also follow the [0.2 → 0.3 migration guide](docs/compatibility.md#migrating-from-02-to-03).
- Upgrading from 0.1: also follow the [0.1 → 0.2 guide](docs/compatibility.md#migrating-from-01-to-02).
Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ pauses, reminders) instead of hard limits that fail the job. Tracking issue:

- [x] Default every limit to unlimited, and hold or pause instead of failing
when a limit that is set is reached ([#112](https://github.com/Epsirom/braid/issues/112)).
- [ ] Replace the schedule/execution split with an execution-only graph of
- [x] Replace the schedule/execution split with an execution-only graph of
lineages, where a started node is changed by replacing it ([#113](https://github.com/Epsirom/braid/issues/113)).
- [ ] Accept unconditional, nested, and overlapping cycles ([#114](https://github.com/Epsirom/braid/issues/114)).
- [ ] Show lineage heads and the full execution history in one Pi graph ([#94](https://github.com/Epsirom/braid/issues/94)).
Expand Down
16 changes: 9 additions & 7 deletions docs/resource-limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,20 @@ well as the compact definition.
| --- | --- | --- |
| Active runtime-managed invocations per graph | 4 | 4 |
| Started and skipped executions across rounds/updates | Unlimited (`maxExecutions`) | Unlimited (`maxExecutions`) |
| Node timeout (starts at admission, stops while suspended) | 60 seconds | Unlimited |
| Node timeout (starts at admission, stops while suspended) | Unlimited | Unlimited |
| On node timeout (`onNodeTimeout`) | Pause with `startBraid` and an interruptible runner; fail with `braid()` | Pause; the parent gets a reminder to resume or cancel |
| Graph timeout (includes queueing, paused gates, and suspensions) | 5 minutes | Unlimited |
| Graph timeout (includes queueing, paused gates, and suspensions) | Unlimited | Unlimited |
| On reaching a limit that is set (`onLimit`) | Pause with `startBraid` (hold the decision at an edge `limit`, or pause the run); fail with `braid()` | Pause; the parent gets a reminder to raise the limit or stop |
| Caller cancellation | `AbortSignal`; `cancelExecutions` for single executions | `braid_cancel` / panel `c`; `braid_cancel` with `executionIds` / panel `x` |
| Pause running work | `pause` / `pauseRun` | `braid_pause` / panel `p` |
| Worker tool loop | Decision continuation / merge Git-tool loop, bounded by deadlines | Unlimited by default; optional `maxToolRounds` and `maxToolCalls` |
| Transient model error retries | Runner-defined | 3 per model request (`maxModelRetries`), within the current execution |
| Result preview | Full result | 50 KB / 2,000 lines of text, then temporary full-text file |
| Token / monetary budget | Not enforced | Not enforced |
| Token budget | Unlimited (`maxTokens`, checked as executions settle) | Unlimited (`maxTokens`) |
| Monetary budget | Not enforced | Not enforced |

Pi keeps unlimited timeouts for interactive background work. For bounded work,
submit explicit `options`, for example:
Core and Pi set no time, execution, or token limit by default, which suits
background work. For bounded work, submit explicit `options`, for example:

```json
{ "maxConcurrency": 2, "nodeTimeoutMs": 30000, "graphTimeoutMs": 120000, "maxToolRounds": 12, "maxToolCalls": 32 }
Expand All @@ -43,8 +45,8 @@ after validation; it does not bound validation CPU or input allocation.

Token counts report only usage returned by runners. Missing counts, failed
requests, or timeout-aborted calls can still incur charges. There is no hard cost
ceiling, and adding a token counter after completion cannot prevent concurrent
calls from overspending. Use provider account quotas, output-token limits in a
ceiling: `maxTokens` counts reported usage as executions settle, so it cannot
prevent running or concurrent calls from overspending. Use provider account quotas, output-token limits in a
custom runner, host admission controls, and finite deadlines where needed.

All events and full results live in memory; handoff events retain output for each
Expand Down
Loading