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

package/plugins/session-title/part.ts

@@ -0,0 +1,172 @@
+// The SessionTitle part, in a module of its own so a test loads its default
+// export (the rutis test tool loads a module's default plugin).
+import { definePlugin } from '@arcships/rutis'
+import type {
+  AgentEvent, AuxiliaryModel, ModelId, Services, SessionBroadcast, SessionMetadata,
+  SessionMethods, SessionMethodReply, Sessions, Settings, SettingsResult,
+} from '../../../npm/plugin.d.ts'
+import type { UserInput } from '../../../npm/branch-services.d.ts'
+
+type Document = { enabled: boolean; maxLength: number; model: ModelId | null }
+type TitleSettings = { read(request: Parameters<Settings['read']>[0]): Promise<SettingsResult<{ document: Document }>> }
+type HistoryEvent = Omit<AgentEvent, 'data'> & { data: Record<string, any> }
+const SYSTEM = "Write a short title for this conversation: at most 8 words, in the language of the user's message, no quotes, no trailing punctuation. Reply with the title only."
+const failure = (code: string, message: string): SessionMethodReply => ({ code, message })
+const reloading = () => failure('service_reloading', 'SessionTitle is closing or reloading')
+
+async function prefix(sessions: Sessions, sessionId: string, sequence: number, inputId: string) {
+  const inputs = new Map<string, UserInput>()
+  let first: UserInput | undefined
+  let model: ModelId | undefined
+  let operator = false
+  let after: number | undefined
+  let through: number | undefined
+  do {
+    const page = await sessions.history({ sessionId, branchId: 'main', after,
+      ...(through === undefined ? { atLeast: sequence } : { through }) })
+    if (!page.ok) throw new Error('history_failed')
+    through = page.value.through
+    if (page.value.events.length === 0) break
+    const events: HistoryEvent[] = page.value.events
+    for (const event of events) {
+      if (event.type === 'input' && event.name === 'message' && event.data.user) {
+        if (!first) inputs.set(event.id, event.data.user)
+        if (event.id === inputId) operator = true
+      }
+      if (event.type === 'input' && event.name === 'applied' && !first) {
+        first = inputs.get(event.data.input_id)
+      }
+      if (event.type === 'context' && event.name === 'configured') {
+        model = { providerId: event.data.settings.providerId, modelId: event.data.settings.modelId }
+      }
+    }
+    after = page.value.events.at(-1)!.sequence
+  } while (after < through)
+  return { first, model, operator }
+}
+
+/** The Session part SessionTitle registers: one copy per Session. */
+export default definePlugin({
+  name: 'SessionTitle',
+  inject: ['sessions', 'settings', 'sessionMetadata', 'auxiliaryModel', 'sessionIdentity', 'sessionConfig', 'sessionLifecycle', 'sessionMethods'],
+  async apply(ctx) {
+    const sessions = ctx.use<Sessions>('sessions')
+    const settings = ctx.use<TitleSettings>('settings')
+    const metadata = ctx.use<SessionMetadata>('sessionMetadata')
+    const auxiliary = ctx.use<AuxiliaryModel>('auxiliaryModel')
+    const { sessionId } = await ctx.use<Services['sessionIdentity']>('sessionIdentity').get()
+    const config = await ctx.use<Services['sessionConfig']>('sessionConfig').get()
+    const lifecycle = ctx.use<Services['sessionLifecycle']>('sessionLifecycle')
+    const tasks = new Set<Promise<void>>()
+    let closed = false
+    let generating = false
+    let epoch = 0
+    let failures = 0
+    let noText = false
+    let cancel: (() => void) | undefined
+    const close = () => { closed = true; cancel?.() }
+    ctx.effect(async () => { close(); await Promise.all(tasks) })
+    void lifecycle.closing().then(close)
+
+    async function attempt(sequence: number, inputId: string, observedEpoch: number) {
+      const started = performance.now()
+      const current = () => !closed && observedEpoch === epoch
+      let entered = false
+      let timer: ReturnType<typeof setTimeout> | undefined
+      let cancelled = false
+      const diagnostic = (outcome: string) => console.warn('SessionTitle', outcome, Math.round(performance.now() - started))
+      try {
+        const configured = await settings.read({ source: 'session-title', scope: 'user' })
+        if (!current() || (configured.ok && !configured.value.document.enabled)) return
+        const stored = await metadata.read({ sessionId: sessionId })
+        if (!current() || (stored.ok && stored.value.title)) return
+        const snapshot = await prefix(sessions, sessionId, sequence, inputId)
+        if (!current() || !snapshot.operator || !snapshot.first) return
+        epoch++
+        entered = true
+        generating = true
+        const cancellation = new Promise<void>(resolve => {
+          cancel = () => { cancelled = true; resolve() }
+        })
+        timer = setTimeout(() => cancel?.(), 30_000)
+        if (!stored.ok) throw new Error('metadata_failed')
+        if (!configured.ok) throw new Error('settings_failed')
+        const document = configured.value.document
+        const text = [...snapshot.first.content.filter(block => block.type === 'text').map(block => block.text).join('\n')].slice(0, 2000).join('')
+        if (!text) { noText = true; return }
+        const model = document.model ?? snapshot.model
+        if (!model) throw new Error('model_unavailable')
+        const reply = await auxiliary.complete({ model, request: {
+          system: SYSTEM, messages: [{ role: 'user', content: text }],
+        } }, () => cancellation)
+        if (closed) return
+        if (cancelled) throw new Error('timed_out')
+        const line = reply.text.trim().split(/[\r\n\u2028\u2029]/, 1)[0].trim()
+        const title = [...line.replace(/^\p{Quotation_Mark}+|\p{P}+$/gu, '').replace(/[\s\p{Cc}]+/gu, ' ').trim()].slice(0, document.maxLength).join('').trim()
+        if (!title) throw new Error('empty_title')
+        const written = await metadata.setTitle({ sessionId: sessionId,
+          expectedRevision: stored.value.revision, title: { text: title, source: 'auto' } })
+        if (!written.ok && written.error.code === 'storage') throw new Error('storage_failed')
+        diagnostic(written.ok ? 'completed' : 'discarded')
+      } catch {
+        if (!closed) {
+          if (entered) failures++
+          diagnostic('failed')
+        }
+      } finally {
+        if (entered) {
+          clearTimeout(timer)
+          cancel = undefined
+          generating = false
+        }
+      }
+    }
+
+    if (config.interactive !== false && config.collaborationRole === 'leader') {
+      ctx.on(`session/${sessionId}`, (record: SessionBroadcast) => {
+        if (closed || record.kind !== 'event' || record.branchId !== 'main') return
+        const event = record.event as HistoryEvent
+        if (generating || noText || failures >= 3
+          || event.type !== 'input' || event.name !== 'applied') return
+        const task = attempt(event.sequence, event.data.input_id, epoch)
+        tasks.add(task)
+        void task.finally(() => tasks.delete(task))
+      })
+    }
+
+    await ctx.use<SessionMethods>('sessionMethods').register(
+      'session.rename',
+      [{ name: 'session.rename', mutating: true, interruption: 'report', progress: false }],
+      async (call, cancelled) => {
+        if (closed) return reloading()
+        const value = call.params.title
+        if (call.method !== 'session.rename' || (value !== null && typeof value !== 'string')) {
+          return failure('invalid_params', 'title must be a string or null')
+        }
+        const text = value === null ? null : value.trim()
+        if (text !== null && (!text || /[\p{Cc}\p{Zl}\p{Zp}]/u.test(value!))) {
+          return failure('invalid_params', 'Invalid title or control character')
+        }
+        let aborted = false
+        cancelled.then(() => { aborted = true })
+        const configured = await settings.read({ source: 'session-title', scope: 'user' })
+        if (closed || aborted) return reloading()
+        if (!configured.ok) return failure('storage_failed', 'Cannot read title settings')
+        if (text !== null && [...text].length > configured.value.document.maxLength) {
+          return failure('invalid_params', 'Invalid title length')
+        }
+        for (let retry = 0; retry <= 3; retry++) {
+          const stored = await metadata.read({ sessionId })
+          if (closed || aborted) return reloading()
+          if (!stored.ok) return failure(stored.error.code === 'not_found' ? 'session_not_found' : 'storage_failed', 'Cannot read title metadata')
+          const written = await metadata.setTitle({ sessionId,
+            expectedRevision: stored.value.revision, title: text === null ? null : { text, source: 'manual' } })
+          if (written.ok) return { kind: 'value', value: { title: text, titleSource: text === null ? null : 'manual', revision: written.value.revision } }
+          if (written.error.code !== 'conflict') return failure(written.error.code === 'not_found' ? 'session_not_found' : 'storage_failed', 'Cannot write title metadata')
+          if (closed || aborted) return reloading()
+        }
+        return failure('service_reloading', 'Title changed during rename')
+      },
+    )
+  },
+})

