@tagma/sdk 0.6.0 → 0.6.1

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/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 };
+}