@yolk-sdk/vercel-workflows 0.1.0-canary.67 → 0.1.0-canary.68
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 +32 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ Vercel Workflow agent-loop contracts, durable stream helpers, and an Effect-nati
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
pnpm add @yolk-sdk/vercel-workflows@canary effect workflow
|
|
8
|
+
pnpm add @yolk-sdk/vercel-workflows@canary effect workflow@^5.0.0-beta.42
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
|
|
@@ -59,11 +59,40 @@ const program = Effect.gen(function* () {
|
|
|
59
59
|
The API wrapper keeps Vercel's SDK underneath. It does not reimplement Vercel backend HTTP,
|
|
60
60
|
queues, hooks, or stream storage.
|
|
61
61
|
|
|
62
|
+
## Test Workflow behavior
|
|
63
|
+
|
|
64
|
+
`@yolk-sdk/vercel-workflows/testing` provides `TestWorkflowWorld`, a behavioral emulator for host
|
|
65
|
+
tests. It covers run lifecycle, append-only streams with close-once conflicts, step retries and
|
|
66
|
+
attempt metadata, hooks/resume, cancellation, and the SDK seam used by
|
|
67
|
+
`VercelWorkflows.layerFromSdk`. Ambient module mocks do not apply retry policy by themselves: wrap
|
|
68
|
+
host step callbacks with `world.step(...)` or call `world.runStep(...)` explicitly when the test
|
|
69
|
+
must exercise platform retry attempts and `getStepMetadata().attempt`.
|
|
70
|
+
|
|
71
|
+
Mock the ambient `workflow` module so production orchestration runs against the active test world:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { vi } from 'vitest'
|
|
75
|
+
import { TestWorkflowWorld } from '@yolk-sdk/vercel-workflows/testing'
|
|
76
|
+
|
|
77
|
+
vi.mock('workflow', async () => {
|
|
78
|
+
const { testWorkflowModule } = await import('@yolk-sdk/vercel-workflows/testing')
|
|
79
|
+
return testWorkflowModule
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
const world = new TestWorkflowWorld()
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Tests whose import graph reaches `workflow` must use Vitest's Node environment, not jsdom, because
|
|
86
|
+
Workflow 5 captures Node `URL` intrinsics at import time. Hosts should test their own `'use workflow'`
|
|
87
|
+
and `'use step'` directive files with `@workflow/vitest` in addition to using the emulator.
|
|
88
|
+
|
|
62
89
|
## Runtime model
|
|
63
90
|
|
|
64
91
|
`runVercelAgentWorkflow` coordinates host-provided callbacks:
|
|
65
92
|
|
|
66
93
|
- model step: produce model events/tool calls
|
|
94
|
+
- no-tool continuation: when a model step returns `done: false` with no tool calls, continue
|
|
95
|
+
directly to the next model step without invoking the tool-batch callback
|
|
67
96
|
- tool batch step: execute requested tools
|
|
68
97
|
- tool batch result: return one ordered tool-result message per host call, including failed `isError` results
|
|
69
98
|
- partial tool-step failure: return wire-safe `failure`, cumulative `usage`, and `eventSequence` when
|
|
@@ -222,7 +251,8 @@ Never close on resumable `AgentAwaitingInput`.
|
|
|
222
251
|
- Write durable terminal events only after host persistence has settled.
|
|
223
252
|
- Implement `closeStream` for successful final closure and `writeError` for safe final error write
|
|
224
253
|
plus failure closure. Release, but do not close, the writer after `AgentAwaitingInput`.
|
|
225
|
-
- Test directive
|
|
254
|
+
- Test host-owned Workflow directive files with `@workflow/vitest`; use the `./testing` emulator for
|
|
255
|
+
platform behavior in host tests.
|
|
226
256
|
|
|
227
257
|
## Boundaries
|
|
228
258
|
|