dimcode-darwin-x64 0.1.0-alpha.14 → 0.1.0-alpha.16

package/plugins/workflow/history.ts

@@ -0,0 +1,71 @@
+import type { Sessions } from '../../../npm/plugin.js'
+import { bounded, type Stage } from './store.ts'
+
+/** One stage's published prefix, keyed by the receipt of its own input. */
+export class StageHistory {
+  readonly sessions: Sessions
+  readonly sessionId: string
+  readonly inputId: string
+  after = 0
+  through: number | undefined
+  applied = false
+  consumed = false
+  deleted = false
+  interrupted = false
+  turn: string | undefined
+  text = ''
+  outcome: Pick<Stage, 'state' | 'reason' | 'result_text'> | undefined
+
+  constructor(sessions: Sessions, sessionId: string, inputId: string) {
+    this.sessions = sessions
+    this.sessionId = sessionId
+    this.inputId = inputId
+  }
+
+  async read(): Promise<boolean> {
+    for (;;) {
+      const page = await this.sessions.history({ sessionId: this.sessionId, branchId: 'main', after: this.after,
+        ...(this.through === undefined ? {} : { through: this.through }), limit: 256,
+      })
+      if (!page.ok) {
+        if (page.error.code === 'reloading') return false
+        if (page.error.code === 'session_closed' || page.error.code === 'branch_missing') {
+          if (!this.outcome) this.outcome = { state: 'failed', reason: 'session_closed' }
+          return true
+        }
+        if (!this.outcome) this.outcome = { state: 'failed', reason: page.error.code }
+        return true
+      }
+      this.through = page.value.through
+      for (const event of page.value.events) {
+        this.after = event.sequence
+        const { type, name, data } = event
+        if (type === 'input' && data.input_id === this.inputId) {
+          if (name === 'applied') this.applied = true
+          if (name === 'deleted') this.deleted = true
+          if (name === 'consumed') this.consumed = true
+        }
+        if (this.applied && !this.consumed && type === 'stop' && name === 'interrupt') this.interrupted = true
+        if (!this.consumed || this.outcome) continue
+        if (type === 'step' && name === 'model-start') {
+          this.turn = data.turn_id as string
+          this.text = ''
+        }
+        if (type === 'step' && name === 'text' && data.turn_id === this.turn) {
+          this.text = bounded(this.text + (data.delta as string), 64 * 1024)
+        }
+        if (type === 'turn' && name === 'end') {
+          if (data.status === 'completed') this.outcome = { state: 'completed', result_text: this.text }
+          else if (data.status === 'failed') this.outcome = { state: 'failed', reason: data.error as string }
+          else this.outcome = { state: 'stopped', reason: data.reason as string }
+        }
+      }
+      if (!page.value.events.length || this.after >= this.through) {
+        this.after = this.through
+        this.through = undefined
+        if (!this.consumed && (this.deleted || (this.applied && this.interrupted))) this.outcome = { state: 'stopped' }
+        return true
+      }
+    }
+  }
+}

package/plugins/workflow/index.ts

