@yolk-sdk/vercel-workflows 0.1.0-canary.97 → 0.1.0-canary.99
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 +33 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -143,6 +143,36 @@ export async function runAgentWorkflow(input: { request: unknown; context: unkno
|
|
|
143
143
|
`runToolBatchStep` may instead be Workflow orchestration calling concrete per-call steps. Keep provider calls, tools, persistence, telemetry, and Effect runtimes in
|
|
144
144
|
those steps, not in the `'use workflow'` orchestration body.
|
|
145
145
|
|
|
146
|
+
## Tool steps are at-least-once
|
|
147
|
+
|
|
148
|
+
Vercel's queue delivers steps at least once. A tool-batch step can run again after a crash and,
|
|
149
|
+
in practice, concurrently with a first execution that is still running, even with
|
|
150
|
+
`noWorkflowStepRetry`. Retry policy cannot prevent duplicate writes; a durable tool ledger can.
|
|
151
|
+
This package does not build tool sets or call `runToolBatch` (your step does), so wire the ledger
|
|
152
|
+
where you resolve tools inside the step:
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
// Inside the host's tool-batch 'use step' function.
|
|
156
|
+
const resolveStepTools = Effect.gen(function* () {
|
|
157
|
+
return yield* resolveTools(modules, context, {
|
|
158
|
+
ledger: { store: makeRunToolLedger(workflowRunId), deadline: () => stepDeadlineMs }
|
|
159
|
+
})
|
|
160
|
+
})
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`resolveTools` and `ToolLedgerStore` come from `@yolk-sdk/agent/tools` (install
|
|
164
|
+
`@yolk-sdk/agent@canary` in the host; this package does not depend on it); `makeRunToolLedger` is
|
|
165
|
+
your durable store (for example Postgres) scoped to the Workflow run. Ledgered calls (by default every
|
|
166
|
+
non-`read` tool plus the built-in `subagent` tool, including code mode scripts and their nested
|
|
167
|
+
writes) then return their recorded result, wait for the running execution, or report that an
|
|
168
|
+
abandoned call may already have been applied; they never run twice under the same ledger key.
|
|
169
|
+
Add custom delegation tools with `isLedgered`. Input and interaction tools are never ledgered (they
|
|
170
|
+
rely on the host's `InteractionHost` receipts). Read calls still re-run, and after an in-flight
|
|
171
|
+
timeout the model may retry under a new call id. An in-memory store does not protect steps.
|
|
172
|
+
`deadline` bounds only waiting for a duplicate: recording a call's outcome can take up to about
|
|
173
|
+
15 s after the call returns, so leave that time before the function budget ends, and keep store
|
|
174
|
+
operations interruptible (the ledger's timeouts cannot cut uninterruptible store work).
|
|
175
|
+
|
|
146
176
|
## Independent children
|
|
147
177
|
|
|
148
178
|
`orchestrateWorkflowToolBatch` runs a full-batch `preflight` before any `execute` callback,
|
|
@@ -195,6 +225,9 @@ streamed retries can duplicate chunks unless host/client de-dupe is ready.
|
|
|
195
225
|
Finite `maxAttempts` values are floored and clamped to at least one; non-finite values normalize to
|
|
196
226
|
one. Retries have no built-in backoff.
|
|
197
227
|
|
|
228
|
+
One attempt does not stop queue redelivery: a step can still run again after a crash or
|
|
229
|
+
concurrently. See [Tool steps are at-least-once](#tool-steps-are-at-least-once).
|
|
230
|
+
|
|
198
231
|
`maxTurns` follows the same positive-integer boundary: finite values are floored and clamped to at
|
|
199
232
|
least one. Omitted or non-finite values use `defaultMaxWorkflowTurns`.
|
|
200
233
|
|