@parcha/agentrun-pi 0.1.0-beta.5 → 0.1.0-beta.9

package/dist/extension-service.js

@@ -54,8 +54,10 @@ async function withAdapterDiagnostic(stage, run) {
                 if (error.code === 'http') {
                     if (Number.isInteger(error.status) && error.status >= 100 && error.status <= 599)
                         diagnostic.status = error.status;
-                    if (reason === 'max_tokens_exceeded')
+                    if (reason === 'max_tokens_exceeded') {
                         diagnostic.reason = reason;
+                        diagnostic.message = 'Jev refused the request: it exceeds the model\'s token budget. Send fewer or shorter items per request. No judgment was accepted; provider details are omitted.';
+                    }
                 }
             }
         }
@@ -124,7 +126,7 @@ function localDiagnostic(error) {
             && stateBytes > maxStateBytes && maxStateBytes > 0)
             return {
                 code: 'jev_state_too_large', stage, stateBytes, maxStateBytes,
-                message: `Jev state at ${stage} is ${stateBytes} UTF-8 bytes; configured host limit is ${maxStateBytes}. No request was sent. A sift batches every item in one state; select original context explicitly or use per-item judgments without losing headers or qualifiers.`
+                message: `Jev state at ${stage} is ${stateBytes} UTF-8 bytes; configured host limit is ${maxStateBytes}. No request was sent. A sift splits its items across requests only when the host sets maxStateBytesPerRequest; otherwise send less of each item or use per-item judgments without losing headers or qualifiers.`
             };
         if (reason === 'invalid_state' || reason === 'invalid_questions')
             return { code: `jev_${reason}`, stage,
@@ -361,11 +363,36 @@ export class WorkflowExtensionService {
                 queue.shift()?.();
             }
         };
