@tagma/sdk 0.4.14 → 0.4.16

package/src/pipeline-runner.ts

@@ -1,156 +1,156 @@
-// ═══ PipelineRunner ═══
-//
-// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
-// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
-//
-// Typical sidecar usage:
-//
-//   const runners = new Map<string, PipelineRunner>();
-//
-//   const runner = new PipelineRunner(config, workDir);
-//   runner.subscribe(event => ipcEmit('pipeline_event', event));
-//   runner.start();
-//   runners.set(runner.instanceId, runner);
-//
-//   // Later, from IPC:
-//   runners.get(id)?.abort();
-
-import { runPipeline } from './engine';
-import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
-import type { PipelineConfig, TaskState } from './types';
-import { generateRunId } from './utils';
-
-export type { PipelineEvent, EngineResult };
-
-export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
-
-export class PipelineRunner {
-  /**
-   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
-   * before the engine-assigned runId becomes available.
-   */
-  readonly instanceId: string;
-
-  /**
-   * The runId generated by the engine. Available after the first 'pipeline_start'
-   * event fires (i.e. effectively immediately after start() is called).
-   * 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: PipelineEvent) => void>();
-  private _states: ReadonlyMap<string, TaskState> | null = null;
-  private _statesMirror = new Map<string, TaskState>();
-
-  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) => {
-        if (event.type === 'pipeline_start') {
-          this._runId = event.runId;
-          // Initialize the live mirror with the full initial state snapshot
-          for (const [id, state] of event.states) {
-            this._statesMirror.set(id, { ...state });
-          }
-        }
-        if (event.type === 'task_status_change') {
-          // Keep the mirror up to date so getStates() works during the run
-          this._statesMirror.set(event.taskId, event.state);
-        }
-        if (event.type === 'pipeline_end') {
-          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
-        }
-        for (const h of this._handlers) h(event);
-      },
-    })
-      .then((result) => {
-        this._states = result.states;
-        if (this._status === 'running') this._status = 'done';
-        return result;
-      })
-      .catch((err) => {
-        this._status = 'aborted';
-        throw err;
-      });
-
-    return this._result;
-  }
-
-  /**
-   * 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 task states. Available from the first pipeline_start event onward
-   * (i.e. as soon as start() is called) and remains accessible after the run completes.
-   * Returns null only if the pipeline has never started.
-   */
-  getStates(): ReadonlyMap<string, TaskState> | null {
-    if (this._states) return snapshotStates(this._states);
-    if (this._statesMirror.size > 0) return snapshotStates(this._statesMirror);
-    return null;
-  }
-
-  /**
-   * Subscribe to pipeline/task 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: PipelineEvent) => void): () => void {
-    this._handlers.add(handler);
-    return () => this._handlers.delete(handler);
-  }
-}
-
-/** Deep-copy a states map so callers cannot mutate SDK internals. */
-function snapshotStates(src: ReadonlyMap<string, TaskState>): ReadonlyMap<string, TaskState> {
-  const copy = new Map<string, TaskState>();
-  for (const [id, s] of src) {
-    copy.set(id, {
-      config: { ...s.config },
-      trackConfig: { ...s.trackConfig },
-      status: s.status,
-      result: s.result ? { ...s.result } : null,
-      startedAt: s.startedAt,
-      finishedAt: s.finishedAt,
-    });
-  }
-  return copy;
-}
+// ═══ PipelineRunner ═══
+//
+// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
+// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
+//
+// Typical sidecar usage:
+//
+//   const runners = new Map<string, PipelineRunner>();
+//
+//   const runner = new PipelineRunner(config, workDir);
+//   runner.subscribe(event => ipcEmit('pipeline_event', event));
+//   runner.start();
+//   runners.set(runner.instanceId, runner);
+//
+//   // Later, from IPC:
+//   runners.get(id)?.abort();
+
+import { runPipeline } from './engine';
+import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
+import type { PipelineConfig, TaskState } from './types';
+import { generateRunId } from './utils';
+
+export type { PipelineEvent, EngineResult };
+
+export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
+
+export class PipelineRunner {
+  /**
+   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
+   * before the engine-assigned runId becomes available.
+   */
+  readonly instanceId: string;
+
+  /**
+   * The runId generated by the engine. Available after the first 'pipeline_start'
+   * event fires (i.e. effectively immediately after start() is called).
+   * 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: PipelineEvent) => void>();
+  private _states: ReadonlyMap<string, TaskState> | null = null;
+  private _statesMirror = new Map<string, TaskState>();
+
+  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) => {
+        if (event.type === 'pipeline_start') {
+          this._runId = event.runId;
+          // Initialize the live mirror with the full initial state snapshot
+          for (const [id, state] of event.states) {
+            this._statesMirror.set(id, { ...state });
+          }
+        }
+        if (event.type === 'task_status_change') {
+          // Keep the mirror up to date so getStates() works during the run
+          this._statesMirror.set(event.taskId, event.state);
+        }
+        if (event.type === 'pipeline_end') {
+          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
+        }
+        for (const h of this._handlers) h(event);
+      },
+    })
+      .then((result) => {
+        this._states = result.states;
+        if (this._status === 'running') this._status = 'done';
+        return result;
+      })
+      .catch((err) => {
+        this._status = 'aborted';
+        throw err;
+      });
+
+    return this._result;
+  }
+
+  /**
+   * 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 task states. Available from the first pipeline_start event onward
+   * (i.e. as soon as start() is called) and remains accessible after the run completes.
+   * Returns null only if the pipeline has never started.
+   */
+  getStates(): ReadonlyMap<string, TaskState> | null {
+    if (this._states) return snapshotStates(this._states);
+    if (this._statesMirror.size > 0) return snapshotStates(this._statesMirror);
+    return null;
+  }
+
+  /**
+   * Subscribe to pipeline/task 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: PipelineEvent) => void): () => void {
+    this._handlers.add(handler);
+    return () => this._handlers.delete(handler);
+  }
+}
+
+/** Deep-copy a states map so callers cannot mutate SDK internals. */
+function snapshotStates(src: ReadonlyMap<string, TaskState>): ReadonlyMap<string, TaskState> {
+  const copy = new Map<string, TaskState>();
+  for (const [id, s] of src) {
+    copy.set(id, {
+      config: { ...s.config },
+      trackConfig: { ...s.trackConfig },
+      status: s.status,
+      result: s.result ? { ...s.result } : null,
+      startedAt: s.startedAt,
+      finishedAt: s.finishedAt,
+    });
+  }
+  return copy;
+}

package/src/prompt-doc.ts

@@ -0,0 +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 };
+}