@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/src/inspect.ts
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/** The observed timeline of a workflow run, projected from its journal. */
|
|
2
|
+
|
|
3
|
+
import { CORE_TYPES, WAIT_ACTION, recordId } from "@niwa-labs/core";
|
|
4
|
+
import type { JournalReader, RecordTypeName, Seq, StoredRecord } from "@niwa-labs/core";
|
|
5
|
+
import { requestAsk } from "@niwa-labs/requests/records";
|
|
6
|
+
import { NiwaSessionIdSchema, SessionStarted } from "@niwa-labs/sessions/records";
|
|
7
|
+
import { SleepRequested } from "@niwa-labs/timer/records";
|
|
8
|
+
import { WAIT_NAME } from "./bridge.ts";
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
|
|
11
|
+
import { InstallationId, RunFinished, RunId, RunRequested, RunStarted, StepPhase, StepReused, WorkflowId, WorkflowVersion } from "./records.ts";
|
|
12
|
+
import { PhaseProgress, RunStatus, statusOf } from "./status.ts";
|
|
13
|
+
|
|
14
|
+
const ReceivedAt = z.iso.datetime();
|
|
15
|
+
|
|
16
|
+
export const WorkflowStep = z.object({
|
|
17
|
+
id: z.string(),
|
|
18
|
+
label: z.string(),
|
|
19
|
+
key: z.string(),
|
|
20
|
+
action: z.string(),
|
|
21
|
+
branch: z.string().optional(),
|
|
22
|
+
prompt: z.string().optional(),
|
|
23
|
+
waitEvent: z.string().optional(),
|
|
24
|
+
dueAt: ReceivedAt.optional(),
|
|
25
|
+
/** A predictable timer.fired filter: empty matches the next scheduled timer. */
|
|
26
|
+
timerName: z.string().optional(),
|
|
27
|
+
/** Open work from a previous invocation no longer executes. */
|
|
28
|
+
historical: z.boolean().optional(),
|
|
29
|
+
startedAt: ReceivedAt,
|
|
30
|
+
endedAt: ReceivedAt.optional(),
|
|
31
|
+
status: z.enum(["running", "paused", "completed", "failed", "unknown", "skipped", "cancelled"]),
|
|
32
|
+
session: NiwaSessionIdSchema.optional(),
|
|
33
|
+
/** The declared phase the step belongs to, when the script named one. */
|
|
34
|
+
phase: z.string().optional(),
|
|
35
|
+
/** The call has an effect: it was made under a contract other than repeat, so running it again repeats the effect. */
|
|
36
|
+
effect: z.boolean().optional(),
|
|
37
|
+
/** A later start of the run took this step's answer instead of making the call again. */
|
|
38
|
+
reused: z.boolean().optional(),
|
|
39
|
+
});
|
|
40
|
+
export type WorkflowStep = z.infer<typeof WorkflowStep>;
|
|
41
|
+
|
|
42
|
+
export const WorkflowInspection = z.object({
|
|
43
|
+
run: RunId,
|
|
44
|
+
status: RunStatus,
|
|
45
|
+
observedAt: ReceivedAt.optional(),
|
|
46
|
+
origin: z.object({
|
|
47
|
+
file: z.string(),
|
|
48
|
+
args: z.unknown().optional(),
|
|
49
|
+
label: z.string().optional(),
|
|
50
|
+
workflow: WorkflowId.optional(),
|
|
51
|
+
version: WorkflowVersion.optional(),
|
|
52
|
+
installation: InstallationId.optional(),
|
|
53
|
+
directory: z.string().optional(),
|
|
54
|
+
requestedAt: ReceivedAt,
|
|
55
|
+
sourceSeq: z.number().optional(),
|
|
56
|
+
startedAt: ReceivedAt.optional(),
|
|
57
|
+
finishedAt: ReceivedAt.optional(),
|
|
58
|
+
}),
|
|
59
|
+
sessions: z.array(z.object({ id: NiwaSessionIdSchema, ref: z.string(), parentSession: z.string().optional(), startedAt: ReceivedAt })),
|
|
60
|
+
/** The phases the script declares, in order, each done, current or ahead, with the steps that named it. Empty when it declares none. */
|
|
61
|
+
phases: z.array(PhaseProgress.extend({ steps: z.array(WorkflowStep) })),
|
|
62
|
+
/** The steps that named no phase. */
|
|
63
|
+
steps: z.array(WorkflowStep),
|
|
64
|
+
});
|
|
65
|
+
export type WorkflowInspection = z.infer<typeof WorkflowInspection>;
|
|
66
|
+
|
|
67
|
+
const Intent = z.object({
|
|
68
|
+
key: z.string(),
|
|
69
|
+
action: z.string(),
|
|
70
|
+
operationId: z.string(),
|
|
71
|
+
input: z.unknown().optional(),
|
|
72
|
+
recovery: z.enum(["repeat", "repeat-with-key", "do-not-repeat"]).optional(),
|
|
73
|
+
});
|
|
74
|
+
const Outcome = z.object({ outcome: z.object({ status: z.enum(["completed", "failed", "denied", "unknown", "cancelled"]) }) });
|
|
75
|
+
const Resolution = z.object({ key: z.string(), choice: z.enum(["retry", "skip", "cancel"]), attempt: z.number().int() });
|
|
76
|
+
const State = z.object({ state: z.string(), reason: z.string().optional(), key: z.string().optional() });
|
|
77
|
+
const WaitInput = z.object({ type: z.string(), place: z.string().optional(), filter: z.looseObject({ key: z.string().optional(), timer: z.string().optional() }).optional() });
|
|
78
|
+
const Prompt = z.object({
|
|
79
|
+
prompt: z.union([z.string(), z.object({ sections: z.array(z.object({ text: z.string() })) }).transform(({ sections }) => sections.map(({ text }) => text).join("\n\n"))]),
|
|
80
|
+
});
|
|
81
|
+
const OwnedSession = SessionStarted.schema.and(z.object({ parentSession: z.string().optional() }));
|
|
82
|
+
const SessionTarget = z.object({ session: NiwaSessionIdSchema });
|
|
83
|
+
const Question = z.object({ input: z.object({ title: z.string() }) });
|
|
84
|
+
const AskEnd = z.object({ outcome: z.object({ status: z.literal("completed"), value: z.object({ ended: z.enum(["cancelled", "expired"]) }) }) });
|
|
85
|
+
|
|
86
|
+
const at = (row: StoredRecord): string => new Date(row.at).toISOString();
|
|
87
|
+
// The key of a call of the script: the path of its branch (groups, scopes and their branches), then its number or its label.
|
|
88
|
+
const scriptKey = /^((?:[^.~]+\.)*?)(call-\d+|label:[^~]+)$/;
|
|
89
|
+
// Nested actions and waits use the parent attempt's key as their namespace.
|
|
90
|
+
const nestedKey = /^(.+)\.(?:step|wait)-\d+$/;
|
|
91
|
+
|
|
92
|
+
/** An action's emissions are keyed by its operation, and have the same invocation as the intent. */
|
|
93
|
+
function sessionOf(journal: JournalReader, invocation: string, intent: StoredRecord, operation: string): WorkflowStep["session"] {
|
|
94
|
+
for (let ordinal = 1; ; ordinal++) {
|
|
95
|
+
const row = journal.get(recordId(`${operation}/emit/${ordinal}`));
|
|
96
|
+
if (row === undefined) return undefined;
|
|
97
|
+
if (row.type === SessionStarted.name && row.seq > intent.seq && row.actor.kind === "handler" && row.actor.invocation === invocation) {
|
|
98
|
+
return SessionStarted.schema.parse(row.data).id;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
export function inspectRun(journal: JournalReader, run: RunId): WorkflowInspection | undefined {
|
|
104
|
+
const forRun = (type: RecordTypeName) => journal.find({ type, field: "run", equals: run });
|
|
105
|
+
const requested = forRun(RunRequested.name).at(-1);
|
|
106
|
+
if (requested === undefined) return undefined;
|
|
107
|
+
const starts = forRun(RunStarted.name);
|
|
108
|
+
const started = starts.findLast((row) => row.seq > requested.seq);
|
|
109
|
+
const finished = forRun(RunFinished.name).findLast((row) => row.seq > requested.seq);
|
|
110
|
+
const status = statusOf(journal, run);
|
|
111
|
+
const { file, args, label, workflow, version, installation, directory } = RunRequested.schema.parse(requested.data);
|
|
112
|
+
// The phase of each step, by its invocation and its key.
|
|
113
|
+
const stepPhases = new Map<string, string>();
|
|
114
|
+
for (const row of forRun(StepPhase.name)) {
|
|
115
|
+
if (row.actor.kind !== "handler") continue;
|
|
116
|
+
const { key, phase } = StepPhase.schema.parse(row.data);
|
|
117
|
+
stepPhases.set(`${row.actor.invocation} ${key}`, phase);
|
|
118
|
+
}
|
|
119
|
+
// The steps a later start took, by the start that made them and their key.
|
|
120
|
+
const reused = new Set(forRun(StepReused.name).map((row) => {
|
|
121
|
+
const { key, from } = StepReused.schema.parse(row.data);
|
|
122
|
+
return `${from} ${key}`;
|
|
123
|
+
}));
|
|
124
|
+
const phases = (status.phases ?? []).map((phase) => ({ ...phase, steps: [] as WorkflowStep[] }));
|
|
125
|
+
const steps: WorkflowStep[] = [];
|
|
126
|
+
const cancellation = finished !== undefined && status.outcome?.status === "cancelled" ? finished : undefined;
|
|
127
|
+
let ended = finished;
|
|
128
|
+
let observed: number = finished?.at ?? requested.at;
|
|
129
|
+
for (const start of starts) {
|
|
130
|
+
if (start.actor.kind !== "handler") continue;
|
|
131
|
+
const invocation = start.actor.invocation;
|
|
132
|
+
const projected = invocationSteps(journal, invocation, start.seq > requested.seq ? cancellation : undefined);
|
|
133
|
+
observed = Math.max(observed, start.at, projected.observed);
|
|
134
|
+
if (start === started && status.outcome?.status === "cancelled") ended ??= projected.cancelled;
|
|
135
|
+
for (const { step } of projected.steps) {
|
|
136
|
+
const phase = stepPhases.get(`${invocation} ${step.key}`);
|
|
137
|
+
if (start !== started && step.endedAt === undefined) step.historical = true;
|
|
138
|
+
if (phase !== undefined) step.phase = phase;
|
|
139
|
+
if (reused.has(`${invocation} ${step.key}`)) step.reused = true;
|
|
140
|
+
(phases.find((one) => one.title === phase)?.steps ?? steps).push(step);
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return {
|
|
144
|
+
run,
|
|
145
|
+
status,
|
|
146
|
+
observedAt: new Date(observed).toISOString(),
|
|
147
|
+
origin: { file, args, ...(started && { sourceSeq: started.seq }), label, workflow, version, installation, directory, requestedAt: at(requested), startedAt: started && at(started), finishedAt: ended && at(ended) },
|
|
148
|
+
phases,
|
|
149
|
+
steps,
|
|
150
|
+
sessions: forRun(SessionStarted.name).map((row) => {
|
|
151
|
+
const session = OwnedSession.parse(row.data);
|
|
152
|
+
return { id: session.id, ref: session.session, parentSession: session.parentSession, startedAt: at(row) };
|
|
153
|
+
}),
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function invocationSteps(
|
|
158
|
+
journal: JournalReader,
|
|
159
|
+
invocation: string,
|
|
160
|
+
cancelledByRun: StoredRecord | undefined,
|
|
161
|
+
): { steps: Array<{ row: StoredRecord; step: WorkflowStep }>; cancelled?: StoredRecord; observed: number } {
|
|
162
|
+
const rows = (type: RecordTypeName) => journal.find({ type, field: "invocation", equals: invocation });
|
|
163
|
+
const stateRow = rows(CORE_TYPES.invocationState).at(-1);
|
|
164
|
+
const state = stateRow === undefined ? undefined : State.parse(stateRow.data);
|
|
165
|
+
const cancelled = cancelledByRun ?? (state?.state === "done" && state.reason === "cancelled" ? stateRow : undefined);
|
|
166
|
+
const resolutions = new Map(rows(CORE_TYPES.invocationResolved).map((row) => {
|
|
167
|
+
const { key, choice, attempt } = Resolution.parse(row.data);
|
|
168
|
+
const operation: string = `${invocation}/${key}${attempt > 0 ? `#${attempt + 1}` : ""}`;
|
|
169
|
+
return [operation, { row, choice }] as const;
|
|
170
|
+
}));
|
|
171
|
+
const outcomes = new Map(rows(CORE_TYPES.stepOutcome).map((row) => [String(row.id), row]));
|
|
172
|
+
const intents = rows(CORE_TYPES.stepIntent).map((row) => ({ row, data: Intent.parse(row.data) }));
|
|
173
|
+
// Script calls with explicit labels can contain dots. A preceding authorize intent proves a
|
|
174
|
+
// direct script call even when its label looks like a key used by an action's nested work.
|
|
175
|
+
const authorized = new Set(intents.filter(({ data }) => data.action === "workflow.authorize").map(({ data }) => data.key));
|
|
176
|
+
const owners = new Map<string, { step: WorkflowStep; outcomeSeq?: Seq }>();
|
|
177
|
+
const steps: Array<{ row: StoredRecord; step: WorkflowStep }> = [];
|
|
178
|
+
for (const { row, data } of intents) {
|
|
179
|
+
const { action, input, key, operationId, recovery } = data;
|
|
180
|
+
const nested = nestedKey.exec(key)?.[1];
|
|
181
|
+
const owner = nested !== undefined && !authorized.has(`${key}~auth`) ? owners.get(nested) : undefined;
|
|
182
|
+
const parsed = scriptKey.exec(key);
|
|
183
|
+
const branch = parsed?.[1]?.slice(0, -1);
|
|
184
|
+
const labeled = parsed?.[2]?.startsWith("label:") === true ? parsed[2].slice("label:".length) : undefined;
|
|
185
|
+
if (owner !== undefined && (owner.outcomeSeq === undefined || row.seq < owner.outcomeSeq)) {
|
|
186
|
+
if (action === "session.start" && owner.step.action.startsWith("session.start.")) {
|
|
187
|
+
owner.step.session ??= sessionOf(journal, invocation, row, operationId);
|
|
188
|
+
}
|
|
189
|
+
continue;
|
|
190
|
+
}
|
|
191
|
+
if (parsed === null) continue;
|
|
192
|
+
const resolution = resolutions.get(operationId);
|
|
193
|
+
const outcome = outcomes.get(row.id.replace(/\/intent$/, "/outcome"));
|
|
194
|
+
const askEnd = action === requestAsk.name ? outcomes.get(`${invocation}/step/${key}~ended/outcome`) : undefined;
|
|
195
|
+
const askStatus = askEnd !== undefined && askEnd.seq > row.seq ? AskEnd.safeParse(askEnd.data).data?.outcome.value.ended : undefined;
|
|
196
|
+
const settledAt = outcome ?? (askStatus === undefined ? undefined : askEnd);
|
|
197
|
+
const settled = outcome === undefined
|
|
198
|
+
? askStatus === "expired" ? "failed" : askStatus
|
|
199
|
+
: Outcome.parse(outcome.data).outcome.status;
|
|
200
|
+
const namespace = operationId.slice(invocation.length + 1).replace(/#(\d+)$/, ".$1");
|
|
201
|
+
const pauseKey = state?.state === "paused" ? state.key : undefined;
|
|
202
|
+
const nestedPause = pauseKey !== undefined && nestedKey.test(pauseKey) && pauseKey.startsWith(`${namespace}.`) && !authorized.has(`${pauseKey}~auth`);
|
|
203
|
+
const cancelledDuringCall = cancelled !== undefined && row.seq < cancelled.seq && (settledAt === undefined || cancelled.seq < settledAt.seq);
|
|
204
|
+
const end = resolution?.choice === "skip" ? resolution.row : cancelledDuringCall ? cancelled : settledAt;
|
|
205
|
+
const prompt = action === requestAsk.name ? Question.safeParse(input).data?.input.title : Prompt.safeParse(input).data?.prompt;
|
|
206
|
+
const wait = action === WAIT_ACTION || action === WAIT_NAME ? WaitInput.safeParse(input).data : undefined;
|
|
207
|
+
const sleep = wait && end === undefined
|
|
208
|
+
? journal.find({ type: SleepRequested.name, field: "key", equals: wait.place ?? wait.filter?.key ?? `${invocation}:${key}` }).at(-1)
|
|
209
|
+
: undefined;
|
|
210
|
+
const step: WorkflowStep = {
|
|
211
|
+
...(wait && { waitEvent: wait.type }),
|
|
212
|
+
...(wait?.type === "timer.fired" && Object.keys(wait.filter ?? {}).every(k => k === "timer") && { timerName: wait.filter?.timer ?? "" }),
|
|
213
|
+
...(sleep && { dueAt: new Date(SleepRequested.schema.parse(sleep.data).at).toISOString() }),
|
|
214
|
+
id: row.id,
|
|
215
|
+
key,
|
|
216
|
+
label: labeled ?? action,
|
|
217
|
+
action,
|
|
218
|
+
branch: branch || undefined,
|
|
219
|
+
prompt,
|
|
220
|
+
startedAt: at(row),
|
|
221
|
+
endedAt: end && at(end),
|
|
222
|
+
status: resolution?.choice === "skip" ? "skipped"
|
|
223
|
+
: cancelledDuringCall ? "cancelled"
|
|
224
|
+
: settled === "denied" ? "failed"
|
|
225
|
+
: settled ?? (pauseKey === key || nestedPause ? "paused" : state?.state === "done" ? "unknown" : "running"),
|
|
226
|
+
session: action === "session.ask" || action === "session.end" ? SessionTarget.safeParse(input).data?.session : sessionOf(journal, invocation, row, operationId),
|
|
227
|
+
...(recovery !== undefined && recovery !== "repeat" ? { effect: true } : {}),
|
|
228
|
+
};
|
|
229
|
+
steps.push({ row, step });
|
|
230
|
+
owners.set(namespace, { step, outcomeSeq: outcome?.seq });
|
|
231
|
+
}
|
|
232
|
+
let observed = Math.max(stateRow?.at ?? 0, intents.at(-1)?.row.at ?? 0);
|
|
233
|
+
for (const outcome of outcomes.values()) observed = Math.max(observed, outcome.at);
|
|
234
|
+
return { steps, cancelled, observed };
|
|
235
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the script processes find their packages.
|
|
3
|
+
*
|
|
4
|
+
* The workflow module does not know the layout it is installed in. It asks package resolution: its
|
|
5
|
+
* own root is the folder above this file, the packages it depends on are found from there the way
|
|
6
|
+
* any import of its own is, and `node_modules` is the one that holds the packages niwa runs with.
|
|
7
|
+
* A script process reads the child and the packages the child loads; a stored script finds the
|
|
8
|
+
* packages it imports by name through a link to that `node_modules`.
|
|
9
|
+
*
|
|
10
|
+
* The script libraries (`@niwa-labs/flow`, `flow-code`, `flow-eval`) are dependencies of this package for
|
|
11
|
+
* that reason alone: so they are in that `node_modules` and among what a box may read, wherever niwa is laid out.
|
|
12
|
+
*
|
|
13
|
+
* Tasks and history are dependencies of this package for that reason too: a script imports their
|
|
14
|
+
* query builders and helpers (`@niwa-labs/tasks/records`, `@niwa-labs/history/flow`) by name.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { existsSync, readFileSync, realpathSync } from "node:fs";
|
|
18
|
+
import { dirname, join, sep } from "node:path";
|
|
19
|
+
import { fileURLToPath } from "node:url";
|
|
20
|
+
|
|
21
|
+
/** The folder of this package. */
|
|
22
|
+
export const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
|
|
23
|
+
|
|
24
|
+
/** The module a script takes its types from: the file of the script package that imports nothing. */
|
|
25
|
+
export const SCRIPT_API = fileURLToPath(import.meta.resolve("@niwa-labs/script/api"));
|
|
26
|
+
|
|
27
|
+
/** The folder of the package `name`, as `from` resolves it; undefined when it is not installed. */
|
|
28
|
+
function packageRootOf(name: string, from: string): string | undefined {
|
|
29
|
+
try {
|
|
30
|
+
return dirname(Bun.resolveSync(`${name}/package.json`, from));
|
|
31
|
+
} catch {
|
|
32
|
+
// A package may keep its manifest out of its exports: its entry then leads to its folder.
|
|
33
|
+
}
|
|
34
|
+
let entry: string;
|
|
35
|
+
try {
|
|
36
|
+
entry = Bun.resolveSync(name, from);
|
|
37
|
+
} catch {
|
|
38
|
+
return undefined;
|
|
39
|
+
}
|
|
40
|
+
for (let dir = dirname(entry); ; dir = dirname(dir)) {
|
|
41
|
+
const manifest = join(dir, "package.json");
|
|
42
|
+
if (existsSync(manifest) && (JSON.parse(readFileSync(manifest, "utf8")) as { name?: string }).name === name) return dir;
|
|
43
|
+
if (dirname(dir) === dir) return undefined;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The folders of the packages a package needs when it runs, and of the ones those need. */
|
|
48
|
+
function dependencyRoots(root: string, found: Set<string>): Set<string> {
|
|
49
|
+
const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { dependencies?: Record<string, string> };
|
|
50
|
+
for (const name of Object.keys(manifest.dependencies ?? {})) {
|
|
51
|
+
const dependency = packageRootOf(name, root);
|
|
52
|
+
if (dependency === undefined || found.has(dependency)) continue;
|
|
53
|
+
found.add(dependency);
|
|
54
|
+
dependencyRoots(dependency, found);
|
|
55
|
+
}
|
|
56
|
+
return found;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The `node_modules` that holds the packages niwa runs with: the one an installation puts the script
|
|
61
|
+
* package in, or, in a checkout that links every package from its own `node_modules`, the one of this package.
|
|
62
|
+
*/
|
|
63
|
+
export function modulesDir(): string | undefined {
|
|
64
|
+
const marker = `${sep}node_modules${sep}`;
|
|
65
|
+
const at = SCRIPT_API.indexOf(marker);
|
|
66
|
+
const found = at < 0 ? join(PACKAGE_ROOT, "node_modules") : SCRIPT_API.slice(0, at + marker.length - 1);
|
|
67
|
+
return existsSync(found) ? found : undefined;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The folder of a package and the folders of the packages it needs when it runs: what reading it takes. */
|
|
71
|
+
export function packageRoots(root: string): string[] {
|
|
72
|
+
return [root, ...dependencyRoots(root, new Set())];
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
let readable: string[] | undefined;
|
|
76
|
+
|
|
77
|
+
/** What a script process in a box may read: this package, the packages it loads, and the packages niwa runs with. */
|
|
78
|
+
export function readableRoots(): string[] {
|
|
79
|
+
if (readable === undefined) {
|
|
80
|
+
const modules = modulesDir();
|
|
81
|
+
readable = [PACKAGE_ROOT, ...dependencyRoots(PACKAGE_ROOT, new Set()), ...(modules === undefined ? [] : [realpathSync(modules)])];
|
|
82
|
+
}
|
|
83
|
+
return readable;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** The folder of the type declarations of bun and node that a check reads, when the package that holds them is installed. */
|
|
87
|
+
export function typeRoots(): string | undefined {
|
|
88
|
+
const bun = packageRootOf("@types/bun", PACKAGE_ROOT);
|
|
89
|
+
return bun === undefined ? undefined : dirname(bun);
|
|
90
|
+
}
|
package/src/language.ts
ADDED
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The names a workflow script is given: `call` and the generated
|
|
3
|
+
* `niwa.<group>.<action>` wrappers, `agent`, `wait`, `sleep`, `ask`, `emit`, `read`, `now`,
|
|
4
|
+
* `random`, `scope`, `parallel`, `stream`, `race`, `moveOnAfter`, `failAfter`, `pipeline`, `phase`, `log`
|
|
5
|
+
* and `workflow`. The script is
|
|
6
|
+
* `export default workflow({ description, input, output, uses, on }, async (input) => { ... })` and
|
|
7
|
+
* ends by returning its result; the names are globals of the disposable process it runs in (see `child.ts`).
|
|
8
|
+
*
|
|
9
|
+
* This file also holds what the script and the parent say to each other: the requests the child
|
|
10
|
+
* sends (`ScriptRequest`) and the way a duration is written.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { z } from "zod";
|
|
14
|
+
|
|
15
|
+
import { JsonSchemaValue, JsonValueSchema, QuestionSchema } from "@niwa-labs/core";
|
|
16
|
+
import type { ActionName } from "@niwa-labs/core";
|
|
17
|
+
import { WorktreeOption } from "@niwa-labs/git/records";
|
|
18
|
+
import type { WorktreeOptionGiven } from "@niwa-labs/git/records";
|
|
19
|
+
import { PromptSchema, SessionModeSchema, ToolsModeSchema, withBlocks } from "@niwa-labs/harness";
|
|
20
|
+
import type { SessionMode, ToolsMode } from "@niwa-labs/harness";
|
|
21
|
+
import { BoxAccessSchema } from "@niwa-labs/sandbox";
|
|
22
|
+
import type { BoxAccessInput } from "@niwa-labs/sandbox";
|
|
23
|
+
|
|
24
|
+
import type { Duration } from "@niwa-labs/script";
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The prefix of a line of the protocol between the child and the parent.
|
|
28
|
+
*
|
|
29
|
+
* The script and the child share one stdout, and the script may write to it: a line of the
|
|
30
|
+
* protocol is told from an ordinary line by this prefix, so a script that writes a line of its
|
|
31
|
+
* own breaks nothing.
|
|
32
|
+
*/
|
|
33
|
+
export const PROTOCOL_PREFIX = "@niwa ";
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* What an `ask()` call may ask for. The options of the harness's kind go in the block named after
|
|
37
|
+
* it (`claude: { advisor: false }`); the block of another kind is refused.
|
|
38
|
+
*/
|
|
39
|
+
export interface AgentOptions {
|
|
40
|
+
/** The harness the session runs in. */
|
|
41
|
+
harness?: string;
|
|
42
|
+
/** The key of the call, so reordering a list does not rerun the work. */
|
|
43
|
+
label?: string;
|
|
44
|
+
/** The actions (names or masks) the session sees besides the one that answers; within the run's grant. */
|
|
45
|
+
visible?: string[];
|
|
46
|
+
tools?: ToolsMode;
|
|
47
|
+
/** The model of the session, set once at its start; the instance's own when absent. */
|
|
48
|
+
model?: string;
|
|
49
|
+
/** The effort of the session, set once at its start; a kind that takes none refuses it. */
|
|
50
|
+
effort?: string;
|
|
51
|
+
/** The working mode of the session, set once at its start: ask, auto or full; the instance's own, else auto, when absent. */
|
|
52
|
+
mode?: SessionMode;
|
|
53
|
+
/** The directory the session starts in; the host's own directory when absent. */
|
|
54
|
+
cwd?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Run the session in a new git worktree of the repository (`cwd` by default). When the call ends with the
|
|
57
|
+
* worktree clean and no new commit, it is removed; otherwise the answer carries `worktree`.
|
|
58
|
+
*/
|
|
59
|
+
worktree?: WorktreeOptionGiven;
|
|
60
|
+
/** A zod schema for the answer: the call gives the answer parsed, typed as the schema says. */
|
|
61
|
+
schema?: z.ZodType;
|
|
62
|
+
/** How long a turn of the session may go with no progress before it counts as stuck. */
|
|
63
|
+
stuckAfter?: Duration;
|
|
64
|
+
/** What the session's box has besides the host's default (`allow`) or instead of it (`only`). */
|
|
65
|
+
box?: BoxAccessInput;
|
|
66
|
+
/**
|
|
67
|
+
* The options block of the harness's kind, named after the kind (`claude: { advisor: false }`). Which kinds there
|
|
68
|
+
* are is the host's to say: the typing `workflow.check` makes of a host knows each harness's block, and the host
|
|
69
|
+
* refuses a block the harness's kind does not declare.
|
|
70
|
+
*/
|
|
71
|
+
[block: string]: unknown;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** The action an agent call goes to by default: `mcode-work` becomes `session.start.mcode-work`. */
|
|
75
|
+
export function agentActionName(harness: string | undefined): ActionName {
|
|
76
|
+
const base = harness === undefined || harness === "" ? "session.start" : `session.start.${harness}`;
|
|
77
|
+
return base as ActionName;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** A phase a script declares in `workflow({ phases })`: a title, and a line of what is done in it. */
|
|
81
|
+
export const WorkflowPhase = z.strictObject({
|
|
82
|
+
title: z.string().regex(/\S/, "a phase has a title"),
|
|
83
|
+
detail: z.string().min(1).optional(),
|
|
84
|
+
});
|
|
85
|
+
export type WorkflowPhase = z.infer<typeof WorkflowPhase>;
|
|
86
|
+
|
|
87
|
+
/** The phases of a script, in the order they come: `phase(title)` names one by its title, so no two share one. */
|
|
88
|
+
export const WorkflowPhases = z.array(WorkflowPhase).superRefine((phases, ctx) => {
|
|
89
|
+
const seen = new Set<string>();
|
|
90
|
+
for (const [index, phase] of phases.entries()) {
|
|
91
|
+
if (seen.has(phase.title)) ctx.addIssue({ code: "custom", path: [index, "title"], message: `the phase "${phase.title}" is declared twice` });
|
|
92
|
+
seen.add(phase.title);
|
|
93
|
+
}
|
|
94
|
+
});
|
|
95
|
+
export type WorkflowPhases = z.infer<typeof WorkflowPhases>;
|
|
96
|
+
|
|
97
|
+
/** The prefix of the record types a script may emit: its own. */
|
|
98
|
+
export const SCRIPT_TYPES = "wf.";
|
|
99
|
+
|
|
100
|
+
const UNITS: Readonly<Record<string, number>> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* A duration in milliseconds.
|
|
104
|
+
*
|
|
105
|
+
* @throws when it is not a non-negative number or a number with a unit.
|
|
106
|
+
*/
|
|
107
|
+
export function durationMs(value: Duration): number {
|
|
108
|
+
if (typeof value === "number") {
|
|
109
|
+
if (!Number.isFinite(value) || value < 0) throw new TypeError(`a duration must be a non-negative number, got ${String(value)}`);
|
|
110
|
+
return value;
|
|
111
|
+
}
|
|
112
|
+
const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/.exec(value);
|
|
113
|
+
const unit = match?.[2];
|
|
114
|
+
const amount = match?.[1];
|
|
115
|
+
if (unit === undefined || amount === undefined) {
|
|
116
|
+
throw new TypeError(`a duration is milliseconds or a number with ms, s, m, h or d, got ${JSON.stringify(value)}`);
|
|
117
|
+
}
|
|
118
|
+
return Math.round(Number(amount) * (UNITS[unit] ?? 1));
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** How a branch of a group ended. */
|
|
122
|
+
export const ScopeOutcome = z.enum(["done", "failed", "cancelled"]);
|
|
123
|
+
export type ScopeOutcome = z.infer<typeof ScopeOutcome>;
|
|
124
|
+
|
|
125
|
+
/** How a group closed: its block returned, threw, or ran out of time. */
|
|
126
|
+
export const ScopeClosing = z.enum(["done", "failed", "deadline"]);
|
|
127
|
+
export type ScopeClosing = z.infer<typeof ScopeClosing>;
|
|
128
|
+
|
|
129
|
+
/** The fields of an `ask()` request: every other key of it is an options block. */
|
|
130
|
+
export const AgentRequestFields = z.object({
|
|
131
|
+
prompt: z.union([z.string(), PromptSchema]).optional(),
|
|
132
|
+
harness: z.string().optional(),
|
|
133
|
+
label: z.string().optional(),
|
|
134
|
+
visible: z.array(z.string()).optional(),
|
|
135
|
+
tools: ToolsModeSchema.optional(),
|
|
136
|
+
model: z.string().min(1).optional(),
|
|
137
|
+
effort: z.string().min(1).optional(),
|
|
138
|
+
mode: SessionModeSchema.optional(),
|
|
139
|
+
cwd: z.string().min(1).optional(),
|
|
140
|
+
worktree: WorktreeOption.optional(),
|
|
141
|
+
/** The JSON Schema the answer must pass, made from the zod schema of the script. */
|
|
142
|
+
schema: JsonSchemaValue.optional(),
|
|
143
|
+
/** How long, in milliseconds, a turn may go with no progress before the session counts as stuck. */
|
|
144
|
+
stuckAfter: z.number().int().positive().optional(),
|
|
145
|
+
/** What the session's box has besides the host's default, or instead of it. */
|
|
146
|
+
box: BoxAccessSchema.optional(),
|
|
147
|
+
});
|
|
148
|
+
|
|
149
|
+
/** The names of the fields of an `ask()` request, so the rest of it is known as its blocks. */
|
|
150
|
+
export const AGENT_REQUEST_FIELDS: readonly string[] = Object.keys(AgentRequestFields.shape);
|
|
151
|
+
|
|
152
|
+
/** What the child asks the parent to do: every request has a key, and the key says which one it is. */
|
|
153
|
+
export const ScriptRequest = z.discriminatedUnion("op", [
|
|
154
|
+
/** `ask()`: start a session of a harness and ask it. */
|
|
155
|
+
z.object({
|
|
156
|
+
op: z.literal("agent"),
|
|
157
|
+
// Every key that is not a field is the options block of the harness's kind, named after it.
|
|
158
|
+
input: withBlocks(AgentRequestFields),
|
|
159
|
+
}),
|
|
160
|
+
/** `call()` and the generated wrappers: any action, by name. */
|
|
161
|
+
z.object({ op: z.literal("call"), action: z.string().min(1), input: JsonValueSchema.optional(), reason: z.string().min(1).optional() }),
|
|
162
|
+
/** `wait()`: the first record of a type whose data holds the filter, after a position or the wait's start, or the timeout. */
|
|
163
|
+
z.object({
|
|
164
|
+
op: z.literal("wait"),
|
|
165
|
+
type: z.string().min(1),
|
|
166
|
+
/** The version a reference to the type holds: the host refuses one it does not write. */
|
|
167
|
+
version: z.number().int().positive().optional(),
|
|
168
|
+
filter: z.record(z.string(), z.unknown()).optional(),
|
|
169
|
+
/** The position to look after: what an earlier wait or read answered. */
|
|
170
|
+
from: z.number().int().nonnegative().optional(),
|
|
171
|
+
timeoutMs: z.number().optional(),
|
|
172
|
+
}),
|
|
173
|
+
z.object({ op: z.literal("sleep"), ms: z.number() }),
|
|
174
|
+
z.object({
|
|
175
|
+
op: z.literal("ask"),
|
|
176
|
+
question: QuestionSchema,
|
|
177
|
+
timeoutMs: z.number().optional(),
|
|
178
|
+
}),
|
|
179
|
+
/** `emit()`: a record the script declares in `emits`, by its short name; the host writes it under `wf.<name>.`. */
|
|
180
|
+
z.object({ op: z.literal("emit"), record: z.string().min(1), data: z.unknown() }),
|
|
181
|
+
z.object({ op: z.literal("read-state"), plugin: z.string().min(1) }),
|
|
182
|
+
/** `read.records()`: the query, and the version each type named by reference holds, so the host refuses one it does not write. */
|
|
183
|
+
z.object({ op: z.literal("read-records"), query: z.record(z.string(), z.unknown()), versions: z.record(z.string(), z.number().int().positive()).optional() }),
|
|
184
|
+
z.object({ op: z.literal("now") }),
|
|
185
|
+
z.object({ op: z.literal("random") }),
|
|
186
|
+
/**
|
|
187
|
+
* `scope()` opens a group of branches: its key prefix, what leaving it does, its deadline and
|
|
188
|
+
* whether an outer cancel waits for it. The answer is what the host knows of the group already.
|
|
189
|
+
*/
|
|
190
|
+
z.object({
|
|
191
|
+
op: z.literal("scope-open"),
|
|
192
|
+
scope: z.string().min(1),
|
|
193
|
+
onExit: z.enum(["wait", "cancel"]),
|
|
194
|
+
deadlineMs: z.number().nonnegative().optional(),
|
|
195
|
+
onDeadline: z.enum(["skip", "fail"]).optional(),
|
|
196
|
+
shield: z.boolean().optional(),
|
|
197
|
+
concurrency: z.number().int().positive().optional(),
|
|
198
|
+
}),
|
|
199
|
+
/** A branch of a group ended: the host commits its outcome and answers its place among the outcomes of the group. */
|
|
200
|
+
z.object({
|
|
201
|
+
op: z.literal("scope-settled"),
|
|
202
|
+
scope: z.string().min(1),
|
|
203
|
+
key: z.string().min(1),
|
|
204
|
+
outcome: ScopeOutcome,
|
|
205
|
+
error: z.object({ name: z.string(), message: z.string() }).optional(),
|
|
206
|
+
}),
|
|
207
|
+
/** Cancel branches of a group: the steps under the prefixes end as cancelled. */
|
|
208
|
+
z.object({ op: z.literal("scope-cancel"), scope: z.string().min(1), prefixes: z.array(z.string().min(1)).min(1), reason: z.string().min(1) }),
|
|
209
|
+
/** What `pending()` or `ready()` sees, recorded once so a replay sees the same. */
|
|
210
|
+
z.object({ op: z.literal("scope-snapshot"), scope: z.string().min(1), keys: z.array(z.string()) }),
|
|
211
|
+
/** Answer when the clock of the host reaches the deadline of a group, or when the script process is gone. */
|
|
212
|
+
z.object({ op: z.literal("scope-deadline"), scope: z.string().min(1), at: z.number() }),
|
|
213
|
+
/** A group closed: how it ended. */
|
|
214
|
+
z.object({ op: z.literal("scope-close"), scope: z.string().min(1), outcome: ScopeClosing }),
|
|
215
|
+
]);
|
|
216
|
+
|
|
217
|
+
export type ScriptRequest = z.infer<typeof ScriptRequest>;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The records entry of the workflow module: what another plugin may import from it. The records it
|
|
3
|
+
* writes, the typed references of its actions, and the pure helpers that read runs, installations
|
|
4
|
+
* and registered versions out of the journal; no factory, and nothing here starts a run. The
|
|
5
|
+
* actions import the records, so this file sits above both and neither imports it.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
export {
|
|
9
|
+
Builtin,
|
|
10
|
+
BuiltinPromoted,
|
|
11
|
+
BuiltinTrial,
|
|
12
|
+
BuiltinsWanted,
|
|
13
|
+
InstallationId,
|
|
14
|
+
PhaseEntered,
|
|
15
|
+
PhaseLeft,
|
|
16
|
+
RunContinued,
|
|
17
|
+
RunFinished,
|
|
18
|
+
RunId,
|
|
19
|
+
RunLog,
|
|
20
|
+
RunPauseRequested,
|
|
21
|
+
RunHoldRequested,
|
|
22
|
+
RunPaused,
|
|
23
|
+
RunRequested,
|
|
24
|
+
RunStarted,
|
|
25
|
+
StepPhase,
|
|
26
|
+
Subscription,
|
|
27
|
+
SubscriptionInstalled,
|
|
28
|
+
SubscriptionUninstalled,
|
|
29
|
+
WORKFLOW_TYPES,
|
|
30
|
+
WorkflowId,
|
|
31
|
+
WorkflowRechecked,
|
|
32
|
+
WorkflowRegistered,
|
|
33
|
+
WorkflowVersion,
|
|
34
|
+
} from "./records.ts";
|
|
35
|
+
export {
|
|
36
|
+
workflowCancel,
|
|
37
|
+
workflowCheck,
|
|
38
|
+
workflowContinue,
|
|
39
|
+
workflowGet,
|
|
40
|
+
workflowGuide,
|
|
41
|
+
workflowInspect,
|
|
42
|
+
workflowInstall,
|
|
43
|
+
workflowInstallationGet,
|
|
44
|
+
workflowInstallationList,
|
|
45
|
+
workflowList,
|
|
46
|
+
workflowBuiltinPromote,
|
|
47
|
+
workflowBuiltinTrial,
|
|
48
|
+
workflowPause,
|
|
49
|
+
workflowRegister,
|
|
50
|
+
workflowResume,
|
|
51
|
+
workflowRevise,
|
|
52
|
+
workflowRuns,
|
|
53
|
+
workflowStart,
|
|
54
|
+
workflowUninstall,
|
|
55
|
+
workflowWait,
|
|
56
|
+
} from "./actions.ts";
|
|
57
|
+
export { installationsOf, profileOf, standing, standingAt } from "./subscriptions.ts";
|
|
58
|
+
export type { Installation } from "./subscriptions.ts";
|
|
59
|
+
export { versionOf, workflowsOf } from "./registry.ts";
|
|
60
|
+
export { RunStatus } from "./status.ts";
|
|
61
|
+
|
|
62
|
+
// Verify that a registered run executed the archived source closure.
|
|
63
|
+
export { storedEntry } from "./store.ts";
|