@@ -0,0 +1,156 @@
+import { definePlugin } from '@arcships/rutis'
+import { z } from 'zod'
+import type { ManagementMethods, MethodReply, PartRegistry, PluginFiles, Sessions, Settings, WorkflowFiles } from '../../../npm/plugin.js'
+import { Catalog, type DefinitionEntry } from './catalog.ts'
+import { WorkflowError, payloadBytes } from './definition.ts'
+import { Workflow } from './engine.ts'
+import { management, unloadingAfterCall, type RunReply, type RunRequest, type WorkflowRuns } from './requests.ts'
+import session from './session.ts'
+import { settings } from './settings.ts'
+import { bounded, boundedEncoded, RunStore, type Run } from './store.ts'
+
+/// `report_guidance` is one line: the entry names the report's last line as
+/// guidance, not part of the workflow's account, so a value with a line
+/// break is refused.
+const guidance = z.string().min(1).refine(value => !/[\r\n]/.test(value), {
+  message: 'report_guidance must be one line: the entry names the report\'s last line as guidance',
+})
+const options = z.strictObject({
+  packages: z.array(z.strictObject({ id: z.string().min(1), root: z.string().min(1) })),
+  report_guidance: guidance.optional(),
+  invalid_definition_guidance: z.string().min(1).optional(),
+})
+const provides = { workflowRuns: { call: 'async' } } as const
+
+/** A listed field's preview: its serialized form stays within `limit`, and a cut
+ * text ends with an ellipsis so it is not read as the whole value. */
+function preview(text: string, limit: number): string {
+  return boundedEncoded(text, limit) === text ? text : `${boundedEncoded(text, limit - 8)}…`
+}
+
+function visible(entry: DefinitionEntry) {
+  return { name: entry.name, source: entry.source, enabled: entry.enabled,
+    ...(entry.package_id ? { package_id: entry.package_id } : {}),
+    ...(entry.definition ? {
+      description: preview(entry.definition.description, 4 * 1024),
+      parameters: (entry.definition.parameters ?? []).map(parameter => ({
+        name: parameter.name,
+        ...(parameter.required === undefined ? {} : { required: parameter.required }),
+        ...(parameter.description === undefined ? {} : { description: preview(parameter.description, 512) }),
+        ...(parameter.default === undefined ? {} : { default: preview(parameter.default, 1024) }),
+      })),
+    } : {}),
+    valid: entry.issues.length === 0,
+    issues: entry.issues.slice(0, 10).map(issue => preview(issue, 1024)),
+    issue_count: entry.issues.length,
+  }
+}
+
+/** One reply's listing: field previews, and entries while the serialized payload fits.
+ * `truncated` says later entries were omitted for the frame bound. */
+function listing(entries: DefinitionEntry[]) {
+  const definitions: ReturnType<typeof visible>[] = []
+  let bytes = Buffer.byteLength(JSON.stringify('{"definitions":[],"truncated":false}'))
+  let truncated = false
+  for (const entry of entries) {
+    const value = visible(entry)
+    const part = `${definitions.length ? ',' : ''}${JSON.stringify(value)}`
+    const size = Buffer.byteLength(JSON.stringify(part)) - 2
+    if (bytes + size + 64 > payloadBytes) { truncated = true; break }
+    definitions.push(value)
+    bytes += size
+  }
+  return { definitions, truncated }
+}
+
+export default definePlugin({
+  name: 'Workflow',
+  // A plain JSON Schema: zod's result also carries `~standard`, which
+  // rutis refuses as a Standard Schema.
+  config: JSON.parse(JSON.stringify(z.toJSONSchema(options))),
+  inject: ['sessions', 'settings', 'pluginFiles', 'workflowFiles', 'managementMethods', 'partRegistry'],
+  provides,
+  async apply(ctx, config: z.infer<typeof options>) {
+    config = options.parse(config)
+    await ctx.use<Settings>('settings').register(settings)
+    const catalog = new Catalog(ctx.use<Settings>('settings'), ctx.use<WorkflowFiles>('workflowFiles'), config.packages)
+    const scope = await ctx.use<PluginFiles>('pluginFiles').open()
+    const workflow = new Workflow(catalog, ctx.use<Sessions>('sessions'), new RunStore(scope), config.report_guidance)
+    ctx.effect(() => workflow.close())
+    try { await workflow.restore() }
+    catch (error) {
+      workflow.fault = error instanceof Error ? error : new Error(String(error))
+      console.error('Workflow', workflow.fault.message)
+    }
+
+    const owner: WorkflowRuns = {
+      async call(request: RunRequest) {
+        try {
+          return await workflow.track(async (): Promise<RunReply> => {
+            if (request.action === 'list') {
+              return { content: JSON.stringify(listing(
+                (await catalog.load(request.caller.cwd)).entries.filter(entry => entry.enabled))) }
+            }
+            let result: Run
+            if (request.action === 'start') {
+              result = await workflow.start({ ...request, cwd: request.caller.cwd }, () => false)
+              const value = { run_id: result.run_id, status: result.state, stages: result.stages }
+              return { content: `${JSON.stringify(value)}\nThe result arrives as a report input.`, structured: value }
+            }
+            if (request.action === 'status') result = await workflow.status(request.run_id, request.caller.sessionId)
+            else result = await workflow.stop(request.run_id, request.caller.sessionId)
+            const status = { run_id: result.run_id, state: result.state,
+              stages: result.stages.map(({ id, state, session_id }) => ({ id, state, session_id })),
+              result_preview: bounded(result.stages.map(stage => `${stage.id}: ${stage.result_text ?? stage.reason ?? stage.state}`).join('\n'), 4 * 1024),
+              log: result.log.slice(-10).map(entry => ({ at: entry.at, message: bounded(entry.message, 512) })),
+            }
+            return { content: JSON.stringify(status), structured: { run: result } }
+          })
+        } catch (error) {
+          if (error instanceof WorkflowError && error.code === 'service_reloading') {
+            return { code: 'service_unavailable', message: unloadingAfterCall }
+          }
+          if (error instanceof WorkflowError) return { code: error.code, message: bounded(error.message, 4 * 1024) }
+          throw error
+        }
+      },
+    }
+    ctx.provide('workflowRuns', owner)
+    await ctx.use<PartRegistry>('partRegistry').registerDefinition('session', 'WorkflowSession', session(config.invalid_definition_guidance))
+
+    await ctx.use<ManagementMethods>('managementMethods').register(
+      'workflow',
+      ['list', 'save', 'start', 'status', 'stop'].map(name => ({
+        name: `workflow.${name}`, mutating: !['list', 'status'].includes(name),
+        interruption: name === 'list' || name === 'status' ? 'report' : 'drain', progress: false,
+      })),
+      async (call, cancellation) => {
+        let cancelled = false
+        void cancellation.then(() => { cancelled = true }, () => { cancelled = true })
+        try {
+          return await workflow.track<MethodReply>(async () => {
+            const name = call.method.slice('workflow.'.length)
+            if (name === 'list') {
+              const { cwd } = management.list.parse(call.params)
+              return { kind: 'value' as const, value: listing((await catalog.load(cwd)).entries) }
+            }
+            if (name === 'save') {
+              return { kind: 'value' as const, value: await catalog.save(management.save.parse(call.params)) }
+            }
+            if (name === 'start') {
+              const request = management.start.parse(call.params)
+              return { kind: 'value' as const, value: { run_id: (await workflow.start(request, () => cancelled)).run_id } }
+            }
+            if (name === 'status') return { kind: 'value' as const, value: await workflow.status(management.status.parse(call.params).run_id) }
+            if (name === 'stop') return { kind: 'value' as const, value: await workflow.stop(management.stop.parse(call.params).run_id) }
+            throw new WorkflowError('invalid_params', 'Unknown Workflow method')
+          })
+        } catch (error) {
+          if (error instanceof z.ZodError) return { code: 'invalid_params', message: bounded(error.message, 4 * 1024) }
+          if (error instanceof WorkflowError) return { code: error.code, message: bounded(error.message, 4 * 1024) }
+          throw error
+        }
+      },
+    )
+  },
+})