package/plugins/session-title/settings.ts

@@ -0,0 +1,49 @@
+import type { SourceDeclaration } from '../../../npm/plugin.js'
+
+export const settings: SourceDeclaration = {
+  "source": "session-title",
+  "userFile": "session-title.json",
+  "userOnly": [],
+  "schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "maxLength": {
+        "type": "integer",
+        "minimum": 10,
+        "maximum": 200,
+        "default": 80
+      },
+      "model": {
+        "default": null,
+        "anyOf": [
+          {
+            "type": "null"
+          },
+          {
+            "type": "object",
+            "required": [
+              "providerId",
+              "modelId"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "providerId": {
+                "type": "string",
+                "minLength": 1
+              },
+              "modelId": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/plugins/workflow/README.md

@@ -0,0 +1,169 @@
+# Workflow
+
+Optional TypeScript package implementing the [Workflow contract](../../../docs/design/plugins/Workflow.md).
+The plugin is one process row. It owns definitions, runs and report settlement, and registers its
+Session part (`session.ts`, as `WorkflowSession`) with `partRegistry`; each Session's copy provides
+the `workflow` tool through the declared `workflowRuns` dependency. All native I/O uses existing `sessions`,
+`settings`, `workflowFiles` and `pluginFiles` ports.
+
+## Loading
+
+```sh
+npm ci --prefix runtime --ignore-scripts
+npm ci --prefix runtime/plugins/workflow --ignore-scripts
+(cd runtime && npm install --no-save --package-lock=false --ignore-scripts --install-links ./plugins/workflow)
+```
+
+These commands set up the shared runtime and this package in the checkout for `--session-rows` embedding and the package's tests. `./dev` needs none of them: it stages the default plugins, with their own dependencies, into `staging/dev-plugins`.
+
+The plugin directory carries [dim-plugin.json](dim-plugin.json) and is a default plugin listed in
+[runtime/default-plugins.json](../../default-plugins.json), which PluginManager loads (`--defaults`).
+An embedding host may still build a row from the manifest's `code` fields for
+`ServerConfig.session_typescript.rows`. A Session without a
+mount list (`SessionConfig.tools`) declares `workflow` once its Session part registers it; a Session with one
+declares it when the list names it. PluginManager creates the product-root `workflow/`
+directory when it turns the plugin on; a host that builds the row itself provisions it before
+enabling the process row. A stage Session takes the stage agent's or default
+profile's mount list: a profile without one exposes `workflow` inside a stage, and one whose list
+omits it has no Workflow tool; Workflow does not add it to `sessions.launch`. When it is declared,
+the non-interactive handler refuses invocation as A.2 requires. Missing parent directories fail with `io`; the plugin
+does not create them through a filesystem fallback.
+
+The process row's trusted `config.packages` is a list of unique `{id, root}` declarations. Roots
+must already be canonical and authorized by the host. The native binding exposes only package ids
+to the plugin. Model arguments and workflow files cannot grant file authority or install packages.
+An unavailable dependency leaves its optional row Pending under existing assembly rules.
+
+## Definitions and execution
+
+`workflow.save` takes one of two strict branches. `{source:"user", document, expectedRevision?}`
+saves the definition into the `workflow` Settings document with owner CAS: at `expectedRevision`
+when the caller gives one, and at the revision the owner reads otherwise; a user save that names
+`cwd` is refused. `{source:"project", cwd, document}` writes
+`.dimcode/workflows/<name>.yaml` through `workflowFiles` and refuses `expectedRevision`, since the
+file belongs to the workspace `cwd` names. Project definitions start disabled.
+Only the user's local `settings.update` can change the protected
+`projectEnabled[canonicalCwd][name]` field. An enabled definition takes effect at the next start;
+a running workflow keeps its accepted definition and parameter snapshot.
+
+```json
+{
+  "schema": "dim.workflow/v1",
+  "name": "review",
+  "description": "Analyze and summarize a target",
+  "parameters": [{"name":"target","required":true}],
+  "steps": [
+    {"stage":{"id":"analyze","prompt":"Analyze {{params.target}}"}},
+    {"stage":{"id":"summary","prompt":"Summarize {{stages.analyze.result}}"}}
+  ]
+}
+```
+
+Tool actions are `list`, `start`, `status` and `stop`. Management exposes the same operations
+plus `save` as `workflow.*` methods. Start returns the run id; status returns stored stage results.
+Tool `list` returns one `{definitions, truncated}` JSON object in `content`; description,
+parameter and issue fields are bounded previews, entries stop at the 8 MiB payload and `truncated`
+marks omitted definitions. Management `workflow.list` returns the same object.
+Tool status/stop text includes stage identities/states and Session ids, one 4 KiB result preview
+and the last 10 log entries; `structuredContent` retains the full stored run.
+Tool status/stop require the caller Session to match the run's tool starter or report destination; unrelated Sessions receive `run_not_found` without record access or mutation. Management methods remain process-global.
+The tool is refused in non-interactive Sessions. Existing Permission handles its unclassified risk:
+ReadOnly denies, WorkspaceWrite asks and FullAccess allows.
+
+Source precedence is enabled project, user, then plugin; invalid enabled definitions are reported
+instead of silently falling through. Duplicate names across installed packages are invalid.
+Templates accept only declared parameters and results of earlier steps, never sibling stages.
+Supplied/default values are inserted literally; an omitted optional parameter inserts empty text.
+Definition files have an 8 MiB read/replace limit so their base64 payload fits the existing 16 MiB bridge frame. Project saves check serialized YAML before a binary call and leave an existing file unchanged on rejection. Larger files are reported as invalid entries. One Workflow payload crossing the bridge is capped at 8 MiB of its serialized bytes: a new definition's compact JSON is capped at 1 MiB, and a user save that would make the `workflow` document exceed 8 MiB is rejected without writing. A user document written before these bounds is still read while it fits one frame; entries over 1 MiB show as invalid, and shrinking a document that stays over the payload is the protected `settings.update` client's operation. Parameters, including unused values and defaults, remain capped at 32 KiB each and 256 KiB total in UTF-8. Rejection precedes run persistence; existing inner-v2 snapshots remain decodable without these admission bounds.
+
+Each stage runs in its own non-interactive Session. The actual first launch reply fixes the run's
+permission ceiling before any sibling receives input. Management starts default to ReadOnly.
+The Settings document contains `max_concurrent_runs` and per-run `max_concurrent_stages`, both
+defaulting to 4; each new run reads their current values. A parallel step is rendered completely
+before admission. A rendered prompt above 32 KiB fails that step without launching any sibling;
+stored stage text is bounded to 64 KiB per stage and 512 KiB of committed JSON per run, each stored
+log message and stage reason to 512 bytes of committed JSON, and report previews to 4 KiB.
+Quote-heavy, backslash-heavy and control-character text is measured in that escaped form. Later
+result text is truncated at a UTF-8 boundary to the run's remaining payload.
+
+## Ownership and recovery
+
+The process row tracks admitted calls, run tasks, native operations and file writes. Cleanup stops
+new work, requests stage shutdown, joins its work and then closes the original file scope. History
+tracking uses a fixed published prefix once per second and follows only each stage's own input.
+Held inputs can be withdrawn. Stopping consumed work addresses the branch's current turn; the
+existing later-turn race and retained applied input limits remain in force.
+
+Completed, failed and interrupted runs report to their recorded destination as one raw Steer block;
+explicit stops and management runs without a destination do not report. Before submission, the
+inner run record persists `pending` with `attempt_open:true` (kept in the format; it decides
+nothing). Every retry, including a replacement generation's recovery, resubmits the same
+`submissionId`; the destination branch accepts it once and replies the first input's receipt.
+An `ambiguous` reply (duplicates written before branches accepted each id once) settles the report
+delivered and records a violation. Missing destinations are undeliverable.
+
+Run storage is `workflow/runs.json`, with inner `{version:2,runs:[...]}` inside the host's S10 v1
+wrapper. Runs admitted under the bounds below keep the text within the 8 MiB payload as the file
+service carries it (the JSON string, where escapes can double): a start projects the store with
+every active run's record, the stage identities, `agent_id` copies, results and logs it can gain
+later, plus the new record; if that exceeds the payload it first expires the oldest settled
+terminal runs and otherwise returns `limit_exceeded` without persisting. The retained store,
+therefore, keeps each read, write and `workflow.status` reply within one bridge frame; a record
+committed before these bounds keeps its original size. Invalid, v1,
+unknown-version or missing-marker records return `invalid_data` and preserve their bytes. There is
+no migration. After a crash, unfinished runs become interrupted/lost without relaunch; a lost
+stage's running turn or pending approval is left untouched. Only orderly unload stops stages under
+A13. Active runs, pending reports and uncertain deletion records are retained; other terminal
+history is limited to 100, and a start may expire older settled records for frame space. Owned
+Sessions are deleted before removing their last ownership record.
+A successful launch that stop overtakes before input remains named in its retained run; no turn
+stop is sent without observed consumption. A.4's retained-reference calculation and 100-run policy
+still apply, and #126 remains the loaded-idle-Session shipping prerequisite. An applied input that
+was not withdrawn or interrupted may keep an explicit stop pending under §3.2; no new deadline
+changes that accepted input/terminal-fact contract.
+
+## Verification and delivery limits
+
+```sh
+node runtime/node_modules/typescript/bin/tsc -p runtime/plugins/workflow/tsconfig.json
+node --test runtime/plugins/workflow/workflow.test.mjs
+```
+
+Actual Node/App Server flows are in
+[workflow.rs](../../../crates/dim-app-server/tests/transport_flow/workflow.rs), using public Node CI's
+`DIM_TEST_NODE`, `DIM_TEST_JS_RUNTIME` and `DIM_TEST_RUTIS_SDK` settings and disposable homes.
+They exercise stage Sessions, published reports, resubmission across row/runtime replacement, crashes and failed
+record replacement. Native retention flows use actual Session deletion, file read/replace failures,
+fixed-row replacement and the existing one-minute maintenance timer. The acceptance mapping below
+separates native coverage from SDK coverage.
+The read-failure retry case needs a valid startup restore before making the run
+file unreadable. It retains two real timer passes; corrupting that file before
+row activation would exercise startup failure instead of retention recovery.
+The existing [#126](https://github.com/arcships/dim/issues/126) idle-unload work must land before
+shipping repeated stage creation. A launch whose reply is lost before its Session id is persisted
+can leave an unidentified Session; it is not relaunched or recovered by a new registry.
+
+## Acceptance coverage
+
+The [SDK flows](workflow.test.mjs) execute the actual modules through their declared ports.
+The [native flows](../../../crates/dim-app-server/tests/transport_flow/workflow.rs) use real
+Node rows, Settings, file authority, S2 calls, publication and Session history. This maps to
+[Workflow Appendix D](../../../docs/design/plugins/Workflow.md#appendix-d-acceptance):
+
+| Items | Evidence |
+| --- | --- |
+| 1 | SDK definition, template, parameter, frozen-run and whole-step overflow flows; native source identities, generic Settings writes and model-visible diagnostics |
+| 2, 5 | Native start + wait batch: report wakes wait, adoption follows the batch result, and interrupting the starter leaves accepted run work alive; native starter closure makes its report undeliverable |
+| 3, 4 | Native held, consumed/approval and completed-turn stop cases; SDK applied-before-consumption and concurrent-withdrawal cases; repeated stop and no-report assertions |
+| 6 | Native project default-disabled/client enablement, editing a running definition and the next run reading the edit |
+| 7 | Native running-stage Node crash, row/runtime report replacement, complete host restart and Agents-index reload; no stage relaunch |
+| 8–11 | Native live first-admission narrowing with the sibling launch gated, cap persistence before siblings, starter loss, non-interactive/default-profile stage Sessions with and without `workflow` in the mount list, ReadOnly denial and handler refusal when it is declared |
+| 12 | Native retention keeps the latest 100 terminal records, newer active/pending work and retained references; SDK flows prove that older active/pending records also survive the terminal limit and that a start expires older settled records for frame space; user forks and external Sessions survive owned-parent deletion. Real deletion/read/atomic-replace failures preserve ownership, minute maintenance retries without active runs or definitions, and Node restart reconciles deletion before record removal. Native terminal/report-settlement triggers continue with an unreadable definition source; native source CAS and invalid-file preservation are also covered |
+| 13 | Native resubmission across row/runtime replacement with the append held, before/after-input crashes, failed atomic replacement, a resubmitted report written once and host restart; SDK rejected, failed, ambiguous, reloading and publication-unknown replies |
+| 14 | SDK definition, user-document, run-store and listing payload flows: over-1-MiB definitions are rejected, a user save over the 8 MiB document is rejected without writing, quote/backslash/control-character results and logs are measured in their committed JSON form and a run's results stop at 512 KiB, `agent_id` copies are charged, an over-payload active admission returns `limit_exceeded` without persisting, a start expires older settled records to fit, the listing is sent once and stops at its payload with `truncated`, and the store and status replies stay within 8 MiB. Native inner-v2 records remain decodable |
+
+Scope cleanup also exercises a failing parallel reader while another native launch is admitted:
+the original task joins its siblings before its file scope can close. No additional lock or owner
+registry is used. The explicit installation and #126 shipping boundary above still apply.
+
+Tool status and stop share a 4 KiB result preview and include only the last ten logs, each message bounded to 512 UTF-8 bytes. Full records remain in structured data and management status. Diagnostic messages are bounded to 4 KiB. A known owner reply, including its run id, survives tool retirement. A thrown issued call with an unknown outcome uses the existing uncertain-effects guidance; accepted work stays owned by the process row.

package/plugins/workflow/catalog.ts

@@ -0,0 +1,131 @@
+import { stringify } from 'yaml'
+import type { Settings, WorkflowFiles, WorkflowFilesErrorThrown, WorkflowRoot } from '../../../npm/plugin.js'
+import { decodeDefinition, decodeFile, issues, payloadBytes, withinDefinitionLimit, WorkflowError, type Definition, type Source, type WorkflowSettings } from './definition.ts'
+import type { SaveRequest } from './requests.ts'
+
+export interface DefinitionEntry {
+  name: string
+  source: Source
+  package_id?: string
+  enabled: boolean
+  definition?: Definition
+  issues: string[]
+}
+
+/** One source read per operation; no definitions or enablement are cached. */
+export class Catalog {
+  readonly settings: Settings
+  readonly files: WorkflowFiles
+  readonly packages: { id: string; root: string }[]
+
+  constructor(settings: Settings, files: WorkflowFiles, packages: { id: string; root: string }[]) {
+    this.settings = settings
+    this.files = files
+    this.packages = packages
+  }
+
+  async load(cwd: string) {
+    const snapshot = await this.settings.read({ source: 'workflow', scope: 'user' })
+    if (!snapshot.ok) throw new WorkflowError('definition_source_failed', snapshot.error.message)
+    const document = snapshot.value.document as unknown as WorkflowSettings
+    const entries: DefinitionEntry[] = Object.entries(document.definitions).map(([name, definition]) => ({
+      name, definition, source: 'user', enabled: true,
+      issues: withinDefinitionLimit(definition) ? issues(definition, name) : ['Definition exceeds 1 MiB'],
+    }))
+    const projects = await this.settings.projects({})
+    if (!projects.ok) throw new WorkflowError('definition_source_failed', projects.error.message)
+    if (!projects.value.projects.some(project => project.cwd === cwd)) {
+      throw new WorkflowError('definition_source_failed', 'The workspace is not registered with Settings')
+    }
+    entries.push(...await this.directory({ project: cwd }, name => document.projectEnabled[cwd]?.[name] === true))
+    for (const item of this.packages) entries.push(...await this.directory({ package: item.id }, () => true))
+    const pluginNames = new Map<string, number>()
+    for (const entry of entries) {
+      if (entry.source === 'plugin') pluginNames.set(entry.name, (pluginNames.get(entry.name) ?? 0) + 1)
+    }
+    for (const entry of entries) {
+      if (entry.source === 'plugin' && pluginNames.get(entry.name)! > 1) {
+        entry.issues.push(`Definition ${entry.name} occurs in multiple installed packages`)
+      }
+    }
+    return { document, entries, revision: snapshot.value.revision }
+  }
+
+  private async directory(root: WorkflowRoot, enabled: (name: string) => boolean): Promise<DefinitionEntry[]> {
+    let files
+    try { files = await this.files.list({ root }) }
+    catch (error) {
+      if ('project' in root && (error as WorkflowFilesErrorThrown).code === 'not_found') return []
+      throw new WorkflowError('definition_source_failed', (error as Error).message)
+    }
+    const entries: DefinitionEntry[] = []
+    for (const file of files) {
+      if (!file.name.endsWith('.yaml')) continue
+      const name = file.name.slice(0, -5)
+      const entry: DefinitionEntry = {
+        name, source: 'package' in root ? 'plugin' : 'project', enabled: enabled(name), issues: [],
+        ...('package' in root ? { package_id: root.package } : {}),
+      }
+      entries.push(entry)
+      if (!/^[a-z0-9-]{1,64}$/.test(name) || file.kind !== 'file') {
+        entry.issues.push('A definition must be a regular file named <name>.yaml')
+        continue
+      }
+      try {
+        entry.definition = decodeFile(await this.files.read({ root, path: file.name }))
+        entry.issues = issues(entry.definition, name)
+      } catch (error) {
+        if (!(error instanceof WorkflowError) && (error as WorkflowFilesErrorThrown).code !== 'invalid_data') {
+          throw new WorkflowError('definition_source_failed', (error as Error).message)
+        }
+        entry.issues.push((error as Error).message)
+      }
+    }
+    return entries
+  }
+
+  async save(request: SaveRequest) {
+    const definition = decodeDefinition(request.document)
+    const invalid = issues(definition, definition.name)
+    if (invalid.length) throw new WorkflowError('invalid_definition', invalid.slice(0, 10).join('; '))
+    if (request.source === 'user') {
+      const snapshot = await this.settings.read({ source: 'workflow', scope: 'user' })
+      if (!snapshot.ok) throw new WorkflowError('definition_source_failed', snapshot.error.message)
+      const document = snapshot.value.document as unknown as WorkflowSettings
+      const next = { ...document, definitions: { ...document.definitions, [definition.name]: definition } }
+      if (Buffer.byteLength(JSON.stringify(next)) > payloadBytes) {
+        throw new WorkflowError('invalid_definition', 'User definitions exceed the 8 MiB frame payload')
+      }
+      const saved = await this.settings.update({ source: 'workflow', scope: 'user',
+        // The caller's revision is the document this write replaces; a
+        // create has none, so the read above is the caller.
+        expectedRevision: request.expectedRevision ?? snapshot.value.revision,
+        document: next,
+      })
+      if (!saved.ok) throw new WorkflowError(saved.error.code, saved.error.message)
+    } else {
+      const { cwd } = request
+      const text = stringify(definition)
+      if (Buffer.byteLength(text) > 8 * 1024 * 1024) {
+        throw new WorkflowError('invalid_definition', 'Definition file exceeds 8 MiB')
+      }
+      try {
+        await this.files.createDirectory({ root: { project: cwd } })
+        await this.files.replace({ root: { project: cwd }, path: `${definition.name}.yaml`,
+          bytes: new TextEncoder().encode(text),
+        })
+      } catch (error) { throw new WorkflowError('definition_source_failed', (error as Error).message) }
+    }
+    return { name: definition.name }
+  }
+}
+
+export function select(entries: DefinitionEntry[], name: string, source?: Source): Definition {
+  for (const category of source ? [source] : ['project', 'user', 'plugin']) {
+    const entry = entries.find(entry => entry.name === name && entry.source === category && entry.enabled)
+    if (!entry) continue
+    if (entry.issues.length || !entry.definition) throw new WorkflowError('invalid_definition')
+    return entry.definition
+  }
+  throw new WorkflowError('definition_not_found')
+}