foldrun 14.0.7 → 14.1.1

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/bin/foldrun.mjs CHANGED
@@ -127,7 +127,7 @@ const HELP = `foldrun — agents are just folders
127
127
  foldrun flow run <flow> start a flow on the platform — the same command as invoke
128
128
  foldrun flow hook <flow> the flow's webhook URL as it is now, changing nothing (--json) — the URL is a credential
129
129
  foldrun flow rotate-hook <flow> a new webhook URL for a flow; the old one stops at once — asks first, --yes means it
130
- foldrun flow set <flow> --step <n|agent> key=value … the step editor: model, effort, retry, timeout, verify, when, case, else, loop, until, each, max, limits, instruction (key= clears) — diff, checked, --dry-run
130
+ foldrun flow set <flow> --step <n|agent> key=value … the step editor: model, effort, max_output_tokens, retry, timeout, verify, when, case, else, loop, until, each, max, limits, instruction (key= clears) — diff, checked, --dry-run
131
131
  foldrun flow trigger <flow> manual|webhook|schedule the trigger picker (--schedule "<cron>", --timezone <zone>) — diff, checked, --dry-run
132
132
  foldrun flow compute <flow> vcpu <n> memory <GiB> disk <GiB> what one run may hold at once across its steps (its compute:) — any of them, --clear for none
133
133
  foldrun flow filter <flow> --payload <file|-|json> would this delivery start it? its filter: and the condition that held it back (--to <ws>: the deployed flow); exit 1 when not
package/docs/agents.md CHANGED
@@ -71,6 +71,7 @@ refused. See [The four jobs](four-jobs).
71
71
  |---|---|---|
72
72
  | `model` | `fast` \| `default` \| `max`, an alias (`opus`), or a full id | a **tier**, so agents don't rot when models are renamed. Synonyms land on their tier: `small`/`cheap` → fast, `large`/`best` → max |
73
73
  | `effort` | `low` \| `medium` \| `high` \| `xhigh` \| `max` | how long it thinks before answering. Unset leaves the model's own default |
74
+ | `max_output_tokens` | a whole number, 1 to 1048576 | the longest one model reply may be, in tokens — on every provider, each under its own name. Lower keeps replies short, cheap and quick; higher lets an agent that writes long documents finish one in a reply. A flow or a step may set its own. On [foldrun's models](providers#foldruns-models) the price list's ceiling for the model applies too (the lower wins; above it is a [check warning](checks#config-output-fitted)); unset there is the ceiling, and elsewhere the runtime's default |
74
75
  | `budget` | a number in USD | the most this agent may spend in **one run**, across every step it takes in it. Its step stops mid-turn at what is left; a later step of its own in the same run is refused before it starts. Unset is no limit. Per run only — a cap over a day, week or month belongs in `AGENTS.md` |
75
76
 
76
77
  The two are orthogonal — the model is which brain, effort is how long it
package/docs/checks.md CHANGED
@@ -401,6 +401,15 @@ place in `@foldrun/core` (`frontmatter-fields.ts`). The editor's completions
401
401
  come from the same list, so what the editor suggests and what `check`
402
402
  accepts cannot drift apart.
403
403
 
404
+ ### config/output-fitted
405
+
406
+ *warn, online only.* A `max_output_tokens:` (an agent's, a flow's default
407
+ or one step's) above the price list's ceiling for the model that step runs on
408
+ [foldrun's models](providers#foldruns-models). The step still runs, with the
409
+ ceiling as its limit, and its log says so. Write a number at or under the
410
+ ceiling, or run the agent on your own key. Checked the way
411
+ [config/effort-fitted](#config-effort-fitted) is.
412
+
404
413
  ### config/cron-never-fires
405
414
 
406
415
  *warn.* A `schedule:` the scheduler can read but whose day never comes:
package/docs/cli.md CHANGED
@@ -56,7 +56,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
56
56
  | `foldrun flow run <flow>` | start a flow on the platform — the same command as `invoke`, spelled the way `agent run` is. `foldrun run` runs HERE; `flow run`/`invoke` run a flow on the platform; `agent run` runs one agent there |
57
57
  | `foldrun flow hook <flow>` | the flow's webhook URL as it is now (`GET …/hooks/<flow>`), changing nothing — `--json` prints `{ flow, url, path }`. Needs `workspace:manage`, like the settings page that shows it; the URL is a credential |
58
58
  | `foldrun flow rotate-hook <flow>` | a new webhook URL for the flow (`POST …/hooks/<flow>/rotate`). The old URL stops working the moment it returns, so it asks first — `--yes` with no terminal. Prints the new URL, which is itself a credential |
59
- | `foldrun flow set <flow> --step <n\|agent> key=value …` | the step editor on the Flows page, from a terminal (core's `updateFlowStep`, and `updateFlowStepInstruction` for `instruction=`): `model`, `effort`, `retry`, `timeout`, `verify`, `when`, `case`, `else`, `loop`, `until`, `each`, `max`, `limits` — only the keys named are touched, `key=` clears one. `each=` takes `lines` only; the other fan-outs are `flow add … fan-out`. A value the rewriter would drop or clamp is refused, nothing written: `effort` one of low, medium, high, xhigh, max (or an alias core reads, e.g. `deep`); `timeout` a whole number of seconds (`timeout=900`, not `15m`); `retry` 0–5, `loop` 1–5, `max` 1–20, whole numbers. Shows the diff, refuses an edit `check` would call a new error, `--dry-run` writes nothing; `--to <workspace>` sends the editor's `PATCH …/flows/<flow> { step, options }` / `{ step, instruction }` with `expect` |
59
+ | `foldrun flow set <flow> --step <n\|agent> key=value …` | the step editor on the Flows page, from a terminal (core's `updateFlowStep`, and `updateFlowStepInstruction` for `instruction=`): `model`, `effort`, `max_output_tokens`, `retry`, `timeout`, `verify`, `when`, `case`, `else`, `loop`, `until`, `each`, `max`, `limits` — only the keys named are touched, `key=` clears one. `each=` takes `lines` only; the other fan-outs are `flow add … fan-out`. A value the rewriter would drop or clamp is refused, nothing written: `effort` one of low, medium, high, xhigh, max (or an alias core reads, e.g. `deep`); `max_output_tokens` a whole number of tokens, 1 to 1048576; `timeout` a whole number of seconds (`timeout=900`, not `15m`); `retry` 0–5, `loop` 1–5, `max` 1–20, whole numbers. Shows the diff, refuses an edit `check` would call a new error, `--dry-run` writes nothing; `--to <workspace>` sends the editor's `PATCH …/flows/<flow> { step, options }` / `{ step, instruction }` with `expect` |
60
60
  | `foldrun flow trigger <flow> manual\|webhook\|schedule` | the trigger picker on a flow card (core's `setFlowTrigger`): only the `trigger:`, `schedule:` and `timezone:` lines change. `--schedule "0 9 * * 1"` (5 fields, or `@daily`) and `--timezone <zone>` go with `schedule`. Diff, checked, `--dry-run`; `--to` sends `PATCH { trigger }` |
61
61
  | `foldrun flow compute <flow> vcpu <n> memory <GiB> disk <GiB>` | what one run of the flow may hold at once across its parallel steps — its `compute:` — any of the three, merged over what is set; `--clear` for no cap of its own. With `--to`, the flows route's `{ compute }` (the flow card's control); without, the flow file's frontmatter ([four levels](budgets-and-billing#compute-at-four-levels)) |
62
62
  | `foldrun flow filter <flow> --payload <file\|-\|json>` | would this delivery start the flow? Its `filter:` against a payload — a webhook's JSON body, an email's `{ from, to, subject, text }`, a chained run's `{ run, flow, status, ending, verdict, summary }`, a storage event's `{ by, paths }` — and the condition that held it back. Reads the local flow; `--to <workspace>` asks the deployed one (`POST …/flows/<flow>/filter`, the Triggers page's Test box). Starts nothing; exits `0` when it would start a run, `1` when not; `--json` for the whole answer |
package/docs/flows.md CHANGED
@@ -106,6 +106,7 @@ begins.
106
106
  | `schema:` | with `output: json` — the JSON Schema the value must satisfy: one-line JSON, a YAML block under the key, or a file under the workspace |
107
107
  | `model:` | override the tier for this step |
108
108
  | `effort:` | override how hard it thinks for this step |
109
+ | `max_output_tokens:` | the longest one model reply may be for this step, in tokens — over the flow's and the agent's |
109
110
  | `retry:` | attempts after the first, clamped to 5. Each retry waits — 15 s, 30 s, 1 m, 2 m, 4 m, jittered — holding no sandbox while it waits; a stop ends the wait. An attempt the cluster ended for want of memory or disk (OOMKilled, Evicted) is retried one `size:` class up. A step refused because the model usage cap is reached is not retried: the window resets in hours, not within the waits. An `outward` step whose check failed after its tools ran is not retried — the retry would send again; `check` and `deploy` warn on `retry:` on an outward step, because a failure mid-send is still retried |
110
111
  | `timeout:` | seconds, or `90s` / `15m` / `4h` / `3d` — **the only clock there is** |
111
112
  | `max_turns:` | the most model turns before the step is stopped (1 to 500) — the third bound beside `budget:` and `timeout:` |
@@ -331,6 +332,7 @@ normal outcome, recorded as one.
331
332
  | `signature` / `signing_secret` | `github` \| `stripe` \| `slack` \| `hmac`, and the NAME of the vault entry to check it against — never the value (`foldrun check` warns: [secret/signing-secret-value](checks#secret-signing-secret-value)) |
332
333
  | `filter` | for a `webhook`, `email`, `flow` or `storage` trigger: the fields a delivery must have to start a run — see [Which deliveries start a run](#which-deliveries-start-a-run) |
333
334
  | `model` / `effort` | defaults for every step |
335
+ | `max_output_tokens` | every step's longest reply, in tokens, unless the step says (over the agent's) |
334
336
  | `budget` | the most one run may spend, in USD — a number, or `unlimited`; unset is no limit |
335
337
  | `compute` | what one run's steps may hold together at once — `{ vcpu: 2, memory: 4Gi, disk: 20Gi }`, any of them. Each run has its own; it only narrows the workspace's and account's. A step past it waits for one of its run's steps to finish; one bigger than it fails at once ([four levels](budgets-and-billing#compute-at-four-levels)) |
336
338
  | `overlap` | `skip` or `queue` when a run is already live |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "14.0.7",
3
+ "version": "14.1.1",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^14.3.0"
14
+ "@foldrun/core": "^14.3.1"
15
15
  },
16
16
  "files": [
17
17
  "bin",
package/src/commands.mjs CHANGED
@@ -295,6 +295,7 @@ const KEY_NOTES = {
295
295
  ["description", "one line; what this role is for"],
296
296
  ["model", "fast | default | max — tier the work, not the desk"],
297
297
  ["effort", "low | high — how hard to think about it"],
298
+ ["max_output_tokens", "the longest one reply may be, in tokens"],
298
299
  ["tools", "the one grant list: built-ins and your own tools/"],
299
300
  ],
300
301
  flows: [
@@ -11140,7 +11141,7 @@ function sameFlow(a, b) {
11140
11141
  }
11141
11142
 
11142
11143
  /** The step options the dashboard's step editor writes (core updateFlowStep). */
11143
- const STEP_OPTION_KEYS = ["model", "effort", "retry", "timeout", "verify", "when", "case", "else", "loop", "until", "each", "max", "limits"];
11144
+ const STEP_OPTION_KEYS = ["model", "effort", "max_output_tokens", "retry", "timeout", "verify", "when", "case", "else", "loop", "until", "each", "max", "limits"];
11144
11145
 
11145
11146
  /**
11146
11147
  * `foldrun flow set <flow> --step <n|agent> key=value …` — the step editor on
@@ -11177,6 +11178,7 @@ async function flowSetCmd(positional, flags, layout) {
11177
11178
  if (key === "each" && value && value !== "lines") throw new Error(`each=${value}: flow set writes \`each: lines\` only — \`foldrun flow add <flow> fan-out --each "${value}"\` writes the rest`);
11178
11179
  if (key === "else" && value && !["true", "1"].includes(value)) throw new Error("else=true, or else= to clear it");
11179
11180
  if (key === "effort" && value && !resolveEffort(value)) throw new Error(`effort=${value} is not an effort — ${EFFORT_LEVELS.join(", ")} (or effort= to clear it)`);
11181
+ if (key === "max_output_tokens" && value && !(/^\d+$/.test(value) && Number(value) >= 1 && Number(value) <= 1048576)) throw new Error(`max_output_tokens=${value} is not a number of tokens, 1 to 1048576 (or max_output_tokens= to clear it)`);
11180
11182
  if (key === "timeout" && value && !/^[1-9]\d*$/.test(value)) {
11181
11183
  const secs = parseDuration(value);
11182
11184
  throw new Error(`timeout=${value}: flow set writes a whole number of seconds — ${secs ? `timeout=${secs}` : "e.g. timeout=900 for 15 minutes"} (or timeout= to clear it)`);