@tagma/sdk 0.7.3 → 0.7.4

package/src/adapters/websocket-approval.ts

@@ -1,224 +1 @@
-import type { ApprovalGateway, ApprovalEvent } from '../approval';
-
-// ═══ WebSocket Approval Adapter ═══
-//
-// Bridges the ApprovalGateway to WebSocket clients (e.g. a frontend UI).
-// Mirrors the stdin-approval adapter pattern: subscribe to gateway events,
-// forward them as JSON to all connected clients, and call gateway.resolve()
-// when a client sends a resolution message.
-//
-// Protocol — server → client:
-//   { type: 'pending',             requests: ApprovalRequest[] }   ← sent on connect
-//   { type: 'approval_requested',  request:  ApprovalRequest }
-//   { type: 'approval_resolved',   request:  ApprovalRequest, decision: ApprovalDecision }
-//   { type: 'approval_expired',    request:  ApprovalRequest }
-//   { type: 'approval_aborted',    request:  ApprovalRequest, reason: string }
-//
-// Protocol — client → server:
-//   { type: 'resolve', approvalId: string, outcome: 'approved'|'rejected',
-//     actor?: string, reason?: string }
-
-export interface WebSocketApprovalAdapterOptions {
-  port?: number; // default: 3000
-  hostname?: string; // default: 'localhost'
-  /**
-   * M11: shared secret required from the client during the WebSocket
-   * upgrade. The token can be supplied either as the `?token=` query
-   * parameter or in the `x-tagma-token` request header. When set, any
-   * upgrade request that fails the check is rejected with HTTP 401 and
-   * never reaches the WebSocket layer (so a misconfigured client cannot
-   * exhaust rate-limit slots either). Leave undefined for backward
-   * compatibility with localhost-only deployments.
-   */
-  token?: string;
-  /**
-   * M11: opt-out of origin checking. Defaults to false, meaning Origin
-   * headers are restricted to loopback hosts (localhost / 127.0.0.1 / ::1).
-   * Requests without an Origin header are still allowed so non-browser local
-   * clients can connect. Set true only for trusted reverse-proxy setups.
-   */
-  allowAnyOrigin?: boolean;
-}
-
-export interface WebSocketApprovalAdapter {
-  readonly port: number;
-  readonly detach: () => void;
-}
-
-// Maximum allowed message payload (bytes) to prevent DoS via oversized messages.
-const MAX_PAYLOAD_BYTES = 4_096;
-// Per-client rate limit: at most this many messages per window.
-const RATE_LIMIT_MAX = 10;
-const RATE_LIMIT_WINDOW_MS = 1_000;
-
-export function attachWebSocketApprovalAdapter(
-  gateway: ApprovalGateway,
-  options: WebSocketApprovalAdapterOptions = {},
-): WebSocketApprovalAdapter {
-  const port = options.port ?? 3000;
-  const hostname = options.hostname ?? 'localhost';
-  const requiredToken = options.token ?? null;
-  const enforceOriginCheck = options.allowAnyOrigin !== true;
-
-  function isLoopbackOrigin(origin: string): boolean {
-    try {
-      const host = new URL(origin).hostname.toLowerCase();
-      return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '[::1]';
-    } catch {
-      return false;
-    }
-  }
-
-  type WS = import('bun').ServerWebSocket<unknown>;
-  const clients = new Set<WS>();
-  const clientRates = new Map<WS, { count: number; resetAt: number }>();
-
-  function broadcast(msg: unknown): void {
-    const text = JSON.stringify(msg);
-    for (const ws of clients) {
-      ws.send(text);
-    }
-  }
-
-  const unsubscribe = gateway.subscribe((event: ApprovalEvent) => {
-    switch (event.type) {
-      case 'requested':
-        broadcast({ type: 'approval_requested', request: event.request });
-        break;
-      case 'resolved':
-        broadcast({ type: 'approval_resolved', request: event.request, decision: event.decision });
-        break;
-      case 'expired':
-        broadcast({ type: 'approval_expired', request: event.request });
-        break;
-      case 'aborted':
-        broadcast({ type: 'approval_aborted', request: event.request, reason: event.reason });
-        break;
-    }
-  });
-
-  const server = Bun.serve({
-    port,
-    hostname,
-
-    fetch(req, server) {
-      if (enforceOriginCheck) {
-        const origin = req.headers.get('origin');
-        if (origin && !isLoopbackOrigin(origin)) {
-          return new Response('forbidden origin', { status: 403 });
-        }
-      }
-      // M11: enforce token before any upgrade so an unauthenticated client
-      // can't even open a socket. Tokens may arrive via header or query.
-      if (requiredToken !== null) {
-        const headerToken = req.headers.get('x-tagma-token') ?? '';
-        let queryToken = '';
-        try {
-          queryToken = new URL(req.url).searchParams.get('token') ?? '';
-        } catch {
-          /* malformed URL — leave queryToken empty */
-        }
-        const presented = headerToken || queryToken;
-        if (presented !== requiredToken) {
-          return new Response('unauthorized', { status: 401 });
-        }
-      }
-      if (server.upgrade(req)) return undefined;
-      return new Response('tagma-sdk WebSocket approval endpoint', { status: 426 });
-    },
-
-    websocket: {
-      open(ws) {
-        clients.add(ws);
-        // Sync current pending approvals to newly connected client.
-        ws.send(JSON.stringify({ type: 'pending', requests: gateway.pending() }));
-      },
-
-      message(ws, raw) {
-        const rawStr = typeof raw === 'string' ? raw : raw.toString();
-
-        // Payload size guard — reject oversized messages before parsing.
-        if (rawStr.length > MAX_PAYLOAD_BYTES) {
-          ws.send(JSON.stringify({ type: 'error', message: 'message too large' }));
-          return;
-        }
-
-        // Per-client rate limit.
-        const now = Date.now();
-        const rate = clientRates.get(ws) ?? { count: 0, resetAt: now + RATE_LIMIT_WINDOW_MS };
-        if (now >= rate.resetAt) {
-          rate.count = 0;
-          rate.resetAt = now + RATE_LIMIT_WINDOW_MS;
-        }
-        rate.count++;
-        clientRates.set(ws, rate);
-        if (rate.count > RATE_LIMIT_MAX) {
-          ws.send(JSON.stringify({ type: 'error', message: 'rate limit exceeded' }));
-          return;
-        }
-
-        let msg: unknown;
-        try {
-          msg = JSON.parse(rawStr);
-        } catch {
-          ws.send(JSON.stringify({ type: 'error', message: 'invalid JSON' }));
-          return;
-        }
-
-        if (!isResolveMessage(msg)) {
-          ws.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
-          return;
-        }
-
-        const ok = gateway.resolve(msg.approvalId, {
-          outcome: msg.outcome,
-          actor: msg.actor ?? 'websocket',
-          reason: msg.reason,
-        });
-
-        if (!ok) {
-          ws.send(
-            JSON.stringify({
-              type: 'error',
-              message: `approval ${msg.approvalId} not found or already resolved`,
-            }),
-          );
-        }
-      },
-
-      close(ws) {
-        clients.delete(ws);
-        clientRates.delete(ws);
-      },
-    },
-  });
-
-  return {
-    port: server.port!,
-    detach() {
-      unsubscribe();
-      clients.clear();
-      server.stop(true);
-    },
-  };
-}
-
-// ── Type guard ──
-
-interface ResolveMessage {
-  type: 'resolve';
-  approvalId: string;
-  outcome: 'approved' | 'rejected';
-  actor?: string;
-  reason?: string;
-}
-
-function isResolveMessage(v: unknown): v is ResolveMessage {
-  if (typeof v !== 'object' || v === null) return false;
-  const m = v as Record<string, unknown>;
-  return (
-    m['type'] === 'resolve' &&
-    typeof m['approvalId'] === 'string' &&
-    (m['outcome'] === 'approved' || m['outcome'] === 'rejected')
-  );
-}
+export * from '../runtime/adapters/websocket-approval';

