@tagma/sdk 0.6.0 → 0.6.2

package/src/pipeline-runner.ts

@@ -1,173 +1,173 @@
-// ═══ PipelineRunner ═══
-//
-// Wraps runPipeline in a lifecycle object suited for multi-pipeline
-// management in sidecar / Tauri IPC scenarios. Each instance controls
-// one pipeline run.
-//
-// The runner forwards wire-shape `RunEventPayload` values to its
-// subscribers — identical to what the editor server broadcasts over SSE —
-// so sidecar hosts don't need to know anything about the engine's
-// internal TaskState.
-//
-// Typical sidecar usage:
-//
-//   const runners = new Map<string, PipelineRunner>();
-//
-//   const runner = new PipelineRunner(config, workDir);
-//   runner.subscribe(event => ipcEmit('run_event', event));
-//   runner.start();
-//   runners.set(runner.instanceId, runner);
-//
-//   // Later, from IPC:
-//   runners.get(id)?.abort();
-
-import { runPipeline } from './engine';
-import type { EngineResult, RunPipelineOptions } from './engine';
-import type { PipelineConfig, RunEventPayload, RunTaskState } from './types';
-import { generateRunId } from './utils';
-
-export type { EngineResult };
-
-export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
-
-export class PipelineRunner {
-  /**
-   * Stable ID assigned before start() — safe to use as a Map key before
-   * the engine-assigned runId becomes available.
-   */
-  readonly instanceId: string;
-
-  /**
-   * The runId generated by the engine. Set when the first `run_start`
-   * event arrives on the forwarded event stream. null until then.
-   */
-  private _runId: string | null = null;
-  private _status: PipelineRunnerStatus = 'idle';
-  private _result: Promise<EngineResult> | null = null;
-  private _abortController = new AbortController();
-  private _handlers = new Set<(event: RunEventPayload) => void>();
-  /**
-   * Wire-shape task mirror, kept in sync with `run_start` / `task_update`
-   * events. Exposed through `getTasks()`. Hosts see the same wire
-   * projection the editor client sees, so there is exactly one task-state
-   * vocabulary across IPC boundaries.
-   */
-  private _tasks = new Map<string, RunTaskState>();
-
-  constructor(
-    private readonly config: PipelineConfig,
-    private readonly workDir: string,
-    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
-  ) {
-    this.instanceId = generateRunId();
-  }
-
-  get runId(): string | null {
-    return this._runId;
-  }
-  get status(): PipelineRunnerStatus {
-    return this._status;
-  }
-
-  /**
-   * Start the pipeline. Calling start() more than once returns the same Promise.
-   */
-  start(): Promise<EngineResult> {
-    if (this._result) return this._result;
-
-    // Guard: if abort() was called before start(), the signal is already
-    // aborted. Create a fresh controller so the pipeline doesn't terminate
-    // immediately. If users truly want pre-abort semantics, they call
-    // abort() after start().
-    if (this._abortController.signal.aborted) {
-      this._abortController = new AbortController();
-      this._status = 'idle';
-    }
-
-    this._status = 'running';
-    this._result = runPipeline(this.config, this.workDir, {
-      ...this.opts,
-      signal: this._abortController.signal,
-      onEvent: (event) => {
-        this._applyEvent(event);
-        for (const h of this._handlers) h(event);
-      },
-    })
-      .then((result) => {
-        if (this._status === 'running') this._status = 'done';
-        return result;
-      })
-      .catch((err) => {
-        this._status = 'aborted';
-        throw err;
-      });
-
-    return this._result;
-  }
-
-  private _applyEvent(event: RunEventPayload): void {
-    switch (event.type) {
-      case 'run_start':
-        this._runId = event.runId;
-        this._tasks.clear();
-        for (const t of event.tasks) this._tasks.set(t.taskId, { ...t });
-        return;
-      case 'task_update': {
-        const prev = this._tasks.get(event.taskId);
-        if (!prev) return;
-        const pick = <T>(incoming: T | undefined, previous: T): T =>
-          incoming !== undefined ? incoming : previous;
-        this._tasks.set(event.taskId, {
-          ...prev,
-          status: event.status,
-          startedAt: pick(event.startedAt, prev.startedAt),
-          finishedAt: pick(event.finishedAt, prev.finishedAt),
-          durationMs: pick(event.durationMs, prev.durationMs),
-          exitCode: pick(event.exitCode, prev.exitCode),
-          stdout: pick(event.stdout, prev.stdout),
-          stderr: pick(event.stderr, prev.stderr),
-          stderrPath: pick(event.stderrPath, prev.stderrPath),
-          sessionId: pick(event.sessionId, prev.sessionId),
-          normalizedOutput: pick(event.normalizedOutput, prev.normalizedOutput),
-          resolvedDriver: pick(event.resolvedDriver, prev.resolvedDriver),
-          resolvedModel: pick(event.resolvedModel, prev.resolvedModel),
-          resolvedPermissions: pick(event.resolvedPermissions, prev.resolvedPermissions),
-        });
-        return;
-      }
-      case 'run_end':
-        this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
-        return;
-      default:
-        return;
-    }
-  }
-
-  /**
-   * Cancel the running pipeline. Safe to call multiple times or before start().
-   */
-  abort(reason?: string): void {
-    this._status = 'aborted';
-    this._abortController.abort(reason);
-  }
-
-  /**
-   * Live snapshot of wire-shape task states. Populated from the first
-   * `run_start` event onward. Returns an empty map before the run starts.
-   */
-  getTasks(): ReadonlyMap<string, RunTaskState> {
-    const copy = new Map<string, RunTaskState>();
-    for (const [id, t] of this._tasks) copy.set(id, { ...t });
-    return copy;
-  }
-
-  /**
-   * Subscribe to run events. Returns an unsubscribe function. Events are
-   * emitted synchronously in the engine's event loop, so keep handlers
-   * non-blocking (e.g. queue to IPC, do not await inside).
-   */
-  subscribe(handler: (event: RunEventPayload) => void): () => void {
-    this._handlers.add(handler);
-    return () => this._handlers.delete(handler);
-  }
-}
+// ═══ PipelineRunner ═══
+//
+// Wraps runPipeline in a lifecycle object suited for multi-pipeline
+// management in sidecar / Tauri IPC scenarios. Each instance controls
+// one pipeline run.
+//
+// The runner forwards wire-shape `RunEventPayload` values to its
+// subscribers — identical to what the editor server broadcasts over SSE —
+// so sidecar hosts don't need to know anything about the engine's
+// internal TaskState.
+//
+// Typical sidecar usage:
+//
+//   const runners = new Map<string, PipelineRunner>();
+//
+//   const runner = new PipelineRunner(config, workDir);
+//   runner.subscribe(event => ipcEmit('run_event', event));
+//   runner.start();
+//   runners.set(runner.instanceId, runner);
+//
+//   // Later, from IPC:
+//   runners.get(id)?.abort();
+
+import { runPipeline } from './engine';
+import type { EngineResult, RunPipelineOptions } from './engine';
+import type { PipelineConfig, RunEventPayload, RunTaskState } from './types';
+import { generateRunId } from './utils';
+
+export type { EngineResult };
+
+export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
+
+export class PipelineRunner {
+  /**
+   * Stable ID assigned before start() — safe to use as a Map key before
+   * the engine-assigned runId becomes available.
+   */
+  readonly instanceId: string;
+
+  /**
+   * The runId generated by the engine. Set when the first `run_start`
+   * event arrives on the forwarded event stream. null until then.
+   */
+  private _runId: string | null = null;
+  private _status: PipelineRunnerStatus = 'idle';
+  private _result: Promise<EngineResult> | null = null;
+  private _abortController = new AbortController();
+  private _handlers = new Set<(event: RunEventPayload) => void>();
+  /**
+   * Wire-shape task mirror, kept in sync with `run_start` / `task_update`
+   * events. Exposed through `getTasks()`. Hosts see the same wire
+   * projection the editor client sees, so there is exactly one task-state
+   * vocabulary across IPC boundaries.
+   */
+  private _tasks = new Map<string, RunTaskState>();
+
+  constructor(
+    private readonly config: PipelineConfig,
+    private readonly workDir: string,
+    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
+  ) {
+    this.instanceId = generateRunId();
+  }
+
+  get runId(): string | null {
+    return this._runId;
+  }
+  get status(): PipelineRunnerStatus {
+    return this._status;
+  }
+
+  /**
+   * Start the pipeline. Calling start() more than once returns the same Promise.
+   */
+  start(): Promise<EngineResult> {
+    if (this._result) return this._result;
+
+    // Guard: if abort() was called before start(), the signal is already
+    // aborted. Create a fresh controller so the pipeline doesn't terminate
+    // immediately. If users truly want pre-abort semantics, they call
+    // abort() after start().
+    if (this._abortController.signal.aborted) {
+      this._abortController = new AbortController();
+      this._status = 'idle';
+    }
+
+    this._status = 'running';
+    this._result = runPipeline(this.config, this.workDir, {
+      ...this.opts,
+      signal: this._abortController.signal,
+      onEvent: (event) => {
+        this._applyEvent(event);
+        for (const h of this._handlers) h(event);
+      },
+    })
+      .then((result) => {
+        if (this._status === 'running') this._status = 'done';
+        return result;
+      })
+      .catch((err) => {
+        this._status = 'aborted';
+        throw err;
+      });
+
+    return this._result;
+  }
+
+  private _applyEvent(event: RunEventPayload): void {
+    switch (event.type) {
+      case 'run_start':
+        this._runId = event.runId;
+        this._tasks.clear();
+        for (const t of event.tasks) this._tasks.set(t.taskId, { ...t });
+        return;
+      case 'task_update': {
+        const prev = this._tasks.get(event.taskId);
+        if (!prev) return;
+        const pick = <T>(incoming: T | undefined, previous: T): T =>
+          incoming !== undefined ? incoming : previous;
+        this._tasks.set(event.taskId, {
+          ...prev,
+          status: event.status,
+          startedAt: pick(event.startedAt, prev.startedAt),
+          finishedAt: pick(event.finishedAt, prev.finishedAt),
+          durationMs: pick(event.durationMs, prev.durationMs),
+          exitCode: pick(event.exitCode, prev.exitCode),
+          stdout: pick(event.stdout, prev.stdout),
+          stderr: pick(event.stderr, prev.stderr),
+          stderrPath: pick(event.stderrPath, prev.stderrPath),
+          sessionId: pick(event.sessionId, prev.sessionId),
+          normalizedOutput: pick(event.normalizedOutput, prev.normalizedOutput),
+          resolvedDriver: pick(event.resolvedDriver, prev.resolvedDriver),
+          resolvedModel: pick(event.resolvedModel, prev.resolvedModel),
+          resolvedPermissions: pick(event.resolvedPermissions, prev.resolvedPermissions),
+        });
+        return;
+      }
+      case 'run_end':
+        this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
+        return;
+      default:
+        return;
+    }
+  }
+
+  /**
+   * Cancel the running pipeline. Safe to call multiple times or before start().
+   */
+  abort(reason?: string): void {
+    this._status = 'aborted';
+    this._abortController.abort(reason);
+  }
+
+  /**
+   * Live snapshot of wire-shape task states. Populated from the first
+   * `run_start` event onward. Returns an empty map before the run starts.
+   */
+  getTasks(): ReadonlyMap<string, RunTaskState> {
+    const copy = new Map<string, RunTaskState>();
+    for (const [id, t] of this._tasks) copy.set(id, { ...t });
+    return copy;
+  }
+
+  /**
+   * Subscribe to run events. Returns an unsubscribe function. Events are
+   * emitted synchronously in the engine's event loop, so keep handlers
+   * non-blocking (e.g. queue to IPC, do not await inside).
+   */
+  subscribe(handler: (event: RunEventPayload) => void): () => void {
+    this._handlers.add(handler);
+    return () => this._handlers.delete(handler);
+  }
+}