package/plugins/workflow/node_modules/.package-lock.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dimcode/workflow",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "node_modules/@arcships/rutis": {
+      "version": "0.19.3",
+      "resolved": "https://registry.npmjs.org/@arcships/rutis/-/rutis-0.19.3.tgz",
+      "integrity": "sha512-mpeVQ2tIZFyiKibgmRtyEhFu0NW3xam/OMUWSkddXIj8a/QqyW3AiE37GKlb4ihpHtuRx1dIz9HyCYHgvnecJw==",
+      "license": "MIT",
+      "engines": {
+        "bun": ">=1.4",
+        "node": ">=22"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.9.1",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
+      "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/plugins/workflow/node_modules/@arcships/rutis/README.md

@@ -0,0 +1,32 @@
+# @arcships/rutis
+
+Write [rutis](https://github.com/arcships/rutis) plugins in TypeScript or JavaScript.
+
+```ts
+import { definePlugin } from '@arcships/rutis'
+
+export default definePlugin({
+  inject: ['llm'],                              // services it uses
+  config: { type: 'object', properties: { city: { type: 'string' } } },
+  apply(ctx, config) {
+    ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+    return () => {}                             // cleanup
+  },
+})
+```
+
+What `ctx.provide` provides reaches rutis by itself, its methods the object's functions, called as `async`. `provides` is optional: `provides: { weather: { unit: 'sync' } }` marks methods `sync` and tells `rutis-host check` what the plugin provides before it runs.
+
+Test it on a real host (`rutis-host test`; `@arcships/rutis-runtime` and `@arcships/rutis-host` as dev dependencies, which `rutis-host new` adds); the plugin is the default export of its module:
+
+```ts
+import { load } from '@arcships/rutis/testing'
+
+const t = await load(plugin, { config: { city: 'Oslo' }, services: { llm: { ask: async () => 'sunny' } } })
+assert.equal(await t.service('weather').today(), 'sunny in Oslo')
+await t.unload()
+```
+
+This package has no dependencies. Events (`ctx.on`, and `ctx.emit` / `parallel` / `serial` / `waterfall` / `bail` / `filter`) are one bus across every plugin, runtime and linked node, dispatched by the host; in a test too (`host()` puts several plugins on one bus). The host installs the runtime that runs the plugin (`@arcships/rutis-runtime` for Node, `@arcships/rutis-bun` for Bun). Start a project with `npx @arcships/rutis-host new <name> --lang node` (or `--lang bun`).
+
+Guide (Chinese): [docs/guide/typescript-plugin.md](https://github.com/arcships/rutis/blob/main/docs/guide/typescript-plugin.md).

package/plugins/workflow/node_modules/@arcships/rutis/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@arcships/rutis",
+  "version": "0.19.3",
+  "description": "Write rutis plugins in JavaScript or TypeScript: definePlugin, types and a test kit",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcships/rutis.git",
+    "directory": "node/rutis"
+  },
+  "homepage": "https://github.com/arcships/rutis/tree/main/docs/guide#readme",
+  "keywords": ["rutis", "plugin", "rutis-plugin"],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    },
+    "./advanced": {
+      "types": "./src/advanced.d.ts",
+      "default": "./src/advanced.mjs"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=22",
+    "bun": ">=1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@arcships/rutis-bun": "file:../../bun/rutis-bun",
+    "@arcships/rutis-runtime": "file:../rutis-runtime"
+  }
+}