package/src/approval.ts

@@ -1,131 +1,9 @@
-import { randomUUID } from 'crypto';
-import { nowISO } from './utils';
-
-// Approval types (ApprovalRequest, ApprovalDecision, ApprovalOutcome,
-// ApprovalEvent, ApprovalListener, ApprovalGateway) live in the shared
-// @tagma/types package so trigger plugins can import them without
-// depending on the engine's runtime implementation. This module keeps
-// only the in-memory implementation. Internal SDK imports go through
-// ./types (the engine-side re-export) for consistency with the rest of
-// the SDK source.
-import type {
-  ApprovalRequest,
-  ApprovalDecision,
-  ApprovalEvent,
-  ApprovalListener,
-  ApprovalGateway,
-} from './types';
-
-// Re-export for existing engine-side consumers that import from this file.
+export { InMemoryApprovalGateway } from '@tagma/core';
 export type {
-  ApprovalRequest,
   ApprovalDecision,
-  ApprovalOutcome,
   ApprovalEvent,
-  ApprovalListener,
   ApprovalGateway,
-} from './types';
-
-// ═══ Default In-Memory Implementation ═══
-
-interface PendingEntry {
-  readonly request: ApprovalRequest;
-  readonly settle: (decision: ApprovalDecision) => void;
-  readonly timer: ReturnType<typeof setTimeout> | null;
-}
-
-export class InMemoryApprovalGateway implements ApprovalGateway {
-  private readonly pendingMap = new Map<string, PendingEntry>();
-  private readonly listeners = new Set<ApprovalListener>();
-
-  request(req: Omit<ApprovalRequest, 'id' | 'createdAt'>): Promise<ApprovalDecision> {
-    const full: ApprovalRequest = {
-      id: randomUUID(),
-      createdAt: nowISO(),
-      taskId: req.taskId,
-      trackId: req.trackId,
-      message: req.message,
-      timeoutMs: req.timeoutMs,
-      metadata: req.metadata,
-    };
-
-    return new Promise<ApprovalDecision>((resolvePromise) => {
-      let timer: ReturnType<typeof setTimeout> | null = null;
-      if (full.timeoutMs > 0) {
-        timer = setTimeout(() => {
-          const entry = this.pendingMap.get(full.id);
-          if (!entry) return;
-          this.pendingMap.delete(full.id);
-          const decision: ApprovalDecision = {
-            approvalId: full.id,
-            outcome: 'timeout',
-            reason: `Approval timed out after ${full.timeoutMs}ms`,
-            decidedAt: nowISO(),
-          };
-          this.emit({ type: 'expired', request: full });
-          resolvePromise(decision);
-        }, full.timeoutMs);
-      }
-
-      this.pendingMap.set(full.id, { request: full, settle: resolvePromise, timer });
-      this.emit({ type: 'requested', request: full });
-    });
-  }
-
-  resolve(
-    approvalId: string,
-    decision: Omit<ApprovalDecision, 'approvalId' | 'decidedAt'>,
-  ): boolean {
-    const entry = this.pendingMap.get(approvalId);
-    if (!entry) return false;
-    this.pendingMap.delete(approvalId);
-    if (entry.timer) clearTimeout(entry.timer);
-
-    const full: ApprovalDecision = {
-      approvalId,
-      outcome: decision.outcome,
-      actor: decision.actor,
-      reason: decision.reason,
-      decidedAt: nowISO(),
-    };
-    this.emit({ type: 'resolved', request: entry.request, decision: full });
-    entry.settle(full);
-    return true;
-  }
-
-  pending(): readonly ApprovalRequest[] {
-    return Array.from(this.pendingMap.values()).map((e) => e.request);
-  }
-
-  subscribe(listener: ApprovalListener): () => void {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-
-  abortAll(reason: string): void {
-    const entries = Array.from(this.pendingMap.entries());
-    this.pendingMap.clear();
-    for (const [id, entry] of entries) {
-      if (entry.timer) clearTimeout(entry.timer);
-      this.emit({ type: 'aborted', request: entry.request, reason });
-      entry.settle({
-        approvalId: id,
-        outcome: 'aborted',
-        reason,
-        decidedAt: nowISO(),
-      });
-    }
-  }
-
-  private emit(event: ApprovalEvent): void {
-    for (const listener of this.listeners) {
-      try {
-        listener(event);
-      } catch (err) {
-        console.error('[approval gateway] listener error:', err);
-      }
-    }
-  }
-}
+  ApprovalListener,
+  ApprovalOutcome,
+  ApprovalRequest,
+} from '@tagma/core';