package/src/plugin-registry.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, test } from 'bun:test';
+import { PluginRegistry, defaultRegistry } from './registry';
+import { bootstrapBuiltins } from './bootstrap';
+import { runPipeline } from './engine';
+import type { DriverPlugin, TriggerPlugin, PipelineConfig } from './types';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function makeDriver(name: string, marker: string[]): DriverPlugin {
+  return {
+    name,
+    capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false },
+    async buildCommand() {
+      marker.push(`buildCommand:${name}`);
+      return { args: ['echo', 'noop'] };
+    },
+  };
+}
+
+function makeTrigger(name: string, marker: string[]): TriggerPlugin {
+  return {
+    name,
+    async watch() {
+      marker.push(`watch:${name}`);
+    },
+  };
+}
+
+describe('PluginRegistry — instance isolation', () => {
+  test('two registries do not share drivers registered under the same type', () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    const markerA: string[] = [];
+    const markerB: string[] = [];
+
+    regA.registerPlugin('drivers', 'mock', makeDriver('mockA', markerA));
+    regB.registerPlugin('drivers', 'mock', makeDriver('mockB', markerB));
+
+    expect(regA.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('mockA');
+    expect(regB.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('mockB');
+
+    expect(regA.hasHandler('drivers', 'mock')).toBe(true);
+    expect(regB.hasHandler('drivers', 'mock')).toBe(true);
+    expect(regA.hasHandler('triggers', 'mock')).toBe(false);
+  });
+
+  test('unregistering in one registry does not affect the other', () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    regA.registerPlugin('drivers', 'mock', makeDriver('mockA', []));
+    regB.registerPlugin('drivers', 'mock', makeDriver('mockB', []));
+
+    expect(regA.unregisterPlugin('drivers', 'mock')).toBe(true);
+    expect(regA.hasHandler('drivers', 'mock')).toBe(false);
+    expect(regB.hasHandler('drivers', 'mock')).toBe(true);
+  });
+
+  test('listRegistered is scoped per instance', () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    regA.registerPlugin('triggers', 'a-only', makeTrigger('a-only', []));
+    regB.registerPlugin('triggers', 'b-only', makeTrigger('b-only', []));
+
+    expect(regA.listRegistered('triggers')).toEqual(['a-only']);
+    expect(regB.listRegistered('triggers')).toEqual(['b-only']);
+  });
+
+  test('registering the same instance twice returns unchanged', () => {
+    const reg = new PluginRegistry();
+    const driver = makeDriver('same', []);
+    expect(reg.registerPlugin('drivers', 'mock', driver)).toBe('registered');
+    expect(reg.registerPlugin('drivers', 'mock', driver)).toBe('unchanged');
+  });
+
+  test('replacing with a different handler returns replaced', () => {
+    const reg = new PluginRegistry();
+    expect(reg.registerPlugin('drivers', 'mock', makeDriver('one', []))).toBe('registered');
+    expect(reg.registerPlugin('drivers', 'mock', makeDriver('two', []))).toBe('replaced');
+    expect(reg.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('two');
+  });
+
+  test('bootstrapBuiltins(target) populates a specific instance without touching the default', () => {
+    const fresh = new PluginRegistry();
+    expect(fresh.hasHandler('drivers', 'opencode')).toBe(false);
+
+    bootstrapBuiltins(fresh);
+
+    expect(fresh.hasHandler('drivers', 'opencode')).toBe(true);
+    expect(fresh.hasHandler('triggers', 'file')).toBe(true);
+    expect(fresh.hasHandler('triggers', 'manual')).toBe(true);
+    expect(fresh.hasHandler('completions', 'exit_code')).toBe(true);
+    expect(fresh.hasHandler('middlewares', 'static_context')).toBe(true);
+
+    // Default registry's state is independent of `fresh` — if the default
+    // happens to have opencode (because another test bootstrapped it), that
+    // is fine; the guarantee is that `fresh.unregister` does not leak.
+    fresh.unregisterPlugin('drivers', 'opencode');
+    expect(fresh.hasHandler('drivers', 'opencode')).toBe(false);
+  });
+});
+
+describe('PluginRegistry — validation', () => {
+  test('rejects unknown category', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'nope' as 'drivers',
+        'x',
+        makeDriver('x', []),
+      ),
+    ).toThrow(/Unknown plugin category/);
+  });
+
+  test('rejects driver missing buildCommand', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'drivers',
+        'broken',
+        // deliberately bad: no buildCommand
+        { name: 'broken', capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false } } as unknown as DriverPlugin,
+      ),
+    ).toThrow(/must export buildCommand/);
+  });
+
+  test('rejects handler with missing name', () => {
+    const reg = new PluginRegistry();
+    expect(() =>
+      reg.registerPlugin(
+        'drivers',
+        'x',
+        // deliberately bad: no name
+        { capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false }, buildCommand: async () => ({ args: [] }) } as unknown as DriverPlugin,
+      ),
+    ).toThrow(/non-empty "name"/);
+  });
+});
+
+describe('runPipeline — options.registry isolation', () => {
+  test('concurrent runs with different registries see their own drivers', async () => {
+    const regA = new PluginRegistry();
+    const regB = new PluginRegistry();
+    const seenA: string[] = [];
+    const seenB: string[] = [];
+
+    bootstrapBuiltins(regA);
+    bootstrapBuiltins(regB);
+
+    regA.registerPlugin('drivers', 'mock', makeDriver('mockA', seenA));
+    regB.registerPlugin('drivers', 'mock', makeDriver('mockB', seenB));
+
+    // Command-only pipeline exercises the preflight path (which uses the
+    // registry) plus the run-loop path without requiring a real driver
+    // invocation. We verify isolation by asserting that preflight with a
+    // registry missing `mock` rejects, while the matching registry accepts.
+    const config: PipelineConfig = {
+      name: 'isolation-test',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [{ id: 'only', name: 'only', command: 'echo hi' }],
+        },
+      ],
+    };
+
+    const tmpA = mkdtempSync(join(tmpdir(), 'tagma-regA-'));
+    const tmpB = mkdtempSync(join(tmpdir(), 'tagma-regB-'));
+    try {
+      const [resA, resB] = await Promise.all([
+        runPipeline(config, tmpA, { registry: regA, skipPluginLoading: true }),
+        runPipeline(config, tmpB, { registry: regB, skipPluginLoading: true }),
+      ]);
+      expect(resA.success).toBe(true);
+      expect(resB.success).toBe(true);
+      expect(resA.runId).not.toBe(resB.runId);
+    } finally {
+      rmSync(tmpA, { recursive: true, force: true });
+      rmSync(tmpB, { recursive: true, force: true });
+    }
+  });
+
+  test('preflight fails when referenced driver is missing from the passed registry', async () => {
+    const regNoOpencode = new PluginRegistry();
+    // Deliberately do NOT bootstrap builtins — opencode is not registered.
+    const config: PipelineConfig = {
+      name: 'preflight-miss',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [{ id: 'x', name: 'x', prompt: 'hello' }],
+        },
+      ],
+    };
+    const tmp = mkdtempSync(join(tmpdir(), 'tagma-miss-'));
+    try {
+      await expect(
+        runPipeline(config, tmp, { registry: regNoOpencode, skipPluginLoading: true }),
+      ).rejects.toThrow(/driver "opencode" not registered/);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('omitting options.registry falls back to defaultRegistry', async () => {
+    // bootstrapBuiltins into default happens in most host callers; do it
+    // explicitly here so the test is independent of module-load order.
+    bootstrapBuiltins(defaultRegistry);
+
+    const config: PipelineConfig = {
+      name: 'default-fallback',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [{ id: 'only', name: 'only', command: 'echo hi' }],
+        },
+      ],
+    };
+    const tmp = mkdtempSync(join(tmpdir(), 'tagma-default-'));
+    try {
+      const res = await runPipeline(config, tmp, { skipPluginLoading: true });
+      expect(res.success).toBe(true);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/src/prompt-doc.ts

@@ -1,49 +1,49 @@
-import type { PromptDocument, PromptContextBlock } from './types';
-
-/**
- * Build a fresh `PromptDocument` from a raw task string.
- * Middlewares receive this from the engine and push context blocks onto
- * `contexts`. `task` is the user's original prompt and should not be
- * rewritten by middlewares (translation middlewares are the rare exception).
- */
-export function promptDocumentFromString(task: string): PromptDocument {
-  return { contexts: [], task };
-}
-
-/**
- * Serialize a `PromptDocument` to the default string form consumed by
- * drivers that read `task.prompt` instead of `ctx.promptDoc`.
- *
- * Format:
- *
- *     [<label1>]
- *     <content1>
- *
- *     [<label2>]
- *     <content2>
- *
- *     <task>
- *
- * Each context block is separated from the next (and from `task`) by a
- * single blank line. No implicit `[Task]` header is emitted — that framing
- * is the driver's responsibility (e.g. opencode's `agent_profile` wrapping).
- * Emitting one here would compose incorrectly with any driver that also
- * adds a `[Task]` header, producing a double header that some models
- * (observed with `opencode/big-pickle`) misread as a cut-off message.
- */
-export function serializePromptDocument(doc: PromptDocument): string {
-  if (doc.contexts.length === 0) return doc.task;
-  const blocks = doc.contexts.map((c) => `[${c.label}]\n${c.content}`);
-  return `${blocks.join('\n\n')}\n\n${doc.task}`;
-}
-
-/**
- * Helper for middlewares: return a new document with the given block
- * appended to `contexts`, preserving immutability of `doc`.
- */
-export function appendContext(
-  doc: PromptDocument,
-  block: PromptContextBlock,
-): PromptDocument {
-  return { contexts: [...doc.contexts, block], task: doc.task };
-}
+import type { PromptDocument, PromptContextBlock } from './types';
+
+/**
+ * Build a fresh `PromptDocument` from a raw task string.
+ * Middlewares receive this from the engine and push context blocks onto
+ * `contexts`. `task` is the user's original prompt and should not be
+ * rewritten by middlewares (translation middlewares are the rare exception).
+ */
+export function promptDocumentFromString(task: string): PromptDocument {
+  return { contexts: [], task };
+}
+
+/**
+ * Serialize a `PromptDocument` to the default string form consumed by
+ * drivers that read `task.prompt` instead of `ctx.promptDoc`.
+ *
+ * Format:
+ *
+ *     [<label1>]
+ *     <content1>
+ *
+ *     [<label2>]
+ *     <content2>
+ *
+ *     <task>
+ *
+ * Each context block is separated from the next (and from `task`) by a
+ * single blank line. No implicit `[Task]` header is emitted — that framing
+ * is the driver's responsibility (e.g. opencode's `agent_profile` wrapping).
+ * Emitting one here would compose incorrectly with any driver that also
+ * adds a `[Task]` header, producing a double header that some models
+ * (observed with `opencode/big-pickle`) misread as a cut-off message.
+ */
+export function serializePromptDocument(doc: PromptDocument): string {
+  if (doc.contexts.length === 0) return doc.task;
+  const blocks = doc.contexts.map((c) => `[${c.label}]\n${c.content}`);
+  return `${blocks.join('\n\n')}\n\n${doc.task}`;
+}
+
+/**
+ * Helper for middlewares: return a new document with the given block
+ * appended to `contexts`, preserving immutability of `doc`.
+ */
+export function appendContext(
+  doc: PromptDocument,
+  block: PromptContextBlock,
+): PromptDocument {
+  return { contexts: [...doc.contexts, block], task: doc.task };
+}