package/plugins/workflow/node_modules/@arcships/rutis/src/advanced.d.ts

@@ -0,0 +1,90 @@
+// What a plugin author rarely writes (#692): the plugin API version, the
+// marks, the value constructors and the types of the events. `definePlugin`
+// and `Context` are in `@arcships/rutis`.
+import type { Plugin } from './index.js'
+
+export type MethodKind = 'sync' | 'async'
+
+/** Where a listener is, as the logical bus describes it (#464): what a filter sees. */
+export interface ListenerDescriptor {
+  /** The event name (a prefix, for a Rust pattern listener). */
+  readonly name: string
+  /** A Rust pattern listener's prefix entry. */
+  readonly prefix: boolean
+  /** The plugin that registered it: its declared name (`PluginSpec.name`, a Cordis plugin's name), else its row's id. */
+  readonly plugin: string
+  /** Its row's id, the name the configuration gives the row (the copies a group's instances make share it); `null` for a plugin a mount loaded. */
+  readonly row: string | null
+  /** The runtime it runs in; `null` for the host's own Rust plugins. */
+  readonly runtime: string | null
+  /** The node it came from over a node link; `null` otherwise. */
+  readonly node: string | null
+  /** Its scope chain, outermost first; `[]` at the root. */
+  readonly scope: ReadonlyArray<{ readonly id: string, readonly group: string }>
+  /** A `global` listener is never filtered. */
+  readonly global: boolean
+}
+
+export interface ListenerOptions {
+  /** Run before every listener of the name registered so far. */
+  prepend?: boolean
+  /** Not subject to emitters' filters. */
+  global?: boolean
+}
+
+/** A listener: the event's arguments, then, in a `waterfall`, `next` (the rest of the chain) last. */
+export type Listener = (...args: any[]) => any
+
+/** The five ways to emit. Each reaches every listener of the name on the root's flat bus, wherever the listener runs, by the same rules as if all were in this process. Emitting `rutis/*` throws `ReservedEvent`; `internal/*` is refused. */
+export interface Emitter {
+  /** Start every listener in registration order; returns at once. A listener's failure is reported where it ran and reaches neither the emitter nor the other listeners. */
+  emit(name: string, ...args: any[]): void
+  /** Start every listener and wait for all. Failures reject with an `AggregateError` in registration order, even a single one. */
+  parallel(name: string, ...args: any[]): Promise<void>
+  /** Run the listeners one by one; resolves to the first result (not `undefined`, `null` or `false`), or `undefined`. An error stops and rejects. */
+  serial<T = any>(name: string, ...args: any[]): Promise<T | undefined>
+  /** Each listener gets `next` (no arguments) last and returns the result; not calling `next` vetoes the rest. Every argument is the event's; the end of the chain gives `undefined` (see `with` for a terminal). Returns the outermost listener's value as is (a Promise whenever a listener runs elsewhere: await it). Calling `next` twice, or after the end, gives a Promise rejected with `WaterfallNext`. */
+  waterfall: Waterfall
+  /** Synchronously, the first result as `serial`. An `async` listener, or one returning a Promise, fails it with `AsyncListener`. */
+  bail<T = any>(name: string, ...args: any[]): T | undefined
+}
+
+export interface Waterfall {
+  <T = any>(name: string, ...args: any[]): T | Promise<T>
+  /** The same waterfall with a terminal: called with the event's arguments at the end of the chain, its value what the last `next` gives. */
+  with<T = any>(terminal: (...args: any[]) => any): <U = T>(name: string, ...args: any[]) => U | Promise<U>
+}
+
+/** The plugin API this SDK writes plugins against. */
+export declare const PLUGIN_API: number
+/** The mark on what `definePlugin` makes (`Symbol.for('rutis.leaf-plugin')`), across copies of this package. */
+export declare const PLUGIN: unique symbol
+/** Whether `value` is a plugin `definePlugin` made. */
+export declare function isPlugin(value: unknown): value is Plugin
+
+/** The mark on a value made by `datetime`, `date`, `time`, `decimal` or `uuid` (`Symbol.for('rutis.value')`). */
+export declare const VALUE: unique symbol
+
+/**
+ * A local date and time, date, time of day, decimal or UUID to send as that
+ * value (#308): JavaScript has no type for them. Received, they are strings
+ * (`value`'s text); a plain string is sent as a string.
+ */
+export interface TaggedValue<Tag extends 'datetime' | 'date' | 'time' | 'decimal' | 'uuid'> {
+  readonly [VALUE]: Tag
+  /** The value's text, as it crosses. */
+  readonly value: string
+  toString(): string
+  toJSON(): string
+}
+
+/** A local date and time without a time zone: `'2026-10-15T14:30'`, `'2026-10-15T14:30:05.25'` (years 0001–9999, 0–9 fraction digits). Received as its text. */
+export declare function datetime(text: string): TaggedValue<'datetime'>
+/** A calendar date: `'2026-10-15'` (years 0001–9999). Received as its text. */
+export declare function date(text: string): TaggedValue<'date'>
+/** A time of day without a time zone: `'14:30'`, `'14:30:05.25'` (24-hour). Received as its text. */
+export declare function time(text: string): TaggedValue<'time'>
+/** A decimal number, trailing zeros kept: `'1.10'`, `'-12.3400'` (no exponent, at most 4300 digits). Received as its text. */
+export declare function decimal(text: string | bigint): TaggedValue<'decimal'>
+/** A UUID, `8-4-4-4-12` hex in either case; sent and received in lowercase. */
+export declare function uuid(text: string): TaggedValue<'uuid'>

