@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/describe.ts
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a script declares: its `workflow({ description, input, output, ... }, fn)`
|
|
3
|
+
* call, read by loading the module in a disposable process in the `describe` mode of the child (`child.ts`).
|
|
4
|
+
*
|
|
5
|
+
* The module's top level runs there, so its imports work and the schemas are the real zod schemas; the
|
|
6
|
+
* names of niwa are stubs that throw, and the function of the script is never called. The schemas come
|
|
7
|
+
* back as JSON Schema, zod's own.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { createHash } from "node:crypto";
|
|
11
|
+
import type { Readable } from "node:stream";
|
|
12
|
+
|
|
13
|
+
import { z } from "zod";
|
|
14
|
+
|
|
15
|
+
import { PROTOCOL_PREFIX, SCRIPT_TYPES, WorkflowPhases } from "./language.ts";
|
|
16
|
+
import { ContractHash, JsonSchemaValue } from "./records.ts";
|
|
17
|
+
import { spawnScriptChild } from "./runner.ts";
|
|
18
|
+
import type { ScriptBox } from "./runner.ts";
|
|
19
|
+
|
|
20
|
+
/** How long a module may take to be read: a top level that never ends is not a script. */
|
|
21
|
+
const DESCRIBE_MS = 30_000;
|
|
22
|
+
|
|
23
|
+
/** One schema of a declaration: its JSON Schema, or what stops it from being one. */
|
|
24
|
+
const Declaration = z.union([z.object({ schema: JsonSchemaValue }), z.object({ problem: z.string() })]);
|
|
25
|
+
|
|
26
|
+
/** The records of `emits`: each with its schema or its problem, or what stops the list from being one. */
|
|
27
|
+
const EmitsDeclaration = z.union([z.array(z.intersection(z.object({ name: z.string().min(1) }), Declaration)), z.object({ problem: z.string() })]);
|
|
28
|
+
|
|
29
|
+
const Message = z.discriminatedUnion("kind", [
|
|
30
|
+
z.object({
|
|
31
|
+
kind: z.literal("described"),
|
|
32
|
+
name: z.string().optional(),
|
|
33
|
+
description: z.string().optional(),
|
|
34
|
+
input: Declaration.optional(),
|
|
35
|
+
output: Declaration.optional(),
|
|
36
|
+
emits: EmitsDeclaration.optional(),
|
|
37
|
+
phases: z.union([z.object({ phases: WorkflowPhases }), z.object({ problem: z.string() })]).optional(),
|
|
38
|
+
}),
|
|
39
|
+
z.object({ kind: z.literal("failed"), error: z.string() }),
|
|
40
|
+
]);
|
|
41
|
+
|
|
42
|
+
/** A record a script declares in `emits`: its short name, and the JSON Schema of its data. */
|
|
43
|
+
export interface DeclaredEmit {
|
|
44
|
+
name: string;
|
|
45
|
+
schema: JsonSchemaValue;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** What a script declares: the schemas that are valid JSON Schema, and the problems of those that are not. */
|
|
49
|
+
export interface Described {
|
|
50
|
+
/** The `name` of the script, when it is text: its records are `wf.<name>.<record>`. */
|
|
51
|
+
name?: string;
|
|
52
|
+
description?: string;
|
|
53
|
+
input?: JsonSchemaValue;
|
|
54
|
+
output?: JsonSchemaValue;
|
|
55
|
+
/** The records the script may emit; absent when it declares no `emits`. */
|
|
56
|
+
emits?: DeclaredEmit[];
|
|
57
|
+
/** The phases the script declares, in order; absent when it declares none. */
|
|
58
|
+
phases?: WorkflowPhases;
|
|
59
|
+
/** What stops a declared schema (or the phases) from being what it must be, by the key of the declaration. */
|
|
60
|
+
problems: Array<{ key: "input" | "output" | "emits" | "phases"; message: string }>;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** The module could not be read: what it threw, or what it did not do. */
|
|
64
|
+
export type DescribeResult = { described: Described } | { failed: string };
|
|
65
|
+
|
|
66
|
+
async function textOf(stream: Readable): Promise<string> {
|
|
67
|
+
const decoder = new TextDecoder();
|
|
68
|
+
let text = "";
|
|
69
|
+
for await (const chunk of stream) text += decoder.decode(chunk as Uint8Array, { stream: true });
|
|
70
|
+
return text + decoder.decode();
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Read what a script declares, in a process of its own, boxed when the runs of the script are.
|
|
75
|
+
* Every call starts a process: what is asked more than once for a version of the script is asked of `describe-cache.ts`.
|
|
76
|
+
*/
|
|
77
|
+
export async function describeScript(file: string, box?: ScriptBox, run = "describe"): Promise<DescribeResult> {
|
|
78
|
+
const child = await spawnScriptChild("describe", file, [], run, box);
|
|
79
|
+
child.stdin.on("error", () => undefined);
|
|
80
|
+
child.stdin.end();
|
|
81
|
+
const stderr = textOf(child.stderr);
|
|
82
|
+
const timer = setTimeout(() => child.kill(), DESCRIBE_MS);
|
|
83
|
+
let said: z.infer<typeof Message> | undefined;
|
|
84
|
+
try {
|
|
85
|
+
const decoder = new TextDecoder();
|
|
86
|
+
let buffer = "";
|
|
87
|
+
for await (const chunk of child.stdout) {
|
|
88
|
+
buffer += decoder.decode(chunk, { stream: true });
|
|
89
|
+
for (let at = buffer.indexOf("\n"); at >= 0; at = buffer.indexOf("\n")) {
|
|
90
|
+
const line = buffer.slice(0, at).trim();
|
|
91
|
+
buffer = buffer.slice(at + 1);
|
|
92
|
+
// A line the module wrote itself is not the child's answer.
|
|
93
|
+
if (line.startsWith(PROTOCOL_PREFIX)) said = Message.parse(JSON.parse(line.slice(PROTOCOL_PREFIX.length)));
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
const reason = (await stderr).trim();
|
|
97
|
+
if (said === undefined) return { failed: reason !== "" ? reason : "the module ended without saying what it declares" };
|
|
98
|
+
if (said.kind === "failed") return { failed: said.error };
|
|
99
|
+
const problems: Described["problems"] = [];
|
|
100
|
+
const schemaOf = (key: "input" | "output", declared: z.infer<typeof Declaration> | undefined): JsonSchemaValue | undefined => {
|
|
101
|
+
if (declared === undefined) return undefined;
|
|
102
|
+
if ("problem" in declared) {
|
|
103
|
+
problems.push({ key, message: declared.problem });
|
|
104
|
+
return undefined;
|
|
105
|
+
}
|
|
106
|
+
return declared.schema;
|
|
107
|
+
};
|
|
108
|
+
const input = schemaOf("input", said.input);
|
|
109
|
+
const output = schemaOf("output", said.output);
|
|
110
|
+
const emits = said.emits === undefined ? undefined : emitsOf(said.emits, problems);
|
|
111
|
+
if (said.phases !== undefined && "problem" in said.phases) problems.push({ key: "phases", message: said.phases.problem });
|
|
112
|
+
const phases = said.phases !== undefined && "phases" in said.phases ? said.phases.phases : undefined;
|
|
113
|
+
return {
|
|
114
|
+
described: {
|
|
115
|
+
...(said.name === undefined ? {} : { name: said.name }),
|
|
116
|
+
...(said.description === undefined ? {} : { description: said.description }),
|
|
117
|
+
...(input === undefined ? {} : { input }),
|
|
118
|
+
...(output === undefined ? {} : { output }),
|
|
119
|
+
...(emits === undefined ? {} : { emits }),
|
|
120
|
+
...(phases === undefined ? {} : { phases }),
|
|
121
|
+
problems,
|
|
122
|
+
},
|
|
123
|
+
};
|
|
124
|
+
} finally {
|
|
125
|
+
clearTimeout(timer);
|
|
126
|
+
child.kill();
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** The records of `emits` whose schema is JSON Schema; the others are problems. */
|
|
131
|
+
function emitsOf(declared: z.infer<typeof EmitsDeclaration>, problems: Described["problems"]): DeclaredEmit[] {
|
|
132
|
+
if ("problem" in declared) {
|
|
133
|
+
problems.push({ key: "emits", message: declared.problem });
|
|
134
|
+
return [];
|
|
135
|
+
}
|
|
136
|
+
const emits: DeclaredEmit[] = [];
|
|
137
|
+
for (const one of declared) {
|
|
138
|
+
if ("problem" in one) problems.push({ key: "emits", message: one.problem });
|
|
139
|
+
else emits.push({ name: one.name, schema: one.schema });
|
|
140
|
+
}
|
|
141
|
+
return emits;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* The record types a script writes, by their full name `wf.<name>.<record>`, with the JSON Schema of their data.
|
|
146
|
+
* A script with no `name` writes none: its records would have no prefix of their own.
|
|
147
|
+
*/
|
|
148
|
+
export function emittedTypesOf(read: DescribeResult): Array<{ record: string; type: string; schema: JsonSchemaValue }> {
|
|
149
|
+
if (!("described" in read) || read.described.name === undefined) return [];
|
|
150
|
+
const prefix = `${SCRIPT_TYPES}${read.described.name}.`;
|
|
151
|
+
return (read.described.emits ?? []).map((one) => ({ record: one.name, type: `${prefix}${one.name}`, schema: one.schema }));
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** The text of a value with its keys in order: two schemas that say the same thing give the same text. */
|
|
155
|
+
function canonical(value: unknown): string {
|
|
156
|
+
if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
|
|
157
|
+
if (typeof value === "object" && value !== null) {
|
|
158
|
+
return `{${Object.entries(value)
|
|
159
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
|
|
160
|
+
.map(([key, member]) => `${JSON.stringify(key)}:${canonical(member)}`)
|
|
161
|
+
.join(",")}}`;
|
|
162
|
+
}
|
|
163
|
+
return JSON.stringify(value) ?? "null";
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* The hash of a contract: the two schemas of a script, as JSON Schema, and the records it emits when it declares any.
|
|
168
|
+
* An absent schema is a part of the contract too.
|
|
169
|
+
*/
|
|
170
|
+
export function contractOf(declared: Pick<Described, "input" | "output" | "emits">): ContractHash {
|
|
171
|
+
const parts: unknown[] = [declared.input ?? null, declared.output ?? null];
|
|
172
|
+
if (declared.emits !== undefined && declared.emits.length > 0) parts.push(declared.emits);
|
|
173
|
+
return ContractHash.parse(createHash("sha256").update(canonical(parts)).digest("hex"));
|
|
174
|
+
}
|
package/src/guide.ts
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The guide of `workflow.guide`: how to write a script, by hand, and then what the host
|
|
3
|
+
* generates — the typing and the catalogue of the actions the caller may use.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import type { ActionDescription, ActionName } from "@niwa-labs/core";
|
|
7
|
+
|
|
8
|
+
import type { Trigger } from "./check.ts";
|
|
9
|
+
import { scriptTyping } from "./script-types.ts";
|
|
10
|
+
import type { HarnessBlock } from "./script-types.ts";
|
|
11
|
+
|
|
12
|
+
/** How a script is written. Short: the types say the rest. */
|
|
13
|
+
export const HOW_TO_WRITE = `A workflow script is a file that exports, by default, the call workflow({ ... }, fn): what it declares, and
|
|
14
|
+
the async function that is the script. It runs in a process of its own; every call it makes goes to the host and
|
|
15
|
+
is a step of the run. The names below are globals: do not import them (z is zod). The generated declarations give
|
|
16
|
+
their types. A script may import packages: the record types, query builders and helpers plugins give scripts.
|
|
17
|
+
|
|
18
|
+
import { taskDone } from "@niwa-labs/tasks/records";
|
|
19
|
+
|
|
20
|
+
export default workflow({
|
|
21
|
+
name: "build",
|
|
22
|
+
description: "Make a task and wait for it",
|
|
23
|
+
input: z.object({ text: z.string(), minutes: z.number().int().default(30) }),
|
|
24
|
+
output: z.object({ task: z.string() }),
|
|
25
|
+
uses: ["task.*", "niwa.records.read"],
|
|
26
|
+
}, async ({ text, minutes }) => {
|
|
27
|
+
const task = await niwa.task.create({ ... }, { label: "create" });
|
|
28
|
+
const done = await wait(taskDone(task.id), { timeout: minutes + "m" });
|
|
29
|
+
if ("timedOut" in done && !(await ask.confirm("Keep waiting?", { timeout: "10m" }))) return { task: "gave up" };
|
|
30
|
+
await sleep("5m");
|
|
31
|
+
return { task: task.id };
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
- The declaration is the contract. input is a z.object: the fields of the flags and the form, and the function is
|
|
35
|
+
given it parsed, with the defaults put in; a start whose arguments do not pass it is refused before a run
|
|
36
|
+
exists (input-invalid, with the fields). output is what the function returns: a script with no output returns
|
|
37
|
+
nothing, and a script with no input is given nothing. The type checker holds the function to both: a wrong field is an
|
|
38
|
+
error with its place. A result that does not pass output ends the run as failed (output-invalid, with the fields).
|
|
39
|
+
Both must be written in JSON Schema without loss: z.unknown(), z.any(), transforms, z.custom and dates are refused.
|
|
40
|
+
- workflow.check reads the declaration by loading the module in a process of its own, where the names of niwa are
|
|
41
|
+
stubs that throw: imports at the top work, and the function is never run. It gives description, input and output as
|
|
42
|
+
JSON Schema and a contract hash; workflow.get and workflow.installation.get show them. A run keeps the hash of the contract it began under: a
|
|
43
|
+
resume that finds another contract stops on the revise pause when the arguments it recorded no longer pass input.
|
|
44
|
+
- name, uses and on are read from the text of the declaration, as literals, so what a script may do is known without
|
|
45
|
+
running it.
|
|
46
|
+
|
|
47
|
+
Calling actions:
|
|
48
|
+
- niwa.<group>.<action>(input, { label }) calls the action <group>.<action>. call(name, input, { label }) is the
|
|
49
|
+
same by name. A name with a dash is niwa.agent["search-old"]. ask({ harness, visible, model, effort, mode, cwd }, prompt) starts a session
|
|
50
|
+
(a call of session.start.<harness>) in the directory cwd, or in the host's own directory when it is absent, with the model,
|
|
51
|
+
effort and mode given (mode is "ask", "auto" or "full"; auto when absent), which it keeps for its whole life (a kind that cannot apply them refuses the call); it sees only the action that answers, plus the names or masks in visible,
|
|
52
|
+
which must lie within the grant of the run. The harness is one the host serves (an unknown one is an error of the check), and a model or an effort is checked against the list its adapter gives, where it gives one.
|
|
53
|
+
The options of the harness's kind go in the block named after the kind:
|
|
54
|
+
ask({ harness: "claude-sonnet", claude: { advisor: false } }, prompt); only the block of that harness's kind is typed,
|
|
55
|
+
the block of another kind, or a field the block does not have, is an error of the check and is refused, and a session
|
|
56
|
+
resumed later starts again with the options it was started with.
|
|
57
|
+
- ask({ worktree: true }, prompt) runs the session in a new git worktree (the git module's git.worktree.create) of cwd's
|
|
58
|
+
repository, or { worktree: { repo, base, description } }; the base is the repository's current branch when absent. When the
|
|
59
|
+
call ends with the worktree clean and no new commit, it is removed; otherwise the answer carries
|
|
60
|
+
worktree: { id, path, branch, changed: true } and the branch stays for you, the agent or the owner to merge: niwa never merges.
|
|
61
|
+
With a worktree the answer is an object, so a schema is a z.object (or z.record); any other schema is an error of the check.
|
|
62
|
+
- ask({ box: { allow: ["bun", { read: "~/data" }] } }, prompt) gives the session's box more than the host's default
|
|
63
|
+
(the project and the toolchains), and { box: { only: [{ read: "." }] } } gives it that instead; an item is a profile's
|
|
64
|
+
name, "project", "toolchains", { read }, { write } or { net }. The session always has its own installation's profile.
|
|
65
|
+
Beyond the default the run's uses needs the rule: "box.use@bun", "box.read@/path/*", "box.write@...", "box.net@<host>".
|
|
66
|
+
- ask({ schema }, prompt) with a zod schema gives a typed answer. z is a global (zod, no import): write the schema
|
|
67
|
+
with z.object({ ... }), pass it, and the call gives the answer already parsed, typed as z.infer<typeof Schema>.
|
|
68
|
+
Without schema the call gives { answer }, the text. The schema goes to the host as JSON Schema and is part of the
|
|
69
|
+
step. A finished one-shot question with the same prompt and harness reuses its recorded answer without
|
|
70
|
+
asking again. An answer that does not pass the schema is never returned: a harness with structured output
|
|
71
|
+
has the call fail (the run pauses for a retry, a skip or a cancel), and for the others the session is told what
|
|
72
|
+
was wrong when it submits, and answers again. A rule JSON Schema cannot say (a .refine, a .transform that
|
|
73
|
+
needs code) is checked only in the script, after the step is recorded: a replay gives the same recorded answer, so
|
|
74
|
+
a failure of such a rule repeats until the call gets a new label or another schema.
|
|
75
|
+
|
|
76
|
+
const Review = z.object({ verdict: z.enum(["approve", "changes"]), notes: z.array(z.string()) });
|
|
77
|
+
const review = await ask({ harness: "codex", schema: Review }, "Review the diff in ./src");
|
|
78
|
+
if (review.verdict === "changes") log(review.notes.join("\n"));
|
|
79
|
+
- For a conversation, const s = session({ harness: "codex", label: "reviewer" }).
|
|
80
|
+
Each await s.ask(prompt, { schema, label }) is a durable turn in that same conversation.
|
|
81
|
+
Use await s.end() to close it. The run closes any sessions still open when it ends.
|
|
82
|
+
uses must cover session.start.<harness>, session.ask and session.end.
|
|
83
|
+
tools chooses "all", "niwa-only", or { allow: [...] } for harness tools. visible selects Niwa actions.
|
|
84
|
+
A prompt can be text or ordered { sections: [{ id, tier, text }] }. The first ask opens the session.
|
|
85
|
+
To obtain its id, ref and address immediately, use const opened = await session(options).
|
|
86
|
+
- To message a named agent, await agent("rin").tell(text, { label: "report" }) with agent.tell in uses.
|
|
87
|
+
Its inbox receives the message and the call returns its message id.
|
|
88
|
+
- uses lists the actions the script calls, as names or masks ("task.*"). The check holds the script to it:
|
|
89
|
+
a call outside the list is an error, and so is an ask() call on a harness it does not list as "session.start.<harness>";
|
|
90
|
+
a harness known only when the script runs is a warning of the check, which asks for an entry that covers it. The run holds exactly those rights, narrowed from the caller's: a mask the
|
|
91
|
+
caller does not hold refuses the start. Without uses a script started by a caller with a grant may call
|
|
92
|
+
nothing; only a caller that nothing limits (the host itself) gets every action.
|
|
93
|
+
- Run workflow.check { file } before workflow.start: it type-checks the script against the declarations below and
|
|
94
|
+
does not run it. workflow.start refuses a script with errors.
|
|
95
|
+
|
|
96
|
+
Registered workflows:
|
|
97
|
+
- workflow.register { file } checks the script and issues its id wf-…; workflow.register { file, id } registers a
|
|
98
|
+
new version of that workflow. A version is the hash of the script and the local files it imports. A registered
|
|
99
|
+
script says what it is in workflow({ description }). workflow.list and workflow.get show the workflows.
|
|
100
|
+
- workflow.start { id, args } runs the latest version and answers the id of the run (run-…); workflow.start { file }
|
|
101
|
+
runs a script once without registering it. A run belongs to a directory, the project it is for: the CLI and the MCP
|
|
102
|
+
server pass their working directory, and workflow.start { directory } names another one.
|
|
103
|
+
- Every registered workflow is the action flow.<id>: it runs the workflow to its end and answers its output. A script
|
|
104
|
+
calls it as niwa.flow["wf-a3f9c2"](input) with "flow.wf-a3f9c2" in uses. When a workflow changes its contract, the
|
|
105
|
+
ones that call it are checked again; one that no longer passes is broken and does not start until a version passes.
|
|
106
|
+
|
|
107
|
+
Scripts niwa starts by itself:
|
|
108
|
+
- on lists the records that start the script: a type, or a type with a filter written as a literal,
|
|
109
|
+
on: ["task.done", { type: "message.sent", filter: { "to.id": "owner" } }]. The header is read as text, so a
|
|
110
|
+
type is named there as text, never by an imported reference; references are for wait and read.records. The filter is equality on fields of
|
|
111
|
+
the data of the record (a dotted path goes into nested data), as the filter of wait is; the check refuses a path
|
|
112
|
+
no record of the type holds, and a literal its field cannot hold. The function gets the record as its argument,
|
|
113
|
+
typed as NiwaTrigger: { id, type, data }, narrowed to the types on lists. A script with on has no input. The record gives its author no rights.
|
|
114
|
+
- workflow.install { id | file, description } checks the script, issues the installation id sub-…, makes the profile
|
|
115
|
+
wf:<sub-…> = narrow(the installer's grant, uses) and pins the hash of the file; from then on niwa starts one run per
|
|
116
|
+
matching record under that profile, and the start of each run names the installation. Records from before the
|
|
117
|
+
installation start nothing. workflow.uninstall { id }, workflow.installation.list and workflow.installation.get
|
|
118
|
+
end and list them. Narrowing the installer's grant narrows the runs that start after it, and closing it stops new runs;
|
|
119
|
+
the runs that live keep the grant they were born with.
|
|
120
|
+
|
|
121
|
+
Time and the outside:
|
|
122
|
+
- wait(type, { filter, from, timeout }) gives { data, at }: the first record of that type written after from (a
|
|
123
|
+
position an earlier wait or read gave) or after the wait began, whose data holds every field of the filter (a
|
|
124
|
+
field, or a dotted path), and its position; or { timedOut: true }. A wait from at misses nothing written after
|
|
125
|
+
the record. There is no waitAny.
|
|
126
|
+
- A type is its name as text, or the type itself imported from the records entry of the plugin that declares it:
|
|
127
|
+
import { TaskDone } from "@niwa-labs/tasks/records"; then wait(TaskDone, { filter: { task: task.id }, from }) and
|
|
128
|
+
read.records(TaskDone, { filter, from, limit }) give data typed by its schema, and read.records({ types: [TaskDone,
|
|
129
|
+
TaskUpdated] }) data typed by each. The import is resolved from the folder of the script, so the plugin's package
|
|
130
|
+
must be found from there; a registered copy and a boxed run find packages in the node_modules niwa runs with, and
|
|
131
|
+
the packages of other repositories that a plugin on the host offers to scripts (@niwa-labs/forge/flow).
|
|
132
|
+
The host waits for and reads the type at the version it writes; the check and the run refuse a type the host
|
|
133
|
+
does not know and a reference to another version of it.
|
|
134
|
+
- The records entry of a plugin also gives query builders: taskDone(task.id) from "@niwa-labs/tasks/records" is the
|
|
135
|
+
type and the filter of the end of one task. wait(taskDone(task.id), { from, timeout }) and
|
|
136
|
+
read.records(taskDone(task.id)) take it as they take a type, and the check follows it to its type. The flow entry of a plugin gives helpers that wait
|
|
137
|
+
as a step of the script: untilSessionEnded("end", { session, timeout }) from "@niwa-labs/history/flow".
|
|
138
|
+
- sleep(ms | "5m") records its wake-up moment: a replay does not sleep from the start.
|
|
139
|
+
- ask.choice(text, options, opts), ask.multi, ask.confirm(text, opts), ask.text(text, opts) and ask.form(text, zodObject, opts) ask the owner and give a typed value (the id picked, the ids, a boolean, a string, what the schema parses); opts is { timeout, label }. A cancel or no answer in time throws an error named AskCancelled or AskExpired, which the script may catch (it is never a false answer); uncaught, the run waits for a revision or a cancel, since a retry would get the same error.
|
|
140
|
+
- const Blocked = record("blocked", z.object({ pr: z.number() })) declares a record; workflow({ name, emits: [Blocked] }) lists it,
|
|
141
|
+
and emit(Blocked, { pr }) writes wf.<name>.blocked, the data held to the schema (a script emits nothing it does not list);
|
|
142
|
+
wait(type) and read.records({ types }) give data typed by the type; read.state(plugin), read.records(query), now() and random()
|
|
143
|
+
are recorded reads. read.records({ from, types, filter, stream, limit, tail }) gives { records, next }: types are exact
|
|
144
|
+
names or families written prefix.*, and next is the position to read or wait on from.
|
|
145
|
+
- What the script does is held to the grant of the run: wait, read.state and read.records need niwa.records.read,
|
|
146
|
+
a call needs its action. ask, emit (emit:wf.*, which every run has), sleep, now and random need nothing in
|
|
147
|
+
uses.
|
|
148
|
+
|
|
149
|
+
Steps and replay:
|
|
150
|
+
- Every call is a step under its label, or under its place among the calls of its branch. Give a label to any
|
|
151
|
+
call that must keep its result when the script is reordered. A finished step is never repeated.
|
|
152
|
+
- parallel([() => ...]) or parallel({ a: () => ..., b: () => ... }, { concurrency }) and pipeline([() => ..., (previous) => ...])
|
|
153
|
+
(two to four stages, each given the value before it, typed) group calls; phase(title) says where the script is (below);
|
|
154
|
+
log(text) writes a line to the log of the run.
|
|
155
|
+
|
|
156
|
+
Scopes:
|
|
157
|
+
- scope(name, { concurrency, onExit, deadline, onDeadline, shield }, async (s) => { s.start(key, fn); await s.next(); }) is a
|
|
158
|
+
group of branches that never outlive it. s.next() gives the outcomes ({ key, result: { ok, value } | { ok: false, error } })
|
|
159
|
+
in the order the host committed them, and null when all were read; s.ready(), s.rest(), s.pending(), s.cancel(reason, keys)
|
|
160
|
+
and s.run(key, { id, args }) (a branch that is a child run) go with it. Keys and names are words: no ".", "~", "/" or ":".
|
|
161
|
+
- Leaving the block waits for the branches left (onExit "wait") or cancels them ("cancel"); a block that throws cancels them,
|
|
162
|
+
and a cancel goes down into the scopes inside, except a shield ({ shield: true }), whose block an outer cancel waits for.
|
|
163
|
+
A cancelled branch gives { ok: false, error: { name: "Cancelled" } }; a branch that ended keeps its result.
|
|
164
|
+
- deadline cancels the scope when it runs out: onDeadline "skip" gives undefined, "fail" throws DeadlineExceeded;
|
|
165
|
+
moveOnAfter(name, "5m", fn) and failAfter(name, "5m", fn) are the short forms. stream(name, { a: fn, b: fn }) starts the
|
|
166
|
+
branches and gives their outcomes one at a time (next(), for await) until it is closed; race(name, { a: fn, b: fn }) gives the
|
|
167
|
+
first branch that succeeds. parallel, stream and race are scopes; workflow.start { concurrency } caps every scope of a run.
|
|
168
|
+
|
|
169
|
+
Phases:
|
|
170
|
+
- workflow({ phases: [{ title: "Review" }, { title: "Fix", detail: "fix what was confirmed" }], ... }) declares the plan of the
|
|
171
|
+
script, in order, as a literal: titles are not empty and are not repeated. phase("Review") enters one: the type checker
|
|
172
|
+
allows only the declared titles (in the declarations below NiwaPhase is never: they declare no phases), and an undeclared
|
|
173
|
+
one fails the script where it is named. Steps take no phase: a step is in the phase its branch is in when it begins.
|
|
174
|
+
- phase() at the top sets the phase of the script. A branch of parallel or pipeline starts in the phase of the branch that
|
|
175
|
+
made it; phase() inside a branch changes that branch only, so branches can be in different phases at once:
|
|
176
|
+
phase("Review");
|
|
177
|
+
await parallel(items.map((item) => async () => { await review(item); phase("Fix"); await fix(item); }));
|
|
178
|
+
phase("Report");
|
|
179
|
+
- workflow.inspect and workflow.wait show the plan (status.phases) and the phases the run is in (status.currentPhases):
|
|
180
|
+
current is the phase of a branch that is going (several while branches are in different ones; the script itself is not
|
|
181
|
+
in its phase while its parallel runs); done is a phase entered, not current, before every current one (with no current
|
|
182
|
+
phase, every phase entered: a run that finished with its result has all it entered done); ahead is the rest — not entered,
|
|
183
|
+
or entered by a branch that ended while another branch has not reached it. workflow.inspect groups the steps by phase;
|
|
184
|
+
workflow.get and workflow.list show the declared phases.
|
|
185
|
+
- Edit the file and resume the run by its id: the calls along the longest unchanged prefix of the earlier start are taken
|
|
186
|
+
(the same key and the same call; an agent call is its prompt and harness), and the first new or changed call and everything
|
|
187
|
+
after it in its branch, or after its scope, run. A call with an effect that ran before is taken all the same, never made
|
|
188
|
+
twice. workflow.resume { run, from } runs the steps from a step key, a branch or a phase on again.`;
|
|
189
|
+
|
|
190
|
+
/** What the guide answers with. */
|
|
191
|
+
export interface Guide {
|
|
192
|
+
guide: string;
|
|
193
|
+
declarations: string;
|
|
194
|
+
actions: Array<{ name: string; description: string; input: string }>;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/** The guide for the actions a caller may call. */
|
|
198
|
+
export function guideFor(
|
|
199
|
+
description: readonly ActionDescription[],
|
|
200
|
+
callable: readonly ActionName[],
|
|
201
|
+
triggers: readonly Trigger[] = [],
|
|
202
|
+
blocks: ReadonlyMap<string, HarnessBlock> = new Map(),
|
|
203
|
+
): Guide {
|
|
204
|
+
const typing = scriptTyping(description, callable, triggers, [], blocks);
|
|
205
|
+
const wanted = new Set<string>(callable);
|
|
206
|
+
return {
|
|
207
|
+
guide: HOW_TO_WRITE,
|
|
208
|
+
declarations: typing.declarations,
|
|
209
|
+
actions: description
|
|
210
|
+
.filter((action) => wanted.has(action.name))
|
|
211
|
+
.map((action) => ({ name: action.name, description: action.description, input: typing.inputs.get(action.name) ?? "unknown" })),
|
|
212
|
+
};
|
|
213
|
+
}
|