@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.21

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.
Files changed (102) hide show
  1. package/README.md +107 -17
  2. package/dist/author.d.ts +96 -0
  3. package/dist/author.js +320 -0
  4. package/dist/authoring.js +1 -1
  5. package/dist/cli.js +8 -3
  6. package/dist/code-exec.d.ts +6 -0
  7. package/dist/code-exec.js +126 -0
  8. package/dist/decision-receipts.d.ts +98 -0
  9. package/dist/decision-receipts.js +51 -0
  10. package/dist/dry-run.d.ts +14 -1
  11. package/dist/dry-run.js +39 -13
  12. package/dist/graph.d.ts +83 -0
  13. package/dist/graph.js +231 -0
  14. package/dist/index.d.ts +12 -4
  15. package/dist/index.js +6 -2
  16. package/dist/inspection.js +2 -2
  17. package/dist/job.d.ts +14 -0
  18. package/dist/job.js +5 -0
  19. package/dist/long-timer.d.ts +7 -0
  20. package/dist/long-timer.js +22 -0
  21. package/dist/observer-snapshot.d.ts +3 -0
  22. package/dist/observer-snapshot.js +46 -0
  23. package/dist/predicates.d.ts +4 -0
  24. package/dist/predicates.js +19 -2
  25. package/dist/recovery/binding.d.ts +10 -0
  26. package/dist/recovery/binding.js +43 -0
  27. package/dist/recovery/call-key.d.ts +13 -0
  28. package/dist/recovery/call-key.js +24 -0
  29. package/dist/recovery/canonical-hash.d.ts +7 -0
  30. package/dist/recovery/canonical-hash.js +22 -0
  31. package/dist/recovery/driver.d.ts +208 -0
  32. package/dist/recovery/driver.js +1222 -0
  33. package/dist/recovery/effect-failure.d.ts +34 -0
  34. package/dist/recovery/effect-failure.js +62 -0
  35. package/dist/recovery/errors.d.ts +31 -0
  36. package/dist/recovery/errors.js +51 -0
  37. package/dist/recovery/execution-path.d.ts +53 -0
  38. package/dist/recovery/execution-path.js +167 -0
  39. package/dist/recovery/file-store.d.ts +7 -0
  40. package/dist/recovery/file-store.js +131 -0
  41. package/dist/recovery/frozen-snapshot.d.ts +244 -0
  42. package/dist/recovery/frozen-snapshot.js +171 -0
  43. package/dist/recovery/handoff-block.d.ts +36 -0
  44. package/dist/recovery/handoff-block.js +148 -0
  45. package/dist/recovery/handoff-digest.d.ts +58 -0
  46. package/dist/recovery/handoff-digest.js +195 -0
  47. package/dist/recovery/handoff-files.d.ts +54 -0
  48. package/dist/recovery/handoff-files.js +162 -0
  49. package/dist/recovery/handoff-receipts.d.ts +42 -0
  50. package/dist/recovery/handoff-receipts.js +53 -0
  51. package/dist/recovery/handoff-redact.d.ts +12 -0
  52. package/dist/recovery/handoff-redact.js +44 -0
  53. package/dist/recovery/handoff.d.ts +44 -0
  54. package/dist/recovery/handoff.js +46 -0
  55. package/dist/recovery/index.d.ts +18 -0
  56. package/dist/recovery/index.js +16 -0
  57. package/dist/recovery/item-state.d.ts +48 -0
  58. package/dist/recovery/item-state.js +89 -0
  59. package/dist/recovery/journal.d.ts +28 -0
  60. package/dist/recovery/journal.js +139 -0
  61. package/dist/recovery/memory-store.d.ts +4 -0
  62. package/dist/recovery/memory-store.js +20 -0
  63. package/dist/recovery/store.d.ts +105 -0
  64. package/dist/recovery/store.js +6 -0
  65. package/dist/recovery/testing/conformance.d.ts +4 -0
  66. package/dist/recovery/testing/conformance.js +268 -0
  67. package/dist/recovery/testing/crash-points.d.ts +18 -0
  68. package/dist/recovery/testing/crash-points.js +43 -0
  69. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  70. package/dist/recovery/testing/crash-sweep.js +146 -0
  71. package/dist/recovery/testing/index.d.ts +3 -0
  72. package/dist/recovery/testing/index.js +4 -0
  73. package/dist/recovery/testing/preload.d.ts +1 -0
  74. package/dist/recovery/testing/preload.js +3 -0
  75. package/dist/recovery/transport-facts.d.ts +23 -0
  76. package/dist/recovery/transport-facts.js +46 -0
  77. package/dist/recovery/with-recovery.d.ts +44 -0
  78. package/dist/recovery/with-recovery.js +87 -0
  79. package/dist/system-one.d.ts +17 -1
  80. package/dist/system-one.js +62 -5
  81. package/dist/vocabulary.d.ts +42 -0
  82. package/dist/vocabulary.js +74 -0
  83. package/dist/workflow-shape.d.ts +7 -0
  84. package/dist/workflow-shape.js +85 -62
  85. package/dist/workflow.d.ts +187 -16
  86. package/dist/workflow.js +1007 -332
  87. package/package.json +18 -2
  88. package/schema/workflow.schema.json +251 -15
  89. package/skills/author/SKILL.md +122 -0
  90. package/skills/author/examples/evidence-gate.input.json +6 -0
  91. package/skills/author/examples/evidence-gate.json +125 -0
  92. package/skills/author/examples/read-file.input.json +1 -0
  93. package/skills/author/examples/read-file.json +44 -0
  94. package/skills/author/examples/read-source-decision.input.json +4 -0
  95. package/skills/author/examples/read-source-decision.json +37 -0
  96. package/skills/author/examples/release-note.txt +10 -0
  97. package/skills/author/examples/review-release-notes.input.json +6 -0
  98. package/skills/author/examples/review-release-notes.json +123 -0
  99. package/skills/author/references/jev-decisions.md +125 -0
  100. package/skills/author/references/language.md +118 -0
  101. package/skills/author/references/sdk-authoring.md +11 -0
  102. package/skills/author/references/workflow-format.md +137 -0