package/plugins/workflow/node_modules/@arcships/rutis/src/advanced.mjs

@@ -0,0 +1,32 @@
+// The names a plugin author rarely writes (#692): the plugin API version,
+// the marks the runtimes recognise plugins and values by, and the value
+// constructors. `ctx` and `definePlugin` are in `@arcships/rutis`.
+//
+//   import { datetime, decimal } from '@arcships/rutis/advanced'
+//   return { at: datetime('2026-10-15T14:30'), price: decimal('1.10') }
+
+// The plugin API this SDK writes plugins against. A runtime refuses a plugin
+// that needs a newer one, naming both.
+// 2: ctx.on and ctx.emit (leaf events). A runtime that supports only 1
+// refuses such a plugin at load instead of failing in apply.
+// 3: the unified events of rutis 0.13 (#464): ctx.parallel, serial,
+// waterfall, bail and filter, ctx.signal, and `prepend` / `global` on
+// ctx.on. A runtime of 0.12 or older refuses such a plugin at load.
+export const PLUGIN_API = 3
+
+// Marks what definePlugin returns, across copies of this package.
+export const PLUGIN = Symbol.for('rutis.leaf-plugin')
+
+// Whether `value` is a plugin definePlugin made.
+export const isPlugin = value => value?.[PLUGIN] === true
+
+// Values JavaScript has no type for, to send as what they are (#308): a
+// local date and time, a date, a time of day, a decimal, a UUID. Received,
+// they are strings; a plain string is sent as a string.
+//
+// A Date, Uint8Array, Map, Set and bigint need no constructor: they cross
+// as an instant, bytes, a map, a set and a big integer.
+export { datetime, date, time, decimal, uuid } from './values.mjs'
+// The mark on what they make, across copies of this package and in the
+// runtimes: `Symbol.for('rutis.value')`.
+export { MARK as VALUE } from './values.mjs'

