@happyvertical/smrt-workflows 0.0.0-stage → 0.62.0

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/AGENTS.md ADDED
@@ -0,0 +1,33 @@
1
+ # smrt-workflows
2
+
3
+ Durable `workflow` runs (#5005; spec: [AI runs](../../docs/content/ai-runs.md)).
4
+ Replaces inference's design runs. `src/driver.ts` (`createWorkflowRunDriver`),
5
+ `src/checkpoint-store.ts` (`createRunCheckpointStore`, `RunConflictError`),
6
+ `src/claim-fence.ts` (`workflowClaimFence`, `workflowStopFence`), `src/types.ts` (`WorkflowStep`,
7
+ `WorkflowDefinition`, `WorkflowRunState`, `RunProgress`). Details:
8
+ [workflow runs](agents/workflow-runs.md).
9
+
10
+ - No models, no tables, no `CREATE TABLE`: runs, events and checkpoints are
11
+ core system DDL. Use core's run API (`openAiRun`, `startAiRunStep`,
12
+ `saveAiRunCheckpoint`, `resumeAiRun`, ...), never SQL on `_smrt_ai_*`.
13
+ - Every step call goes through `resolvePrompt` and core's tracked client
14
+ with the run context; a step's own `execute` must pass `runContext` too.
15
+ - The checkpoint state is the run type's: step index, phase, repair and
16
+ repeat counts, inline input or `inputRef`, accepted outputs. Never tokens,
17
+ attempts or totals (usage rows and events are the record).
18
+ - A stop (budget, child, stop, cancel) is written by core and is never a
19
+ repair; `AiRunClaimLostError` and `RunConflictError` propagate.
20
+ - Depends on core, prompts and jobs only; no smrt peer dependencies, no
21
+ cycle. The root loads under plain Node.
22
+ - Job running (`src/jobs.ts`: `createWorkflowRunJobs`,
23
+ `registerWorkflowRunHandler`, `WORKFLOW_RUN_HANDLER`) is a named job
24
+ handler, not a model target: one handler job per run, run id in the payload,
25
+ claim fencing on. Handler registration must happen before any runner
26
+ claims: creating a host after `TaskRunner.start()` throws
27
+ `JobHandlerRegistrationClosedError`; create hosts at startup, dispose after
28
+ stopping runners. Steps and checks must be safe to repeat (crash recovery
29
+ repeats the step in flight). Details: [workflow runs](agents/workflow-runs.md).
30
+ - A pending job row with no worker stays pending until a worker runs
31
+ (unclaimed-row gap): admitting a run's job does not run it.
32
+
33
+ Validate with package `build`, `typecheck`, `test`; no containers.
package/CLAUDE.md ADDED
@@ -0,0 +1 @@
1
+ @AGENTS.md
package/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ Copyright <2025> <Happy Vertical Corporation>
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4
+
5
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6
+
7
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,120 @@
1
- # Temporary Holding Version
1
+ # @happyvertical/smrt-workflows
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Durable workflow runs for s-m-r-t. A host defines an ordered list of steps; each
4
+ step names a registered prompt, a JSON Schema for its output and an optional
5
+ check. The driver runs them as one `workflow` run on smrt-core's run records
6
+ (see the [AI runs concepts page](../../docs/content/ai-runs.md)):
7
+
8
+ - every step call resolves its prompt through `resolvePrompt` and goes out on
9
+ core's tracked client inside the run, so it is reserved against the run's
10
+ budget and recorded as a `call` event and a usage row carrying the step, the
11
+ attempt and the prompt's template hash;
12
+ - output that fails the schema is repaired (attempt 2, 3, ...) up to the
13
+ budget's `repairRetries`, then the run fails with `repairs_exhausted`;
14
+ - accepted output goes to the host check, recorded as a `check` event; a check
15
+ may reject it (`check_failed`), ask for the step again, finish the run early
16
+ or pause it for a person's approval (`approval` events, one hold per
17
+ gated action; a step passes only with no hold outstanding);
18
+ - a budget limit, a stop or a child run's stop leaves the run `stopped` with a
19
+ typed reason and resumable; a cancel ends it for good; a failed run can be
20
+ retried from its last accepted step as a new run.
21
+
22
+ ## Installation
23
+
24
+ ```bash
25
+ pnpm add @happyvertical/smrt-workflows
26
+ ```
27
+
28
+ Run the application's migrations first. The package creates no tables: runs,
29
+ events and checkpoints live in core's system tables.
30
+
31
+ ## Usage
32
+
33
+ ```ts
34
+ import { createTrackedAiClient } from '@happyvertical/smrt-core';
35
+ import { definePrompt } from '@happyvertical/smrt-prompts';
36
+ import { createWorkflowRunDriver } from '@happyvertical/smrt-workflows';
37
+
38
+ definePrompt({ key: 'kitchen.propose', template: 'Propose a layout for {input}.' });
39
+
40
+ const driver = createWorkflowRunDriver({
41
+ ai: createTrackedAiClient({ db, tenantId }),
42
+ definition: {
43
+ key: 'kitchen-design',
44
+ version: '1',
45
+ steps: [
46
+ {
47
+ name: 'Propose',
48
+ promptKey: 'kitchen.propose',
49
+ schema: layoutSchema,
50
+ check: async (output) => (fits(output) ? {} : { repeat: true }),
51
+ maxRepeats: 2,
52
+ },
53
+ ],
54
+ },
55
+ validate: (schema, output) => ajvErrors(schema, output),
56
+ });
57
+
58
+ const run = await driver.start({
59
+ ownerId,
60
+ input: { room: 'kitchen' },
61
+ budget: { maxTokens: 200_000, maxSteps: 4, repairRetries: 1 },
62
+ });
63
+ // From the background job that holds the run, with its signal and claim:
64
+ await driver.run(run.id, ownerId, { signal, fence: workflowClaimFence(claim) });
65
+ ```
66
+
67
+ `get`, `stop`, `cancel`, `resume` (raise a limit after a budget stop), `decide`
68
+ (a person's approval decision) and `retry` complete the API. Large input is
69
+ passed by reference: start with `inputRef` and supply `readInput`.
70
+
71
+ ## Running from background jobs
72
+
73
+ `createWorkflowRunJobs` is the job bridge. It registers the named job handler
74
+ `@happyvertical/smrt-workflows:workflow-run`, admits one handler job per run
75
+ (`enqueueHandlerJob`, the run id in its payload) and works the run inside it
76
+ with claim fencing and a lease renewed while it works:
77
+
78
+ ```ts
79
+ import { createTrackedAiClient } from '@happyvertical/smrt-core';
80
+ import { TaskRunner } from '@happyvertical/smrt-jobs';
81
+ import { createWorkflowRunJobs } from '@happyvertical/smrt-workflows';
82
+
83
+ // At startup, before any runner starts.
84
+ const workflows = createWorkflowRunJobs<{ room: string }>({
85
+ db,
86
+ definition,
87
+ authorize: async (owner) => assertMayDesign(owner),
88
+ configure: (owner) => ({
89
+ ai: createTrackedAiClient({ db, tenantId: owner.tenantId }),
90
+ validate: (schema, output) => ajvErrors(schema, output),
91
+ }),
92
+ });
93
+ const runner = new TaskRunner({ claimFencing: true });
94
+ await runner.initialize(db);
95
+ await runner.start();
96
+
97
+ const mine = workflows.forOwner(ownerId, tenantId);
98
+ const run = await mine.start({ key: 'request-1', input: { room: 'kitchen' } });
99
+ ```
100
+
101
+ - `start` is idempotent per key and request (the same key with another
102
+ request throws `WorkflowRunKeyConflictError`); `get`, `stop`, `cancel`,
103
+ `resume`, `decide`, `continueAfterApproval` and `retry` follow the driver's.
104
+ A stopped run resumes by admitting a new job; a run that waits for approval
105
+ holds no job, and `decide` admits one.
106
+ - Register before claiming: creating a host (or calling
107
+ `registerWorkflowRunHandler()`) after a `TaskRunner` started throws
108
+ `JobHandlerRegistrationClosedError`. Create a host for every definition a
109
+ worker consumes; a worker without one fails the job and the run is stopped
110
+ or failed on the next read (see [workflow runs](agents/workflow-runs.md)).
111
+ - Steps, checks and prompts must be safe to repeat: after a crash a second
112
+ worker repeats the step that was in flight. Recover with `resume(runId)`
113
+ once the job runner has recovered the dead worker's job.
114
+ - A pending job with no worker stays pending until a worker runs it.
115
+
116
+ ## Validation
117
+
118
+ Run the package `build`, `typecheck` and `test`. Tests run on in-process
119
+ SQLite, DuckDB and PGlite with a scripted model; the PostgreSQL lane runs when
120
+ `SMRT_TEST_POSTGRES_URL` is set.
@@ -0,0 +1,125 @@
1
+ # Workflow runs
2
+
3
+ ## Lifecycle
4
+
5
+ `start` opens a durable `workflow` run through the tracked client
6
+ (`openRun`), with its first checkpoint, in one transaction; it fails with
7
+ `AiRunTrackingDisabledError` while usage tracking is off. `run` works it:
8
+
9
+ 1. Reconciles reservations a dead worker left (`reconcileAiRunOnClaim`).
10
+ 2. Checks the checkpoint's definition version. Another version stops the run
11
+ with `definition_changed`, unless `definition.olderCheckpoints.accepts` it;
12
+ then `migrate` returns the state in this version's shape and the save
13
+ records the new version on the checkpoint and run row.
14
+ 3. Per step: `startAiRunStep` with the checkpoint (counted once per step
15
+ index against `maxSteps`; a re-entry or repeat gets a new step instance),
16
+ then the call with an `AiRunContext` carrying step index, name, instance
17
+ and attempt, and the prompt's call options (`promptMessageOptions`
18
+ without tier keys: params, model, temperature, maxTokens, effort as
19
+ `reasoning`). The judged event of the attempt is the last `call` or
20
+ `handoff` event it added (a fusion answers through a child run and a
21
+ `handoff`).
22
+ 4. Schema errors, unreadable JSON and `AiCallLimitError` are repairable
23
+ attempts; past `budget.repairRetries` the run fails `repairs_exhausted`.
24
+ 5. The check: `failure` → `check` failed, run `failed`/`check_failed`;
25
+ `waitingApproval` → a new `approval` requested (`payload_ref` from
26
+ `holdRef`), run `waiting-approval`. Every `waitingApproval` is a new hold,
27
+ also after an approval: a step gating several actions holds once per
28
+ action, `approvals` (in the checkpoint and the check context) counts the
29
+ ones approved, and the step passes only when its check returns without a
30
+ hold, so a run never ends `done` with a hold outstanding;
31
+ `repeat` → `check` failed, step again up to `maxRepeats`; `complete` →
32
+ `check` passed, run `done`; otherwise `check` passed, next step.
33
+
34
+ `decide` appends the decision event (parent: the request); a run stopped while it waited keeps the decision and stays stopped until `resume`. Otherwise it resumes the run
35
+ (approved: the next `run` counts it, clears the outstanding hold and re-runs the check with `approval: 'approved'`) or
36
+ fails it (`check_failed`). `stop` is `interrupted` (resumable); `cancel` is
37
+ final. `resume` passes the definition version, the app ceiling and the
38
+ reconciler to `resumeAiRun`; a budget stop needs the stopping limit raised.
39
+ `retry` opens a new run with `retry_of_run_id`, carrying the failed run's
40
+ accepted outputs of completed steps; refusals are core's
41
+ `AiRunResumeRefusedError` reasons.
42
+
43
+ ## Leases and fencing
44
+
45
+ With `holder`, `run` writes `{ holder, expiresAt }` to the checkpoint's
46
+ `lease` and renews it every third of `leaseTtlMs` through the same serialized
47
+ save path as the driver's own saves, on the driver's database handle (never a
48
+ second connection). A run refuses a second `run` or `resume` of the same run
49
+ in its process. Across processes, safety is claim fencing: pass
50
+ `workflowClaimFence(getJobClaim(context))` from a runner started with
51
+ `claimFencing: true`; every save, step start, reservation, event and status
52
+ change (done, failed, waiting for approval) asserts it, and a taken-over
53
+ worker gets `AiRunClaimLostError` before it writes: it never fails, finishes or
54
+ stops the run the new worker holds. The stop written when the signal aborts
55
+ uses `stopFence` (default `fence`): `workflowStopFence(claim)` accepts the
56
+ worker's own attempt after its job settled (cancelled, timed out) and refuses
57
+ a claim another worker took over, or a job a newer job of the run replaced
58
+ (stale recovery keeps the worker on its failed row). It locks the run's
59
+ chain root first, down to the run (the accounting lock order, so it never
60
+ deadlocks with a settle on the same chain), before it looks for a newer job,
61
+ and `resume` changes the run's status and admits its new job in one
62
+ accounting transaction (`driver.resume`'s `admit`; retried as a whole on a
63
+ conflict) while holding that row, so a stale stop never lands between them
64
+ and stops the resumed run. Settlements do not assert it: spending that happened is counted.
65
+
66
+ ## Job running (`src/jobs.ts`)
67
+
68
+ `createWorkflowRunJobs({ db, jobs?, definition, queue?, authorize?,
69
+ resumeBudget?, configure })` registers the handler
70
+ `@happyvertical/smrt-workflows:workflow-run` (a `smrt-jobs` named handler, no
71
+ model, no table) and returns `{ handler, dispose, forOwner(ownerId, tenantId) }`.
72
+ `forOwner` has `start`, `get`, `stop`, `cancel`, `resume`, `decide`,
73
+ `continueAfterApproval` and `retry`. `configure(owner, input)` rebuilds the
74
+ driver wiring on every job (after a restart nothing lives in a closure); its
75
+ `ai` must be the owner's tenant on the same `db`.
76
+
77
+ - **Registration before claim.** The jobs registry closes at
78
+ `TaskRunner.start()`. Creating a host calls `registerWorkflowRunHandler()`,
79
+ which unregisters and registers the handler (both throw
80
+ `JobHandlerRegistrationClosedError` while a runner runs, before changing
81
+ anything), so a late host of any definition fails loudly and leaves no route
82
+ behind. One handler serves every definition in the process: the payload's
83
+ `definition` key picks the host; a duplicate key throws. `dispose()` of the
84
+ last host unregisters the handler, so stop runners first.
85
+ - **Admission.** `start` derives the run id from definition key, owner,
86
+ tenant and `key`, stores a digest of the request in the run's tags, opens the
87
+ run and enqueues `enqueueHandlerJob({ handler, payload: { runId, definition
88
+ }, dedupeKey: runId, maxAttempts: 1 })`. Run and job are not one
89
+ transaction: a repeated `start` with the same key admits the job a crash lost.
90
+ A pending job row with no worker stays pending until a worker runs.
91
+ - **The handler** requires an authentic runner context and a claim
92
+ (`claimFencing: true`), reads owner and tenant from the run row (never the
93
+ payload), checks the claim's target, `authorize`s, then `driver.run` with
94
+ `fence: workflowClaimFence(claim)`, `stopFence: workflowStopFence(claim)`,
95
+ the job's signal and
96
+ `holder: workerId:jobId`; the driver renews the checkpoint lease every third
97
+ of `leaseTtlMs`. A failure before the driver began (authorization,
98
+ configuration, missing definition) stops the run (`interrupted`, resumable)
99
+ while the claim is live and fails the job; a failure inside the driver is the
100
+ driver's (`failed` / `error`). `AiRunClaimLostError` propagates and writes
101
+ nothing.
102
+ - **Job ends, run follows** (read by `get` and `resume`): a cancelled job with
103
+ the run still `running` cancels the run; a job failed with any kind but
104
+ stale recovery fails it (`error`); `handler-unregistered` and
105
+ `handler-unclaimed` stop it (resumable once a worker registers the
106
+ handler). Stale recovery (the worker
107
+ died) leaves the run `running`: `resume(runId)` then proves the dead
108
+ dispatch (`assertFailedJobDispatch`) and admits a new job in one
109
+ transaction; the second worker's `reconcileAiRunOnClaim` returns what the
110
+ first reserved. Actions (`execute`, `check`, host effects) are therefore
111
+ at-least-once and must be safe to repeat.
112
+ - **Resume, approval, retry.** A stopped run resumes with `resumeBudget` as
113
+ the host's cap; its new job is admitted in the same transaction. A run at an approval holds no job: `decide`
114
+ waits for the parking job to settle, records the decision and, when
115
+ approved, admits a job that re-runs the check; `continueAfterApproval` does
116
+ the same for a decision recorded elsewhere, and is harmless to repeat.
117
+ `retry` opens the new run and admits its job.
118
+ - **Mixed fleets.** A runner claims a workflow run's job only when its
119
+ process registered the workflow-run handler; a job no such runner claims
120
+ within `handlerUnclaimedDeadlineMs` (default 24 h) fails
121
+ `handler-unclaimed` and the run stops, resumable. A worker that registered
122
+ the handler but created no host for the job's definition still fails that
123
+ job (the run is then failed on the next read), so create every
124
+ definition's host in each process that registers the handler, or give
125
+ definitions their own queues. Upgrade every runner before enqueueing.
@@ -0,0 +1,61 @@
1
+ import { type AiRunCheckpoint, type AiRunClaimFence, type AiRunRow } from '@happyvertical/smrt-core';
2
+ import type { DatabaseInterface } from '@happyvertical/sql';
3
+ import { type WorkflowCheckpointState } from './types.js';
4
+ /**
5
+ * The run moved on underneath the caller (a checkpoint save from an older
6
+ * revision, a run that is no longer where the caller expected, another
7
+ * worker still holding it). Reload its current state.
8
+ */
9
+ export declare class RunConflictError extends Error {
10
+ constructor(message?: string);
11
+ }
12
+ /** A workflow run is not visible to this owner and tenant. */
13
+ export declare class WorkflowRunNotFoundError extends Error {
14
+ readonly runId: string;
15
+ constructor(runId: string);
16
+ }
17
+ /** One workflow run with its checkpoint. */
18
+ export interface LoadedWorkflowRun {
19
+ run: AiRunRow;
20
+ checkpoint: AiRunCheckpoint;
21
+ state: WorkflowCheckpointState;
22
+ }
23
+ /** Input of {@link RunCheckpointStore.save}. */
24
+ export interface SaveRunCheckpointInput {
25
+ expectedRevision: number;
26
+ state: WorkflowCheckpointState;
27
+ lease?: string | null;
28
+ definitionVersion?: string | null;
29
+ }
30
+ /** Owner- and tenant-scoped access to workflow checkpoints. */
31
+ export interface RunCheckpointStore {
32
+ readonly db: DatabaseInterface;
33
+ readonly ownerId: string;
34
+ readonly tenantId: string | null;
35
+ /** The run and its checkpoint, or null when this owner cannot see it. */
36
+ load(runId: string): Promise<LoadedWorkflowRun | null>;
37
+ /**
38
+ * Save with the run row, compare-and-swap on `expectedRevision`, after the
39
+ * claim fence. Throws {@link RunConflictError} when another save won; an
40
+ * `AiRunStoppedError` when the run is no longer `running`.
41
+ */
42
+ save(runId: string, input: SaveRunCheckpointInput): Promise<number>;
43
+ }
44
+ /** Options of {@link createRunCheckpointStore}. */
45
+ export interface RunCheckpointStoreOptions {
46
+ db: DatabaseInterface;
47
+ /** The authenticated owner; never taken from model or tool arguments. */
48
+ ownerId: string;
49
+ tenantId?: string | null;
50
+ /** The job claim of the worker running the run (claim fencing). */
51
+ fence?: AiRunClaimFence;
52
+ }
53
+ /** Whether a stored state has the workflow state's shape. */
54
+ export declare function isWorkflowCheckpointState(value: unknown): value is WorkflowCheckpointState;
55
+ /**
56
+ * Workflow checkpoints in core's `_smrt_ai_run_checkpoints`, scoped to one
57
+ * authenticated owner and tenant. It creates no schema: the table is core
58
+ * system DDL.
59
+ */
60
+ export declare function createRunCheckpointStore(options: RunCheckpointStoreOptions): RunCheckpointStore;
61
+ //# sourceMappingURL=checkpoint-store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../src/checkpoint-store.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,eAAe,EACpB,KAAK,QAAQ,EAId,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,SAAoD;CAIxE;AAED,8DAA8D;AAC9D,qBAAa,wBAAyB,SAAQ,KAAK;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAInC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,QAAQ,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,uBAAuB,CAAC;CAChC;AAED,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,uBAAuB,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACvD;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrE;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,iBAAiB,CAAC;IACtB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,6DAA6D;AAC7D,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAclC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CA6CpB"}
@@ -0,0 +1,25 @@
1
+ import { type AiRunClaimFence } from '@happyvertical/smrt-core';
2
+ import { type JobClaim } from '@happyvertical/smrt-jobs';
3
+ /**
4
+ * Claim fencing for a workflow run worked from a background job: every
5
+ * checkpoint save, step start, reservation, event and status change asserts,
6
+ * inside its own transaction, that this worker still holds the job's claim
7
+ * (`getJobClaim(context)` from a runner started with `claimFencing: true`).
8
+ * A worker whose claim was taken over is refused before it writes.
9
+ */
10
+ export declare function workflowClaimFence(claim: Readonly<JobClaim>): AiRunClaimFence;
11
+ /**
12
+ * The fence of the stop a worker writes when its job's signal aborts: the
13
+ * job may already be settled (cancelled, timed out), so this one accepts the
14
+ * worker's own attempt in any state, and refuses a claim another worker took
15
+ * over and a job that a newer job of the same run (same dedupe key; stale
16
+ * recovery keeps the worker on the failed row) replaced
17
+ * (`WorkflowRunOptions.stopFence`). It locks the durable run's chain, root
18
+ * first (the page's lock order, so a settle on the same chain cannot
19
+ * deadlock with it), before it looks for a newer job: a resume commits the
20
+ * run's status and its new job together while holding that row, so the look
21
+ * sees the new job once the resume has committed (on PostgreSQL each
22
+ * statement reads what committed before it).
23
+ */
24
+ export declare function workflowStopFence(claim: Readonly<JobClaim>): AiRunClaimFence;
25
+ //# sourceMappingURL=claim-fence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"claim-fence.d.ts","sourceRoot":"","sources":["../src/claim-fence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,QAAQ,EAGd,MAAM,0BAA0B,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,eAAe,CAE7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,eAAe,CA8B5E"}
@@ -0,0 +1,154 @@
1
+ import { type AiRunBudget, type AiRunCheckpoint, type AiRunClaimFence, type TrackedAiClient } from '@happyvertical/smrt-core';
2
+ import type { DatabaseInterface } from '@happyvertical/sql';
3
+ import { type RunProgress, type WorkflowCheckpointState, type WorkflowDefinition, type WorkflowRunState } from './types.js';
4
+ /** A step's output could not be read as the step's JSON (a repairable attempt). */
5
+ export declare class WorkflowOutputError extends Error {
6
+ constructor(message: string);
7
+ }
8
+ /** Host wiring of one workflow definition. */
9
+ export interface WorkflowRunDriverOptions {
10
+ /**
11
+ * Core's tracked client of the runs' tenant and database
12
+ * (`createTrackedAiClient`): runs open through it, and every step call is
13
+ * sent on it with the run's context.
14
+ */
15
+ ai: TrackedAiClient;
16
+ definition: WorkflowDefinition;
17
+ /** The host's full JSON Schema validator (Ajv or equal); errors, or none. */
18
+ validate(schema: Record<string, unknown>, output: unknown): readonly string[];
19
+ /** Resolve input passed by reference (`inputRef`). */
20
+ readInput?(ref: string, scope: {
21
+ ownerId: string;
22
+ tenantId: string | null;
23
+ }): Promise<unknown>;
24
+ /** Progress for the host's event stream; its failures never stop work. */
25
+ onProgress?(progress: RunProgress): void | Promise<void>;
26
+ /** The app's ceiling on a budget raised at resume. */
27
+ ceiling?: AiRunBudget;
28
+ /** Lease length while a worker holds a run (default 30 s). */
29
+ leaseTtlMs?: number;
30
+ now?: () => Date;
31
+ }
32
+ /** Input of `start`. */
33
+ export interface StartWorkflowRun {
34
+ /** The authenticated owner. */
35
+ ownerId: string;
36
+ /** Minted when absent. */
37
+ id?: string;
38
+ /** Small input, kept in the checkpoint. */
39
+ input?: unknown;
40
+ /** A pointer at large input the host stores; resolved with `readInput`. */
41
+ inputRef?: string | null;
42
+ budget?: AiRunBudget;
43
+ tags?: Record<string, unknown>;
44
+ experimentId?: string | null;
45
+ datasetItem?: string | null;
46
+ parentRunId?: string | null;
47
+ }
48
+ /** Options of `run`. */
49
+ export interface WorkflowRunOptions {
50
+ /** Cooperative stop: the job's signal. Aborting stops with `interrupted`. */
51
+ signal?: AbortSignal;
52
+ /**
53
+ * Claim fencing: asserts, in every checkpoint save, step start,
54
+ * reservation, event and status change, that this worker still holds the
55
+ * run's job claim. A worker whose claim was taken over changes nothing: the
56
+ * run rejects with `AiRunClaimLostError` and leaves the run to the worker
57
+ * that holds it now.
58
+ */
59
+ fence?: AiRunClaimFence;
60
+ /**
61
+ * The fence of the stop this worker writes when its signal aborts (default
62
+ * `fence`). The job behind that signal may already be settled (cancelled,
63
+ * timed out), so this one accepts this worker's own attempt in any state
64
+ * and refuses only a claim another worker took over
65
+ * (`workflowStopFence(claim)`).
66
+ */
67
+ stopFence?: AiRunClaimFence;
68
+ /** Who holds the run while it works; written to and renewed on the lease. */
69
+ holder?: string;
70
+ }
71
+ /** A lease as stored in the checkpoint's `lease` column. */
72
+ export interface WorkflowRunLease {
73
+ holder: string;
74
+ expiresAt: string;
75
+ }
76
+ /** Read a checkpoint's lease; null when absent or not one of ours. */
77
+ export declare function readWorkflowRunLease(checkpoint: Pick<AiRunCheckpoint, 'lease'>): WorkflowRunLease | null;
78
+ /** The first state of a run. */
79
+ export declare function initialWorkflowState(input: unknown, inputRef: string | null): WorkflowCheckpointState;
80
+ /**
81
+ * The workflow run driver: a host's ordered steps run as one durable
82
+ * `workflow` run (docs/content/ai-runs.md). Each step's call resolves its
83
+ * registered prompt and goes out on the tracked client inside the run, so it
84
+ * is reserved against the budget, recorded as a `call` event and a usage row
85
+ * carrying the step, attempt and template hash, and settled. Invalid output
86
+ * is repaired up to `repairRetries`; accepted output goes to the host check
87
+ * (a `check` event) and may pause for approval (`approval` events). A budget
88
+ * limit stops the run resumable; a child run's stop stops it the same way,
89
+ * never as a repair. It owns no queue: a host runs it from a background job
90
+ * with claim fencing, and the job's signal stops it.
91
+ */
92
+ export declare function createWorkflowRunDriver(options: WorkflowRunDriverOptions): {
93
+ definition: WorkflowDefinition;
94
+ /**
95
+ * Open the durable `workflow` run with its first checkpoint, in one
96
+ * transaction. Throws `AiRunTrackingDisabledError` while usage tracking
97
+ * is off. Schedule `run` on a background job; never on a request.
98
+ */
99
+ start(input: StartWorkflowRun): Promise<WorkflowRunState>;
100
+ /** The run as this owner sees it. */
101
+ get(runId: string, ownerId: string): Promise<WorkflowRunState>;
102
+ /**
103
+ * Work the run until it finishes, stops, fails or waits for approval.
104
+ * Run it only from the job that holds the run, with that job's signal
105
+ * and claim fence. Reconciles reservations a dead worker left behind
106
+ * before the first call.
107
+ */
108
+ run(runId: string, ownerId: string, runOptions?: WorkflowRunOptions): Promise<WorkflowRunState>;
109
+ /** Pause the run (`stopped`, `interrupted`): resumable. */
110
+ stop(runId: string, ownerId: string): Promise<WorkflowRunState>;
111
+ /** End the run for good, with every child run: never resumed or retried. */
112
+ cancel(runId: string, ownerId: string): Promise<WorkflowRunState>;
113
+ /**
114
+ * Resume a stopped run (page section 7): under this definition version
115
+ * (or one that accepts the checkpoint), with limits only raised and at
116
+ * most to the app's ceiling; a budget stop needs the limit that stopped
117
+ * it raised. Reconciles the run's stale reservations first. Then admit
118
+ * its job again: with `admit`, the status change and `admit`'s writes
119
+ * (the new job) commit in one transaction, so no stale worker's stop
120
+ * can land between them.
121
+ */
122
+ resume(runId: string, ownerId: string, resumeOptions?: {
123
+ budget?: AiRunBudget;
124
+ fence?: AiRunClaimFence;
125
+ admit?: (tx: DatabaseInterface, budget: AiRunBudget) => Promise<void>;
126
+ }): Promise<WorkflowRunState>;
127
+ /**
128
+ * Record a person's decision on the approval the run waits for (an
129
+ * `approval` event whose parent is the request). Approved: the run goes
130
+ * back to `running` and its next `run` re-runs the check with the
131
+ * approval; refused: the run fails with `check_failed`. A run stopped
132
+ * while it waited keeps the decision and stays stopped: `resume` then
133
+ * continues with it.
134
+ */
135
+ decide(runId: string, ownerId: string, decision: {
136
+ approved: boolean;
137
+ note?: string;
138
+ }): Promise<WorkflowRunState>;
139
+ /**
140
+ * Retry a failed run from its last accepted step (page section 7): a new
141
+ * durable run naming it in `retry_of_run_id`, inheriting only the
142
+ * accepted outputs of its completed steps; its totals start at zero and
143
+ * the inherited steps are not counted against its `maxSteps`. Refused
144
+ * with `AiRunResumeRefusedError` (`not_retryable`, `definition_changed`,
145
+ * `retry_source_pruned`) and nothing is opened.
146
+ */
147
+ retry(runId: string, ownerId: string, retryOptions?: {
148
+ id?: string;
149
+ budget?: AiRunBudget;
150
+ }): Promise<WorkflowRunState>;
151
+ };
152
+ /** A workflow run driver. */
153
+ export type WorkflowRunDriver = ReturnType<typeof createWorkflowRunDriver>;
154
+ //# sourceMappingURL=driver.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @happyvertical/smrt-workflows: durable workflow runs (docs/content/ai-runs.md).
3
+ * A host's ordered steps, each a registered prompt with a schema and a check,
4
+ * run as one `workflow` run on core's run records and checkpoints.
5
+ */
6
+ export { createRunCheckpointStore, isWorkflowCheckpointState, type LoadedWorkflowRun, type RunCheckpointStore, type RunCheckpointStoreOptions, RunConflictError, type SaveRunCheckpointInput, WorkflowRunNotFoundError, } from './checkpoint-store.js';
7
+ export { workflowClaimFence, workflowStopFence } from './claim-fence.js';
8
+ export { createWorkflowRunDriver, initialWorkflowState, readWorkflowRunLease, type StartWorkflowRun, WorkflowOutputError, type WorkflowRunDriver, type WorkflowRunDriverOptions, type WorkflowRunLease, type WorkflowRunOptions, } from './driver.js';
9
+ export { createWorkflowRunJobs, registerWorkflowRunHandler, type StartWorkflowRunJob, WORKFLOW_RUN_HANDLER, WorkflowRunJobError, type WorkflowRunJobPayload, type WorkflowRunJobs, type WorkflowRunJobsOptions, WorkflowRunKeyConflictError, type WorkflowRunOwner, } from './jobs.js';
10
+ export { type RunProgress, WORKFLOW_RUN_TYPE, WORKFLOW_STATE_VERSION, type WorkflowCheckContext, type WorkflowCheckpointState, type WorkflowDefinition, type WorkflowRunState, type WorkflowStep, type WorkflowStepCheck, type WorkflowStepContext, type WorkflowStepExecute, } from './types.js';
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,2BAA2B,EAC3B,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,WAAW,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC"}