package/src/bootstrap.ts

@@ -1,4 +1,4 @@
-import type { PluginRegistry } from './registry';
+import type { PluginRegistry } from '@tagma/core';
 import type { TagmaPlugin } from './types';
 
 // Built-in Drivers

package/src/core/run-context.test.ts

@@ -12,6 +12,41 @@ const fakeRuntime: TagmaRuntime = {
   async runSpawn() {
     throw new Error('fakeRuntime.runSpawn should not be called by RunContext tests');
   },
+  async ensureDir() {
+    /* no-op */
+  },
+  async fileExists() {
+    return false;
+  },
+  async *watch() {
+    /* no-op */
+  },
+  logStore: {
+    openRunLog() {
+      return {
+        path: 'mem://pipeline.log',
+        dir: 'mem://run',
+        append() {
+          /* no-op */
+        },
+        close() {
+          /* no-op */
+        },
+      };
+    },
+    taskOutputPath({ taskId, stream }) {
+      return `mem://${taskId}.${stream}`;
+    },
+    logsDir() {
+      return 'mem://logs';
+    },
+  },
+  now() {
+    return new Date('2026-04-26T00:00:00.000Z');
+  },
+  sleep() {
+    return Promise.resolve();
+  },
 };
 
 function makeContext(overrides: Partial<{

package/src/core/task-executor.ts

@@ -1,4 +1,3 @@
-import { resolve } from 'path';
 import type {
   CompletionPlugin,
   DriverContext,
@@ -136,6 +135,7 @@ export async function executeTask(options: ExecuteTaskOptions): Promise<void> {
             workDir: task.cwd ?? workDir,
             signal: ctx.abortController.signal,
             approvalGateway,
+            runtime: ctx.runtime,
           })
           .then(
             (v) => {
@@ -395,9 +395,18 @@ export async function executeTask(options: ExecuteTaskOptions): Promise<void> {
     // and keep only a bounded tail in the returned TaskResult. Filenames
     // mirror the existing `.stderr` naming — dots in task ids are replaced
     // so hierarchical ids (e.g. `track1.task2`) map cleanly to a flat dir.
-    const fsSafeTaskId = taskId.replace(/\./g, '_');
-    const stdoutPath = resolve(log.dir, `${fsSafeTaskId}.stdout`);
-    const stderrPath = resolve(log.dir, `${fsSafeTaskId}.stderr`);
+    const stdoutPath = ctx.runtime.logStore.taskOutputPath({
+      workDir,
+      runId: ctx.runId,
+      taskId,
+      stream: 'stdout',
+    });
+    const stderrPath = ctx.runtime.logStore.taskOutputPath({
+      workDir,
+      runId: ctx.runId,
+      taskId,
+      stream: 'stderr',
+    });
     const runOpts = {
       timeoutMs,
       signal: ctx.abortController.signal,

package/src/engine-ports-mixed.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { bootstrapBuiltins } from './bootstrap';
 import { runPipeline, type RunEventPayload } from './engine';
 import { PluginRegistry } from './registry';
-import type { DriverPlugin, PipelineConfig, TaskConfig } from './types';
+import type { DriverPlugin, PipelineConfig, TagmaRuntime, TaskConfig, TaskResult } from './types';
 
 const PERMS = { read: true, write: false, execute: false };
 
@@ -13,40 +13,7 @@ function makeDir(): string {
   return mkdtempSync(join(tmpdir(), 'tagma-bindings-mixed-'));
 }
 
-function writeEmitScript(dir: string, name: string, payload: Record<string, unknown>): string {
-  const path = join(dir, `${name}.js`);
-  writeFileSync(
-    path,
-    `process.stdout.write(${JSON.stringify(JSON.stringify(payload))});\nprocess.stdout.write('\\n');\n`,
-  );
-  return path;
-}
-
-function writeEchoArgsScript(dir: string): string {
-  const path = join(dir, 'echo.js');
-  writeFileSync(path, `process.stdout.write(process.argv.slice(2).join('|'));\n`);
-  return path;
-}
-
-function writeMockDriverScript(dir: string): string {
-  const path = join(dir, 'mock-driver.js');
-  writeFileSync(
-    path,
-    [
-      `const fs = require('fs');`,
-      `let buf = '';`,
-      `process.stdin.setEncoding('utf8');`,
-      `process.stdin.on('data', (c) => { buf += c; });`,
-      `process.stdin.on('end', () => {`,
-      `  fs.writeFileSync(process.env.MOCK_RECORD_PATH, buf);`,
-      `  process.stdout.write(process.env.MOCK_RESPONSE + '\\n');`,
-      `});`,
-    ].join('\n'),
-  );
-  return path;
-}
-
-function registry(script: string, responses: Record<string, Record<string, unknown>>, records: Record<string, string>) {
+function registry(responses: Record<string, Record<string, unknown>>, records: Record<string, string>) {
   const reg = new PluginRegistry();
   bootstrapBuiltins(reg);
   const driver: DriverPlugin = {
@@ -54,7 +21,7 @@ function registry(script: string, responses: Record<string, Record<string, unkno
     capabilities: { sessionResume: false, systemPrompt: true, outputFormat: true },
     async buildCommand(task) {
       return {
-        args: ['node', script],
+        args: ['mock-driver', task.id],
         stdin: task.prompt ?? '',
         env: {
           MOCK_RESPONSE: JSON.stringify(responses[task.id] ?? {}),
@@ -85,12 +52,75 @@ async function run(config: PipelineConfig, workDir: string, reg: PluginRegistry)
   const events: RunEventPayload[] = [];
   const result = await runPipeline(config, workDir, {
     registry: reg,
+    runtime: fakeRuntime(),
     skipPluginLoading: true,
     onEvent: (e) => events.push(e),
   });
   return { events, success: result.success };
 }
 
+function taskResult(stdout: string, normalizedOutput: string | null = null): TaskResult {
+  return {
+    exitCode: 0,
+    stdout,
+    stderr: '',
+    stdoutPath: null,
+    stderrPath: null,
+    stdoutBytes: stdout.length,
+    stderrBytes: 0,
+    durationMs: 1,
+    sessionId: null,
+    normalizedOutput,
+    failureKind: null,
+  };
+}
+
+function fakeRuntime(): TagmaRuntime {
+  return {
+    async runCommand(command) {
+      if (command.startsWith('emit-city')) return taskResult('{"city":"Berlin"}\n');
+      return taskResult('ok\n');
+    },
+    async runSpawn(spec) {
+      const response = spec.env?.['MOCK_RESPONSE'] ?? '{}';
+      const recordPath = spec.env?.['MOCK_RECORD_PATH'];
+      if (recordPath) writeFileSync(recordPath, spec.stdin ?? '');
+      return taskResult(response + '\n', response);
+    },
+    async ensureDir() {
+      /* no-op */
+    },
+    async fileExists() {
+      return false;
+    },
+    async *watch() {
+      /* no-op */
+    },
+    logStore: {
+      openRunLog({ runId }) {
+        return {
+          path: `mem://${runId}/pipeline.log`,
+          dir: `mem://${runId}`,
+          append() {
+            /* memory sink */
+          },
+          close() {
+            /* memory sink */
+          },
+        };
+      },
+      taskOutputPath({ runId, taskId, stream }) {
+        return `mem://${runId}/${taskId}.${stream}`;
+      },
+      logsDir() {
+        return 'mem://logs';
+      },
+    },
+    now: () => new Date('2026-04-26T00:00:00.000Z'),
+    sleep: () => Promise.resolve(),
+  };
+}
+
 function finalUpdateFor(events: RunEventPayload[], qid: string): RunEventPayload | undefined {
   let last: RunEventPayload | undefined;
   for (const ev of events) {
@@ -103,17 +133,15 @@ describe('engine — mixed prompt/command unified bindings', () => {
   test('prompt outputs are inferred from downstream command inputs', async () => {
     const dir = makeDir();
     try {
-      const driverScript = writeMockDriverScript(dir);
-      const echo = writeEchoArgsScript(dir);
       const record = join(dir, 'prompt.txt');
-      const reg = registry(driverScript, { plan: { city: 'Paris' } }, { plan: record });
+      const reg = registry({ plan: { city: 'Paris' } }, { plan: record });
       const config = pipeline([
         task({ id: 'plan', prompt: 'Pick a city' }),
         task({
           id: 'fetch',
           driver: 'opencode',
           depends_on: ['plan'],
-          command: `node "${echo}" "{{inputs.city}}"`,
+          command: 'echo-city "{{inputs.city}}"',
           inputs: { city: { from: 't.plan.outputs.city', type: 'string', required: true } },
         }),
       ]);
@@ -131,15 +159,13 @@ describe('engine — mixed prompt/command unified bindings', () => {
   test('prompt inputs are inferred from upstream command outputs', async () => {
     const dir = makeDir();
     try {
-      const emit = writeEmitScript(dir, 'emit', { city: 'Berlin' });
-      const driverScript = writeMockDriverScript(dir);
       const record = join(dir, 'prompt.txt');
-      const reg = registry(driverScript, { summarize: {} }, { summarize: record });
+      const reg = registry({ summarize: {} }, { summarize: record });
       const config = pipeline([
         task({
           id: 'up',
           driver: 'opencode',
-          command: `node "${emit}"`,
+          command: 'emit-city',
           outputs: { city: { type: 'string' } },
         }),
         task({ id: 'summarize', depends_on: ['up'], prompt: 'City is {{inputs.city}}' }),