package/plugins/workflow/node_modules/@arcships/rutis/src/index.d.ts

@@ -0,0 +1,43 @@
+import type * as advanced from './advanced.js'
+
+/**
+ * An error a listener threw arrives, through the host, as an `Error` of the
+ * same built-in class (`TypeError`, `RangeError`, …, `AggregateError`) or a
+ * plain `Error` with the thrower's `name`, `message` and `code`, never as
+ * the thrower's own class: match errors by `name`.
+ */
+export interface Context extends advanced.Emitter {
+  /** The service `name`, which the plugin declares in `inject`: the object itself when a plugin in the same process provides it, else a proxy whose methods are sync or async as declared. */
+  use<T = any>(name: string): T
+  /** Provide `value` as the service `name` until the plugin unloads, or until the returned function is called. It reaches rutis by itself: its methods are the object's functions (own and inherited, not `constructor`), `async` unless `provides` marks them `sync`. */
+  provide(name: string, value: unknown): () => unknown
+  /** Run `cleanup` when the plugin unloads. */
+  effect(cleanup: () => unknown): void
+  /** Aborted when the plugin unloads; its running listeners are then waited for (up to the host's shutdown deadline) before the cleanups run. */
+  readonly signal: AbortSignal
+  /** Listen to `name` on the host's logical bus: every event of that name, from any process or language (a scope is a descriptor). Registered with the host by itself; unregistered when the plugin unloads or the returned function is called. `rutis/*` (the host's framework events) can be listened to; `internal/*` cannot. */
+  on(name: string, listener: advanced.Listener, options?: advanced.ListenerOptions): () => void
+  /** The five ways to emit, delivered only to the listeners `keep` returns true for (`global` listeners are always delivered). `keep` runs in this process, once per candidate, before any listener runs. */
+  filter(keep: (listener: advanced.ListenerDescriptor) => unknown): advanced.Emitter
+}
+
+export interface PluginSpec<C = any> {
+  /** Its name: what listener descriptors (`ListenerDescriptor.plugin`) call it. Without one, they call it by its row's id. */
+  name?: string
+  /** Services the plugin uses: rutis starts it once they are all available, and stops it when one goes. */
+  inject?: string[]
+  /** Optional: services it provides, with the kind of methods to call `sync` (the others are `async`). Without it, what `ctx.provide` provides still reaches rutis; with it, `rutis-host check` knows before the plugin runs. */
+  provides?: Record<string, Record<string, advanced.MethodKind>>
+  /** The JSON Schema of its config. */
+  config?: object
+  apply(ctx: Context, config: C): void | (() => unknown) | Promise<void | (() => unknown)>
+}
+
+export interface Plugin<C = any> extends Readonly<Required<Pick<PluginSpec<C>, 'inject' | 'provides'>>>, Readonly<Omit<PluginSpec<C>, 'inject' | 'provides'>> {
+  /** The plugin API it was written against. */
+  readonly api: number
+  /** Always `true`: what it provides beyond `provides` reaches rutis by itself, known once it runs. */
+  readonly announces: boolean
+}
+
+export declare function definePlugin<C = any>(spec: PluginSpec<C>): Plugin<C>

