fyflow-plugin-sdk 0.3.0 → 0.5.0

package/README.md

@@ -18,13 +18,17 @@ export default definePlugin({
   id: "acme.signer", // stable and unique across Plugins
   version: "1.0.0",
   base: import.meta.url, // what Worker `url`s resolve against
+  // Set on the Host's Profiles, once for every Node Type that takes them (see Profiles and secrets).
+  profile: {
+    schema: {
+      type: "object",
+      properties: { key: { type: "string", writeOnly: true } }, // a secret
+    },
+    startup: ["key"], // read once, when a Worker starts
+  },
   workers: {
     sign: {
       url: "./sign.worker.js",
-      configSchema: {
-        type: "object",
-        properties: { key: { type: "string", writeOnly: true } }, // a Profile secret
-      },
       settingsSchema: { type: "object", properties: { field: { type: "string" } } },
     },
   },
@@ -32,6 +36,7 @@ export default definePlugin({
     Sign: {
       worker: "sign",
       inline: true,
+      profile: ["key"], // the fields of `profile` its Workers get
       groups: ["acme.signing"],
       icon: "signature", // from the app's icon set, below
       description: "Signs a field with HMAC.",
@@ -50,11 +55,12 @@ export default definePlugin({
 
 | Field | What it is |
 | --- | --- |
-| `workers` | Worker modules by key. A Worker module's default export is a class: its constructor gets the Profile's config, and `run({ settings, input }, context)` does one Task (see [Workers](#workers)). Schemas are JSON Schema in fyflow's subset. A Worker's `outputSchema`, what `run` returns (accepted by every version of the SDK, as fyflow's own Worker entry), is the form a person fills in to mark a failed Task done, and the paths the editor suggests for conditions on its Node's Edges and gates before any Run. |
-| `nodeTypes` | Node Types by name, each naming one of this Plugin's `workers`, with fyflow's declaration fields (`inline`, `pool`, `config`, `settings` defaults, `retryPolicy`, `groups`), and, since 0.2.0, how the app shows it: an optional `icon` and a one-line `description`. |
+| `profile` | The Plugin's Profile fields, since 0.5.0: one object `schema`, `defaults` for fields no Profile sets, the `startup` fields its Workers read when they start, and the per-Task fields only a Profile may set (`profileOnly`). See [Profiles and secrets](#profiles-and-secrets). |
+| `workers` | Worker modules by key. A Worker module's default export is a class: its constructor gets the start-up fields its Node Type takes, and `run({ settings, input }, context)` does one Task (see [Workers](#workers)). A Worker declares no `configSchema` since 0.5.0: its config is the Plugin's `profile`. Schemas are JSON Schema in fyflow's subset. A Worker's `outputSchema`, what `run` returns (accepted by every version of the SDK, as fyflow's own Worker entry), is the form a person fills in to mark a failed Task done, and the paths the editor suggests for conditions on its Node's Edges and gates before any Run. |
+| `nodeTypes` | Node Types by name, each naming one of this Plugin's `workers`, with fyflow's declaration fields (`inline`, `pool`, `settings` defaults, `retryPolicy`, `groups`; no `config` since 0.5.0), since 0.2.0 how the app shows it (an optional `icon` and a one-line `description`), and since 0.5.0 the `profile` fields it takes. |
 | `gateTypes` | Gate types by name: their routes, default route, settings schema, and the decision `fn`. |
 | `groupTypes` | Resource Group types by name: a `create(config, key)` factory for the scheduler's limit, and a `configSchema`. |
-| `groups` | Resource Groups by key, of fyflow's built-in types (`ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`) or this Plugin's own. A Node Type may use its own Plugin's groups, and the built-in Plugin's `disk` group (below). |
+| `groups` | Resource Groups by key, of fyflow's built-in types (`ConcurrentLimitGroup`, `RateLimitGroup`, `KeyedRateLimitGroup`) or this Plugin's own. A Node Type may use its own Plugin's groups, and the built-in Plugin's `disk` and `cpu` groups (below). |
 
 Do not name a setting like a member of every JavaScript object (`constructor`, `toString`, `valueOf`, `hasOwnProperty`, `__proto__`). The Host hands Agents a Flow Definition's shape as a JSON Schema that includes your `settingsSchema`, and some JSON Schema validators misread such a property: they refuse, or throw, on a Flow that is valid.
 
@@ -74,10 +80,10 @@ A Plugin's own imports resolve from the Plugin directory's `node_modules`, so `n
 Declare the SDK versions your Plugin works with as a peer dependency:
 
 ```json
-{ "peerDependencies": { "fyflow-plugin-sdk": "^0.2.0" } }
+{ "peerDependencies": { "fyflow-plugin-sdk": "^0.5.0" } }
 ```
 
-A Host implements its SDK version (`SDK_VERSION`, exported here) and the earlier ones it is compatible with (`SDK_COMPATIBLE`): a 0.3 Host still loads a Plugin declaring `^0.2.0` or `^0.1.0`. It skips, with the reason, a Plugin whose range excludes them all. Raise the range only for what a Host must do at run time: declare `^0.2.0` when you use `icon` or `description`. The Worker types of 0.3.0 vanish at run time (`import type`), so take 0.3 as a devDependency for them and leave the peer range as it was.
+A Host implements its SDK version (`SDK_VERSION`, exported here) and the earlier ones it is compatible with (`SDK_COMPATIBLE`). It skips, with the reason, a Plugin whose range excludes them all. 0.5.0 changed what Profiles are, so it is compatible with no earlier version: a Plugin written for 0.4 or before is skipped until it is upgraded, as [UPGRADING.md](./UPGRADING.md) describes. From 0.5 on, raise the range only for what a Host must do at run time.
 
 ## Icons
 
@@ -85,7 +91,7 @@ A Node Type's `icon` names one of the app's icons, from [Lucide](https://lucide.
 
 ## Workers
 
-A Worker module's default export is a class. The Host builds each instance (one per worker of the pool: a thread, or on an inline pool an object on the Host's own thread) with the config of the Profile the pool is for, and reuses it across Tasks, so keep per-Task state out of fields. `run` gets the Task's envelope (the Node's `settings` and the Task input) and a context; what it returns is the Task's result, and throwing fails the Task with the error's message. Since 0.3.0 the SDK types all of it:
+A Worker module's default export is a class. The Host builds each instance (one per worker of the pool: a thread, or on an inline pool an object on the Host's own thread) with the start-up fields its Node Type takes, from the Profile the pool is for, and reuses it across Tasks, so keep per-Task state out of fields. `run` gets the Task's envelope (the Node's `settings` and the Task input) and a context; what it returns is the Task's result, and throwing fails the Task with the error's message. Since 0.3.0 the SDK types all of it:
 
 ```ts
 import type { TaskEnvelope, Worker, WorkerContext } from "fyflow-plugin-sdk";
@@ -112,26 +118,77 @@ export default class Sign implements Worker<Settings> {
 
 `WorkerClass<Config, Settings, Input, Output>` types the class itself, constructor included. Check `context.signal` between steps, or pass it to anything that takes one (`fetch`, streams): a Worker that stops promptly frees its slot sooner, and what it returns after a Cancel is discarded. Use `import type`, so a Worker module needs nothing from the SDK at run time. The context offers what the Host shows (progress) and Cancel; fyflow's scheduler passes more, but the SDK promises only these.
 
-## The `disk` group
+### A Worker's lifecycle
+
+Since 0.5.0 the SDK also promises what happens to an instance between Tasks, for a Worker that owns something long-lived (a child process, a connection, a loaded model):
+
+1. **Built**: `new Worker(config, pool)`, where `config` is its start-up fields and `pool` a `PoolContext`.
+2. **`setup()`**, if it has one: once, awaited before its first Task. Start what it owns here, not in the constructor.
+3. **`run`**, for any number of Tasks.
+4. **`teardown()`**, if it has one: once, when the pool retires the instance. That is when it has been idle past its pool's `idleTimeout` (the pool checks every 5 seconds, so up to 5 seconds later), when it asked to be replaced, and when its Runtime shuts down: the Host stopping, or after a Reload once the last Run on the replaced Runtime ends.
+
+```ts
+import type { PoolContext, Worker } from "fyflow-plugin-sdk";
+
+export default class Thumbnails implements Worker {
+  readonly #pool: PoolContext | undefined;
+  #service: Service | undefined; // Service, start: your own
+
+  constructor(_config: object, pool?: PoolContext) {
+    this.#pool = pool;
+  }
+
+  async setup() {
+    // Port 0: another copy of this Worker may be running (see below).
+    this.#service = await start({ port: 0, onExit: (error) => this.#pool?.terminateWithError(error, { canRestart: true }) });
+  }
+
+  async teardown() {
+    await this.#service?.stop(); // undefined when setup() did not get that far
+  }
+
+  async run() {
+    return this.#service?.thumbnail();
+  }
+}
+```
+
+What to rely on, and what not to:
 
-The Host's built-in Plugin declares one Resource Group any Plugin's Node Types may name: `disk` (exported as `DISK_GROUP` since 0.3.0), a concurrency limit on Tasks that read or write the Host's disks. It is 4 unless the Host overrides it on its Resource Groups page. Name it when your Tasks do heavy disk work (copying, transcoding, indexing), so they share one budget with the Host's own file system Node Types instead of thrashing the disk beside them:
+- **A `setup()` that throws** fails every Task the instance is given, with its message, and its `teardown()` runs at once. It is not tried again on that instance: the pool builds a new one only once it retires this one, at a Reload, or once no Task has reached it for its `idleTimeout`, which a steady stream of Tasks never allows. So a `setup()` that may fail for a passing reason (a port taken, a service still starting) should retry within itself before it throws, and `teardown()` must cope with a `setup()` that never finished.
+- **`pool.terminateWithError(error, { canRestart: true })`** asks the pool to replace the instance, say after the process it owns dies. It returns at once and never throws, so call it from a callback or a timer. The instance's `teardown()` runs, its Tasks still running go back in the queue to run again on a new instance, and that one is built and set up. With `canRestart: false` those Tasks fail instead. The pool replaces instances only so many times (3, fyflow-scheduler's `maxWorkerRestarts`); after that it builds no more, and its Tasks wait until a Reload. So ask when the instance is broken, not because a Task failed: throw from `run` for that.
+- **Never assume one copy.** Each Profile has its own pool, a pool may hold several instances (up to its `maxThreads`), and after a Reload the replaced Runtime's instances keep running its Runs while the new Runtime sets up its own. Bind port 0, not a fixed port, and keep anything shared outside the Worker.
+- **`idleTimeout`** defaults to 5 seconds. For a Worker costly to set up, give its Node Type's `pool` a longer one (`pool: { idleTimeout: 60_000 }`); a Profile may override it for that Node Type. `0` keeps an instance until its Runtime shuts down.
+
+## The `disk` and `cpu` groups
+
+The Host's built-in Plugin declares two Resource Groups any Plugin's Node Types may name, each a concurrency limit a Host can override on its Resource Groups page:
+
+- `disk` (exported as `DISK_GROUP` since 0.3.0), on Tasks that read or write the Host's disks. It is 4. Name it when your Tasks do heavy disk work (copying, transcoding, indexing), so they share one budget with the Host's own file system Node Types instead of thrashing the disk beside them.
+- `cpu` (exported as `CPU_GROUP` since 0.4.0), on Tasks that keep a processor busy (hashing, encoding, image work). It is the Host's logical processor count, so such Tasks from every Plugin together take no more processors than there are.
+
+A Task that does both names both:
 
 ```ts
-import { DISK_GROUP, definePlugin } from "fyflow-plugin-sdk";
+import { CPU_GROUP, DISK_GROUP, definePlugin } from "fyflow-plugin-sdk";
 
 export default definePlugin({
   // …
-  nodeTypes: { Transcode: { worker: "transcode", groups: [DISK_GROUP] } },
+  nodeTypes: { Transcode: { worker: "transcode", groups: [DISK_GROUP, CPU_GROUP] } },
 });
 ```
 
-Other Plugins' groups stay out of reach, so Disabling one Plugin never breaks another. `DISK_GROUP` is a value, so a Plugin that imports it needs the SDK at run time; writing `"disk"` instead works on any Host that has the group.
+Other Plugins' groups stay out of reach, so Disabling one Plugin never breaks another. The keys are values, so a Plugin that imports them needs the SDK at run time; writing `"disk"` or `"cpu"` instead works on any Host that has the group. Hosts before SDK 0.4.0 have no `cpu` and skip a Plugin naming it, so a Plugin that names it says `^0.4.0` in its peer range.
 
 ## Profiles and secrets
 
-A Node Type's Worker config lives on the Host, not in Flows: a **Profile** is a named configuration of a Node Type, edited in the Host's UI with a form built from the Worker's `configSchema`, and a task Node chooses one. Every Node Type has a default Profile seeded from its declaration's `config`. A Profile's config is merged over the default's, which is merged over yours.
+A Plugin's configuration lives on the Host, not in Flows: a **Profile** is a named configuration with a section for each Plugin, edited in the Host's UI with a form built from the Plugin's `profile.schema`. Every Host has a Default Profile. Declare your fields once, in `profile`, and list on each Node Type the ones it takes: a field several Node Types take is set once, for all of them. A field no Profile sets is its `defaults` value.
+
+A **start-up field** (listed in `profile.startup`) is read when a Worker starts: the start-up fields a Node Type takes are its Workers' config, the constructor's argument, and a change takes effect at the Host's next Reload. Use one for what a Worker sets up once: a connection, a loaded model.
+
+Every other field is a **per-Task field**: the Host reads it as each Task is dispatched and hands the ones the Node Type takes to `run` as `settings.profile` (`{}` when it takes none), so a change reaches the next Task with no Reload. Type them with `TaskEnvelope<Settings, Input, ProfileFields>`. Your `settingsSchema` may not name `profile`. List in `profile.profileOnly` the per-Task fields only a Profile may set: a grant, such as the folders Tasks may reach, beside a field a Flow may set to narrow it, which your Worker checks against the grant. Per-Task fields never reach a Run's records, but what `run` returns is recorded, so do not return them.
 
-Mark a config property `writeOnly: true` to make it a **secret**: the Host never shows it again, only whether it is set, and redacts its value from errors and logs. Only properties of the config object can be secrets.
+Mark a property of `profile.schema` `writeOnly: true` to make it a **secret**: the Host never shows it again, only whether it is set, and redacts its value from errors and logs. Only properties of the schema can be secrets.
 
 ## Versioning
 

package/UPGRADING.md

@@ -0,0 +1,160 @@
+# Upgrading a Plugin
+
+How to move a Plugin written for an earlier `fyflow-plugin-sdk` to this one, one version step at a time, newest first. A Host skips a Plugin whose peer range it does not implement, and says so on its Plugins page; when the Plugin was written for an earlier SDK, the reason points here.
+
+To upgrade across several steps, apply them oldest first: a Plugin on 0.3 takes [0.3 to 0.4](#03-to-04), then [0.4 to 0.5](#04-to-05).
+
+## 0.4 to 0.5
+
+0.5.0 changed what a Profile is. A Profile used to be a configuration of one Node Type, validated by its Worker's `configSchema` and seeded from the Node Type's `config`. Now a Profile is a named, Host-wide configuration with one **section per Plugin**: the Plugin declares its fields once, in `profile`, and each Node Type lists the fields it takes. A Host on 0.5 implements no earlier SDK version, so a Plugin is skipped until it is upgraded.
+
+Each field is one of these:
+
+- a **start-up field** (listed in `profile.startup`): read once, when a Worker starts, as its config (the constructor's argument). Only a Profile sets it, and a change takes effect at the Host's next Reload. This is what every Profile field was before 0.5.
+- a **per-Task field** (every other field): handed to each Task as `settings.profile`, read when the Task is dispatched, so a change needs no Reload. A Flow or one of its Nodes may set its own value, unless the field is listed in `profile.profileOnly`.
+
+A property marked `writeOnly: true` is still a **secret**. Moving it into `profile.schema` keeps it one. Resource Groups, `DISK_GROUP` and `CPU_GROUP`, icons and gate types are as in 0.4. The Worker types gained what per-Task fields need: `TaskEnvelope` and `Worker` take a third type parameter, `ProfileFields`, typing `settings.profile`; with it left out, a Worker typed for 0.4 still type-checks. And the SDK now promises a Worker's lifecycle, which fyflow already gave it: optional `setup()` and `teardown()`, and the constructor's second argument, a `PoolContext` with `terminateWithError` (README, "A Worker's lifecycle"). A Worker that already uses them can drop its own types for them and import `PoolContext`; one that does not changes nothing.
+
+### Checklist
+
+Do each step, in order. Each one is mechanical: the Plugin behaves as before once all are done.
+
+1. **The peer range.** In `package.json`, set `"peerDependencies": { "fyflow-plugin-sdk": "^0.5.0" }`.
+2. **One schema of the Plugin's fields.** Add `profile: { schema }` to the Plugin. Its `schema` is an object schema (`type: "object"`, `properties`, and `additionalProperties: false` if your `configSchema`s had it) holding every property of every Worker's `configSchema`, each once.
+   - Two Workers' `configSchema`s naming the same property with different schemas: keep one property per meaning, and rename the other (say `timeoutMs` and `uploadTimeoutMs`). Rename it in that Worker's code too (step 6).
+   - Keep `writeOnly: true` on secrets. Only a property may be `writeOnly` (a nested one, such as `auth.password`, too), never the schema itself.
+3. **Delete `configSchema` from every Worker.** A Host refuses a Worker that still declares one.
+4. **Move each Node Type's `config` to `profile.defaults`**, and delete `config` from the Node Type. A Host refuses a Node Type that still declares one.
+   - Two Node Types giving the same field different values: a default is one value for the whole Plugin. To keep both, split the field in two, one for each Node Type (say `greeting` and `shoutGreeting`), each with its old value as its default, and have each Node Type take its own in step 5. A Worker class serving both reads whichever it was given (`config.shoutGreeting ?? config.greeting`). This keeps the Plugin working as before with nothing set on the Host.
+   - A default must pass `profile.schema` (a `minLength`, an `enum`). A field with no default, such as a secret, is absent from a Worker's config until a Profile sets it, as it was before.
+5. **List what each Node Type takes.** Give each Node Type `profile: [...]`, naming the fields of its Worker's old `configSchema`. A field left out never reaches its Workers, and a name `profile.schema` lacks is refused.
+6. **Make them start-up fields.** Set `profile.startup` to every field you listed (each must be a property of `profile.schema`). Workers still get the start-up fields their Node Type takes as their constructor's `config`, exactly as before, so no Worker code changes, except for a field you renamed or split in step 2 or 4.
+7. **Optional: per-Task fields.** A field a Worker could read per Task instead (a timeout, a target folder) can leave `startup`. Then:
+   - read it in `run` from `settings.profile.<field>`, not from the constructor's config;
+   - type it with `TaskEnvelope<Settings, Input, ProfileFields>` (or `Worker<Settings, Input, Output, ProfileFields>`);
+   - list a per-Task field a Flow must never set for itself (a grant, such as the folders Tasks may reach) in `profile.profileOnly`. Check any field a Flow narrows it with against the grant in the Worker.
+8. **Rename `profile` in a `settingsSchema`.** A Worker's `settingsSchema` may not have a property called `profile`: the Host puts the per-Task fields there. Flows that set it need their Nodes' settings renamed to match.
+9. **Error messages.** Where a Worker tells a person to set a value "on this Node's Profile of <Node Type>", say "in the <Plugin id> section of this Node's Profile".
+
+A Host's stored Profiles from before 0.5 are not carried over: each Host sets its values again, on its Profiles page, once the upgraded Plugin loads.
+
+### Before and after
+
+The example `signer` Plugin, as it moved from 0.2 to 0.5. Before:
+
+```ts
+export default definePlugin({
+  id: "example.signer",
+  version: "1.0.0",
+  base: import.meta.url,
+  workers: {
+    sign: {
+      url: "./sign.worker.ts",
+      configSchema: {
+        type: "object",
+        properties: {
+          key: { type: "string", writeOnly: true, minLength: 8 },
+          algorithm: { enum: ["SHA-256", "SHA-512"] },
+        },
+        additionalProperties: false,
+      },
+      settingsSchema: {
+        type: "object",
+        properties: { field: { type: "string", minLength: 1 } },
+        additionalProperties: false,
+      },
+    },
+  },
+  nodeTypes: {
+    Sign: {
+      worker: "sign",
+      inline: true,
+      config: { algorithm: "SHA-256" },
+      groups: ["example.signing"],
+      icon: "signature",
+      description: "Signs a field of what reaches it with HMAC, keyed by its Profile's secret.",
+    },
+  },
+  groups: { "example.signing": { type: "ConcurrentLimitGroup", config: { limit: 2 } } },
+  // gateTypes unchanged
+});
+```
+
+After:
+
+```ts
+export default definePlugin({
+  id: "example.signer",
+  version: "1.0.0",
+  base: import.meta.url,
+  // Steps 2, 4 and 6: the old configSchema's properties, the old config as defaults, both read at start-up.
+  profile: {
+    schema: {
+      type: "object",
+      properties: {
+        key: { type: "string", writeOnly: true, minLength: 8 },
+        algorithm: { enum: ["SHA-256", "SHA-512"] },
+      },
+      additionalProperties: false,
+    },
+    defaults: { algorithm: "SHA-256" },
+    startup: ["key", "algorithm"],
+  },
+  workers: {
+    sign: {
+      url: "./sign.worker.ts",
+      // Step 3: no configSchema.
+      settingsSchema: {
+        type: "object",
+        properties: { field: { type: "string", minLength: 1 } },
+        additionalProperties: false,
+      },
+    },
+  },
+  nodeTypes: {
+    Sign: {
+      worker: "sign",
+      inline: true,
+      profile: ["key", "algorithm"], // step 5, in place of `config` (step 4)
+      groups: ["example.signing"],
+      icon: "signature",
+      description: "Signs a field of what reaches it with HMAC, keyed by its Profile's secret.",
+    },
+  },
+  groups: { "example.signing": { type: "ConcurrentLimitGroup", config: { limit: 2 } } },
+  // gateTypes unchanged
+});
+```
+
+Its Worker kept its constructor and `run`; only its error message changed (step 9):
+
+```ts
+if (key === undefined)
+  throw new Error("No signing key: set `key` in the example.signer section of this Node's Profile");
+```
+
+and its `package.json` says `"fyflow-plugin-sdk": "^0.5.0"` (step 1).
+
+### Check the result
+
+- **Types.** With `definePlugin` from `fyflow-plugin-sdk` 0.5 given the Plugin as one object literal, `tsc` refuses a leftover `configSchema` or Node Type `config`. A definition built from variables or spreads escapes that check, so rely on the Host's.
+- **It loads.** Put the Plugin in a Host's Plugin directory and Reload on the Plugins page. A Plugin the Host refuses is listed as skipped, with the reason: each reason names what to fix, for instance ``its Node Type "Sign" takes the Profile field "keys", which its Plugin's `profile` does not declare``. The same list is `GET /api/plugins` (`skipped`).
+- **It runs.** On the Profiles page, open the Default Profile: your Plugin's section shows a form from `profile.schema`. Set what has no default (a secret, typically), Reload when you set a start-up field, then run a Flow with one of its Node Types.
+
+## 0.3 to 0.4
+
+0.4.0 added `CPU_GROUP`, the key of the built-in `cpu` Resource Group: a concurrency limit, the Host's logical processor count unless it overrides it, for Tasks that keep a processor busy. Nothing else changed, and a Plugin for 0.3 loads as it is on a 0.4 Host.
+
+- To name the group, add `CPU_GROUP` (or `"cpu"`) to a Node Type's `groups`, beside `DISK_GROUP` when its Tasks do both.
+- A Host before 0.4 has no `cpu` group and skips a Plugin naming it, so such a Plugin's peer range says `^0.4.0`. One that does not name it may keep its range.
+
+## 0.2 to 0.3
+
+0.3.0 added types and `DISK_GROUP`; nothing a Plugin says changed meaning, and a Plugin for 0.2 loads as it is on a 0.3 Host.
+
+- `Worker`, `WorkerClass`, `TaskEnvelope` and `WorkerContext` type a Worker class, its `run(envelope, context)` and its constructor's config. Import them with `import type`.
+- `DISK_GROUP` is the key of the built-in `disk` Resource Group, for Tasks that do heavy disk work. A Plugin naming it says `^0.3.0`.
+
+## 0.1 to 0.2
+
+0.2.0 added a Node Type's optional `icon` (a name from the app's icon set, listed in the README) and one-line `description`, which the palette shows. Nothing changed meaning, and a Plugin for 0.1 loads as it is on a 0.2 Host.

package/dist/index.d.ts

@@ -1,14 +1,15 @@
-import type { GateType, GroupInstance, GroupType, NodeTypeDeclaration, WorkerEntry } from "fyflow-orchestration";
+import type { GateType, GroupInstance, GroupType, JsonSchema, NodeTypeDeclaration, WorkerEntry } from "fyflow-orchestration";
 export type { GateContext, GateType, GroupInstance, GroupType, JsonSchema, NodeTypeDeclaration, RetryPolicy, WorkerEntry, } from "fyflow-orchestration";
 /**
  * The SDK version this package is, and so the one a Host built with it implements. A Plugin whose
  * `fyflow-plugin-sdk` peer range excludes it, and every one in `SDK_COMPATIBLE`, is not loaded. Kept equal to
  * package.json's `version` (tested).
  */
-export declare const SDK_VERSION = "0.3.0";
+export declare const SDK_VERSION = "0.5.0";
 /**
  * The earlier SDK versions this one is a superset of: nothing a Plugin written for them says has changed meaning,
- * so a Host implements them too (ADR-0021). 0.2.0 only added optional fields, and 0.3.0 only types.
+ * so a Host implements them too (ADR-0021). None: 0.5.0 replaced per-Node-Type Profiles with the Plugin's `profile`
+ * (ADR-0024), so a Plugin written for an earlier one is upgraded first (UPGRADING.md).
  */
 export declare const SDK_COMPATIBLE: readonly string[];
 /**
@@ -18,12 +19,44 @@ export declare const SDK_COMPATIBLE: readonly string[];
  * are out of reach.
  */
 export declare const DISK_GROUP = "disk";
-/** A Node Type as a Plugin declares it: fyflow's declaration, and how the app shows it (since 0.2.0). */
-export interface PluginNodeType extends NodeTypeDeclaration {
+/**
+ * The key of the `cpu` Resource Group the Host's built-in Plugin declares (exported since 0.4.0): a concurrency
+ * limit (the Host's logical processors unless it overrides it) on Tasks that keep a processor busy. Any Plugin's
+ * Node Type may name it in `groups`, beside `disk` when its Tasks do both.
+ */
+export declare const CPU_GROUP = "cpu";
+/**
+ * A Node Type as a Plugin declares it: fyflow's declaration, how the app shows it (since 0.2.0), and the Profile
+ * fields it takes (since 0.5.0). Its config comes from Profiles: it declares none of its own.
+ */
+export interface PluginNodeType extends Omit<NodeTypeDeclaration, "config"> {
     /** An icon from the app's icon set (Lucide names, listed in the README); an unknown one shows its Kind's icon. */
     icon?: string;
     /** One line on what it does, shown in the palette. */
     description?: string;
+    /** The fields of its Plugin's `profile` its Workers get; none when left out (since 0.5.0). */
+    profile?: readonly string[];
+}
+/**
+ * The fields a Plugin's Profile section holds (since 0.5.0, ADR-0024): set once per Profile, for every Node Type of
+ * the Plugin that takes them. A property of `schema` marked `writeOnly: true` is a secret: a Host never shows it.
+ */
+export interface PluginProfile {
+    /** An object schema (fyflow's subset) of the fields, by name. */
+    schema: JsonSchema;
+    /** What a field is where no Profile sets it; checked against `schema`. */
+    defaults?: Readonly<Record<string, unknown>>;
+    /**
+     * The start-up fields: read once, when a Worker starts, as its config (its constructor's argument). Only a
+     * Profile sets them, and a change takes effect at the Host's next Reload. Every other field is a per-Task field:
+     * it reaches each Task as `settings.profile`, read when the Task is dispatched, so a change needs no Reload.
+     */
+    startup?: readonly string[];
+    /**
+     * The per-Task fields only a Profile may set, never a Flow or a Node: a grant, such as the folders Tasks may
+     * reach, beside a field a Flow may set to narrow it, which the Worker checks against the grant.
+     */
+    profileOnly?: readonly string[];
 }
 export interface Plugin {
     /** Stable, unique id, e.g. `acme.images`. */
@@ -32,10 +65,12 @@ export interface Plugin {
     /** What worker `url`s resolve against: the plugin module's own `import.meta.url`. */
     base: string;
     /**
-     * Worker modules by key; `url` is relative to `base`. A property of a `configSchema` marked `writeOnly: true` is
-     * a Profile secret: a Host never shows it (ADR-0016).
+     * Worker modules by key; `url` is relative to `base`. Their config is the Profile's start-up fields (see
+     * `profile`), so a Worker declares no `configSchema` of its own (since 0.5.0).
      */
-    workers?: Readonly<Record<string, WorkerEntry>>;
+    workers?: Readonly<Record<string, Omit<WorkerEntry, "configSchema">>>;
+    /** This Plugin's Profile fields, which its Node Types take by name (since 0.5.0). */
+    profile?: PluginProfile;
     /**
      * Node Types by name, each naming one of this plugin's `workers`; `groups` names Resource Groups (from this
      * plugin's `groups`) every Task of the type acquires.
@@ -50,10 +85,14 @@ export interface Plugin {
 }
 /**
  * What a Worker's `run` is handed for one Task: the Node's `settings` (checked by the Worker's `settingsSchema`)
- * and the Task input, after the Node's transform if it has one (since 0.3.0).
+ * and the Task input, after the Node's transform if it has one (since 0.3.0). The Host adds the per-Task fields the
+ * Node Type takes as `settings.profile` (since 0.5.0; `{}` when it takes none), so a Worker's own `settingsSchema`
+ * may not name `profile`.
  */
-export interface TaskEnvelope<Settings = Record<string, unknown>, Input = unknown> {
-    settings: Settings;
+export interface TaskEnvelope<Settings = Record<string, unknown>, Input = unknown, ProfileFields = Readonly<Record<string, unknown>>> {
+    settings: Settings & {
+        readonly profile: ProfileFields;
+    };
     input: Input;
 }
 /** The second argument to a Worker's `run`: what it may do while its Task runs (since 0.3.0). */
@@ -66,15 +105,46 @@ export interface WorkerContext {
      */
     readonly signal: AbortSignal;
 }
-/** One instance of a Worker, reused across the Tasks of its pool (since 0.3.0). */
-export interface Worker<Settings = Record<string, unknown>, Input = unknown, Output = unknown> {
+/**
+ * The second argument to a Worker's constructor: what it may ask of its pool while no Task is involved, such as after
+ * the process it owns dies (since 0.5.0).
+ */
+export interface PoolContext {
+    /**
+     * Asks the pool to retire this instance: its `teardown()` runs, and a new instance is built and set up for what
+     * comes next. Its Tasks still running go back in the queue, unless `canRestart` is false, which fails them. It
+     * returns at once and never throws, so it is safe from a timer or a callback.
+     */
+    terminateWithError(error: Error, options?: {
+        canRestart?: boolean;
+    }): void;
+}
+/**
+ * One instance of a Worker, reused across the Tasks of its pool (since 0.3.0); `ProfileFields` its per-Task fields.
+ * Since 0.5.0 the SDK promises its lifecycle: built, `setup()`, any number of Tasks, `teardown()`.
+ */
+export interface Worker<Settings = Record<string, unknown>, Input = unknown, Output = unknown, ProfileFields = Readonly<Record<string, unknown>>> {
     /** Does one Task. Throwing fails it; the error's message is what the Host shows. */
-    run(envelope: TaskEnvelope<Settings, Input>, context: WorkerContext): Output | Promise<Output>;
+    run(envelope: TaskEnvelope<Settings, Input, ProfileFields>, context: WorkerContext): Output | Promise<Output>;
+    /**
+     * Runs once, after the constructor and before the first Task: where to start what the instance owns (a process, a
+     * connection, a loaded model). Throwing fails every Task of this instance with the error's message. It is not tried
+     * again on this instance: the pool builds a new one only once it retires this one (a Reload, or no Task reaching it for
+     * its `idleTimeout`).
+     */
+    setup?(): Promise<void>;
+    /**
+     * Runs once, when the pool retires the instance: idle past its `idleTimeout`, replaced, or its Runtime shut down
+     * (the Host stopping, or a Reload once the Runtime's last Run ends). Also after a `setup()` that threw, so it must
+     * cope with one that never finished.
+     */
+    teardown?(): Promise<void>;
 }
 /**
- * A Worker module's default export: a class whose constructor gets the config of the Profile its pool was built
- * for (the Worker's `configSchema` checks it), once per instance (since 0.3.0).
+ * A Worker module's default export: a class whose constructor gets, once per instance, the start-up fields its
+ * Node Type takes from the Profile its pool was built for (since 0.3.0; from the Plugin's `profile` since 0.5.0), and its
+ * pool's context (since 0.5.0).
  */
-export type WorkerClass<Config = Record<string, unknown>, Settings = Record<string, unknown>, Input = unknown, Output = unknown> = new (config: Config) => Worker<Settings, Input, Output>;
+export type WorkerClass<Config = Record<string, unknown>, Settings = Record<string, unknown>, Input = unknown, Output = unknown> = new (config: Config, pool?: PoolContext) => Worker<Settings, Input, Output>;
 /** Identity at runtime; gives plugin authors type checking and a single import. */
 export declare function definePlugin(plugin: Plugin): Plugin;

package/dist/index.js

@@ -1,10 +1,11 @@
-// The contract between fyflow-app and the code that extends it (ADR-0007, ADR-0015, ADR-0016). Published as
-// `fyflow-plugin-sdk`: everything here is types but `definePlugin`, `SDK_VERSION`, `SDK_COMPATIBLE` and
-// `DISK_GROUP`.
+// The contract between fyflow-app and the code that extends it (ADR-0007, ADR-0015, ADR-0024). Published as
+// `fyflow-plugin-sdk`: everything here is types but `definePlugin`, `SDK_VERSION`, `SDK_COMPATIBLE`, `DISK_GROUP`
+// and `CPU_GROUP`.
              
            
                 
             
+             
                       
               
                               
@@ -25,13 +26,14 @@
  * `fyflow-plugin-sdk` peer range excludes it, and every one in `SDK_COMPATIBLE`, is not loaded. Kept equal to
  * package.json's `version` (tested).
  */
-export const SDK_VERSION = "0.3.0";
+export const SDK_VERSION = "0.5.0";
 
 /**
  * The earlier SDK versions this one is a superset of: nothing a Plugin written for them says has changed meaning,
- * so a Host implements them too (ADR-0021). 0.2.0 only added optional fields, and 0.3.0 only types.
+ * so a Host implements them too (ADR-0021). None: 0.5.0 replaced per-Node-Type Profiles with the Plugin's `profile`
+ * (ADR-0024), so a Plugin written for an earlier one is upgraded first (UPGRADING.md).
  */
-export const SDK_COMPATIBLE                    = ["0.2.0", "0.1.0"];
+export const SDK_COMPATIBLE                    = [];
 
 /**
  * The key of the `disk` Resource Group the Host's built-in Plugin declares (exported since 0.3.0): a concurrency
@@ -41,12 +43,46 @@ export const SDK_COMPATIBLE                    = ["0.2.0", "0.1.0"];
  */
 export const DISK_GROUP = "disk";
 
-/** A Node Type as a Plugin declares it: fyflow's declaration, and how the app shows it (since 0.2.0). */
-                                                             
+/**
+ * The key of the `cpu` Resource Group the Host's built-in Plugin declares (exported since 0.4.0): a concurrency
+ * limit (the Host's logical processors unless it overrides it) on Tasks that keep a processor busy. Any Plugin's
+ * Node Type may name it in `groups`, beside `disk` when its Tasks do both.
+ */
+export const CPU_GROUP = "cpu";
+
+/**
+ * A Node Type as a Plugin declares it: fyflow's declaration, how the app shows it (since 0.2.0), and the Profile
+ * fields it takes (since 0.5.0). Its config comes from Profiles: it declares none of its own.
+ */
+                                                                             
                                                                                                                     
                 
                                                         
                        
+                                                                                                
+                              
+ 
+
+/**
+ * The fields a Plugin's Profile section holds (since 0.5.0, ADR-0024): set once per Profile, for every Node Type of
+ * the Plugin that takes them. A property of `schema` marked `writeOnly: true` is a secret: a Host never shows it.
+ */
+                                
+                                                                   
+                     
+                                                                            
+                                               
+     
+                                                                                                             
+                                                                                                                   
+                                                                                                               
+     
+                              
+     
+                                                                                                               
+                                                                                                  
+     
+                                  
  
 
                          
@@ -56,10 +92,12 @@ export const DISK_GROUP = "disk";
                                                                                        
                
      
-                                                                                                                   
-                                                        
+                                                                                                           
+                                                                                 
      
-                                                  
+                                                                        
+                                                                                       
+                          
      
                                                                                                               
                                                         
@@ -75,10 +113,16 @@ export const DISK_GROUP = "disk";
 
 /**
  * What a Worker's `run` is handed for one Task: the Node's `settings` (checked by the Worker's `settingsSchema`)
- * and the Task input, after the Node's transform if it has one (since 0.3.0).
+ * and the Task input, after the Node's transform if it has one (since 0.3.0). The Host adds the per-Task fields the
+ * Node Type takes as `settings.profile` (since 0.5.0; `{}` when it takes none), so a Worker's own `settingsSchema`
+ * may not name `profile`.
  */
-                                                                                    
-                     
+                              
+                                     
+                  
+                                                    
+   
+                                                           
                
  
 
@@ -93,22 +137,60 @@ export const DISK_GROUP = "disk";
                                
  
 
-/** One instance of a Worker, reused across the Tasks of its pool (since 0.3.0). */
-                                                                                                
+/**
+ * The second argument to a Worker's constructor: what it may ask of its pool while no Task is involved, such as after
+ * the process it owns dies (since 0.5.0).
+ */
+                              
+     
+                                                                                                                  
+                                                                                                                 
+                                                                                
+     
+                                                                             
+ 
+
+/**
+ * One instance of a Worker, reused across the Tasks of its pool (since 0.3.0); `ProfileFields` its per-Task fields.
+ * Since 0.5.0 the SDK promises its lifecycle: built, `setup()`, any number of Tasks, `teardown()`.
+ */
+                        
+                                     
+                  
+                   
+                                                    
+   
                                                                                       
-                                                                                                 
+      
+                                                           
+                           
+                              
+     
+                                                                                                                    
+                                                                                                                      
+                                                                                                                          
+                        
+     
+                          
+     
+                                                                                                                   
+                                                                                                                     
+                                       
+     
+                             
  
 
 /**
- * A Worker module's default export: a class whose constructor gets the config of the Profile its pool was built
- * for (the Worker's `configSchema` checks it), once per instance (since 0.3.0).
+ * A Worker module's default export: a class whose constructor gets, once per instance, the start-up fields its
+ * Node Type takes from the Profile its pool was built for (since 0.3.0; from the Plugin's `profile` since 0.5.0), and its
+ * pool's context (since 0.5.0).
  */
                         
                                    
                                      
                   
                    
-                                                            
+                                                                                
 
 /** Identity at runtime; gives plugin authors type checking and a single import. */
 export function definePlugin(plugin        )         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fyflow-plugin-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Types and definePlugin for fyflow-app Plugins: Node Types, Workers, gate types and Resource Groups",
   "keywords": [
     "fyflow",
@@ -20,7 +20,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "fyflow-orchestration": "^0.12.0"
+    "fyflow-orchestration": "^0.13.0"
   },
   "peerDependenciesMeta": {
     "fyflow-orchestration": {
@@ -28,12 +28,13 @@
     }
   },
   "devDependencies": {
-    "fyflow-orchestration": "0.12.0"
+    "fyflow-orchestration": "0.13.0"
   },
   "files": [
     "dist",
     "src",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "UPGRADING.md"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"

package/src/index.ts

@@ -1,10 +1,11 @@
-// The contract between fyflow-app and the code that extends it (ADR-0007, ADR-0015, ADR-0016). Published as
-// `fyflow-plugin-sdk`: everything here is types but `definePlugin`, `SDK_VERSION`, `SDK_COMPATIBLE` and
-// `DISK_GROUP`.
+// The contract between fyflow-app and the code that extends it (ADR-0007, ADR-0015, ADR-0024). Published as
+// `fyflow-plugin-sdk`: everything here is types but `definePlugin`, `SDK_VERSION`, `SDK_COMPATIBLE`, `DISK_GROUP`
+// and `CPU_GROUP`.
 import type {
   GateType,
   GroupInstance,
   GroupType,
+  JsonSchema,
   NodeTypeDeclaration,
   WorkerEntry,
 } from "fyflow-orchestration";
@@ -25,13 +26,14 @@ export type {
  * `fyflow-plugin-sdk` peer range excludes it, and every one in `SDK_COMPATIBLE`, is not loaded. Kept equal to
  * package.json's `version` (tested).
  */
-export const SDK_VERSION = "0.3.0";
+export const SDK_VERSION = "0.5.0";
 
 /**
  * The earlier SDK versions this one is a superset of: nothing a Plugin written for them says has changed meaning,
- * so a Host implements them too (ADR-0021). 0.2.0 only added optional fields, and 0.3.0 only types.
+ * so a Host implements them too (ADR-0021). None: 0.5.0 replaced per-Node-Type Profiles with the Plugin's `profile`
+ * (ADR-0024), so a Plugin written for an earlier one is upgraded first (UPGRADING.md).
  */
-export const SDK_COMPATIBLE: readonly string[] = ["0.2.0", "0.1.0"];
+export const SDK_COMPATIBLE: readonly string[] = [];
 
 /**
  * The key of the `disk` Resource Group the Host's built-in Plugin declares (exported since 0.3.0): a concurrency
@@ -41,12 +43,46 @@ export const SDK_COMPATIBLE: readonly string[] = ["0.2.0", "0.1.0"];
  */
 export const DISK_GROUP = "disk";
 
-/** A Node Type as a Plugin declares it: fyflow's declaration, and how the app shows it (since 0.2.0). */
-export interface PluginNodeType extends NodeTypeDeclaration {
+/**
+ * The key of the `cpu` Resource Group the Host's built-in Plugin declares (exported since 0.4.0): a concurrency
+ * limit (the Host's logical processors unless it overrides it) on Tasks that keep a processor busy. Any Plugin's
+ * Node Type may name it in `groups`, beside `disk` when its Tasks do both.
+ */
+export const CPU_GROUP = "cpu";
+
+/**
+ * A Node Type as a Plugin declares it: fyflow's declaration, how the app shows it (since 0.2.0), and the Profile
+ * fields it takes (since 0.5.0). Its config comes from Profiles: it declares none of its own.
+ */
+export interface PluginNodeType extends Omit<NodeTypeDeclaration, "config"> {
   /** An icon from the app's icon set (Lucide names, listed in the README); an unknown one shows its Kind's icon. */
   icon?: string;
   /** One line on what it does, shown in the palette. */
   description?: string;
+  /** The fields of its Plugin's `profile` its Workers get; none when left out (since 0.5.0). */
+  profile?: readonly string[];
+}
+
+/**
+ * The fields a Plugin's Profile section holds (since 0.5.0, ADR-0024): set once per Profile, for every Node Type of
+ * the Plugin that takes them. A property of `schema` marked `writeOnly: true` is a secret: a Host never shows it.
+ */
+export interface PluginProfile {
+  /** An object schema (fyflow's subset) of the fields, by name. */
+  schema: JsonSchema;
+  /** What a field is where no Profile sets it; checked against `schema`. */
+  defaults?: Readonly<Record<string, unknown>>;
+  /**
+   * The start-up fields: read once, when a Worker starts, as its config (its constructor's argument). Only a
+   * Profile sets them, and a change takes effect at the Host's next Reload. Every other field is a per-Task field:
+   * it reaches each Task as `settings.profile`, read when the Task is dispatched, so a change needs no Reload.
+   */
+  startup?: readonly string[];
+  /**
+   * The per-Task fields only a Profile may set, never a Flow or a Node: a grant, such as the folders Tasks may
+   * reach, beside a field a Flow may set to narrow it, which the Worker checks against the grant.
+   */
+  profileOnly?: readonly string[];
 }
 
 export interface Plugin {
@@ -56,10 +92,12 @@ export interface Plugin {
   /** What worker `url`s resolve against: the plugin module's own `import.meta.url`. */
   base: string;
   /**
-   * Worker modules by key; `url` is relative to `base`. A property of a `configSchema` marked `writeOnly: true` is
-   * a Profile secret: a Host never shows it (ADR-0016).
+   * Worker modules by key; `url` is relative to `base`. Their config is the Profile's start-up fields (see
+   * `profile`), so a Worker declares no `configSchema` of its own (since 0.5.0).
    */
-  workers?: Readonly<Record<string, WorkerEntry>>;
+  workers?: Readonly<Record<string, Omit<WorkerEntry, "configSchema">>>;
+  /** This Plugin's Profile fields, which its Node Types take by name (since 0.5.0). */
+  profile?: PluginProfile;
   /**
    * Node Types by name, each naming one of this plugin's `workers`; `groups` names Resource Groups (from this
    * plugin's `groups`) every Task of the type acquires.
@@ -75,10 +113,16 @@ export interface Plugin {
 
 /**
  * What a Worker's `run` is handed for one Task: the Node's `settings` (checked by the Worker's `settingsSchema`)
- * and the Task input, after the Node's transform if it has one (since 0.3.0).
+ * and the Task input, after the Node's transform if it has one (since 0.3.0). The Host adds the per-Task fields the
+ * Node Type takes as `settings.profile` (since 0.5.0; `{}` when it takes none), so a Worker's own `settingsSchema`
+ * may not name `profile`.
  */
-export interface TaskEnvelope<Settings = Record<string, unknown>, Input = unknown> {
-  settings: Settings;
+export interface TaskEnvelope<
+  Settings = Record<string, unknown>,
+  Input = unknown,
+  ProfileFields = Readonly<Record<string, unknown>>,
+> {
+  settings: Settings & { readonly profile: ProfileFields };
   input: Input;
 }
 
@@ -93,22 +137,60 @@ export interface WorkerContext {
   readonly signal: AbortSignal;
 }
 
-/** One instance of a Worker, reused across the Tasks of its pool (since 0.3.0). */
-export interface Worker<Settings = Record<string, unknown>, Input = unknown, Output = unknown> {
+/**
+ * The second argument to a Worker's constructor: what it may ask of its pool while no Task is involved, such as after
+ * the process it owns dies (since 0.5.0).
+ */
+export interface PoolContext {
+  /**
+   * Asks the pool to retire this instance: its `teardown()` runs, and a new instance is built and set up for what
+   * comes next. Its Tasks still running go back in the queue, unless `canRestart` is false, which fails them. It
+   * returns at once and never throws, so it is safe from a timer or a callback.
+   */
+  terminateWithError(error: Error, options?: { canRestart?: boolean }): void;
+}
+
+/**
+ * One instance of a Worker, reused across the Tasks of its pool (since 0.3.0); `ProfileFields` its per-Task fields.
+ * Since 0.5.0 the SDK promises its lifecycle: built, `setup()`, any number of Tasks, `teardown()`.
+ */
+export interface Worker<
+  Settings = Record<string, unknown>,
+  Input = unknown,
+  Output = unknown,
+  ProfileFields = Readonly<Record<string, unknown>>,
+> {
   /** Does one Task. Throwing fails it; the error's message is what the Host shows. */
-  run(envelope: TaskEnvelope<Settings, Input>, context: WorkerContext): Output | Promise<Output>;
+  run(
+    envelope: TaskEnvelope<Settings, Input, ProfileFields>,
+    context: WorkerContext,
+  ): Output | Promise<Output>;
+  /**
+   * Runs once, after the constructor and before the first Task: where to start what the instance owns (a process, a
+   * connection, a loaded model). Throwing fails every Task of this instance with the error's message. It is not tried
+   * again on this instance: the pool builds a new one only once it retires this one (a Reload, or no Task reaching it for
+   * its `idleTimeout`).
+   */
+  setup?(): Promise<void>;
+  /**
+   * Runs once, when the pool retires the instance: idle past its `idleTimeout`, replaced, or its Runtime shut down
+   * (the Host stopping, or a Reload once the Runtime's last Run ends). Also after a `setup()` that threw, so it must
+   * cope with one that never finished.
+   */
+  teardown?(): Promise<void>;
 }
 
 /**
- * A Worker module's default export: a class whose constructor gets the config of the Profile its pool was built
- * for (the Worker's `configSchema` checks it), once per instance (since 0.3.0).
+ * A Worker module's default export: a class whose constructor gets, once per instance, the start-up fields its
+ * Node Type takes from the Profile its pool was built for (since 0.3.0; from the Plugin's `profile` since 0.5.0), and its
+ * pool's context (since 0.5.0).
  */
 export type WorkerClass<
   Config = Record<string, unknown>,
   Settings = Record<string, unknown>,
   Input = unknown,
   Output = unknown,
-> = new (config: Config) => Worker<Settings, Input, Output>;
+> = new (config: Config, pool?: PoolContext) => Worker<Settings, Input, Output>;
 
 /** Identity at runtime; gives plugin authors type checking and a single import. */
 export function definePlugin(plugin: Plugin): Plugin {