@@ -0,0 +1,208 @@
1
+ import type { RouteNode, Workflow, WorkflowDeps, WorkflowNode } from "../workflow.js";
2
+ import { FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, type RouteDecision, type QuestionReceipts, type StepRecord, type EscalationRow } from "./frozen-snapshot.js";
3
+ import type { RecoveryBinding, RecoveryEffect, RecoveryStore } from "./store.js";
4
+ /** The branch a route runs for its answer, as the interpreter takes it: the node's `unsure` branch when
5
+ * the answer's confidence is below `unsure.gte`, else the choice the answer names. */
6
+ export declare function routeTaken(node: RouteNode, answers: unknown): {
7
+ branch: string;
8
+ choice: string;
9
+ unsure: boolean;
10
+ };
11
+ /** The binding of a run of `workflow` under what the host binds beside it. */
12
+ export declare function recoveryBinding(workflow: Workflow, bind?: Record<string, unknown>): string;
13
+ /** What a store is opened under for a run of `workflow`: its binding, and the digest of each input the binding
14
+ * covers. The driver opens its store under it, and so does an operator who reconciles an effect by hand. */
15
+ export declare function recoveryBound(workflow: Workflow, bind?: Record<string, unknown>): RecoveryBinding;
16
+ /** A host's pause or cancel, and who issued it. */
17
+ export type RecoveryStop = {
18
+ action: "pause" | "cancel";
19
+ source?: string;
20
+ };
21
+ /** How the driver reads the files a workflow declares it writes. */
22
+ export type RecoveryFiles = {
23
+ /** Whether two names are one file. */
24
+ same(a: string, b: string): boolean;
25
+ /** The SHA-256 of each named file, by name. A missing file, or one outside the place files live, is refused
26
+ * with FROZEN_ARTIFACT_INVALID. */
27
+ hashes(names: string[]): Record<string, string>;
28
+ };
29
+ /** The files of a workspace directory: a name is relative to it, and a file that resolves outside it is refused. */
30
+ export declare function workspaceFiles(cwd: string): RecoveryFiles;
31
+ export type RecoveryOptions = {
32
+ /** The run's identity. Its step sessions, its effects' receipts and the continuation of its escalation are named
33
+ * under it, so the same run is opened with the same key in every process. */
34
+ key: string;
35
+ /** What else must not change between two opens of the run, beside the workflow: the host's own inputs. */
36
+ bind?: Record<string, unknown>;
37
+ /** The document the interpreter runs, when the host rewrites the authored one before running it. Execution paths
38
+ * resolve in it; the binding, the labels and the declared files are the authored document's. Absent, the
39
+ * desugared workflow. */
40
+ view?: Workflow;
41
+ /** Files only the host writes. A workflow that declares one of them is refused before any step runs. */
42
+ reservedOutputs?: readonly string[];
43
+ /** The files a workflow declares it writes. Absent, the files of the process's working directory. */
44
+ files?: RecoveryFiles;
45
+ /** Closes the session of an LLM step's attempt that ended without a submission. It runs on the driver's commit
46
+ * chain, before the commit that records the attempt as closed; its failure is the run's. */
47
+ closeStepSession?: (sessionId: string) => Promise<unknown>;
48
+ /** Settles effects a killed process left unknown, through the driver's own open of the run (one generation per process).
49
+ * `openRecovery` calls it once, after the open and before anything resumes, when the journal holds an effect that was
50
+ * admitted and never completed; `unknown` is those effects, with their `intent` and the `args` the call was admitted with (what the host's door is sent; absent on a record written before args were kept). `complete(id, value, receipt)`
51
+ * records `value` as the effect's result, as `journal.complete` does with `{ value, files }`, hashing the files the effect declares (a missing one refuses the settlement); `receipt.intent` names
52
+ * the call the host's door answered, as a handoff reads it. `receipt.calls` are the outside calls the host MADE or FOUND APPLIED
53
+ * while settling it, records of the shape `{ outcome: "applied" | "failed" | "unknown", ... }`, so that the effect's `calls` lists
54
+ * every applied call exactly once. They are kept on the effect before it completes, after the calls an earlier process kept, as a
55
+ * dispatch keeps its own. A re-send is a call of this process. A settle from evidence that the call applied (a provider's own
56
+ * lookup, an answer the host kept) reports `{ outcome: "applied" }` when the calls the effect holds include no applied entry,
57
+ * and adds none when its applied call is already there. A settle that made no call and found none applied reports none. The
58
+ * effect is then answered from that result and not
59
+ * dispatched again. One it leaves unknown is refused at resume (`FROZEN_EFFECT_UNKNOWN`). A throw fails the open with
60
+ * `RECOVERY_RECONCILE_FAILED`, keeping the cause, before any effect is dispatched. */
61
+ reconcile?: (unknown: RecoveryEffect[], complete: (id: string, value: unknown, receipt?: {
62
+ intent?: {
63
+ tool: string;
64
+ args?: unknown;
65
+ };
66
+ calls?: unknown[];
67
+ }) => Promise<void>) => Promise<void>;
68
+ /** How a new run, or one stored whole, is kept. `"v3"` (the default in this release) keeps the driver's whole state in
69
+ * one record, rewritten at every commit, so a map's commits grow with the square of its items. `"v4"`, the keyed
70
+ * layout, keeps what lies in each map item in that item's record and each state the driver references once by its
71
+ * digest (a failed map's finished results too), so a commit writes what it changed: a run stored whole moves to it at
72
+ * its first commit. After that move, the checkpoint bases of the driver's record keep the ids of the effects admitted
73
+ * before it: a cost bounded by the work done before the move, which later commits do not grow; each commit after the
74
+ * move costs the same however many items the map has. Only a store that
75
+ * keeps parts (its opened journal has `items` and `stateOf`) can hold it; on any other the driver keeps `"v3"` and says
76
+ * why once per open, in a `layout` note. A run stored in the keyed layout stays in it whatever this says, and a driver
77
+ * that knows only `"v3"` refuses to open it (`FROZEN_CHECKPOINT_INVALID`). Release 0.1.0-beta.13 and earlier fail their
78
+ * own task on a run in the keyed layout and report it refused; that ends the run's agent nodes in flight, and the run
79
+ * then fails on this release too, with no call repeated and nothing corrupted. So opt in only when no process on an
80
+ * earlier release can open the run. A build from this release on leaves a run stored in a schema newer than it knows
81
+ * pending (`RECOVERY_SCHEMA_NEWER`), for a build that knows it. */
82
+ layout?: "v3" | "v4";
83
+ };
84
+ /** What a host's effect adapter receives under the driver: the interpreter's parameters, `call`, which keeps each
85
+ * outside call the effect makes on its record as the call ends, and `effect`, the admitted effect: its journal id and
86
+ * the hash of its arguments, as the journal stores them and the same in every process of the run. A host that keeps
87
+ * what an outside call answered under them can settle an effect whose call was cut with `journal.complete`. */
88
+ export type RecoveryEffectParams = Parameters<NonNullable<WorkflowDeps["runEffect"]>>[0] & {
89
+ call?: (record: unknown) => void;
90
+ effect?: {
91
+ id: string;
92
+ argsHash: string;
93
+ };
94
+ };
95
+ /** Opens the durable state of one run of `workflow` in `store` and takes ownership of it. Execution remains in the
96
+ * interpreter: the workflow runs with the returned driver's hooks, and `close` lets go of the run. */
97
+ export declare function openRecovery(store: RecoveryStore, workflow: Workflow, options: RecoveryOptions): Promise<{
98
+ recovery: {
99
+ supportsExecutionPaths?: boolean;
100
+ resume: (node: WorkflowNode, state: Record<string, unknown>, item?: import("../workflow.js").MapItem, executionPath?: string) => Promise<Record<string, unknown> | undefined>;
101
+ commit: (node: WorkflowNode, state: Record<string, unknown>, item?: import("../workflow.js").MapItem, executionPath?: string) => Promise<void>;
102
+ pollStartedAt: (node: import("../workflow.js").CallNode, item?: import("../workflow.js").MapItem, executionPath?: string) => number;
103
+ wait: (node: import("../workflow.js").CallNode, ms: number, item?: import("../workflow.js").MapItem, executionPath?: string) => Promise<void>;
104
+ fail?: (node: WorkflowNode, results: unknown[], error: unknown, executionPath?: string) => Promise<void>;
105
+ failItem?: (node: WorkflowNode, failure: import("../workflow.js").MapItemFailure, executionPath?: string) => Promise<void>;
106
+ itemFailure?: (node: WorkflowNode, executionPath?: string) => Promise<import("../workflow.js").MapItemFailure | undefined>;
107
+ decision?: (id: string) => Promise<import("../decision-receipts.js").DecisionReceipt | undefined>;
108
+ };
109
+ signal: AbortSignal;
110
+ resumed: boolean;
111
+ /** This process's generation of the run: a request this process makes is named with it, so a
112
+ * process that asks again never reuses an earlier process's invocation. */
113
+ readonly generation: number;
114
+ /** A refusal found before any step, or null: the host escalates it before any step runs. */
115
+ preStepRefusal: {
116
+ code: string;
117
+ kind: string;
118
+ message: string;
119
+ label: string;
120
+ } | null;
121
+ /** How this open keeps the run: the layout's schema, and why it is not the keyed one the host asked for. */
122
+ readonly layout: {
123
+ schema: typeof FROZEN_SNAPSHOT_SCHEMA | typeof FROZEN_SNAPSHOT_SCHEMA_V4;
124
+ reason?: string;
125
+ };
126
+ binding: string;
127
+ /** The run's key: what its step sessions and effects are named under. */
128
+ driverId: string;
129
+ /** The host hands the driver its stop here. A cancel stops the driver at once, and its steps and effects through
130
+ * its signal. A pause refuses new work at once and is taken when no effect is in flight: an effect already
131
+ * dispatched completes and commits its receipt first, so a paused run resumes without a reconciliation. */
132
+ stop: (stop: RecoveryStop) => void;
133
+ /** The driver's stop check, for a branch that hands off without entering the interpreter: a pause or cancel the
134
+ * driver took stops the run here, before anything resumes. */
135
+ checkStop(): void;
136
+ /** A seam for new work: it waits while a pause waits for an effect in flight, then applies any stop taken. */
137
+ seam: () => Promise<void>;
138
+ /** An LLM step's execution record, admitted before it dispatches. The first call fixes the label
139
+ * the interpreter names it by (a child's step under its invocation) and the retry limit; a resume
140
+ * at this path gets the same record, so its session is found again. A closed attempt advances to a new
141
+ * session identity here, and only here; a failed step never gets another. */
142
+ stepSession(executionPath: unknown, label: string, admission?: {
143
+ attemptsAllowed: number;
144
+ }): StepRecord & {
145
+ stepId: string;
146
+ sessionId: string;
147
+ earlierSessionIds: string[];
148
+ };
149
+ /** Whether the step already has an execution record: a resumed step was admitted in an earlier
150
+ * process and is continued, never refused again. */
151
+ stepAdmitted(executionPath: unknown): boolean;
152
+ /** The current attempt did not submit: its session closes with its spend kept.
153
+ * The step is `closed` until a retry is admitted, or `failed` when no attempt remains. */
154
+ stepAttemptFailed(executionPath: unknown, final?: boolean, error?: unknown): void;
155
+ /** The step delivered its record; the row and the step record agree before the step commit. */
156
+ stepSubmitted(executionPath: unknown): void;
157
+ /** The short identity of an admitted LLM step (a digest of its frame and path), for the escalation
158
+ * row when it fails; null for a path that ran no LLM step. */
159
+ stepId(executionPath: unknown): string | null;
160
+ /** Spend outside any question or session, committed with the driver's state the moment it is priced, so the run's
161
+ * recorded spend holds it. It may be called inside a tool, so it never applies a stop; a failed commit is the run's
162
+ * persistence failure. */
163
+ charge(usd: number): Promise<void>;
164
+ /** A question's metered spend, committed with the driver's state so a resume that skips the
165
+ * finished question still reports it; an unpriced answer (`null`) adds nothing. A route's answer is its decision: it commits in the same save, once per route path, and a resume
166
+ * inside the branch follows it instead of asking again. */
167
+ recordQuestionSpend(usd: number | null, route?: {
168
+ executionPath: unknown;
169
+ label: string;
170
+ result: Record<string, unknown>;
171
+ receipts: QuestionReceipts | null;
172
+ }): void;
173
+ /** The host has written what it keeps of the route at `executionPath`: its decision no longer carries the
174
+ * receipts a resume would write. */
175
+ routeReceipted(executionPath: unknown): void;
176
+ /** The committed decision of the route at `executionPath`, if it was answered in an earlier process. */
177
+ routeDecision(executionPath: unknown): RouteDecision | undefined;
178
+ /** The escalation that ended this run (a gate that fired, or an LLM step that failed), written once
179
+ * as an escalation commit before anything acts on it. A later open gets the same row and the same
180
+ * continuation identity, whatever fires again. */
181
+ escalate(row: Omit<EscalationRow, "tail" | "revision">): Promise<EscalationRow>;
182
+ escalation(): EscalationRow | undefined;
183
+ /** How many effects the driver admitted. */
184
+ effectCalls(): number;
185
+ /** What the continuation inherited, against the escalation that admitted it: the level, the sizes of what it
186
+ * read and its identity. */
187
+ annotateHandoff(detail: {
188
+ escalation_revision: number;
189
+ tail: string;
190
+ inherit: string;
191
+ block_chars: number;
192
+ digest_chars: number;
193
+ }): Promise<void>;
194
+ /** The run's spend at the moment its continuation is admitted. Spend may land under this run after
195
+ * the escalation commit, so the row the continuation reads the spend from is brought current here,
196
+ * by one `handoff` commit that names the escalation. The escalation's revision, what the
197
+ * continuation binds on, does not change. */
198
+ handoff(spend: Pick<EscalationRow, "cost_usd" | "turns" | "effect_calls">): Promise<EscalationRow>;
199
+ /** The state the document's committed top-level prefix left behind, plus what a failed map's finished
200
+ * items produced under the map's key: what an escalation on a failure carries. */
201
+ lastState(): Record<string, unknown>;
202
+ readonly started: boolean;
203
+ wrapEffect(run: (params: RecoveryEffectParams) => Promise<unknown>): NonNullable<WorkflowDeps["runEffect"]>;
204
+ /** Every commit the driver started has landed; a failed one is thrown. */
205
+ flush: () => Promise<void>;
206
+ /** Let go of the run once every commit the driver started has landed. */
207
+ close(): Promise<void>;
208
+ }>;