package/plugins/workflow/node_modules/@arcships/rutis/src/index.mjs

@@ -0,0 +1,71 @@
+// Write a rutis plugin in JavaScript or TypeScript. A plugin declares the
+// services it uses (`inject`), and `apply(ctx, config)` uses and provides
+// them through `ctx`; rutis decides when it starts, stops and restarts. The
+// runtime that runs it is installed by the host (`@arcships/rutis-runtime`
+// in Node, `@arcships/rutis-bun` in Bun), not by the plugin.
+//
+//   export default definePlugin({
+//     inject: ['llm'],
+//     config: { type: 'object', properties: { city: { type: 'string' } } },
+//     apply(ctx, config) {
+//       ctx.provide('weather', new Weather(ctx.use('llm'), config.city))
+//       ctx.on('weather/ask', city => city === config.city ? 'sunny' : undefined)
+//       return () => {}
+//     },
+//   })
+//
+// Events cross every process and language on the host (#464): `ctx.on`
+// listens to every event of the name on the flat bus, and
+// `ctx.emit` / `parallel` / `serial` / `waterfall` / `bail` reach every
+// listener, wherever it runs, as if all were in this process.
+//
+// What `ctx.provide` provides reaches rutis by itself: its methods are the
+// object's functions (its own and its prototype chain's, not `constructor`),
+// called as `async`. `provides` is optional: `{ weather: { unit: 'sync' } }`
+// marks methods `sync` and tells `rutis-host check` what the plugin
+// provides before it runs.
+
+import { PLUGIN, PLUGIN_API } from './advanced.mjs'
+
+// `config` is a JSON Schema object: the host fills its defaults and checks
+// the config with it before `apply`. A Standard Schema object (schemastery,
+// zod, …) was never applied: refused (config schema design §2.3).
+function checkSchema(config) {
+  const standard = config?.['~standard']
+  if (standard !== undefined) {
+    throw new TypeError(`config of definePlugin should be a JSON Schema object, got ${standard?.vendor === 'schemastery' ? 'a schemastery Schema' : 'a Standard Schema'}`)
+  }
+}
+
+// The module that defined a plugin, as a file URL: the test tool
+// (`@arcships/rutis/testing`) has a real runtime load the plugin from it.
+const FILE = Symbol.for('rutis.plugin-file')
+function definedIn() {
+  const prepare = Error.prepareStackTrace
+  try {
+    Error.prepareStackTrace = (_, sites) => sites
+    const holder = {}
+    Error.captureStackTrace(holder, definePlugin)
+    const file = holder.stack?.[0]?.getFileName?.()
+    return typeof file === 'string' ? file : undefined
+  } catch {
+    return undefined
+  } finally {
+    Error.prepareStackTrace = prepare
+  }
+}
+
+export function definePlugin(spec) {
+  if (typeof spec?.apply !== 'function') throw new TypeError('a plugin needs apply(ctx, config)')
+  checkSchema(spec.config)
+  const inject = spec.inject ?? []
+  if (!Array.isArray(inject) || inject.some(name => typeof name !== 'string')) throw new TypeError('inject must be a list of service names')
+  for (const [name, methods] of Object.entries(spec.provides ?? {})) {
+    for (const [method, kind] of Object.entries(methods ?? {})) {
+      if (kind !== 'sync' && kind !== 'async') throw new TypeError(`${name}.${method}: kind must be 'sync' or 'async'`)
+    }
+  }
+  // `announces`: what it provides beyond `provides` (all of it, without
+  // one) reaches rutis by itself, and is known once it runs.
+  return Object.freeze({ ...spec, inject, provides: spec.provides ?? {}, announces: true, api: PLUGIN_API, [PLUGIN]: true, [FILE]: definedIn() })
+}