@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.
Files changed (114) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +13 -2
  3. package/package.json +55 -4
  4. package/src/actions.ts +408 -0
  5. package/src/agent.ts +211 -0
  6. package/src/ask.ts +84 -0
  7. package/src/bridge.ts +710 -0
  8. package/src/catalogue.ts +74 -0
  9. package/src/check.ts +880 -0
  10. package/src/child.ts +1378 -0
  11. package/src/cockpit/actions.ts +128 -0
  12. package/src/cockpit/catalogue-actions.ts +97 -0
  13. package/src/cockpit/dashboard.tsx +134 -0
  14. package/src/cockpit/groups.ts +45 -0
  15. package/src/cockpit/index.tsx +50 -0
  16. package/src/cockpit/launch.tsx +136 -0
  17. package/src/cockpit/plan.ts +101 -0
  18. package/src/cockpit/run-commands.tsx +102 -0
  19. package/src/cockpit/run-page.tsx +140 -0
  20. package/src/cockpit/run-summary.ts +16 -0
  21. package/src/cockpit/runs.tsx +73 -0
  22. package/src/cockpit/statistics.tsx +176 -0
  23. package/src/cockpit/track.tsx +159 -0
  24. package/src/cockpit/workflows.tsx +383 -0
  25. package/src/describe-cache.ts +122 -0
  26. package/src/describe.ts +174 -0
  27. package/src/guide.ts +213 -0
  28. package/src/index.ts +2813 -0
  29. package/src/inspect.ts +235 -0
  30. package/src/installation.ts +90 -0
  31. package/src/language.ts +217 -0
  32. package/src/records-entry.ts +63 -0
  33. package/src/records.ts +574 -0
  34. package/src/registry.ts +250 -0
  35. package/src/revise.ts +89 -0
  36. package/src/runner.ts +339 -0
  37. package/src/script-types.ts +549 -0
  38. package/src/stats.ts +460 -0
  39. package/src/status.ts +512 -0
  40. package/src/store.ts +259 -0
  41. package/src/subscriptions.ts +102 -0
  42. package/src/waiting.ts +61 -0
  43. package/test/cockpit-actions.test.ts +20 -0
  44. package/test/cockpit-groups.test.ts +42 -0
  45. package/test/cockpit-plan.test.ts +118 -0
  46. package/test/fixtures/branches-host.ts +58 -0
  47. package/test/fixtures/branches-script.js +23 -0
  48. package/test/fixtures/bridge-host.ts +23 -0
  49. package/test/fixtures/bridge-keys-script.js +15 -0
  50. package/test/fixtures/bridge-wait-script.js +8 -0
  51. package/test/fixtures/cancel-host.ts +58 -0
  52. package/test/fixtures/cancel-script.js +12 -0
  53. package/test/fixtures/crash-host.ts +61 -0
  54. package/test/fixtures/crash-script.js +14 -0
  55. package/test/fixtures/ping-records.ts +20 -0
  56. package/test/fixtures/revision-host.ts +57 -0
  57. package/test/fixtures/revision-script.js +11 -0
  58. package/test/fixtures/running-host.ts +61 -0
  59. package/test/fixtures/running-script.js +12 -0
  60. package/test/fixtures/with-data/flow.ts +2 -0
  61. package/test/fixtures/with-data/table.json +1 -0
  62. package/test/git-repo.ts +45 -0
  63. package/test/git-worktree.test.ts +413 -0
  64. package/test/question-format.test.ts +279 -0
  65. package/test/workflow-agent-caps.test.ts +91 -0
  66. package/test/workflow-agent-lifetime.test.ts +93 -0
  67. package/test/workflow-agent-options.test.ts +216 -0
  68. package/test/workflow-agent-schema.test.ts +386 -0
  69. package/test/workflow-agent-typings.test.ts +241 -0
  70. package/test/workflow-ask-resume.test.ts +145 -0
  71. package/test/workflow-branch-keys.test.ts +133 -0
  72. package/test/workflow-bridge-inproc.test.ts +230 -0
  73. package/test/workflow-bridge.test.ts +141 -0
  74. package/test/workflow-builtin-candidate.test.ts +230 -0
  75. package/test/workflow-builtin.test.ts +197 -0
  76. package/test/workflow-cancel-agent.test.ts +144 -0
  77. package/test/workflow-cancel.test.ts +166 -0
  78. package/test/workflow-chain.test.ts +84 -0
  79. package/test/workflow-check-options.test.ts +144 -0
  80. package/test/workflow-check-uses.test.ts +148 -0
  81. package/test/workflow-check.test.ts +282 -0
  82. package/test/workflow-contract.test.ts +295 -0
  83. package/test/workflow-crash-resume.test.ts +141 -0
  84. package/test/workflow-deadline.test.ts +102 -0
  85. package/test/workflow-describe-cache.test.ts +240 -0
  86. package/test/workflow-directory.test.ts +73 -0
  87. package/test/workflow-emits.test.ts +261 -0
  88. package/test/workflow-group-keys.test.ts +72 -0
  89. package/test/workflow-harnesses.test.ts +262 -0
  90. package/test/workflow-inspect.test.ts +152 -0
  91. package/test/workflow-language-types.test.ts +148 -0
  92. package/test/workflow-manifest.test.ts +93 -0
  93. package/test/workflow-manual-pause.test.ts +116 -0
  94. package/test/workflow-owners.test.ts +154 -0
  95. package/test/workflow-pause.test.ts +200 -0
  96. package/test/workflow-phases.test.ts +445 -0
  97. package/test/workflow-plugin-entries.test.ts +59 -0
  98. package/test/workflow-record-refs.test.ts +310 -0
  99. package/test/workflow-replay.test.ts +206 -0
  100. package/test/workflow-resume-once.test.ts +188 -0
  101. package/test/workflow-revision.test.ts +216 -0
  102. package/test/workflow-scope.test.ts +505 -0
  103. package/test/workflow-script-defaults.test.ts +119 -0
  104. package/test/workflow-script-error.test.ts +228 -0
  105. package/test/workflow-script-libraries.test.ts +88 -0
  106. package/test/workflow-script-packages.test.ts +119 -0
  107. package/test/workflow-stdout.test.ts +89 -0
  108. package/test/workflow-stop.test.ts +299 -0
  109. package/test/workflow-store.test.ts +220 -0
  110. package/test/workflow-visible.test.ts +136 -0
  111. package/test/workflow-wait-version.test.ts +54 -0
  112. package/test/workflow-wait.test.ts +224 -0
  113. package/test/workflow-waiting-agent.test.ts +64 -0
  114. package/tsconfig.json +15 -0
