@parcha/agentrun-dsl 0.1.0-beta.34 → 0.1.0-beta.36

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/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Typed workflows that your agent writes. It drafts a workflow, checks it, dry-runs it for free, then runs it; `@parcha/agentrun-dsl/graph` turns the workflow into its graph. The core provides the v2 workflow types, validator, interpreter, events, schema, and an offline CLI. Supply agent, judgment, and effect functions only when a workflow needs them.
4
4
 
5
- Beta, on npm under the `latest` dist-tag (`npm view @parcha/agentrun-dsl dist-tags`). Requires Node 22.19+; TypeScript consumers require TypeScript 5.4+.
5
+ Beta, on npm under the `latest` dist-tag (`npm view @parcha/agentrun-dsl dist-tags`). Requires Node 24.22.3+; TypeScript consumers require TypeScript 5.4+.
6
6
 
7
7
  ```sh
8
8
  npm install @parcha/agentrun-dsl@latest
@@ -174,8 +174,8 @@ The package root exports a deliberate API. The beta retains agent, structured-ou
174
174
  | Build judgment adapters | `compileQuestions`, `validateAnswers`, `answersToValue`, `answersSidecar`, `answerConfidence`, `deriveConfidence`, `completeConfidence`, `refusedQuestions`, `SYSTEM_ONE_LIMITS`, `SystemOneError`; `SystemOneQuestion`, `SystemOneAnswer`, `SystemOneResult`, `SystemOneRetryClass`, `CompiledQuestions`, `AnswersSidecar`, `ConfidenceSource`. |
175
175
  | Plug in a decision model | `judgeFromProvider` (a `DecisionProvider` as `runJudge`), `checkCapabilities`, `DecisionProviderError`; `DecisionProvider`, `DecisionCapabilities`, `DecisionRequest`, `DecisionContext`, `DecisionOutcome`, `DecisionEvidence`, `ProviderAnswer`, `CostBasis`. `@parcha/agentrun-dsl/testing` has `registerDecisionProviderConformance`, the suite a provider's own tests register: exact answers, a null cost never read as 0, typed errors, abort and deadline, no key in what it returns or throws, its declared limits refused before sending, a refusal kept as one. Jev's provider is `jevProvider` in `@parcha/agentrun-jev`; Parallel's is in `@parcha/agentrun-decisions`. |
176
176
  | Integrate a host | `runWorkflowSlice`, `assertWorkflowCapabilities`, `desugarWorkflow`, `resolveSchemaForWorkflow`, `stageSchemaForNode`, `submissionSchemaForNode`, `mergeStageDelta`, `REPORT_SCHEMA`, `SHELL_RESULT_SCHEMA`, `getPath`, `predicateMatches`, `deniedGlobalReferences`. |
177
- | Author workflows | `authorContract`, `renderAuthorContract` (text and sha256), `renderAuthorHostAddendum`, `authorWorkflow`, `candidatePolicyErrors`, `applyHostOutputTypes`, `AUTHOR_SKILL_NAME`, `authorSkillDirectory`, `loadAuthorReference`, `loadAuthorSkillBundle`; `AuthorHostAddendum`, `AuthorWorkflowOptions`, `AuthoredWorkflow`, `CandidatePolicyOptions`. The one author contract and its packaged skill (`skills/author`); a host adds only an addendum. See [the author contract](../../docs/authoring.md#one-author-contract). |
178
- | Language vocabulary | `WORKFLOW_NODE_KINDS`, `GENERATIVE_NODE_KINDS`, `JUDGMENT_NODE_KINDS`, `NODE_FIELDS`, `IGNORED_NODE_FIELDS`, `WORKFLOW_PREDICATES`, `MECHANICAL_PREDICATES`, `PREDICATE_FIELDS`, `FIELD_TYPES`, `EFFORT_LEVELS`, `THINKING_LEVELS`, `MODEL_TIERS`, `CALL_TRANSPORTS`, `CALL_RETRY_CLASSES`, `EFFECT_FAILURE_CODES`, `PROSE_ARTIFACT_TYPES`; `WorkflowNodeKind`, `WorkflowPredicateName`, `FieldType`. The validator and the author contract read these same constants. |
177
+ | Author workflows | `authorContract`, `renderAuthorContract` (text and sha256), `renderAuthorHostAddendum`, `authorWorkflow`, `applyHostOutputTypes`, `authorSkillDirectory`, `loadAuthorReference`, `loadAuthorSkillBundle`; `AuthorHostAddendum`, `AuthorWorkflowOptions`, `AuthoredWorkflow`, `CandidatePolicyOptions`. The one author contract and its packaged skill (`skills/author`); a host adds only an addendum. See [the author contract](../../docs/authoring.md#one-author-contract). |
178
+ | Language vocabulary | `GENERATIVE_NODE_KINDS`, `JUDGMENT_NODE_KINDS`, `NODE_FIELDS`, `IGNORED_NODE_FIELDS`, `WORKFLOW_PREDICATES`, `MECHANICAL_PREDICATES`, `PREDICATE_FIELDS`, `FIELD_TYPES`, `EFFORT_LEVELS`, `THINKING_LEVELS`, `MODEL_TIERS`, `CALL_TRANSPORTS`, `CALL_RETRY_CLASSES`, `EFFECT_FAILURE_CODES`, `PROSE_ARTIFACT_TYPES`; `WorkflowNodeKind`, `WorkflowPredicateName`, `FieldType`. The validator and the author contract read these same constants. |
179
179
  | Test without a model | `synthesizeInstance`, `synthesizeAnswers`, `DryRunOptions`, `DryRunResult`. Synthetic answers exercise execution mechanics; they do not establish judgment quality. A dry run stops after `maxSteps` synthetic steps (10,000 by default) or at its `signal`, with `skipped` saying so. |
180
180
 
181
181
  A `code` node runs in the host process through the package's own executor, which shadows common globals and is not a sandbox. A host that runs code from an untrusted author supplies `deps.runCode`: the interpreter then hands it each code node with the state and the transform's context, merges what it returns under the same patch rules and state checks, and never executes a code body itself, not even as a validation probe. `dryRunWorkflow` takes the same `runCode` option and honors it the same way. `validateWorkflow` is synchronous and cannot call a host executor: a host that has one validates with `executeCode: false`, as `runWorkflow` and `dryRunWorkflow` do for it. `deniedGlobalReferences` names the globals a code body reaches for (a lint, never a boundary), so such a host can refuse the node before it runs. A failed effect carries a closed `code` from `EFFECT_FAILURE_CODES` on its `EffectFailure` and on every `effect.failed` event (null when the failure is not an `EffectFailure` with a listed code; any other typed error's own code rides as `error_code`), and `retry.on` names codes as well as retry classes.
package/dist/author.d.ts CHANGED
@@ -89,8 +89,6 @@ export interface AuthoredWorkflow {
89
89
  /** Author one workflow and retain every candidate with its review in a new directory under `outputDir`.
90
90
  * Policy, validation and host acceptance review each submission; a rejection returns to the same session. */
91
91
  export declare function authorWorkflow(options: AuthorWorkflowOptions): Promise<AuthoredWorkflow>;
92
- /** The packaged author skill's name, as a skill-loading host registers it. */
93
- export declare const AUTHOR_SKILL_NAME = "agentrun-author";
94
92
  /** The absolute directory of the packaged author skill (the one holding SKILL.md). */
95
93
  export declare function authorSkillDirectory(): string;
96
94
  /** A reference shipped with the author skill, for hosts without file-reading tools. */
package/dist/author.js CHANGED
@@ -309,8 +309,6 @@ export async function authorWorkflow(options) {
309
309
  throw error;
310
310
  }
311
311
  }
312
- /** The packaged author skill's name, as a skill-loading host registers it. */
313
- export const AUTHOR_SKILL_NAME = "agentrun-author";
314
312
  const skillRoot = new URL("../skills/author/", import.meta.url);
315
313
  /** The absolute directory of the packaged author skill (the one holding SKILL.md). */
316
314
  export function authorSkillDirectory() {
package/dist/index.d.ts CHANGED
@@ -15,13 +15,13 @@ export { evidenceOf, EVIDENCE_EXCERPT_MAX, EVIDENCE_EXCERPTS_PER_ITEM, EVIDENCE_
15
15
  export type { DecisionProvider, DecisionCapabilities, DecisionInput, DecisionRequest, DecisionContext, DecisionEvidence, DecisionOutcome, ProviderAnswer, CostBasis, DecisionProviderErrorCode, DecisionImage, LoadImage, JudgeFromProviderOptions, } from "./decision-provider.js";
16
16
  export { inspectWorkflow, formatWorkflowTree } from "./inspection.js";
17
17
  export type { WorkflowInspection, WorkflowInspectionNode } from "./inspection.js";
18
- export { runWorkflowSlice, assertWorkflowCapabilities, desugarWorkflow, stageSchemaForNode, submissionSchemaForNode, mergeStageDelta, REPORT_SCHEMA, SHELL_RESULT_SCHEMA, childSteps, declaredWrites, terminalArtifactType, artifactNodeIsProse, schemaProblems, HOST_STATE_KEY, buildReferenceContext, normalizeStringNullsForSchema, parseCsvRows, } from "./workflow.js";
18
+ export { runWorkflowSlice, assertWorkflowCapabilities, desugarWorkflow, stageSchemaForNode, submissionSchemaForNode, mergeStageDelta, REPORT_SCHEMA, SHELL_RESULT_SCHEMA, childSteps, declaredWrites, artifactNodeIsProse, schemaProblems, HOST_STATE_KEY, normalizeStringNullsForSchema, } from "./workflow.js";
19
19
  export { compileTransform, compileTransformSyntax, deniedGlobalReferences } from "./code-exec.js";
20
20
  export { resolveSchemaForWorkflow } from "./schema-references.js";
21
21
  export { submitParameters } from "./submit-envelope.js";
22
22
  export { getPath, predicateMatches } from "./predicates.js";
23
23
  export type { StopPredicate, AcceptPredicate } from "./predicates.js";
24
- export { authorContract, renderAuthorContract, renderAuthorHostAddendum, candidatePolicyErrors, applyHostOutputTypes, authorWorkflow, AUTHOR_SKILL_NAME, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
24
+ export { authorContract, renderAuthorContract, renderAuthorHostAddendum, applyHostOutputTypes, authorWorkflow, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
25
25
  export type { AuthorHostAddendum, CandidatePolicyOptions, AuthorWorkflowOptions, AuthoredWorkflow, HostOutputTypeOptions } from "./author.js";
26
- export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, FIELD_TYPES, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
26
+ export { GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, FIELD_TYPES, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
27
27
  export type { WorkflowNodeKind, WorkflowPredicateName, FieldType } from "./vocabulary.js";
package/dist/index.js CHANGED
@@ -9,12 +9,12 @@ export { evidenceOf, EVIDENCE_EXCERPT_MAX, EVIDENCE_EXCERPTS_PER_ITEM, EVIDENCE_
9
9
  export { inspectWorkflow, formatWorkflowTree } from "./inspection.js";
10
10
  export { runWorkflowSlice, assertWorkflowCapabilities, desugarWorkflow, stageSchemaForNode, submissionSchemaForNode, mergeStageDelta, REPORT_SCHEMA, SHELL_RESULT_SCHEMA,
11
11
  // Document helpers a host facade needs to speak about a workflow without re-implementing the walk.
12
- childSteps, declaredWrites, terminalArtifactType, artifactNodeIsProse, schemaProblems, HOST_STATE_KEY,
13
- // Host-side data helpers the interpreter itself uses: the same normalization and reference shaping.
14
- buildReferenceContext, normalizeStringNullsForSchema, parseCsvRows, } from "./workflow.js";
12
+ childSteps, declaredWrites, artifactNodeIsProse, schemaProblems, HOST_STATE_KEY,
13
+ // The host-side normalization the interpreter itself uses.
14
+ normalizeStringNullsForSchema, } from "./workflow.js";
15
15
  export { compileTransform, compileTransformSyntax, deniedGlobalReferences } from "./code-exec.js";
16
16
  export { resolveSchemaForWorkflow } from "./schema-references.js";
17
17
  export { submitParameters } from "./submit-envelope.js";
18
18
  export { getPath, predicateMatches } from "./predicates.js";
19
- export { authorContract, renderAuthorContract, renderAuthorHostAddendum, candidatePolicyErrors, applyHostOutputTypes, authorWorkflow, AUTHOR_SKILL_NAME, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
20
- export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, FIELD_TYPES, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
19
+ export { authorContract, renderAuthorContract, renderAuthorHostAddendum, applyHostOutputTypes, authorWorkflow, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
20
+ export { GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, FIELD_TYPES, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
@@ -7,7 +7,3 @@ export declare const CALL_KEY_BYTES = 256;
7
7
  * call always has the same key, and two different wide ids share a key only on a digest collision.
8
8
  * Only keys use it: what goes back to the provider is always the id it minted. */
9
9
  export declare function callKey(callId: string): string;
10
- /** The key a ledger holds a call under. Writes always use `callKey`; a read also accepts a row a
11
- * ledger already keys by the raw id (`holds` answers for the raw id), so a run whose ledger keyed a
12
- * wide id as it was resumes against its own receipts and never re-runs a recorded call. */
13
- export declare function heldCallKey(callId: string, holds: (rawKey: string) => boolean): string;
@@ -15,10 +15,3 @@ export function callKey(callId) {
15
15
  const prefix = callId.slice(0, PREFIX_CHARS).replace(/[^A-Za-z0-9_.-]/g, "_");
16
16
  return `${prefix}~${createHash("sha256").update(callId).digest("hex").slice(0, DIGEST_HEX)}`;
17
17
  }
18
- /** The key a ledger holds a call under. Writes always use `callKey`; a read also accepts a row a
19
- * ledger already keys by the raw id (`holds` answers for the raw id), so a run whose ledger keyed a
20
- * wide id as it was resumes against its own receipts and never re-runs a recorded call. */
21
- export function heldCallKey(callId, holds) {
22
- const key = callKey(callId);
23
- return key !== callId && holds(callId) ? callId : key;
24
- }
@@ -220,20 +220,6 @@ export declare function openRecovery(store: RecoveryStore, workflow: Workflow, o
220
220
  pinJson(): string;
221
221
  /** How many effects the driver admitted. */
222
222
  effectCalls(): number;
223
- /** What the continuation inherited, against the escalation that admitted it: the level, the sizes of what it
224
- * read and its identity. */
225
- annotateHandoff(detail: {
226
- escalation_revision: number;
227
- tail: string;
228
- inherit: string;
229
- block_chars: number;
230
- digest_chars: number;
231
- }): Promise<void>;
232
- /** The run's spend at the moment its continuation is admitted. Spend may land under this run after
233
- * the escalation commit, so the row the continuation reads the spend from is brought current here,
234
- * by one `handoff` commit that names the escalation. The escalation's revision, what the
235
- * continuation binds on, does not change. */
236
- handoff(spend: Pick<EscalationRow, "cost_usd" | "turns" | "effect_calls">): Promise<EscalationRow>;
237
223
  /** The state the document's committed top-level prefix left behind, plus what a failed map's finished
238
224
  * items produced under the map's key: what an escalation on a failure carries. */
239
225
  lastState(): Record<string, unknown>;
@@ -1197,29 +1197,6 @@ export async function openRecovery(store, workflow, options) {
1197
1197
  pinJson() { return JSON.stringify(snapshot.pin); },
1198
1198
  /** How many effects the driver admitted. */
1199
1199
  effectCalls() { return journal.effects().length; },
1200
- /** What the continuation inherited, against the escalation that admitted it: the level, the sizes of what it
1201
- * read and its identity. */
1202
- async annotateHandoff(detail) {
1203
- await persist(() => journal.note("inherited", detail));
1204
- },
1205
- /** The run's spend at the moment its continuation is admitted. Spend may land under this run after
1206
- * the escalation commit, so the row the continuation reads the spend from is brought current here,
1207
- * by one `handoff` commit that names the escalation. The escalation's revision, what the
1208
- * continuation binds on, does not change. */
1209
- async handoff(spend) {
1210
- guard();
1211
- const row = snapshot.escalation;
1212
- if (!row)
1213
- throw failure("FROZEN_CHECKPOINT_INVALID", "A handoff follows an escalation; none is recorded");
1214
- if (row.cost_usd === spend.cost_usd && row.turns === spend.turns && row.effect_calls === spend.effect_calls)
1215
- return row;
1216
- const detail = { escalation_revision: row.revision, previous_cost_usd: row.cost_usd,
1217
- cost_usd: spend.cost_usd, turns: spend.turns, effect_calls: spend.effect_calls };
1218
- Object.assign(row, spend);
1219
- const write = writeOf();
1220
- await persist(() => journal.save(write.state, { kind: "handoff", detail }, write.parts));
1221
- return row;
1222
- },
1223
1200
  /** The state the document's committed top-level prefix left behind, plus what a failed map's finished
1224
1201
  * items produced under the map's key: what an escalation on a failure carries. */
1225
1202
  lastState() {
@@ -1,38 +1,3 @@
1
- import type { RecoveryEffect, RecoveryIntent } from "./store.js";
2
- /** A completed tool effect a continuation may answer an exact repeat from: the external call it paid for, and its value. */
3
- export type InheritedReceipt = {
4
- id: string;
5
- name: string;
6
- tool: string;
7
- argsHash: string;
8
- result: unknown;
9
- session: string | null;
10
- };
11
- /** An effect whose outcome is unknown: its call is never dispatched again. `intent` is the external call it was admitted
12
- * for, when its journal recorded one. */
13
- export type InheritedUnknown = {
14
- id: string;
15
- name: string;
16
- argsHash: string;
17
- session: string | null;
18
- intent?: RecoveryIntent;
19
- };
20
- /** A tool value that is itself a returned failure: an error envelope (`ok: false`, `isError: true`, `outcome: "error"`) as
21
- * an object or as its JSON text. Such a value is not a paid result; the continuation may make the call again. Structural,
22
- * never prose. */
23
- export declare function returnedFailure(value: unknown): boolean;
24
- /** The receipts a journal hands to its continuation: completed effects whose receipt names the external call (tool
25
- * effects; shell and executor effects have no external call to repeat) and whose value is a result, not a returned
26
- * failure. */
27
- export declare function inheritableReceipts(effects: readonly RecoveryEffect[]): InheritedReceipt[];
28
- /** The effects a continuation must not dispatch again: every effect whose outcome is unknown, by the name and argument
29
- * hash its admission recorded, and by the external call it was admitted for when the journal holds one. A call the
30
- * continuation's own tools make is matched by `reuseReceipts` on either key. A session effect's name and hash are
31
- * already a tool's name and the hash of its arguments. A tool effect the driver admitted for a workflow node is named
32
- * by the node's label and hashed over the node's whole invocation, so it is matched by its intent (the tool and the
33
- * hash of its arguments, keyed as `gatewayIntentOf` keys a call); one a journal admitted before intents were recorded
34
- * has none, and is matched by name and hash only. */
35
- export declare function inheritableUnknowns(effects: readonly RecoveryEffect[]): InheritedUnknown[];
36
1
  /** The external call a model tool call stands for: the gateway tool and the hash of its arguments. Only a `fetch`
37
2
  * wrapper names the gateway tool in its arguments; every other tool is its own name, whatever its arguments look like.
38
3
  * The same key is computed for an effect from its receipt's intent. */
@@ -1,47 +1,4 @@
1
1
  import { canonicalHash } from "./canonical-hash.js";
2
- /** A tool value that is itself a returned failure: an error envelope (`ok: false`, `isError: true`, `outcome: "error"`) as
3
- * an object or as its JSON text. Such a value is not a paid result; the continuation may make the call again. Structural,
4
- * never prose. */
5
- export function returnedFailure(value) {
6
- const failed = (parsed) => Boolean(parsed && typeof parsed === "object" && !Array.isArray(parsed) && (parsed.ok === false || parsed.isError === true || parsed.outcome === "error"));
7
- if (typeof value !== "string")
8
- return failed(value);
9
- // The envelope may be the whole text (pretty-printed or not) or one line of it with guidance appended; each
10
- // candidate is parsed structurally, never matched as prose.
11
- for (const candidate of [value.trim(), ...value.split("\n").map((line) => line.trim())]) {
12
- if (!candidate.startsWith("{"))
13
- continue;
14
- try {
15
- if (failed(JSON.parse(candidate)))
16
- return true;
17
- }
18
- catch { /* not this candidate */ }
19
- }
20
- return false;
21
- }
22
- /** The receipts a journal hands to its continuation: completed effects whose receipt names the external call (tool
23
- * effects; shell and executor effects have no external call to repeat) and whose value is a result, not a returned
24
- * failure. */
25
- export function inheritableReceipts(effects) {
26
- return effects.filter((e) => e.status === "completed" && e.result && typeof e.result === "object" && e.result.intent && typeof e.result.intent.tool === "string" && !returnedFailure(e.result.value))
27
- .map((e) => {
28
- const receipt = e.result;
29
- // Keyed as a continuation's own call is: a node that reached the gateway through the fetch wrapper paid for the tool the wrapper names.
30
- const { tool, argsHash } = gatewayIntentOf(receipt.intent.tool, receipt.intent.args ?? {});
31
- return { id: e.id, name: e.name, tool, argsHash, result: receipt.value, session: e.session };
32
- });
33
- }
34
- /** The effects a continuation must not dispatch again: every effect whose outcome is unknown, by the name and argument
35
- * hash its admission recorded, and by the external call it was admitted for when the journal holds one. A call the
36
- * continuation's own tools make is matched by `reuseReceipts` on either key. A session effect's name and hash are
37
- * already a tool's name and the hash of its arguments. A tool effect the driver admitted for a workflow node is named
38
- * by the node's label and hashed over the node's whole invocation, so it is matched by its intent (the tool and the
39
- * hash of its arguments, keyed as `gatewayIntentOf` keys a call); one a journal admitted before intents were recorded
40
- * has none, and is matched by name and hash only. */
41
- export function inheritableUnknowns(effects) {
42
- return effects.filter((e) => e.status === "unknown").map((e) => ({ id: e.id, name: e.name, argsHash: e.argsHash, session: e.session,
43
- ...(e.intent ? { intent: { tool: e.intent.tool, argsHash: e.intent.argsHash } } : {}) }));
44
- }
45
2
  /** The external call a model tool call stands for: the gateway tool and the hash of its arguments. Only a `fetch`
46
3
  * wrapper names the gateway tool in its arguments; every other tool is its own name, whatever its arguments look like.
47
4
  * The same key is computed for an effect from its receipt's intent. */
@@ -8,12 +8,7 @@ export { openJournal, type JournalBackend, type JournalRecord } from "./journal.
8
8
  export { RecoveryError, asRecoveryError, isRecoveryError, runStopOf, runStoppedError } from "./errors.js";
9
9
  export { bindingDigests, bindingMismatch, LEDGER_FORMAT } from "./binding.js";
10
10
  export { canonicalHash, canonicalSha256 } from "./canonical-hash.js";
11
- export { callKey, heldCallKey, CALL_KEY_BYTES } from "./call-key.js";
12
- export { FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, DECISION_REQUEST, validateFrozenSnapshot, openedFrozenSnapshot, serializeFrozenSnapshot, emptyPathFrame, stateDelta, applyStateDelta, itemState, partialResults, canonicalJson, frozenStepSessionId, frozenStepId, frozenEffectId, frozenEffectPath, admitFrozenStep, closeFrozenStepAttempt, frozenStop, type FrozenSnapshot, type FrozenSnapshotV4, type ItemRecord, type MapEntry, type StateDelta, type Sha256, type PartialSlot, type PathFrame, type RouteDecision, type DecisionRequest, type QuestionReceipts, type FrameTag, type StepRecord, type EscalationRow, type FrozenShape, } from "./frozen-snapshot.js";
11
+ export { callKey, CALL_KEY_BYTES } from "./call-key.js";
12
+ export { FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, DECISION_REQUEST, validateFrozenSnapshot, openedFrozenSnapshot, serializeFrozenSnapshot, emptyPathFrame, stateDelta, applyStateDelta, itemState, partialResults, frozenStepId, admitFrozenStep, closeFrozenStepAttempt, frozenStop, type FrozenSnapshot, type FrozenSnapshotV4, type ItemRecord, type MapEntry, type StateDelta, type Sha256, type PartialSlot, type PathFrame, type RouteDecision, type DecisionRequest, type QuestionReceipts, type FrameTag, type StepRecord, type EscalationRow, type FrozenShape, } from "./frozen-snapshot.js";
13
13
  export { chainStep, childrenOf, completedIteration, enclosingChains, enclosingIterations, isWithin, mapItemOf, nodeAt, pathSegments, topLevelCompletion } from "./execution-path.js";
14
- export { TypedEffectFailure, EffectEnvelopeFailure, classifyEffectFailure } from "./effect-failure.js";
15
14
  export { effectRetryClass, transportFactOf, type TransportFact } from "./transport-facts.js";
16
- export { buildHandoff, handoffFirstTurn, type Handoff, type HandoffOptions } from "./handoff.js";
17
- export { gatewayIntentOf, inheritableReceipts, inheritableUnknowns, returnedFailure, type InheritedReceipt, type InheritedUnknown } from "./handoff-receipts.js";
18
- export { inputProvenance, judgedRecords, type InputProvenance } from "./handoff-files.js";
19
- export { type InheritedSession, type InheritedEffect, type TranscriptMessage } from "./handoff-digest.js";
@@ -7,11 +7,7 @@ export { openJournal } from "./journal.js";
7
7
  export { RecoveryError, asRecoveryError, isRecoveryError, runStopOf, runStoppedError } from "./errors.js";
8
8
  export { bindingDigests, bindingMismatch, LEDGER_FORMAT } from "./binding.js";
9
9
  export { canonicalHash, canonicalSha256 } from "./canonical-hash.js";
10
- export { callKey, heldCallKey, CALL_KEY_BYTES } from "./call-key.js";
11
- export { FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, DECISION_REQUEST, validateFrozenSnapshot, openedFrozenSnapshot, serializeFrozenSnapshot, emptyPathFrame, stateDelta, applyStateDelta, itemState, partialResults, canonicalJson, frozenStepSessionId, frozenStepId, frozenEffectId, frozenEffectPath, admitFrozenStep, closeFrozenStepAttempt, frozenStop, } from "./frozen-snapshot.js";
10
+ export { callKey, CALL_KEY_BYTES } from "./call-key.js";
11
+ export { FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, DECISION_REQUEST, validateFrozenSnapshot, openedFrozenSnapshot, serializeFrozenSnapshot, emptyPathFrame, stateDelta, applyStateDelta, itemState, partialResults, frozenStepId, admitFrozenStep, closeFrozenStepAttempt, frozenStop, } from "./frozen-snapshot.js";
12
12
  export { chainStep, childrenOf, completedIteration, enclosingChains, enclosingIterations, isWithin, mapItemOf, nodeAt, pathSegments, topLevelCompletion } from "./execution-path.js";
13
- export { TypedEffectFailure, EffectEnvelopeFailure, classifyEffectFailure } from "./effect-failure.js";
14
13
  export { effectRetryClass, transportFactOf } from "./transport-facts.js";
15
- export { buildHandoff, handoffFirstTurn } from "./handoff.js";
16
- export { gatewayIntentOf, inheritableReceipts, inheritableUnknowns, returnedFailure } from "./handoff-receipts.js";
17
- export { inputProvenance, judgedRecords } from "./handoff-files.js";
@@ -68,8 +68,10 @@ export function withRecovery(driver, deps, options = {}) {
68
68
  throw error;
69
69
  }
70
70
  // A cut call (a cancel, the run's failure) has no outcome: a later open finds it asked and unanswered. A call
71
- // that ended on its own failed, and the next process asks again.
72
- if (!driver.signal.aborted && !params.signal?.aborted)
71
+ // that ended on its own failed, and the next process asks again; so does one that never left (`unsent`, a host's
72
+ // refusal before it sent anything), whatever stopped the run meanwhile: nothing went out to answer.
73
+ const unsent = error instanceof DecisionProviderError && error.unsent === true;
74
+ if (unsent || (!driver.signal.aborted && !params.signal?.aborted))
73
75
  driver.decisionEnded(params.executionPath, decisionId, "failed", null);
74
76
  throw error;
75
77
  }
@@ -65,7 +65,6 @@ export declare const SYSTEM_ONE_LIMITS: {
65
65
  readonly minScoreLevels: 2;
66
66
  readonly maxScoreLevels: 10;
67
67
  };
68
- export declare const SYSTEM_ONE_DEFAULT_MODEL = "jev-latest";
69
68
  export type CompiledQuestions = Record<string, SystemOneQuestion>;
70
69
  export declare function compileQuestions(schema: Record<string, unknown>, definitions?: Record<string, unknown>): {
71
70
  ok: true;
@@ -1,5 +1,4 @@
1
1
  export const SYSTEM_ONE_LIMITS = { maxChoiceOptions: 240, minScoreLevels: 2, maxScoreLevels: 10 };
2
- export const SYSTEM_ONE_DEFAULT_MODEL = "jev-latest";
3
2
  const CRITERIA = "criteria";
4
3
  export function compileQuestions(schema, definitions = {}) {
5
4
  const errors = [];
@@ -320,7 +320,6 @@ export type ArtifactState = {
320
320
  };
321
321
  export declare function artifactNodeIsProse(node: ArtifactNode): boolean;
322
322
  export declare function desugarWorkflow(workflow: Workflow): Workflow;
323
- export declare function terminalArtifactType(workflow: Workflow): string | null;
324
323
  /** A predicate a `call` evaluates against ITS OWN RESULT: paths are result-relative. */
325
324
  export type CallPredicate = MechanicalPredicate;
326
325
  export type PollClause = {
@@ -667,14 +666,6 @@ export declare class EffectFailure extends Error {
667
666
  cause?: unknown;
668
667
  });
669
668
  }
670
- export declare function parseCsvRows(text: string): string[][];
671
- export declare function buildReferenceContext(files: Record<string, string>): {
672
- references: Record<string, string>;
673
- references_parsed: Record<string, {
674
- header: string[];
675
- rows: string[][];
676
- }>;
677
- };
678
669
  export declare function normalizeStringNullsForSchema(value: unknown, schema: Record<string, unknown> | undefined, depth?: number, root?: Record<string, unknown> | undefined): unknown;
679
670
  export declare function workflowSha256(workflow: Workflow): string;
680
671
  /** Bound the complete document before any recursive schema or semantic traversal. Shared
package/dist/workflow.js CHANGED
@@ -44,13 +44,6 @@ export function desugarWorkflow(workflow) {
44
44
  return workflow;
45
45
  return { ...workflow, root: visit(workflow.root) };
46
46
  }
47
- export function terminalArtifactType(workflow) {
48
- const steps = workflow?.root?.node === "chain" ? workflow.root.steps || [] : [workflow?.root];
49
- const last = steps[steps.length - 1];
50
- if (!last || last.node !== "artifact")
51
- return null;
52
- return last.type;
53
- }
54
47
  export const SHELL_RESULT_SCHEMA = {
55
48
  type: "object",
56
49
  required: ["code", "stdout", "stderr"],
@@ -269,63 +262,6 @@ function resultPathMissing(shape, dotted) {
269
262
  }
270
263
  return false;
271
264
  }
272
- export function parseCsvRows(text) {
273
- const rows = [];
274
- let field = "", row = [], inQuotes = false;
275
- for (let i = 0; i < text.length; i += 1) {
276
- const ch = text[i];
277
- if (inQuotes) {
278
- if (ch === '"' && text[i + 1] === '"') {
279
- field += '"';
280
- i += 1;
281
- }
282
- else if (ch === '"')
283
- inQuotes = false;
284
- else
285
- field += ch;
286
- }
287
- else if (ch === '"')
288
- inQuotes = true;
289
- else if (ch === ",") {
290
- row.push(field);
291
- field = "";
292
- }
293
- else if (ch === "\n" || ch === "\r") {
294
- if (ch === "\r" && text[i + 1] === "\n")
295
- i += 1;
296
- row.push(field);
297
- field = "";
298
- if (row.some((c) => c.trim() !== ""))
299
- rows.push(row);
300
- row = [];
301
- }
302
- else
303
- field += ch;
304
- }
305
- if (field !== "" || row.length) {
306
- row.push(field);
307
- if (row.some((c) => c.trim() !== ""))
308
- rows.push(row);
309
- }
310
- return rows;
311
- }
312
- export function buildReferenceContext(files) {
313
- // Null prototypes: reference filenames are external data. On a plain object a name like
314
- // "__proto__" hits the prototype SETTER on assignment — the file silently vanishes from
315
- // the map (and worse shapes pollute it). A null-prototype object stores it as an ordinary
316
- // own key, so every filename round-trips.
317
- const references = Object.create(null);
318
- const referencesParsed = Object.create(null);
319
- for (const [name, body] of Object.entries(files)) {
320
- references[name] = body;
321
- if (name.toLowerCase().endsWith(".csv")) {
322
- const rows = parseCsvRows(body);
323
- if (rows.length)
324
- referencesParsed[name] = { header: rows[0], rows: rows.slice(1) };
325
- }
326
- }
327
- return { references, references_parsed: referencesParsed };
328
- }
329
265
  /** Whether a field's schema lists the value itself: its own `const`, or a member of its own `enum`, or the same in the
330
266
  * schema a local `$ref` names in the root schema's `definitions` or `$defs`, or in any `anyOf` or `oneOf` branch, at any
331
267
  * depth. A schema's own listed values count beside its `$ref`, never in place of it. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.34",
3
+ "version": "0.1.0-beta.36",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -47,7 +47,7 @@
47
47
  "skills"
48
48
  ],
49
49
  "engines": {
50
- "node": ">=24.11.0"
50
+ "node": ">=24.22.3"
51
51
  },
52
52
  "scripts": {
53
53
  "build": "tsc -p tsconfig.json",
@@ -1,34 +0,0 @@
1
- import { EffectFailure, type CallRetryClass, type EffectFailureCode } from "../workflow.js";
2
- /** A failed effect: its closed code, the prose for the reader, and what the host observed
3
- * (`detail`: the deadline, the elapsed time, the output tail, the filed output) which the
4
- * interpreter writes onto the attempt's `effect.failed` event. The retry class is the transport's
5
- * when it gave one, else the code's. */
6
- export declare class TypedEffectFailure extends EffectFailure {
7
- readonly code: EffectFailureCode;
8
- constructor(code: EffectFailureCode, message: string, options?: {
9
- detail?: Record<string, unknown>;
10
- cause?: unknown;
11
- retryClass?: CallRetryClass | null;
12
- });
13
- }
14
- /** A dispatch that succeeded around a failed tool: the transport answered with the tool's own failure
15
- * envelope as its text. The envelope is the effect's failure, never its result. */
16
- export declare class EffectEnvelopeFailure extends Error {
17
- readonly tool: string;
18
- readonly envelope: string;
19
- constructor(tool: string, envelope: string);
20
- }
21
- /** A thrown error at an effect boundary, as a TypedEffectFailure. A TypedEffectFailure passes through; a
22
- * tool the host did not grant (`notGranted` names it) is effect_not_granted; an unknown transport
23
- * (`via` outside the interpreter's list) is effect_unknown_transport; a tool's failure envelope is
24
- * effect_transport; otherwise the error's typed transport facts decide: a deadline (a TimeoutError, an
25
- * AbortError, a 408, an idle cut, a timed-out connect) is effect_timeout, any other typed fact (a
26
- * status, a system code, an error class) is effect_transport with the retry class those facts earn
27
- * (effectRetryClass), and an error with no typed fact came through no transport that can be named:
28
- * effect_unknown_transport. The message is carried for the reader and never read. */
29
- export declare function classifyEffectFailure(error: unknown, at: {
30
- label: string;
31
- via: string;
32
- }, options?: {
33
- notGranted?: (error: unknown) => string | undefined;
34
- }): TypedEffectFailure;
@@ -1,62 +0,0 @@
1
- // An effect's failure, typed at every boundary. Every failure carries one closed code (EFFECT_FAILURE_CODES, the
2
- // interpreter's list, which `retry.on` names); the prose stays beside it as `message`, for the reader,
3
- // and is never the discriminator. This module holds the class a host's effect adapters throw, and the one
4
- // classifier that maps a thrown transport error to a code from its typed facts (the error's class, its
5
- // HTTP status, its system code), never from its text.
6
- import { CALL_TRANSPORTS } from "../vocabulary.js";
7
- import { EffectFailure } from "../workflow.js";
8
- import { effectRetryClass, transportFactOf } from "./transport-facts.js";
9
- /** The retry class a code implies when the failure's transport facts name none: a deadline is a
10
- * timeout and a non-zero exit is an exit, the two the interpreter's default retry list names; every
11
- * other code is not transient by nature. */
12
- const IMPLIED_RETRY_CLASS = { effect_timeout: "timeout", effect_exit: "exit" };
13
- /** A failed effect: its closed code, the prose for the reader, and what the host observed
14
- * (`detail`: the deadline, the elapsed time, the output tail, the filed output) which the
15
- * interpreter writes onto the attempt's `effect.failed` event. The retry class is the transport's
16
- * when it gave one, else the code's. */
17
- export class TypedEffectFailure extends EffectFailure {
18
- constructor(code, message, options = {}) {
19
- super(message, options.retryClass !== undefined ? options.retryClass : IMPLIED_RETRY_CLASS[code] ?? null, {
20
- code, ...(options.detail ? { detail: options.detail } : {}), ...(options.cause !== undefined ? { cause: options.cause } : {}),
21
- });
22
- }
23
- }
24
- /** A dispatch that succeeded around a failed tool: the transport answered with the tool's own failure
25
- * envelope as its text. The envelope is the effect's failure, never its result. */
26
- export class EffectEnvelopeFailure extends Error {
27
- tool;
28
- envelope;
29
- constructor(tool, envelope) {
30
- super(`tool "${tool}" returned a failure: ${envelope.slice(0, 500)}`);
31
- this.tool = tool;
32
- this.envelope = envelope;
33
- this.name = "EffectEnvelopeFailure";
34
- }
35
- }
36
- /** A thrown error at an effect boundary, as a TypedEffectFailure. A TypedEffectFailure passes through; a
37
- * tool the host did not grant (`notGranted` names it) is effect_not_granted; an unknown transport
38
- * (`via` outside the interpreter's list) is effect_unknown_transport; a tool's failure envelope is
39
- * effect_transport; otherwise the error's typed transport facts decide: a deadline (a TimeoutError, an
40
- * AbortError, a 408, an idle cut, a timed-out connect) is effect_timeout, any other typed fact (a
41
- * status, a system code, an error class) is effect_transport with the retry class those facts earn
42
- * (effectRetryClass), and an error with no typed fact came through no transport that can be named:
43
- * effect_unknown_transport. The message is carried for the reader and never read. */
44
- export function classifyEffectFailure(error, at, options = {}) {
45
- if (error instanceof TypedEffectFailure)
46
- return error;
47
- const text = error instanceof Error ? error.message : String(error);
48
- const message = `call node "${at.label}": ${text.slice(0, 500)}`;
49
- const refused = options.notGranted?.(error);
50
- if (refused !== undefined)
51
- return new TypedEffectFailure("effect_not_granted", message, { cause: error, detail: { tool: refused } });
52
- if (!CALL_TRANSPORTS.includes(at.via))
53
- return new TypedEffectFailure("effect_unknown_transport", message, { cause: error, detail: { transport: at.via } });
54
- if (error instanceof EffectEnvelopeFailure)
55
- return new TypedEffectFailure("effect_transport", message, { cause: error, retryClass: null });
56
- const fact = transportFactOf(error);
57
- const retryClass = effectRetryClass(fact);
58
- if (retryClass === "timeout" || fact.errorName === "AbortError")
59
- return new TypedEffectFailure("effect_timeout", message, { cause: error, retryClass });
60
- const typed = fact.status !== undefined || fact.causeCode !== undefined || fact.errorName !== undefined || fact.providerType !== undefined || fact.providerCode !== undefined;
61
- return new TypedEffectFailure(typed ? "effect_transport" : "effect_unknown_transport", message, { cause: error, retryClass });
62
- }
@@ -1,36 +0,0 @@
1
- import { type InputProvenance } from "./handoff-files.js";
2
- /** What the block says of the escalation. */
3
- export type HandoffBlockInput = {
4
- kind: string;
5
- stage: string;
6
- summary: string;
7
- step_label?: string | null;
8
- step_exec_id?: string | null;
9
- state?: Record<string, unknown> | null;
10
- workflow_sha_used?: string | null;
11
- cost_usd?: number | null;
12
- evidence_dir?: string | null;
13
- /** Where the attempt's report.md was moved, when one existed. */
14
- report_path?: string | null;
15
- /** Workspace-relative paths the attempt's files were written to. */
16
- files?: readonly string[] | null;
17
- /** Where each input the attempt started from came from, and its form. */
18
- inputs?: readonly InputProvenance[] | null;
19
- /** The host's sizes for the continuation, stated as one line. */
20
- budget?: {
21
- max_tool_calls?: number;
22
- max_seconds?: number;
23
- } | null;
24
- };
25
- /** The state at the gate is rendered whole up to this size; beyond it the block points at state.json. */
26
- export declare const STATE_LIMIT: number;
27
- /** Strings above the limit become a prefix plus a marker with the omitted length; nested values recurse. */
28
- export declare function boundedValue(value: unknown, limit?: number): unknown;
29
- /** One line per completed output in the state: the key the workflow wrote and the shape it holds. */
30
- export declare function stateShapes(state: Record<string, unknown> | null | undefined): string[];
31
- /** The one line that states the host's sizes for the continuation, or "" when the host sent none. */
32
- export declare function escalationBudgetLine(budget: HandoffBlockInput["budget"]): string;
33
- /** The block the continuation reads first. Deterministic for a given row; policy-agnostic. The reason is the
34
- * workflow's own text, whole; the state at the gate is whole up to STATE_LIMIT, and beyond it the
35
- * block points at the file that holds it. */
36
- export declare function escalationContextBlock(context: HandoffBlockInput): string;