@parcha/agentrun-dsl 0.1.0-beta.35 → 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
@@ -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
@@ -21,7 +21,7 @@ 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
@@ -16,5 +16,5 @@ export { compileTransform, compileTransformSyntax, deniedGlobalReferences } from
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";
@@ -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,26 +1,3 @@
1
- import type { 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
1
  /** The external call a model tool call stands for: the gateway tool and the hash of its arguments. Only a `fetch`
25
2
  * wrapper names the gateway tool in its arguments; every other tool is its own name, whatever its arguments look like.
26
3
  * The same key is computed for an effect from its receipt's intent. */
@@ -1,24 +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
2
  /** The external call a model tool call stands for: the gateway tool and the hash of its arguments. Only a `fetch`
23
3
  * wrapper names the gateway tool in its arguments; every other tool is its own name, whatever its arguments look like.
24
4
  * The same key is computed for an effect from its receipt's intent. */
@@ -9,7 +9,6 @@ export { RecoveryError, asRecoveryError, isRecoveryError, runStopOf, runStoppedE
9
9
  export { bindingDigests, bindingMismatch, LEDGER_FORMAT } from "./binding.js";
10
10
  export { canonicalHash, canonicalSha256 } from "./canonical-hash.js";
11
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, 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";
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
14
  export { effectRetryClass, transportFactOf, type TransportFact } from "./transport-facts.js";
15
- export { gatewayIntentOf, returnedFailure, type InheritedReceipt, type InheritedUnknown } from "./handoff-receipts.js";
@@ -8,7 +8,6 @@ export { RecoveryError, asRecoveryError, isRecoveryError, runStopOf, runStoppedE
8
8
  export { bindingDigests, bindingMismatch, LEDGER_FORMAT } from "./binding.js";
9
9
  export { canonicalHash, canonicalSha256 } from "./canonical-hash.js";
10
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, canonicalJson, frozenStepSessionId, frozenStepId, frozenEffectId, frozenEffectPath, admitFrozenStep, closeFrozenStepAttempt, frozenStop, } from "./frozen-snapshot.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
13
  export { effectRetryClass, transportFactOf } from "./transport-facts.js";
14
- export { gatewayIntentOf, returnedFailure } from "./handoff-receipts.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.35",
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",