@@ -0,0 +1,549 @@
1
+ /**
2
+ * The typing of a workflow script, generated from what the host describes: the language
3
+ * functions and one typed wrapper `niwa.<group>.<action>(input, opts)` per
4
+ * action. Nothing here is kept by hand per action: a plugin that declares an action adds it to
5
+ * the typing with no change in this file.
6
+ *
7
+ * The text is global declarations with no import and no export, so it is the same text for the
8
+ * type checker (`check.ts`) and for an author (`workflow.guide`).
9
+ */
10
+
11
+ import { z } from "zod";
12
+
13
+ import type { ActionDescription, Grant, JsonSchema } from "@niwa-labs/core";
14
+ import type { ActionName } from "@niwa-labs/core";
15
+ import type { OptionsBlock } from "@niwa-labs/harness";
16
+
17
+ /** The options block a harness takes, as the sessions module reports it: its name, and its JSON Schema. */
18
+ export interface HarnessBlock {
19
+ readonly block: OptionsBlock;
20
+ readonly schema: JsonSchema;
21
+ }
22
+
23
+ /** The names of a script that do not depend on the host: the language, and the call by name. */
24
+ const LANGUAGE = `type NiwaDuration = number | string;
25
+ type NiwaCallOptions = { label?: string; reason?: string };
26
+
27
+ /** zod, with no import: z.object({ ... }) as a value, z.infer<typeof Schema> as a type. */
28
+ declare const z: typeof import("zod").z;
29
+ declare namespace z {
30
+ type infer<T> = import("zod").z.infer<T>;
31
+ type input<T> = import("zod").z.input<T>;
32
+ type output<T> = import("zod").z.output<T>;
33
+ }
34
+ type NiwaPrompt = string | { sections: { id: string; tier: "constant" | "stable" | "volatile"; text: string }[] };
35
+ interface NiwaSession {
36
+ readonly id: string;
37
+ readonly ref: string;
38
+ readonly address: { kind: "session"; harness: string; id: string };
39
+ readonly worktree?: Omit<NiwaSessionWorktree, "changed">;
40
+ ask<S extends import("zod").z.ZodType>(prompt: NiwaPrompt, options: { schema: S; label?: string }): Promise<import("zod").z.output<S>>;
41
+ ask(prompt: NiwaPrompt, options?: { label?: string }): Promise<{ answer: string }>;
42
+ end(options?: NiwaCallOptions): Promise<void>;
43
+ }
44
+
45
+ /** The worktree an ask({ worktree }) call left because the work changed something in it; a clean one is removed. */
46
+ type NiwaSessionWorktree = { id: string; path: string; branch: string; changed: boolean };
47
+ /** What ask({ worktree }) takes: true, or the repository (default: cwd), the base (default: its current branch) and a description. */
48
+ type NiwaWorktreeOption = true | { repo?: string; base?: string; description?: string };
49
+ /** One thing a box asks for: a profile by its name, "project", "toolchains", or a path or a host. */
50
+ type NiwaBoxItem = string | { read: string } | { write: string } | { net: string };
51
+ /** What ask({ box }) takes: items added to the host's default (allow), or put instead of it (only). Beyond the default takes the run's box.* rules. */
52
+ type NiwaBoxAccess = { allow: NiwaBoxItem[] } | { only: NiwaBoxItem[] };
53
+ declare function session(options: NiwaSessionOptions): Pick<NiwaSession, "ask" | "end"> & PromiseLike<NiwaSession>;
54
+ declare function agent(name: "agent.tell" extends keyof NiwaActions ? string : never): { tell(text: string, options?: NiwaCallOptions): Promise<{ message: string }> };
55
+ /** Sleep; a replay does not sleep from the start. */
56
+ declare function sleep(duration: NiwaDuration, opts?: NiwaCallOptions): Promise<void>;
57
+ type NiwaAskOption = string | { id: string; label?: string; description?: string };
58
+ type NiwaAskId<T> = T extends string ? T : T extends { id: infer I extends string } ? I : never;
59
+ type NiwaAskOptions = { timeout?: NiwaDuration; label?: string };
60
+ /** Ask a model with ask(options, prompt), or the owner with a named method. Each owner question gives a typed value. A cancel or no answer within the timeout throws AskCancelled or AskExpired, which the script may catch; uncaught, the run waits for a revision or a cancel. */
61
+ declare const ask: {
62
+ <S extends import("zod").z.ZodObject | import("zod").z.ZodRecord>(options: NiwaSessionOptions & { schema: S; worktree: NonNullable<NiwaSessionOptions["worktree"]> }, prompt: NiwaPrompt): Promise<import("zod").z.output<S> & { worktree?: NiwaSessionWorktree }>;
63
+ (options: NiwaSessionOptions & { schema?: undefined; worktree: NonNullable<NiwaSessionOptions["worktree"]> }, prompt: NiwaPrompt): Promise<{ answer: string; worktree?: NiwaSessionWorktree }>;
64
+ <S extends import("zod").z.ZodType>(options: NiwaSessionOptions & { schema: S; worktree?: undefined }, prompt: NiwaPrompt): Promise<import("zod").z.output<S>>;
65
+ (options: NiwaSessionOptions & { schema?: undefined; worktree?: undefined }, prompt: NiwaPrompt): Promise<{ answer: string }>;
66
+ choice<const O extends readonly NiwaAskOption[]>(text: string, options: O, opts?: NiwaAskOptions): Promise<NiwaAskId<O[number]>>;
67
+ multi<const O extends readonly NiwaAskOption[]>(text: string, options: O, opts?: NiwaAskOptions): Promise<NiwaAskId<O[number]>[]>;
68
+ confirm(text: string, opts?: NiwaAskOptions): Promise<boolean>;
69
+ text(text: string, opts?: NiwaAskOptions): Promise<string>;
70
+ form<S extends import("zod").z.ZodType>(text: string, schema: S, opts?: NiwaAskOptions): Promise<import("zod").z.output<S>>;
71
+ };
72
+ /** A record a script declares with record(name, schema), lists in workflow({ emits }) and writes with emit. */
73
+ interface NiwaRecordType<S extends import("zod").z.ZodType = import("zod").z.ZodType> { readonly niwaRecord: true; readonly name: string; readonly schema: S }
74
+ /** Declare a record the script writes: its name, under the script's own wf.<name>., and the zod schema of its data. */
75
+ declare function record<S extends import("zod").z.ZodType>(name: string, schema: S): NiwaRecordType<S>;
76
+ /** Write a record the script lists in workflow({ emits }): the data is held to the record's schema. */
77
+ declare function emit<S extends import("zod").z.ZodType>(record: NiwaRecordType<S>, data: import("zod").z.input<S>, opts?: NiwaCallOptions): Promise<void>;
78
+ /** The clock of the host, recorded. */
79
+ declare function now(opts?: NiwaCallOptions): Promise<number>;
80
+ /** A random number, recorded. */
81
+ declare function random(opts?: NiwaCallOptions): Promise<number>;
82
+ /** How a branch ended: its value, or its error by name and message (a cancelled branch is named Cancelled). */
83
+ type NiwaSettled<T> = { ok: true; value: T } | { ok: false; error: { name: string; message: string } };
84
+ /** A branch of a scope: its key, its outcome, and its value (which throws what the branch threw). */
85
+ interface NiwaBranch<R> { readonly key: string; settled(): Promise<NiwaSettled<R>>; value(): Promise<R> }
86
+ /** A scope: start branches in it, read their outcomes in the order the host committed them, cancel the ones left. */
87
+ interface NiwaScope {
88
+ readonly path: string[];
89
+ start<R>(key: string, fn: () => R | Promise<R>): NiwaBranch<Awaited<R>>;
90
+ /** A branch that is a run of a registered workflow, started as a child of this run. */
91
+ run<R = unknown>(key: string, child: { id: string; version?: string; args?: unknown }): NiwaBranch<R>;
92
+ /** The next outcome, or null when every branch ended and was read. */
93
+ next(): Promise<{ key: string; result: NiwaSettled<unknown> } | null>;
94
+ /** The outcomes ready now and not read yet. */
95
+ ready(): Promise<Array<{ key: string; result: NiwaSettled<unknown> }>>;
96
+ /** Every branch, by key, once each ended. */
97
+ rest(): Promise<Record<string, NiwaSettled<unknown>>>;
98
+ /** The keys of the branches still going. */
99
+ pending(): Promise<string[]>;
100
+ /** Cancel the branches still going, or those named. */
101
+ cancel(reason?: string, keys?: string[]): Promise<void>;
102
+ }
103
+ type NiwaScopeOptions = { concurrency?: number; onExit?: "wait" | "cancel"; deadline?: NiwaDuration; onDeadline?: "skip" | "fail"; shield?: boolean };
104
+ /**
105
+ * A group of branches: nothing started in it outlives it. Leaving the block waits for the branches (onExit "wait", the default)
106
+ * or cancels them ("cancel"); a block that throws cancels them, and so does an outer cancel unless the scope is a shield. With a
107
+ * deadline the scope is cancelled when it runs out: onDeadline "skip" gives undefined, "fail" throws DeadlineExceeded.
108
+ */
109
+ declare function scope<T>(name: string, opts: (NiwaScopeOptions & { deadline?: undefined }) | undefined, fn: (s: NiwaScope) => Promise<T>): Promise<T>;
110
+ /** With a deadline and onDeadline "fail" the scope gives its value or throws. */
111
+ declare function scope<T>(name: string, opts: NiwaScopeOptions & { deadline: NiwaDuration; onDeadline: "fail" }, fn: (s: NiwaScope) => Promise<T>): Promise<T>;
112
+ /** With a deadline that may skip (the default), the scope past it gives undefined. */
113
+ declare function scope<T>(name: string, opts: NiwaScopeOptions | undefined, fn: (s: NiwaScope) => Promise<T>): Promise<T | undefined>;
114
+ declare function scope<T>(name: string, fn: (s: NiwaScope) => Promise<T>): Promise<T>;
115
+ /** Run the block for at most the duration: past it the block is cancelled and the call gives undefined. */
116
+ declare function moveOnAfter<T>(name: string, duration: NiwaDuration, fn: () => Promise<T>): Promise<T | undefined>;
117
+ /** Run the block for at most the duration: past it the block is cancelled and the call throws DeadlineExceeded. */
118
+ declare function failAfter<T>(name: string, duration: NiwaDuration, fn: () => Promise<T>): Promise<T>;
119
+ /** The error a scope that ran out of time throws with onDeadline "fail". */
120
+ declare class DeadlineExceeded extends Error {}
121
+ /** Branches at once, by the index of a list or the keys of an object; the answer has the same shape. A branch that fails cancels the others. */
122
+ declare function parallel<T>(thunks: Array<() => T | Promise<T>>, opts?: { concurrency?: number }): Promise<Awaited<T>[]>;
123
+ declare function parallel<B extends Record<string, () => unknown>>(branches: B, opts?: { concurrency?: number }): Promise<{ [K in keyof B]: Awaited<ReturnType<B[K]>> }>;
124
+ /** A stream of branches: their outcomes one at a time, in the order the host committed them; closing it cancels the rest. */
125
+ interface NiwaStream<K extends string, T> extends AsyncIterable<{ key: K; result: NiwaSettled<T> }> {
126
+ next(): Promise<{ key: K; result: NiwaSettled<T> } | null>;
127
+ ready(): Promise<Array<{ key: K; result: NiwaSettled<T> }>>;
128
+ rest(): Promise<Record<K, NiwaSettled<T>>>;
129
+ pending(): Promise<K[]>;
130
+ cancel(keys?: K[]): Promise<void>;
131
+ close(): Promise<void>;
132
+ [Symbol.asyncDispose](): Promise<void>;
133
+ }
134
+ declare function stream<K extends string, T>(name: string, branches: Record<K, () => T | Promise<T>>, opts?: { concurrency?: number }): NiwaStream<K, Awaited<T>>;
135
+ /** The first branch to succeed, with its key; the others are cancelled. When every branch fails, the first error is thrown. */
136
+ declare function race<K extends string, T>(name: string, branches: Record<K, () => T | Promise<T>>): Promise<{ key: K; value: Awaited<T> }>;
137
+ /** Stages run one after another; each is given what the one before gave, awaited, and the call gives all of them. From two to four stages. */
138
+ declare function pipeline<A, B>(stages: [() => A, (previous: Awaited<A>) => B]): Promise<[Awaited<A>, Awaited<B>]>;
139
+ declare function pipeline<A, B, C>(stages: [() => A, (previous: Awaited<A>) => B, (previous: Awaited<B>) => C]): Promise<[Awaited<A>, Awaited<B>, Awaited<C>]>;
140
+ declare function pipeline<A, B, C, D>(stages: [() => A, (previous: Awaited<A>) => B, (previous: Awaited<B>) => C, (previous: Awaited<C>) => D]): Promise<[Awaited<A>, Awaited<B>, Awaited<C>, Awaited<D>]>;
141
+ /** Enter a phase the script declares in workflow({ phases }): the steps after it belong to it. In a branch of parallel or pipeline it changes that branch only; a branch starts in the phase of the one that made it. */
142
+ declare function phase(title: NiwaPhase): void;
143
+ declare function log(text: string): void;
144
+ /** The record a script with \`on\` is given, as a name or a name with a filter written as a literal. */
145
+ type NiwaOn = string | { type: string; filter?: Record<string, unknown> };
146
+ /** What \`workflow\` declares that does not depend on the shape of the script. */
147
+ type NiwaDeclaration = { name?: string; description?: string; uses?: string[]; emits?: NiwaRecordType[]; phases?: Array<{ title: string; detail?: string }> };
148
+ /** What the default export of a script is: what \`workflow(...)\` gives. */
149
+ interface NiwaWorkflow { readonly niwaWorkflow: true }
150
+ /** The result a function of a script returns: what its \`output\` says, or nothing when it has none. */
151
+ type NiwaResult<O extends import("zod").z.ZodType> = [O] extends [never] ? void : import("zod").z.output<O>;
152
+ /** What the function of a script is given: the record for a script with \`on\`, else its parsed \`input\`, else nothing. */
153
+ type NiwaInput<I extends import("zod").z.ZodObject, On> = [On] extends [undefined] ? ([I] extends [never] ? [] : [import("zod").z.output<I>]) : [NiwaTrigger];
154
+ /**
155
+ * The script: \`export default workflow({ description, input, output, uses, on }, async (input) => { ... })\`.
156
+ * The function is given \`input\` parsed (a script with no \`input\` is given nothing, a script with \`on\` is given the
157
+ * record, typed by what \`on\` lists) and returns what \`output\` says (a script with no \`output\` returns nothing).
158
+ * \`input\` is a \`z.object\`, and a script has an \`input\` or an \`on\`, not both.
159
+ */
160
+ declare function workflow<I extends import("zod").z.ZodObject = never, O extends import("zod").z.ZodType = never, On extends NiwaOn[] | undefined = undefined>(
161
+ declaration: NiwaDeclaration & { input?: I; output?: O; on?: On },
162
+ run: (...input: NiwaInput<I, On>) => Promise<NiwaResult<O>>,
163
+ ): NiwaWorkflow;`;
164
+
165
+ /** The prefix of the action that starts a session of a harness and asks it: what an `session({ harness })` goes to. */
166
+ const AGENT_ACTION_PREFIX = "session.start.";
167
+
168
+ /** The harness an agent action serves: `codex` of `session.start.codex`; absent for any other action. */
169
+ export function harnessOfAction(name: string): string | undefined {
170
+ return name.startsWith(AGENT_ACTION_PREFIX) && name.length > AGENT_ACTION_PREFIX.length ? name.slice(AGENT_ACTION_PREFIX.length) : undefined;
171
+ }
172
+
173
+ /** The type of a field of the input of an action: the literals it lists, else what its schema says. */
174
+ function fieldType(input: Schema, field: string): string {
175
+ const properties = typeof input === "object" && typeof input.properties === "object" && input.properties !== null ? (input.properties as Record<string, unknown>) : {};
176
+ const member = properties[field];
177
+ return isSchema(member) ? schemaToType(member, { root: "unknown", defs: "unknown" }) : "string";
178
+ }
179
+
180
+ /** The names of the blocks the harnesses of a host take, each once. */
181
+ function blockNames(blocks: ReadonlyMap<string, HarnessBlock>): OptionsBlock[] {
182
+ return [...new Set([...blocks.values()].map((one) => one.block))].sort();
183
+ }
184
+
185
+ /**
186
+ * The options blocks of a harness: the block of its kind, typed as that kind declares it, and every other block `never`,
187
+ * so the block of another kind is an error of the check and not an extra field the checker may let through.
188
+ */
189
+ function blocksTyping(names: readonly OptionsBlock[], own: OptionsBlock | undefined): string {
190
+ return `{ ${names.map((block) => (block === own ? `${literal(block)}?: NiwaOptionBlocks[${literal(block)}]` : `${literal(block)}?: never`)).join("; ")} }`;
191
+ }
192
+
193
+ /**
194
+ * The options of `ask()`: the harness is one of those the caller may call a `session.start.<harness>` action for; the
195
+ * model and the effort are the literals that action lists, where the adapter lists them; and the options block is the
196
+ * one the sessions module binds the harness to (`blocks`), and no other. A call with no harness names no kind, so it
197
+ * takes no block. A host that serves no harness has nothing to check one against, so a harness is any text and any block
198
+ * is taken; a host that serves some holds a script to the ones it may call, and a script that may call none names none.
199
+ */
200
+ function agentTyping(description: readonly ActionDescription[], callable: ReadonlySet<string>, blocks: ReadonlyMap<string, HarnessBlock>): string {
201
+ const names = blockNames(blocks);
202
+ const common = `{ label?: string; visible?: string[]; tools?: "all" | "niwa-only" | { allow: readonly string[] }; mode?: "ask" | "auto" | "full"; cwd?: string; worktree?: NiwaWorktreeOption; stuckAfter?: NiwaDuration; box?: NiwaBoxAccess }`;
203
+ const hosted = description.filter((action) => harnessOfAction(action.name) !== undefined);
204
+ const served = hosted.filter((action) => callable.has(action.name));
205
+ const variants =
206
+ hosted.length === 0
207
+ ? ["{ harness?: string; model?: string; effort?: string } & NiwaOptionBlocks"]
208
+ : [
209
+ `{ harness?: undefined; model?: string; effort?: string } & ${blocksTyping(names, undefined)}`,
210
+ ...served.map((action) => {
211
+ const harness = action.name.slice(AGENT_ACTION_PREFIX.length);
212
+ return `{ harness: ${literal(harness)}; model?: ${fieldType(action.input, "model")}; effort?: ${fieldType(action.input, "effort")} } & ${blocksTyping(names, blocks.get(harness)?.block)}`;
213
+ }),
214
+ ];
215
+ return `/** What ask() takes: the harness is one the host serves, its model and effort are the ones that harness lists, and its options block is the one of its kind. */\ntype NiwaSessionOptions = ${common} & (${variants.map((variant) => `(${variant})`).join(" | ")});`;
216
+ }
217
+
218
+ /** A JSON Schema as a value: an object, or a boolean. */
219
+ type Schema = Readonly<Record<string, unknown>> | boolean;
220
+
221
+ /** Where a rendered schema finds the types it points at. */
222
+ interface Scope {
223
+ /** The alias the root of the schema is, for `$ref: "#"`. */
224
+ readonly root: string;
225
+ /** The prefix of the aliases of the definitions, for `$ref: "#/$defs/<name>"`. */
226
+ readonly defs: string;
227
+ }
228
+
229
+ const isSchema = (value: unknown): value is Schema =>
230
+ typeof value === "boolean" || (typeof value === "object" && value !== null && !Array.isArray(value));
231
+
232
+ const list = (value: unknown): Schema[] => (Array.isArray(value) ? value.filter(isSchema) : []);
233
+
234
+ const identifier = (text: string): string => text.replace(/[^A-Za-z0-9_]/g, "_");
235
+
236
+ /** A comment that cannot end early. */
237
+ const doc = (text: string, indent: string): string =>
238
+ `${indent}/** ${text.replace(/\*\//g, "*\\/").replace(/\s*\n\s*/g, " ")} */\n`;
239
+
240
+ const literal = (value: unknown): string => JSON.stringify(value) ?? "unknown";
241
+
242
+ function union(parts: readonly string[]): string {
243
+ const unique = [...new Set(parts)];
244
+ if (unique.length === 0) return "never";
245
+ return unique.length === 1 ? (unique[0] ?? "never") : unique.map((part) => `(${part})`).join(" | ");
246
+ }
247
+
248
+ /** A JSON Schema as a TypeScript type. A member with no equivalent is `unknown`. */
249
+ export function schemaToType(schema: Schema, scope: Scope, indent = ""): string {
250
+ if (schema === true) return "unknown";
251
+ if (schema === false) return "never";
252
+ const ref = schema.$ref;
253
+ if (typeof ref === "string") {
254
+ if (ref === "#") return scope.root;
255
+ if (ref.startsWith("#/$defs/")) return `${scope.defs}${identifier(ref.slice("#/$defs/".length))}`;
256
+ return "unknown";
257
+ }
258
+ if ("const" in schema) return literal(schema.const);
259
+ if (Array.isArray(schema.enum)) return union(schema.enum.map(literal));
260
+ const variants = list(schema.anyOf ?? schema.oneOf);
261
+ if (variants.length > 0) return union(variants.map((variant) => schemaToType(variant, scope, indent)));
262
+ const parts = list(schema.allOf);
263
+ if (parts.length > 0) return parts.map((part) => `(${schemaToType(part, scope, indent)})`).join(" & ");
264
+ const type = schema.type;
265
+ if (Array.isArray(type)) {
266
+ return union(type.map((one) => schemaToType({ ...schema, type: one }, scope, indent)));
267
+ }
268
+ switch (type) {
269
+ case "string":
270
+ return "string";
271
+ case "number":
272
+ case "integer":
273
+ return "number";
274
+ case "boolean":
275
+ return "boolean";
276
+ case "null":
277
+ return "null";
278
+ case "array":
279
+ return arrayType(schema, scope, indent);
280
+ case "object":
281
+ return objectType(schema, scope, indent);
282
+ default:
283
+ return schema.properties === undefined ? "unknown" : objectType(schema, scope, indent);
284
+ }
285
+ }
286
+
287
+ function arrayType(schema: Readonly<Record<string, unknown>>, scope: Scope, indent: string): string {
288
+ const prefix = list(schema.prefixItems).map((item) => schemaToType(item, scope, indent));
289
+ const items = isSchema(schema.items) ? schemaToType(schema.items, scope, indent) : undefined;
290
+ if (prefix.length === 0) return `Array<${items ?? "unknown"}>`;
291
+ return `[${[...prefix, ...(items === undefined ? [] : [`...Array<${items}>`])].join(", ")}]`;
292
+ }
293
+
294
+ function objectType(schema: Readonly<Record<string, unknown>>, scope: Scope, indent: string): string {
295
+ const properties =
296
+ typeof schema.properties === "object" && schema.properties !== null
297
+ ? Object.entries(schema.properties as Record<string, unknown>)
298
+ : [];
299
+ const required = new Set(Array.isArray(schema.required) ? schema.required : []);
300
+ const extra = schema.additionalProperties;
301
+ const open = isSchema(extra) && extra !== false;
302
+ const index = open ? `[key: string]: ${schemaToType(extra, scope, indent)}` : undefined;
303
+ // An object that takes no field at all is not `{}`, which takes any value but null.
304
+ if (properties.length === 0) return index !== undefined ? `{ ${index} }` : extra === false ? "Record<string, never>" : "{}";
305
+ const inner = `${indent} `;
306
+ const lines = properties.map(([name, member]) => {
307
+ const note =
308
+ typeof member === "object" && member !== null && typeof (member as { description?: unknown }).description === "string"
309
+ ? doc((member as { description: string }).description, inner)
310
+ : "";
311
+ const type = isSchema(member) ? schemaToType(member, scope, inner) : "unknown";
312
+ return `${note}${inner}${literal(name)}${required.has(name) ? "" : "?"}: ${type};\n`;
313
+ });
314
+ const body = `{\n${lines.join("")}${indent}}`;
315
+ // Named properties and an open index meet in an intersection, so the properties need not fit the index.
316
+ return index === undefined ? body : `${body} & { ${index} }`;
317
+ }
318
+
319
+ /**
320
+ * The options of each kind the host's harnesses are of, one block each, made from the schemas those kinds declare: what
321
+ * ask() takes besides its own options. Two harnesses of one kind have one block.
322
+ */
323
+ function optionBlocksTyping(blocks: ReadonlyMap<string, HarnessBlock>): string {
324
+ const first = new Map<OptionsBlock, JsonSchema>();
325
+ for (const one of blocks.values()) if (!first.has(one.block)) first.set(one.block, one.schema);
326
+ const each = [...first.entries()]
327
+ .sort(([a], [b]) => a.localeCompare(b))
328
+ .map(([block, schema]) => ({ block, alias: `NiwaOptionBlock$${identifier(block)}`, schema }));
329
+ const text = each.map((one) => aliases(one.schema as Schema, one.alias).text).join("");
330
+ const fields = each.map((one) => `${literal(one.block)}?: ${one.alias}`).join("; ");
331
+ return `${text}/** The options of the harness's kind, in the block named after the kind; the block of another kind is refused. */\ntype NiwaOptionBlocks = { ${fields} };\n`;
332
+ }
333
+
334
+ /** The language of a script that reads the journal: \`wait\` and \`read\`, typed by the data of the record types the script names. */
335
+ const RECORDS = `/** The dotted paths into data: a field, or a field of a field. */
336
+ type NiwaPath<D, Depth extends unknown[] = []> = Depth["length"] extends 4
337
+ ? never
338
+ : D extends readonly unknown[]
339
+ ? never
340
+ : D extends object
341
+ ? { [K in keyof D & string]-?: K | \`\${K}.\${NiwaPath<NonNullable<D[K]>, [...Depth, 0]>}\` }[keyof D & string]
342
+ : never;
343
+ /** The value at a dotted path into data. */
344
+ type NiwaAt<D, P extends string> = D extends unknown
345
+ ? P extends keyof D
346
+ ? D[P]
347
+ : P extends \`\${infer Head}.\${infer Rest}\`
348
+ ? Head extends keyof D
349
+ ? NiwaAt<NonNullable<D[Head]>, Rest>
350
+ : never
351
+ : never
352
+ : never;
353
+ /** The filter of a wait: values for fields of the data, by field name or dotted path. Data of any shape takes any field. */
354
+ type NiwaFilter<D> = unknown extends D ? Record<string, unknown> : { [P in NiwaPath<D>]?: NiwaAt<D, P> };
355
+ /**
356
+ * A record type a plugin declares, imported from its records entry (\`import { TaskDone } from "@niwa-labs/tasks/records"\`):
357
+ * a wait or a read that names it gives the data its schema gives.
358
+ */
359
+ type NiwaRecordRef<D = unknown> = { readonly kind: "record"; readonly name: string; readonly version: number; readonly schema: { readonly _zod: { readonly output: D } } };
360
+ /** The data of the records of a referenced type. */
361
+ type NiwaDataOf<R> = R extends { readonly schema: { readonly _zod: { readonly output: infer D } } } ? D : unknown;
362
+ /** The first record of the type whose data holds every field of the filter, written after \`from\` or after the wait began: its data and its position. Without a timeout it waits for ever. */
363
+ declare function wait<T extends keyof NiwaRecords>(type: T, opts?: { filter?: NiwaFilter<NiwaRecords[T]>; from?: number; label?: string; timeout?: undefined }): Promise<{ data: NiwaRecords[T]; at: number }>;
364
+ /** The same, or { timedOut: true } at the end of the timeout: options that may hold a timeout give both. */
365
+ declare function wait<T extends keyof NiwaRecords>(type: T, opts: { filter?: NiwaFilter<NiwaRecords[T]>; from?: number; label?: string; timeout?: NiwaDuration }): Promise<{ data: NiwaRecords[T]; at: number } | { timedOut: true }>;
366
+ /** The first record of the referenced type whose data holds every field of the filter, written after \`from\` or after the wait began: its data, typed by the type, and its position. */
367
+ declare function wait<R extends NiwaRecordRef<any>>(type: R, opts?: { filter?: NiwaFilter<NiwaDataOf<R>>; from?: number; label?: string; timeout?: undefined }): Promise<{ data: NiwaDataOf<R>; at: number }>;
368
+ /** The same, or { timedOut: true } at the end of the timeout. */
369
+ declare function wait<R extends NiwaRecordRef<any>>(type: R, opts: { filter?: NiwaFilter<NiwaDataOf<R>>; from?: number; label?: string; timeout?: NiwaDuration }): Promise<{ data: NiwaDataOf<R>; at: number } | { timedOut: true }>;
370
+ /** A query of one referenced type and a filter on its data, as a plugin's query builder gives it (\`taskDone(task)\`). A wait looks at every stream: a query that names one is for a read. */
371
+ type NiwaTypeQuery<R> = { readonly types: readonly [R]; readonly filter?: NiwaFilter<NiwaDataOf<R>>; readonly from?: number; readonly stream?: undefined };
372
+ /** The first record that answers the query, written after \`from\` (the option, else the query's) or after the wait began: its data, typed by the type, and its position. */
373
+ declare function wait<R extends NiwaRecordRef<any>>(query: NiwaTypeQuery<R>, opts?: { from?: number; label?: string; timeout?: undefined }): Promise<{ data: NiwaDataOf<R>; at: number }>;
374
+ /** The same, or { timedOut: true } at the end of the timeout. */
375
+ declare function wait<R extends NiwaRecordRef<any>>(query: NiwaTypeQuery<R>, opts: { from?: number; label?: string; timeout?: NiwaDuration }): Promise<{ data: NiwaDataOf<R>; at: number } | { timedOut: true }>;
376
+ /** A record as the journal keeps it. */
377
+ type NiwaStoredRecord<T extends string, D> = { id: string; seq: number; stream: string; type: T; schema: number; data: D; cause: string | null; root: string; at: number; actor: { kind: string } };
378
+ /** Where a read of the journal starts, what stream it reads, and how much. */
379
+ type NiwaReadQuery = { from?: number; stream?: string; limit?: number; tail?: number };
380
+ /** What a read answers: the records, and the position to read or wait on from. */
381
+ type NiwaRead<R> = { records: R[]; next: number };
382
+ /**
383
+ * Whether a list of record types names only known types: a tuple of at least one type of the catalogue or reference. A
384
+ * list that may be empty (one built at run time) selects every type when it is, and one that holds a name the catalogue does
385
+ * not know, or a family, has no data type to give.
386
+ */
387
+ type NiwaKnownOnly<T extends readonly unknown[]> = T extends readonly [] ? false : number extends T["length"] ? false : T[number] extends (keyof NiwaRecords & string) | NiwaRecordRef<any> ? true : false;
388
+ /** The data of a record type named as text or by reference. */
389
+ type NiwaDataOfType<S> = S extends keyof NiwaRecords ? NiwaRecords[S] : NiwaDataOf<S>;
390
+ /** The filter of a read of a list of types: by the data of the types when every one is known, else by any field. */
391
+ type NiwaTypesFilter<T extends readonly unknown[]> = NiwaKnownOnly<T> extends true ? NiwaFilter<NiwaDataOfType<T[number]>> : Record<string, unknown>;
392
+ /** A record of one known type, with its data typed by it; over a union of types, one record type each. */
393
+ type NiwaRecordOf<S> = S extends keyof NiwaRecords & string ? NiwaStoredRecord<S, NiwaRecords[S]> : S extends NiwaRecordRef<any> ? NiwaStoredRecord<string, NiwaDataOf<S>> : never;
394
+ /** The records a read of a list of types answers with: typed when every type is known, else of data of unknown shape. */
395
+ type NiwaTypesRecords<T extends readonly unknown[]> = NiwaKnownOnly<T> extends true ? NiwaRecordOf<T[number]> : NiwaStoredRecord<string, unknown>;
396
+ declare const read: {
397
+ state(plugin: string, opts?: NiwaCallOptions): Promise<any>;
398
+ /** The records of a referenced type whose data holds the filter, with their data typed by the type. */
399
+ records<R extends NiwaRecordRef<any>>(type: R, query?: NiwaReadQuery & { filter?: NiwaFilter<NiwaDataOf<R>> }, opts?: NiwaCallOptions): Promise<NiwaRead<NiwaStoredRecord<string, NiwaDataOf<R>>>>;
400
+ /**
401
+ * The records of a list of types: names, families written prefix.* or references; a query a plugin's builder gives is one. A list
402
+ * of known types written out ([TaskDone], ["task.done"]) types the filter and the data of each record by its type; any other list,
403
+ * one that may be empty or has a name the catalogue does not know, takes a filter on any field and gives data of unknown shape.
404
+ */
405
+ records<const T extends ReadonlyArray<string | NiwaRecordRef<any>> = readonly []>(query?: NiwaReadQuery & { types?: T; filter?: NiwaTypesFilter<T> }, opts?: NiwaCallOptions): Promise<NiwaRead<NiwaTypesRecords<T>>>;
406
+ };`;
407
+
408
+ /** The typing of what a script reads of the journal: the data of each record type of the catalogue, and `wait` and `read` typed by it. */
409
+ function recordTyping(records: ReadonlyArray<{ name: string; schema: JsonSchema }>): string {
410
+ const data = records.map((one, index) => aliases(one.schema, `NiwaRecord${String(index)}Data`));
411
+ const byType = records.map((one, index) => ` ${literal(one.name)}: NiwaRecord${String(index)}Data;\n`);
412
+ return `${data.map((alias) => alias.text).join("")}/** The data of the records a script may wait for and read, by type. */\ninterface NiwaRecords {\n${byType.join("")}}\n${RECORDS}`;
413
+ }
414
+
415
+ /** The titles of the phases the script declares: what \`phase(title)\` may name. A script with no phases names none. */
416
+ function phaseTyping(phases: readonly string[]): string {
417
+ return `/** The phases the script declares in workflow({ phases }), by title: phase(title) names one. No phases declared: phase() takes nothing. */\ntype NiwaPhase = ${union(phases.map(literal))};`;
418
+ }
419
+
420
+ /** The aliases of one schema: its root, and the definitions it holds; and the type the root is. */
421
+ function aliases(schema: Schema, name: string): { text: string; type: string } {
422
+ const scope: Scope = { root: name, defs: `${name}$` };
423
+ const defs =
424
+ typeof schema === "object" && typeof schema.$defs === "object" && schema.$defs !== null
425
+ ? Object.entries(schema.$defs as Record<string, unknown>)
426
+ : [];
427
+ const own = defs.map(([key, def]) => `type ${scope.defs}${identifier(key)} = ${isSchema(def) ? schemaToType(def, scope) : "unknown"};\n`);
428
+ const type = schemaToType(schema, scope);
429
+ return { text: `${own.join("")}type ${name} = ${type};\n`, type };
430
+ }
431
+
432
+ /**
433
+ * The action names a script may call: the names of a catalogue that a mask of `uses` allows.
434
+ *
435
+ * A script with no `uses` asks for nothing, so it may call nothing, unless whoever starts it is
436
+ * limited by no grant: then there is nothing to narrow and it may call whatever is served.
437
+ */
438
+ export function allowedFor(
439
+ names: readonly ActionName[],
440
+ uses: readonly string[] | undefined,
441
+ rights: Grant | "unlimited",
442
+ ): ActionName[] {
443
+ if (uses === undefined) return rights === "unlimited" ? [...names] : [];
444
+ return names.filter((name) => uses.some((mask) => matches(mask, name)));
445
+ }
446
+
447
+ /** Whether a mask names the action: `task.create`, `task.*` (everything under `task.`) or `*`. */
448
+ export function matches(mask: string, name: string): boolean {
449
+ if (mask === "*") return true;
450
+ if (mask.endsWith(".*")) return name.startsWith(mask.slice(0, -1));
451
+ return mask === name;
452
+ }
453
+
454
+ interface Node {
455
+ action?: { input: string; output: string };
456
+ children: Map<string, Node>;
457
+ }
458
+
459
+ function addAction(root: Node, name: string, action: { input: string; output: string }): void {
460
+ let node = root;
461
+ for (const part of name.split(".")) {
462
+ let child = node.children.get(part);
463
+ if (child === undefined) {
464
+ child = { children: new Map() };
465
+ node.children.set(part, child);
466
+ }
467
+ node = child;
468
+ }
469
+ node.action = action;
470
+ }
471
+
472
+ function renderNode(node: Node, indent: string): string {
473
+ const inner = `${indent} `;
474
+ const members = [...node.children].map(([key, child]) => `${inner}${literal(key)}: ${renderNode(child, inner)};\n`);
475
+ const call =
476
+ node.action === undefined
477
+ ? []
478
+ : [`${inner}(input: ${node.action.input}, opts?: NiwaCallOptions): Promise<${node.action.output}>;\n`];
479
+ return `{\n${call.join("")}${members.join("")}${indent}}`;
480
+ }
481
+
482
+ /** The typing of a script: the declarations, and the type of the input of each action in them. */
483
+ export interface ScriptTyping {
484
+ declarations: string;
485
+ inputs: ReadonlyMap<ActionName, string>;
486
+ }
487
+
488
+ /**
489
+ * The typing of a script: the language, the actions by name for `call`, and the wrappers
490
+ * `niwa.<group>.<action>`.
491
+ *
492
+ * `callable` is the list of the actions the script may call: it decides what is declared. The
493
+ * host's own list is `description`; an action not in `callable` is not declared, so a call of it
494
+ * is an error of the type checker. `blocks` binds each harness to its options block; `phases` are the titles the script declares: what `phase(title)` may name.
495
+ */
496
+ export function scriptTyping(
497
+ description: readonly ActionDescription[],
498
+ callable: readonly ActionName[],
499
+ triggers: ReadonlyArray<{ name: string; schema: JsonSchema }> = [],
500
+ records: ReadonlyArray<{ name: string; schema: JsonSchema }> = [],
501
+ blocks: ReadonlyMap<string, HarnessBlock> = new Map(),
502
+ phases: readonly string[] = [],
503
+ ): ScriptTyping {
504
+ const wanted = new Set<string>(callable);
505
+ const taken = new Set<string>();
506
+ const root: Node = { children: new Map() };
507
+ const types: string[] = [];
508
+ const byName: string[] = [];
509
+ const inputs = new Map<ActionName, string>();
510
+ for (const action of description) {
511
+ if (!wanted.has(action.name)) continue;
512
+ const base = action.name
513
+ .split(/[^A-Za-z0-9]+/)
514
+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
515
+ .join("");
516
+ let own = base;
517
+ for (let n = 2; taken.has(own); n += 1) own = `${base}${String(n)}`;
518
+ taken.add(own);
519
+ const input = aliases(action.input, `${own}Input`);
520
+ types.push(input.text, aliases(action.output, `${own}Output`).text);
521
+ inputs.set(action.name, input.type);
522
+ byName.push(` ${literal(action.name)}: { input: ${own}Input; output: ${own}Output };\n`);
523
+ addAction(root, action.name, { input: `${own}Input`, output: `${own}Output` });
524
+ }
525
+ // The record a script that starts on records is given: what the default export takes.
526
+ const triggerTypes = triggers.map((trigger, index) => aliases(trigger.schema, `NiwaTrigger${String(index)}Data`));
527
+ const triggerUnion = union(
528
+ triggers.map((trigger, index) => `{ id: string; type: ${literal(trigger.name)}; data: NiwaTrigger${String(index)}Data }`),
529
+ );
530
+ const declarations = [
531
+ "// Generated from the actions the host describes. Do not edit.",
532
+ LANGUAGE,
533
+ phaseTyping(phases),
534
+ optionBlocksTyping(blocks),
535
+ agentTyping(description, wanted, blocks),
536
+ "",
537
+ triggerTypes.map((alias) => alias.text).join(""),
538
+ `/** The record that started the run, for a script with on: the argument of its function. */\ntype NiwaTrigger = ${triggerUnion};`,
539
+ recordTyping(records),
540
+ types.join(""),
541
+ `interface NiwaActions {\n${byName.join("")}}`,
542
+ "/** Call an action by name. */",
543
+ 'declare function call<Name extends keyof NiwaActions>(name: Name, input: NiwaActions[Name]["input"], opts?: NiwaCallOptions): Promise<NiwaActions[Name]["output"]>;',
544
+ `/** The actions as functions: niwa.task.create(input, { label }) is call("task.create", input, { label }). */`,
545
+ `declare const niwa: ${renderNode(root, "")};`,
546
+ "",
547
+ ].join("\n");
548
+ return { declarations, inputs };
549
+ }