@niwa-labs/workflow 0.0.0-stage → 0.0.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/LICENSE +21 -0
- package/README.md +13 -2
- package/package.json +55 -4
- package/src/actions.ts +408 -0
- package/src/agent.ts +211 -0
- package/src/ask.ts +84 -0
- package/src/bridge.ts +710 -0
- package/src/catalogue.ts +74 -0
- package/src/check.ts +880 -0
- package/src/child.ts +1378 -0
- package/src/cockpit/actions.ts +128 -0
- package/src/cockpit/catalogue-actions.ts +97 -0
- package/src/cockpit/dashboard.tsx +134 -0
- package/src/cockpit/groups.ts +45 -0
- package/src/cockpit/index.tsx +50 -0
- package/src/cockpit/launch.tsx +136 -0
- package/src/cockpit/plan.ts +101 -0
- package/src/cockpit/run-commands.tsx +102 -0
- package/src/cockpit/run-page.tsx +140 -0
- package/src/cockpit/run-summary.ts +16 -0
- package/src/cockpit/runs.tsx +73 -0
- package/src/cockpit/statistics.tsx +176 -0
- package/src/cockpit/track.tsx +159 -0
- package/src/cockpit/workflows.tsx +383 -0
- package/src/describe-cache.ts +122 -0
- package/src/describe.ts +174 -0
- package/src/guide.ts +213 -0
- package/src/index.ts +2813 -0
- package/src/inspect.ts +235 -0
- package/src/installation.ts +90 -0
- package/src/language.ts +217 -0
- package/src/records-entry.ts +63 -0
- package/src/records.ts +574 -0
- package/src/registry.ts +250 -0
- package/src/revise.ts +89 -0
- package/src/runner.ts +339 -0
- package/src/script-types.ts +549 -0
- package/src/stats.ts +460 -0
- package/src/status.ts +512 -0
- package/src/store.ts +259 -0
- package/src/subscriptions.ts +102 -0
- package/src/waiting.ts +61 -0
- package/test/cockpit-actions.test.ts +20 -0
- package/test/cockpit-groups.test.ts +42 -0
- package/test/cockpit-plan.test.ts +118 -0
- package/test/fixtures/branches-host.ts +58 -0
- package/test/fixtures/branches-script.js +23 -0
- package/test/fixtures/bridge-host.ts +23 -0
- package/test/fixtures/bridge-keys-script.js +15 -0
- package/test/fixtures/bridge-wait-script.js +8 -0
- package/test/fixtures/cancel-host.ts +58 -0
- package/test/fixtures/cancel-script.js +12 -0
- package/test/fixtures/crash-host.ts +61 -0
- package/test/fixtures/crash-script.js +14 -0
- package/test/fixtures/ping-records.ts +20 -0
- package/test/fixtures/revision-host.ts +57 -0
- package/test/fixtures/revision-script.js +11 -0
- package/test/fixtures/running-host.ts +61 -0
- package/test/fixtures/running-script.js +12 -0
- package/test/fixtures/with-data/flow.ts +2 -0
- package/test/fixtures/with-data/table.json +1 -0
- package/test/git-repo.ts +45 -0
- package/test/git-worktree.test.ts +413 -0
- package/test/question-format.test.ts +279 -0
- package/test/workflow-agent-caps.test.ts +91 -0
- package/test/workflow-agent-lifetime.test.ts +93 -0
- package/test/workflow-agent-options.test.ts +216 -0
- package/test/workflow-agent-schema.test.ts +386 -0
- package/test/workflow-agent-typings.test.ts +241 -0
- package/test/workflow-ask-resume.test.ts +145 -0
- package/test/workflow-branch-keys.test.ts +133 -0
- package/test/workflow-bridge-inproc.test.ts +230 -0
- package/test/workflow-bridge.test.ts +141 -0
- package/test/workflow-builtin-candidate.test.ts +230 -0
- package/test/workflow-builtin.test.ts +197 -0
- package/test/workflow-cancel-agent.test.ts +144 -0
- package/test/workflow-cancel.test.ts +166 -0
- package/test/workflow-chain.test.ts +84 -0
- package/test/workflow-check-options.test.ts +144 -0
- package/test/workflow-check-uses.test.ts +148 -0
- package/test/workflow-check.test.ts +282 -0
- package/test/workflow-contract.test.ts +295 -0
- package/test/workflow-crash-resume.test.ts +141 -0
- package/test/workflow-deadline.test.ts +102 -0
- package/test/workflow-describe-cache.test.ts +240 -0
- package/test/workflow-directory.test.ts +73 -0
- package/test/workflow-emits.test.ts +261 -0
- package/test/workflow-group-keys.test.ts +72 -0
- package/test/workflow-harnesses.test.ts +262 -0
- package/test/workflow-inspect.test.ts +152 -0
- package/test/workflow-language-types.test.ts +148 -0
- package/test/workflow-manifest.test.ts +93 -0
- package/test/workflow-manual-pause.test.ts +116 -0
- package/test/workflow-owners.test.ts +154 -0
- package/test/workflow-pause.test.ts +200 -0
- package/test/workflow-phases.test.ts +445 -0
- package/test/workflow-plugin-entries.test.ts +59 -0
- package/test/workflow-record-refs.test.ts +310 -0
- package/test/workflow-replay.test.ts +206 -0
- package/test/workflow-resume-once.test.ts +188 -0
- package/test/workflow-revision.test.ts +216 -0
- package/test/workflow-scope.test.ts +505 -0
- package/test/workflow-script-defaults.test.ts +119 -0
- package/test/workflow-script-error.test.ts +228 -0
- package/test/workflow-script-libraries.test.ts +88 -0
- package/test/workflow-script-packages.test.ts +119 -0
- package/test/workflow-stdout.test.ts +89 -0
- package/test/workflow-stop.test.ts +299 -0
- package/test/workflow-store.test.ts +220 -0
- package/test/workflow-visible.test.ts +136 -0
- package/test/workflow-wait-version.test.ts +54 -0
- package/test/workflow-wait.test.ts +224 -0
- package/test/workflow-waiting-agent.test.ts +64 -0
- package/tsconfig.json +15 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,14 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/workflow
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Durable workflows: the runner, the static check, the registry and store, branch scopes, and candidate versions.
|
|
4
|
+
|
|
5
|
+
A workflow is a script that niwa runs in a disposable process and answers call by call, so a run
|
|
6
|
+
survives the death of the host and resumes from its journal. Registered versions keep a copy of
|
|
7
|
+
their source under the home. Plugins hand it scripts of their own through the `BUILTIN_WORKFLOW`
|
|
8
|
+
offer.
|
|
9
|
+
|
|
10
|
+
The module reads the record types and the offers of the plugins installed before it, so install
|
|
11
|
+
`timers` and every plugin that offers a built-in workflow ahead of `workflow()`.
|
|
12
|
+
|
|
13
|
+
The `./records` entry exports the records, the action references and the pure readers of runs,
|
|
14
|
+
installations and versions, for plugins that read workflows without importing the module itself.
|
package/package.json
CHANGED
|
@@ -1,6 +1,57 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/workflow",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts",
|
|
8
|
+
"./records": "./src/records-entry.ts",
|
|
9
|
+
"./cockpit": "./src/cockpit/index.tsx"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@niwa-labs/cockpit-sdk": "0.0.0",
|
|
13
|
+
"@niwa-labs/core": "0.0.0",
|
|
14
|
+
"@niwa-labs/flow": "0.0.0",
|
|
15
|
+
"@niwa-labs/flow-code": "0.0.0",
|
|
16
|
+
"@niwa-labs/flow-eval": "0.0.0",
|
|
17
|
+
"@niwa-labs/git": "0.0.0",
|
|
18
|
+
"@niwa-labs/harness": "0.0.0",
|
|
19
|
+
"@niwa-labs/history": "0.0.0",
|
|
20
|
+
"@niwa-labs/plugin": "0.0.0",
|
|
21
|
+
"@niwa-labs/requests": "0.0.0",
|
|
22
|
+
"@niwa-labs/sandbox": "0.0.0",
|
|
23
|
+
"@niwa-labs/script": "0.0.0",
|
|
24
|
+
"@niwa-labs/sessions": "0.0.0",
|
|
25
|
+
"@niwa-labs/tasks": "0.0.0",
|
|
26
|
+
"@niwa-labs/timer": "0.0.0",
|
|
27
|
+
"@niwa-labs/ui-kit": "0.0.0",
|
|
28
|
+
"@types/bun": "^1.4.4",
|
|
29
|
+
"typescript": "~5.9.3",
|
|
30
|
+
"zod": "^4.6.7"
|
|
31
|
+
},
|
|
32
|
+
"devDependencies": {
|
|
33
|
+
"@happy-dom/global-registrator": "^21.0.4",
|
|
34
|
+
"@niwa-labs/testing": "0.0.0",
|
|
35
|
+
"@tanstack/react-query": "^5.108.2",
|
|
36
|
+
"@types/react": "^19.3.0",
|
|
37
|
+
"@types/react-dom": "^19.3.0",
|
|
38
|
+
"react": "^19.3.1",
|
|
39
|
+
"react-dom": "^19.3.1"
|
|
40
|
+
},
|
|
41
|
+
"peerDependencies": {
|
|
42
|
+
"@tanstack/react-query": "^5.108.2",
|
|
43
|
+
"react": "^19.3.1",
|
|
44
|
+
"react-dom": "^19.3.1"
|
|
45
|
+
},
|
|
46
|
+
"peerDependenciesMeta": {
|
|
47
|
+
"@tanstack/react-query": {
|
|
48
|
+
"optional": true
|
|
49
|
+
},
|
|
50
|
+
"react": {
|
|
51
|
+
"optional": true
|
|
52
|
+
},
|
|
53
|
+
"react-dom": {
|
|
54
|
+
"optional": true
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
package/src/actions.ts
ADDED
|
@@ -0,0 +1,408 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The actions of the workflow module, as typed references: name, description and the two schemas.
|
|
3
|
+
*
|
|
4
|
+
* A caller imports these to call a workflow action with input and output checked by the type
|
|
5
|
+
* checker, on the host and on a client. The module's factory builds its real actions from the same
|
|
6
|
+
* references (`action(workflowStart, { recovery, run })`).
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
|
|
11
|
+
import { EntityDescription, IdText, JsonValueSchema, actionRef, getRef, listRef } from "@niwa-labs/core";
|
|
12
|
+
|
|
13
|
+
import {
|
|
14
|
+
Builtin,
|
|
15
|
+
CheckProblem,
|
|
16
|
+
ContractHash,
|
|
17
|
+
EmittedRecord,
|
|
18
|
+
FlowCall,
|
|
19
|
+
InstallationId,
|
|
20
|
+
JsonSchemaValue,
|
|
21
|
+
RunId,
|
|
22
|
+
Subscription,
|
|
23
|
+
TrialVersion,
|
|
24
|
+
WorkflowId,
|
|
25
|
+
WorkflowVersion,
|
|
26
|
+
} from "./records.ts";
|
|
27
|
+
import { WorkflowPhases } from "./language.ts";
|
|
28
|
+
import { RunEntry, RunState, RunStatus } from "./status.ts";
|
|
29
|
+
import { WorkflowInspection } from "./inspect.ts";
|
|
30
|
+
|
|
31
|
+
/** An absolute path: a POSIX root, or a drive letter and a separator. */
|
|
32
|
+
const ABSOLUTE_PATH = /^(\/|[A-Za-z]:[\\/])/;
|
|
33
|
+
|
|
34
|
+
export const StartInput = z.object({
|
|
35
|
+
/** The registered workflow to run, at its latest version: its id or any text that names it. */
|
|
36
|
+
id: IdText.optional(),
|
|
37
|
+
/**
|
|
38
|
+
* With `id`: run this version of it instead of the latest. A candidate version of a gated built-in is started only by a
|
|
39
|
+
* run in the trusted suite's pinned trial.
|
|
40
|
+
*/
|
|
41
|
+
version: WorkflowVersion.optional(),
|
|
42
|
+
/** A script file to run once, unregistered. A start names `id` or `file`, not both. */
|
|
43
|
+
file: z.string().optional(),
|
|
44
|
+
args: z.unknown().optional(),
|
|
45
|
+
label: z.string().optional(),
|
|
46
|
+
/** Run the script process in an empty box. Default: the module's own choice, which is no box. */
|
|
47
|
+
box: z.boolean().optional(),
|
|
48
|
+
/**
|
|
49
|
+
* The directory the run is for, an absolute path: the project it belongs to, which the cockpit groups runs by. The CLI and
|
|
50
|
+
* the MCP server fill it with their working directory when the caller names none; a start with none has no directory.
|
|
51
|
+
*/
|
|
52
|
+
directory: z.string().regex(ABSOLUTE_PATH, "a directory is an absolute path").optional(),
|
|
53
|
+
/** The most branches each scope of the run runs at once; a scope's own lower limit holds. Default: no limit from outside. */
|
|
54
|
+
concurrency: z.number().int().positive().optional(),
|
|
55
|
+
/**
|
|
56
|
+
* The limits of the run: `depth`, how many runs deep its tree may go, the run itself being one; `deadline`, how long the
|
|
57
|
+
* whole script may take, in milliseconds. A run that reaches its deadline pauses until it is extended or cancelled. Its
|
|
58
|
+
* child runs take them, and never end later than it.
|
|
59
|
+
*/
|
|
60
|
+
limits: z.object({ depth: z.number().int().positive().optional(), deadline: z.number().int().positive().optional() }).optional(),
|
|
61
|
+
/**
|
|
62
|
+
* Rules that narrow the run below what `uses` and the caller give it, never wider: a call of the run is decided on its
|
|
63
|
+
* final input against them. A rule the run would not have refuses the start.
|
|
64
|
+
*/
|
|
65
|
+
allow: z.array(z.string().min(1)).optional(),
|
|
66
|
+
/** Answer when the run finishes or pauses, or when `timeoutMs` has passed, as `workflow.wait` does. Default: answer at once. */
|
|
67
|
+
wait: z.boolean().optional(),
|
|
68
|
+
/** With `wait`: how long to wait, in milliseconds. Default: a minute. */
|
|
69
|
+
timeoutMs: z.number().int().positive().optional(),
|
|
70
|
+
});
|
|
71
|
+
export const RunInput = z.object({ run: z.string() });
|
|
72
|
+
/** What a resume may say: which run, and with `choice` how to answer its pause. */
|
|
73
|
+
/** Run again the steps from one on: a step key, the key prefix of a branch or a scope, or the title of a phase. */
|
|
74
|
+
const From = z.string().min(1);
|
|
75
|
+
export const ResumeInput = RunInput.extend({
|
|
76
|
+
/** Answer the pause of the run: retry the step it paused on, skip it, or cancel the run. Without it the run is started again from the top. */
|
|
77
|
+
choice: z.enum(["retry", "skip", "cancel"]).optional(),
|
|
78
|
+
/** Started again from the top, run the steps from this one on instead of taking them from the earlier start. */
|
|
79
|
+
from: From.optional(),
|
|
80
|
+
});
|
|
81
|
+
export const ReviseInput = z.object({ run: z.string(), file: z.string(), from: From.optional() });
|
|
82
|
+
|
|
83
|
+
export const RunOutput = z.object({ run: RunId, finished: z.boolean() });
|
|
84
|
+
|
|
85
|
+
/** What a start answers: the run, and with `wait` where it got to. */
|
|
86
|
+
export const StartOutput = RunOutput.merge(RunStatus.partial().omit({ run: true }));
|
|
87
|
+
|
|
88
|
+
export const WaitInput = z.object({
|
|
89
|
+
run: z.string(),
|
|
90
|
+
/** How long to wait, in milliseconds. Default: a minute. */
|
|
91
|
+
timeoutMs: z.number().int().positive().optional(),
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
export const RunsInput = z.object({
|
|
95
|
+
/** Only the runs in this state. */
|
|
96
|
+
state: RunState.optional(),
|
|
97
|
+
/** Only the latest this many runs. */
|
|
98
|
+
limit: z.number().int().positive().optional(),
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
/** What a revision found: the calls taken from the earlier starts of the run, and the ones that run again. */
|
|
102
|
+
export const Revision = z.object({
|
|
103
|
+
reused: z.array(z.object({ key: z.string(), action: z.string(), input: JsonValueSchema, outcome: JsonValueSchema })),
|
|
104
|
+
rerun: z.array(
|
|
105
|
+
z.object({
|
|
106
|
+
key: z.string(),
|
|
107
|
+
action: z.string(),
|
|
108
|
+
input: JsonValueSchema,
|
|
109
|
+
reason: z.enum(["new", "changed", "unfinished", "after a change", "recomputed"]),
|
|
110
|
+
}),
|
|
111
|
+
),
|
|
112
|
+
/** Why the edited script could not be read to its end, when it could not. */
|
|
113
|
+
unresolved: z.string().optional(),
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
export const CheckInput = z.object({ file: z.string() });
|
|
117
|
+
|
|
118
|
+
/** One error of a check, with its place in the file. */
|
|
119
|
+
export const CheckError = CheckProblem;
|
|
120
|
+
|
|
121
|
+
/** What a script declares: its description, its schemas as JSON Schema, and the hash of the two schemas. */
|
|
122
|
+
export const ScriptContract = z.object({
|
|
123
|
+
description: z.string().optional(),
|
|
124
|
+
/** What the script takes: absent for a script with no `input` and for a script with `on`, which is given the record. */
|
|
125
|
+
input: JsonSchemaValue.optional(),
|
|
126
|
+
/** What the script returns: absent when it returns nothing. */
|
|
127
|
+
output: JsonSchemaValue.optional(),
|
|
128
|
+
contract: ContractHash,
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
/** A check: the errors, and what the script declares when its schemas could be read. */
|
|
132
|
+
export const CheckOutput = ScriptContract.partial().extend({
|
|
133
|
+
/** The records the script emits: the name it gives each, its type `wf.<name>.<record>`, and the JSON Schema of its data. */
|
|
134
|
+
emits: z.array(EmittedRecord).optional(),
|
|
135
|
+
/** The phases the script declares, in order. */
|
|
136
|
+
phases: WorkflowPhases.optional(),
|
|
137
|
+
file: z.string(),
|
|
138
|
+
ok: z.boolean(),
|
|
139
|
+
errors: z.array(CheckError),
|
|
140
|
+
/** What the check could not settle, such as an `ask()` call whose harness is known only when the script runs; absent when there is none. */
|
|
141
|
+
warnings: z.array(CheckError).optional(),
|
|
142
|
+
note: z.literal("described, the script was not run"),
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
export const GuideOutput = z.object({
|
|
146
|
+
/** How to write a script. */
|
|
147
|
+
guide: z.string(),
|
|
148
|
+
/** The typing of a script, generated from the actions the caller may call. */
|
|
149
|
+
declarations: z.string(),
|
|
150
|
+
/** The actions the caller may call, with the type of their input as the declarations name it. */
|
|
151
|
+
actions: z.array(z.object({ name: z.string(), description: z.string(), input: z.string() })),
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
export const ReviseOutput = RunOutput.extend({ revision: Revision });
|
|
155
|
+
|
|
156
|
+
export const ResumeOutput = RunOutput.extend({ revision: Revision.optional() });
|
|
157
|
+
|
|
158
|
+
export const workflowStart = actionRef("workflow.start", {
|
|
159
|
+
description:
|
|
160
|
+
"Run a script now: a registered workflow by its id (its latest version), or a script file run once, and the arguments it gets. It starts one run and subscribes to nothing (workflow.install does that). Answers the id of the run (run-…). A broken workflow does not start.",
|
|
161
|
+
input: StartInput,
|
|
162
|
+
output: StartOutput,
|
|
163
|
+
});
|
|
164
|
+
|
|
165
|
+
export const workflowResume = actionRef("workflow.resume", {
|
|
166
|
+
description: "Run a workflow again from the top: the calls along the longest unchanged prefix of the earlier start are taken from it (each marked as taken), and the first new or changed call and everything after it run; a call with an effect that was made before is never made twice. from names a step, a branch or a phase to run again from. A script that was edited is a revision, and the answer says what is taken and what runs. With choice (retry, skip or cancel) it answers the pause of the run instead. For whoever started the run, and the owner.",
|
|
167
|
+
input: ResumeInput,
|
|
168
|
+
output: ResumeOutput,
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
/** What a pause may say: which run, and with `effects: "deny"` a hold instead of a pause at a boundary. */
|
|
172
|
+
export const PauseInput = RunInput.extend({
|
|
173
|
+
/**
|
|
174
|
+
* `"deny"`: hold the run instead of pausing it. A new call of an action that writes or cannot be undone is refused;
|
|
175
|
+
* reads and niwa's own records go on, and operations already going are left to end.
|
|
176
|
+
*/
|
|
177
|
+
effects: z.literal("deny").optional(),
|
|
178
|
+
/** With `effects: "deny"`: hold the runs this run started too, at any depth. A pause at a boundary goes down the tree by itself. */
|
|
179
|
+
tree: z.boolean().optional(),
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
export const workflowPause = actionRef("workflow.pause", {
|
|
183
|
+
description:
|
|
184
|
+
'Request a durable pause at a workflow boundary. Operations already admitted can complete. Answers the current state and the pause identifier. With effects: "deny" the run is held instead: new writes and irreversible calls are refused while reads and records of niwa\'s own go on; the hold is holding while operations it began are still going (listed in hold.inFlight) and held once they ended; tree: true holds the runs it started too. workflow.continue with the hold\'s id releases it. For whoever started the run, and the owner.',
|
|
185
|
+
input: PauseInput,
|
|
186
|
+
output: RunStatus,
|
|
187
|
+
});
|
|
188
|
+
|
|
189
|
+
export const workflowBuiltinTrial = actionRef("workflow.builtin.trial", {
|
|
190
|
+
description: "Pin the offered versions for an approved built-in suite run and its descendants. Only the plugin's designated suite may open a trial.",
|
|
191
|
+
input: z.strictObject({}),
|
|
192
|
+
output: z.object({ entries: z.array(TrialVersion) }),
|
|
193
|
+
});
|
|
194
|
+
|
|
195
|
+
export const workflowBuiltinPromote = actionRef("workflow.builtin.promote", {
|
|
196
|
+
description: "Accept all candidates pinned by this suite run. If the proposal or the accepted set has changed, accept none and return stale.",
|
|
197
|
+
input: z.strictObject({}),
|
|
198
|
+
output: z.object({
|
|
199
|
+
status: z.enum(["promoted", "stale"]),
|
|
200
|
+
run: RunId,
|
|
201
|
+
versions: z.array(z.object({ workflow: WorkflowId, version: WorkflowVersion })),
|
|
202
|
+
}),
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
export const workflowContinue = actionRef("workflow.continue", {
|
|
206
|
+
description: "Release the specified manual pause and let the same workflow invocation continue. An outstanding question or failed step keeps its own state. For whoever started the run, and the owner.",
|
|
207
|
+
input: RunInput.extend({ pause: z.string().min(1) }),
|
|
208
|
+
output: RunStatus,
|
|
209
|
+
});
|
|
210
|
+
|
|
211
|
+
export const workflowRevise = actionRef("workflow.revise", {
|
|
212
|
+
description: "Resume a run on an edited script: the calls along the longest unchanged prefix of the earlier start are taken from it, and the first new or changed call and everything after it run; a call with an effect that was made before is never made twice. from names a step, a branch or a phase to run again from.",
|
|
213
|
+
input: ReviseInput,
|
|
214
|
+
output: ReviseOutput,
|
|
215
|
+
});
|
|
216
|
+
|
|
217
|
+
/** What a stop names: the run, and a branch, scope or step of it by its key prefix; with none, the whole run. */
|
|
218
|
+
export const StopInput = RunInput.extend({
|
|
219
|
+
/** The key prefix of what is stopped: a scope (`@review`), a branch of it (`@review.a`), or a step. Absent: the whole run. */
|
|
220
|
+
at: z.string().min(1).optional(),
|
|
221
|
+
/** Stop through the shields under it as well: their blocks are not waited for. */
|
|
222
|
+
force: z.boolean().optional(),
|
|
223
|
+
/** Why it is stopped, which the cancelled steps keep. Default: stopped by the owner. */
|
|
224
|
+
reason: z.string().min(1).optional(),
|
|
225
|
+
});
|
|
226
|
+
|
|
227
|
+
export const workflowStop = actionRef("workflow.stop", {
|
|
228
|
+
description:
|
|
229
|
+
"Stop a branch, a scope or a step of a run by its key prefix: its steps end as cancelled, its sessions are interrupted and its child runs cancelled, and the rest of the run goes on. A shielded scope under it is spared unless force is set. Without at it stops the whole run with its child runs. For whoever started the run, and the owner.",
|
|
230
|
+
input: StopInput,
|
|
231
|
+
output: RunOutput,
|
|
232
|
+
});
|
|
233
|
+
|
|
234
|
+
export const workflowExtend = actionRef("workflow.extend", {
|
|
235
|
+
description:
|
|
236
|
+
"Move the deadline of a run later by `by` milliseconds, from the deadline or from now when it has passed. A run paused at its deadline goes on. For whoever started the run, and the owner.",
|
|
237
|
+
input: RunInput.extend({ by: z.number().int().positive() }),
|
|
238
|
+
output: RunStatus,
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
export const workflowCancel = actionRef("workflow.cancel", {
|
|
242
|
+
description: "End a workflow run and interrupt the sessions it started. For whoever started the run, and the owner.",
|
|
243
|
+
input: RunInput,
|
|
244
|
+
output: RunOutput,
|
|
245
|
+
});
|
|
246
|
+
|
|
247
|
+
export const workflowWait = actionRef("workflow.wait", {
|
|
248
|
+
description: "Wait for a run to finish or pause: the state (finished, paused or running), the result or the reason and the choices, and the questions the run asked that are still open. The end of the timeout is not an error: the state is then running.",
|
|
249
|
+
input: WaitInput,
|
|
250
|
+
output: RunStatus,
|
|
251
|
+
});
|
|
252
|
+
|
|
253
|
+
export const workflowInspect = actionRef("workflow.inspect", {
|
|
254
|
+
description: "Read a run's current state and the phases and script steps recorded in the journal. For whoever started the run, and the owner.",
|
|
255
|
+
input: RunInput,
|
|
256
|
+
output: WorkflowInspection,
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
export const workflowRuns = actionRef("workflow.runs", {
|
|
260
|
+
description: "The runs, one line each: the id, the name, the state, a few words of what it is up to or how it ended, the questions it asked, and for a paused run the command that answers it. `entries` has the same runs as fields, with the directory each was started for.",
|
|
261
|
+
input: RunsInput,
|
|
262
|
+
output: z.object({ runs: z.array(z.string()), entries: z.array(RunEntry) }),
|
|
263
|
+
});
|
|
264
|
+
|
|
265
|
+
export const workflowCheck = actionRef("workflow.check", {
|
|
266
|
+
description: "Type-check a workflow script against the actions the caller may call, and the uses of the script, and read what it declares (description, input and output as JSON Schema, the contract hash). The module is loaded in a disposable process to read its schemas; the script function is not run. Returns the errors with file, line and column.",
|
|
267
|
+
input: CheckInput,
|
|
268
|
+
output: CheckOutput,
|
|
269
|
+
});
|
|
270
|
+
|
|
271
|
+
export const workflowGuide = actionRef("workflow.guide", {
|
|
272
|
+
description: "How to write a workflow script: a short guide, the generated TypeScript declarations of everything a script may call, and the catalogue of those actions.",
|
|
273
|
+
input: z.object({}),
|
|
274
|
+
output: GuideOutput,
|
|
275
|
+
});
|
|
276
|
+
|
|
277
|
+
export const InstallInput = z.object({
|
|
278
|
+
/** The registered workflow to install, at its latest version: its id or any text that names it. */
|
|
279
|
+
id: IdText.optional(),
|
|
280
|
+
/** A script file to install, unregistered. An installation names `id` or `file`, not both. */
|
|
281
|
+
file: z.string().optional(),
|
|
282
|
+
/** What the installation is for, in a few words. */
|
|
283
|
+
description: EntityDescription,
|
|
284
|
+
/** Run the scripts of the installation in an empty box. Default: the module's own choice, which is no box. */
|
|
285
|
+
box: z.boolean().optional(),
|
|
286
|
+
});
|
|
287
|
+
export const UninstallInput = z.object({ id: IdText });
|
|
288
|
+
|
|
289
|
+
/** An installation as `workflow.installation.get` shows it. */
|
|
290
|
+
export const Installation = ScriptContract.omit({ description: true }).extend({
|
|
291
|
+
id: InstallationId,
|
|
292
|
+
description: EntityDescription,
|
|
293
|
+
workflow: WorkflowId.optional(),
|
|
294
|
+
version: WorkflowVersion.optional(),
|
|
295
|
+
file: z.string(),
|
|
296
|
+
hash: z.string(),
|
|
297
|
+
on: z.array(Subscription),
|
|
298
|
+
uses: z.array(z.string()),
|
|
299
|
+
/** Why its runs do not start: the workflow it installed is broken. */
|
|
300
|
+
broken: z.string().optional(),
|
|
301
|
+
/** The built-in it is, and the plugin that ships it: it is not uninstalled by hand. */
|
|
302
|
+
builtin: Builtin.optional(),
|
|
303
|
+
});
|
|
304
|
+
|
|
305
|
+
export const workflowInstall = actionRef("workflow.install", {
|
|
306
|
+
description:
|
|
307
|
+
"Subscribe a workflow: niwa starts it by itself, one run per record that matches its `on`; nothing runs now (workflow.start runs a script once). A registered workflow by its id, or a script file. Answers the id of the installation (sub-…). The runs are held to the profile wf:<sub-…> (the id of the installation), which is narrow(the caller's grant, uses). Records from before the installation start nothing.",
|
|
308
|
+
input: InstallInput,
|
|
309
|
+
output: z.object({ id: InstallationId, profile: z.string(), on: z.array(Subscription) }),
|
|
310
|
+
});
|
|
311
|
+
|
|
312
|
+
export const workflowUninstall = actionRef("workflow.uninstall", {
|
|
313
|
+
description: "Remove an installation: nothing starts from it any more, and its profile is emptied. Runs that live are left to end. For whoever installed it, and the owner. A built-in is refused: it is turned off by the option of its plugin.",
|
|
314
|
+
input: UninstallInput,
|
|
315
|
+
output: z.object({ id: InstallationId }),
|
|
316
|
+
});
|
|
317
|
+
|
|
318
|
+
export const workflowInstallationList = listRef("workflow.installation.list", {
|
|
319
|
+
kind: "subscription",
|
|
320
|
+
noun: "workflow installation",
|
|
321
|
+
detail: "Only the installations that stand.",
|
|
322
|
+
item: { workflow: WorkflowId.optional(), file: z.string(), hash: z.string(), on: z.array(Subscription), builtin: Builtin.optional() },
|
|
323
|
+
});
|
|
324
|
+
|
|
325
|
+
export const workflowInstallationGet = getRef("workflow.installation.get", {
|
|
326
|
+
kind: "subscription",
|
|
327
|
+
noun: "workflow installation",
|
|
328
|
+
entity: Installation,
|
|
329
|
+
});
|
|
330
|
+
|
|
331
|
+
export const RegisterInput = z.object({
|
|
332
|
+
file: z.string(),
|
|
333
|
+
/** Register the script as a new version of this workflow. Without it, the script is a new workflow. */
|
|
334
|
+
id: IdText.optional(),
|
|
335
|
+
});
|
|
336
|
+
|
|
337
|
+
export const workflowRegister = actionRef("workflow.register", {
|
|
338
|
+
description:
|
|
339
|
+
"Register a workflow script: it becomes the action flow.<id>, with its input and output as its schemas. Without id a new workflow is made and its id (wf-…) is answered; with id the script is a new version of that workflow, which only whoever made it and the owner may register; a built-in (one a plugin ships) is refused, its versions come with the plugin. The version is the hash of the script and the local files it imports. A changed contract checks the workflows that call it again, and the ones that no longer pass are marked broken.",
|
|
340
|
+
input: RegisterInput,
|
|
341
|
+
output: z.object({
|
|
342
|
+
id: WorkflowId,
|
|
343
|
+
version: WorkflowVersion,
|
|
344
|
+
description: EntityDescription,
|
|
345
|
+
/** Whether this version is new: registering the same version again changes nothing. */
|
|
346
|
+
added: z.boolean(),
|
|
347
|
+
/** The workflows that call this one and were checked again, and whether each passed. */
|
|
348
|
+
rechecked: z.array(z.object({ id: WorkflowId, version: WorkflowVersion, ok: z.boolean() })),
|
|
349
|
+
}),
|
|
350
|
+
});
|
|
351
|
+
|
|
352
|
+
/** One version of a registered workflow, as `workflow.get` shows it. */
|
|
353
|
+
export const WorkflowVersionEntry = z.object({
|
|
354
|
+
version: WorkflowVersion,
|
|
355
|
+
/** The file the version was registered from. */
|
|
356
|
+
file: z.string(),
|
|
357
|
+
/** The copy of its code niwa keeps in its home: what the version runs from. Absent when niwa holds no copy of it. */
|
|
358
|
+
stored: z.string().optional(),
|
|
359
|
+
description: EntityDescription,
|
|
360
|
+
input: JsonSchemaValue.optional(),
|
|
361
|
+
output: JsonSchemaValue.optional(),
|
|
362
|
+
contract: ContractHash,
|
|
363
|
+
uses: z.array(z.string()),
|
|
364
|
+
calls: z.array(FlowCall),
|
|
365
|
+
/** The record types it declares in `emits`. */
|
|
366
|
+
emits: z.array(EmittedRecord).optional(),
|
|
367
|
+
/** The records that start it once it is installed: a workflow without them can be started, not installed. */
|
|
368
|
+
on: z.array(Subscription).optional(),
|
|
369
|
+
/** The phases it declares, in order: the plan a run of it is shown against. */
|
|
370
|
+
phases: WorkflowPhases.optional(),
|
|
371
|
+
/** Why it does not start, when it is broken. */
|
|
372
|
+
broken: z.string().optional(),
|
|
373
|
+
/** A candidate version of a gated built-in: not accepted yet, it is started only by name of its version. */
|
|
374
|
+
candidate: z.literal(true).optional(),
|
|
375
|
+
/** A candidate superseded by another proposal before acceptance. */
|
|
376
|
+
superseded: z.literal(true).optional(),
|
|
377
|
+
});
|
|
378
|
+
|
|
379
|
+
export const workflowList = listRef("workflow.list", {
|
|
380
|
+
kind: "workflow",
|
|
381
|
+
noun: "workflow",
|
|
382
|
+
detail: "Each is the action flow.<id>.",
|
|
383
|
+
item: {
|
|
384
|
+
version: WorkflowVersion,
|
|
385
|
+
versions: z.number().int(),
|
|
386
|
+
candidate: z.literal(true).optional(),
|
|
387
|
+
broken: z.boolean(),
|
|
388
|
+
installations: z.array(InstallationId),
|
|
389
|
+
/** The phases its latest version declares, in order. */
|
|
390
|
+
phases: WorkflowPhases.optional(),
|
|
391
|
+
/** The built-in it is, and the plugin that ships it. */
|
|
392
|
+
builtin: Builtin.optional(),
|
|
393
|
+
},
|
|
394
|
+
});
|
|
395
|
+
|
|
396
|
+
export const workflowGet = getRef("workflow.get", {
|
|
397
|
+
kind: "workflow",
|
|
398
|
+
noun: "workflow",
|
|
399
|
+
detail: "Its versions, the latest last, with their schemas and whether they are broken, and its installations.",
|
|
400
|
+
entity: z.object({
|
|
401
|
+
id: WorkflowId,
|
|
402
|
+
description: EntityDescription,
|
|
403
|
+
versions: z.array(WorkflowVersionEntry),
|
|
404
|
+
installations: z.array(InstallationId),
|
|
405
|
+
/** The built-in it is, and the plugin that ships it. */
|
|
406
|
+
builtin: Builtin.optional(),
|
|
407
|
+
}),
|
|
408
|
+
});
|