+        const rejectTrace = (error) => {
+            rejectedEvents++;
+            traceTruncated = true;
+            if (!signal.aborted) {
+                // Snapshot rejects unsafe/non-JSON values separately from resource bounds.
+                // Keep fail-closed cancellation; never echo values or arbitrary error text.
+                const diagnostic = error instanceof ExtensionServiceError && error.code === 'data'
+                    ? new ExtensionServiceError('trace_invalid_data', 'Workflow trace contains non-JSON data. Numbers must be finite; objects and arrays must be plain, acyclic and free of accessors or symbols.')
+                    : error instanceof ExtensionServiceError && error.code === 'bounds'
+                        ? new ExtensionServiceError('limit', 'Workflow trace exceeded its JSON byte, depth or value-count limit.')
+                        : new ExtensionServiceError('trace_capture_failed', 'Workflow trace capture failed. Unsafe event details are omitted.');
+                controller.abort(diagnostic);
+            }
+        };
+        const prepareEvent = (event) => {
+            if (closed)
+                return { type: event.type, label: event.label };
+            try {
+                return snapshot(event, this.limits.maxEventBytes);
+            }
+            catch (error) {
+                rejectTrace(error);
+                return undefined;
+            }
+        };
         const onEvent = (event) => {
             if (closed)
                 return;
             try {
-                const clean = sanitize(snapshot(event, this.limits.maxEventBytes));
+                const clean = sanitize(event);
                 const size = Buffer.byteLength(JSON.stringify(clean));
                 if (size > this.limits.maxEventBytes)
                     throw new ExtensionServiceError('bounds', 'Workflow event exceeds its serialized byte limit.');
@@ -405,26 +432,17 @@ export class WorkflowExtensionService {
                 }
             }
             catch (error) {
-                rejectedEvents++;
-                traceTruncated = true;
-                if (!signal.aborted) {
-                    // Snapshot rejects unsafe/non-JSON values separately from resource bounds.
-                    // Keep fail-closed cancellation; never echo values or arbitrary error text.
-                    const diagnostic = error instanceof ExtensionServiceError && error.code === 'data'
-                        ? new ExtensionServiceError('trace_invalid_data', 'Workflow trace contains non-JSON data. Numbers must be finite; objects and arrays must be plain, acyclic and free of accessors or symbols.')
-                        : error instanceof ExtensionServiceError && error.code === 'bounds'
-                            ? new ExtensionServiceError('limit', 'Workflow trace exceeded its JSON byte, depth or value-count limit.')
-                            : new ExtensionServiceError('trace_capture_failed', 'Workflow trace capture failed. Unsafe event details are omitted.');
-                    controller.abort(diagnostic);
-                }
+                rejectTrace(error);
             }
         };
         const sections = Object.entries(this.rubricSections);
         const deps = {
-            signal, onEvent,
+            signal, onEvent, prepareEvent,
             ...(options.deps.skill ? { skill: options.deps.skill } : {}),
             ...(sections.length ? { sop: sections.map(([name, text]) => `## ${name}\n${text}`).join('\n\n') } : options.deps.sop ? { sop: options.deps.sop } : {}),
-            ...(options.deps.maxQuestionsPerRequest ? { maxQuestionsPerRequest: options.deps.maxQuestionsPerRequest } : {}),
+            // Forward any set limit, so the interpreter rejects an invalid one rather than running without it.
+            ...(options.deps.maxQuestionsPerRequest !== undefined ? { maxQuestionsPerRequest: options.deps.maxQuestionsPerRequest } : {}),
+            ...(options.deps.maxStateBytesPerRequest !== undefined ? { maxStateBytesPerRequest: options.deps.maxStateBytesPerRequest } : {}),
             ...(options.deps.runNode ? { runNode: params => dispatch('agent', params.signal, () => withAdapterDiagnostic(params.label, () => options.deps.runNode({ ...params, tools: params.tools ?? [...this.allowedTools] })), true) } : {}),
             ...(options.deps.runJudge ? { runJudge: params => dispatch('judge', params.signal, () => withAdapterDiagnostic(params.label, () => options.deps.runJudge(params)), true) } : {}),
             ...(options.deps.runEffect ? { runEffect: params => dispatch('tool', params.signal, () => {

package/dist/runner.js

@@ -70,6 +70,9 @@ export function createPiRunner(options) {
         for (const name of requested)
             if (!names.has(name))
                 throw new Error(`Pi tool was not explicitly registered: ${name}`);
+        // Every Pi node starts a fresh session, so there is no caller transcript to fork.
+        if (request.context === "fork")
+            throw new Error(`Pi node "${request.label}" asks for context: "fork", but the Pi runner starts every node in a fresh session and has no caller transcript to fork. Declare context: "fresh", or run it on a host that supports fork.`);
         const validator = Compile(request.schema);
         const parameters = submitParameters(request.schema);
         const envelopeValidator = Compile(parameters);

package/dist/skills/author/references/language.md

@@ -20,14 +20,14 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
 This is the complete set. Each kind accepts exactly these fields; any other field is an error.
 - `chain`: `steps`
 - `code`: `label`, `code`, `as`
-- `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
+- `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `budget_usd`, `context`
 - `decide`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
 - `extract`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
 - `report`: `label`, `state`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
 - `artifact`: `label`, `state`, `type`, `path`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
 - `map`: `label`, `itemsPath`, `body`, `as`, `resultPath`, `maxConcurrency`
 - `parallel`: `label`, `branches`
-- `loop`: `label`, `body`, `until`, `maxIters`
+- `loop`: `label`, `body`, `until`, `maxIters`, `expect_iters`
 - `escalate`: `label`, `when`, `kind`, `stage`, `summary`
 - `call`: `label`, `via`, `tool`, `args`, `code`, `input`, `command`, `env`, `where`, `out`, `as`, `produces`, `deadline_s`, `retry`, `poll`, `requires`
 - `workflow`: `label`, `workflow`, `input`, `out`, `as`
@@ -51,9 +51,10 @@ Their fields:
 - `out` names the schema the submission must satisfy; the value lands at `as`.
 - `requires` lists state paths that must hold evidence before the node runs, each produced upstream: missing values, null, blank strings, empty arrays and empty objects stop the run; `false` and `0` pass.
 - `tools` names tools the host offers. `[]` means no tools; omitting `tools` offers every tool the host allows. Never name a tool the host did not offer.
-- `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's, and nodes carry no budgets.
+- `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's.
+- An `agent` node may carry `budget_usd`, the most it asks to spend in dollars (above 0), which the host caps by what it has left, and `context`, fresh|fork: `fresh` (the default) sees only its instructions and state; `fork` asks the host to start it from the caller's transcript, which a host refuses where it has none.
 - `sopSection` names one heading of the host's SOP, or a list of them, as the exact text after "## ". The node receives those sections verbatim.
-- `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: 1..4 (default 2), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below `override.below`; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
+- `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: an integer >= 1 (default 2, no maximum), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below `override.below`; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
 - When the workflow has a report, no decide or extract `out` schema carries `report_markdown`.
 
 ### Terminal nodes: report and artifact
@@ -68,7 +69,7 @@ Typed questions answered by the host's judge in one request each: no tools, no s
 - A question schema is a flat object. Each property's `description` is its question. A boolean yields a yes-probability; a string enum (at most 240 options, optional per-option `criteria`) yields a choice; an integer with `criteria`: [level descriptions] (2 to 10 levels, minimum 0, maximum the last level index) yields a score. Nothing else is a question.
 - `judge`: a non-empty `state` map, `out` (a question schema) and `as`. The decoded value lands at `as`, the raw answers at `<as>$answers`.
 - `pick`: `itemsPath`, `describe` (the option text per item, such as "{item.name}"), `instructions` (the one question) and `as`; `allowNone` adds a none-of-these option. The result is {index, item, none, option}.
-- `sift`: `itemsPath`, `out` (a question schema asked of every item in one request) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
+- `sift`: `itemsPath`, `out` (a question schema asked of every item; the host splits the items across requests when they exceed its limits) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
 - `route`: a non-empty `state` map, `instructions` (the one question) and 2 to 240 named `branches`, each {criteria?, body}. `unsure` {branch: one of the branches, gte: a number in (0, 1]} takes that branch when the choice's confidence is below `gte`. `as` records the choice.
 - A decoded boolean is true at yes-probability 0.5. To hold a different threshold, read `<as>$answers.answers.<id>.noul` in a code node.
 
@@ -77,21 +78,22 @@ Typed questions answered by the host's judge in one request each: no tools, no s
 - `chain`: non-empty `steps`, run in order.
 - `map`: `itemsPath` (an upstream list), `body` and `as`. The body sees `item` and `item_index`; `maxConcurrency` is a positive integer (default 4); `resultPath` selects one path from each completed item's state.
 - `parallel`: at least two `branches`, each starting from the state before the parallel node. Branches write disjoint keys and never read a sibling's writes.
-- `loop`: `body`, `until` (a predicate) and an integer `maxIters` from 1 to 20. At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
+- `loop`: `body`, `until` (a predicate) and an integer `maxIters` of at least 1 (no maximum), optionally an integer `expect_iters` of at least 1 (priced passes). At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
 - `escalate`: `when` (a predicate), and non-empty `kind`, `stage` and `summary`. When the predicate holds the run stops without output and returns the escalation with its interpolated summary.
 - `workflow`: `label`, `workflow` (a complete inline child), `input` (an object, interpolated, the child's entire initial state), `out` (a parent schema checked against the child's output) and `as`. The child declares `input.schemaId` in its own schemas and contains no report or artifact.
 - `code`: `code` is one synchronous function expression such as "(s) => ({ total: s.items.length })". It receives the full state; return new values and never mutate it. `Date`, `Promise`, timers, `fetch`, `require`, `process`, `Function` and `globalThis` are unavailable. It is trusted host JavaScript, not a sandbox. Use code for typed-state mechanics, never to read meaning from prose.
-- `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (greater than 0, at most 3600) are required.
+- `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (a finite number greater than 0, no maximum) are required — an unbounded effect is how a stalled provider becomes a stalled job.
   - `via: tool` takes `tool` (a host tool address), `args` (an object) and `out` (the tool's result schema).
   - `via: executor` takes `code` (a body that returns its JSON result and uses only `tools` and `input`), `input` and `out`.
   - `via: shell` takes `command` (literal) and `env` (UPPER_CASE names to strings, interpolated by value; the way long values reach a command). Its result has the fixed shape {code, stdout, stderr, truncated?}: no `out`. Only a shell call may declare `produces` (workspace-relative files, checked after the effect).
-  - `retry` {attempts: 1..5, backoff_s?: 0..60, on?: [timeout, http_5xx, http_429, connection, exit]}. `where` accepts only "sandbox".
-  - `poll` {until, fail_when?, interval_s: 0.1..300, deadline_s: from the call's deadline_s to 7200} repeats the call until `until` holds on its own result; `fail_when` fails it at once. Both are mechanical predicates whose paths are relative to the result and lie in its declared shape.
+  - `retry` {attempts: an integer >= 1, backoff_s?: a number >= 0, on?: [timeout, http_5xx, http_429, connection, exit, effect_timeout, effect_exit, effect_transport, effect_not_granted, effect_produces_missing, effect_path_escape, effect_code_unsafe, output_invalid, state_invalid, effect_unknown_transport]}. `where` accepts only "sandbox".
+  - `poll` {until, fail_when?, interval_s: >= 0.1 (a busy-loop guard), deadline_s: at least the call's deadline_s (no maximum)} repeats the call until `until` holds on its own result; `fail_when` fails it at once. Both are mechanical predicates whose paths are relative to the result and lie in its declared shape.
   - Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
 
 ## Predicates
 
 `loop.until` and `escalate.when` take one of these; `poll` takes only the first 8. Each path or key reads a state value an input or an earlier node produced.
+A predicate is one JSON object that names itself in its `predicate` field beside its own fields, for example `{"predicate": "field_true", "path": "review.approved"}`.
 - `field_equals` {path, value}: holds when the value at `path` equals `value` (a string, number or boolean)
 - `field_true` {path}: holds when the value at `path` is `true`
 - `in` {path, values}: holds when the value at `path` is one of `values` (a non-empty list of strings, numbers or booleans)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parcha/agentrun-pi",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.9",
   "description": "Pi extension for building, running and evaluating AgentRun workflows",
   "type": "module",
   "license": "Apache-2.0",
@@ -35,8 +35,8 @@
     "@earendil-works/pi-ai": "0.87.0"
   },
   "dependencies": {
-    "@parcha/agentrun-dsl": "0.1.0-beta.5",
-    "@parcha/agentrun-jev": "0.1.0-beta.5",
+    "@parcha/agentrun-dsl": "0.1.0-beta.9",
+    "@parcha/agentrun-jev": "0.1.0-beta.9",
     "@earendil-works/pi-agent-core": "0.87.0",
     "@earendil-works/pi-coding-agent": "0.87.0",
     "@earendil-works/pi-tui": "0.87.0",