@tagma/sdk 0.7.3 → 0.7.5

package/src/adapters/websocket-approval.ts

@@ -1,224 +0,0 @@
-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')
-  );
-}

package/src/approval.ts

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

package/src/bootstrap.ts

@@ -1,55 +0,0 @@
-import type { PluginRegistry } from './registry';
-import type { TagmaPlugin } from './types';
-
-// Built-in Drivers
-// Only opencode is built in. Other drivers (codex, claude-code) ship as
-// workspace plugins under packages/ and must be declared in pipeline.yaml
-// via the `plugins` field, e.g.:
-//   plugins: ["@tagma/driver-codex", "@tagma/driver-claude-code"]
-import { OpenCodeDriver } from './drivers/opencode';
-
-// Built-in Triggers
-import { FileTrigger } from './triggers/file';
-import { ManualTrigger } from './triggers/manual';
-
-// Built-in Completions
-import { ExitCodeCompletion } from './completions/exit-code';
-import { FileExistsCompletion } from './completions/file-exists';
-import { OutputCheckCompletion } from './completions/output-check';
-
-// Built-in Middleware
-import { StaticContextMiddleware } from './middlewares/static-context';
-
-export const BuiltinTagmaPlugin = {
-  name: '@tagma/sdk/builtins',
-  capabilities: {
-    drivers: {
-      opencode: OpenCodeDriver,
-    },
-    triggers: {
-      file: FileTrigger,
-      manual: ManualTrigger,
-    },
-    completions: {
-      exit_code: ExitCodeCompletion,
-      file_exists: FileExistsCompletion,
-      output_check: OutputCheckCompletion,
-    },
-    middlewares: {
-      static_context: StaticContextMiddleware,
-    },
-  },
-} satisfies TagmaPlugin;
-
-/**
- * Register every built-in plugin into `target`. Hosts instantiate one
- * PluginRegistry per workspace or SDK instance and call this once per
- * instance so each workspace sees the same built-ins without sharing
- * registration state.
- *
- * Built-in handlers are stateless module singletons — registering the same
- * handler object into N registries is cheap and safe; no cloning is needed.
- */
-export function bootstrapBuiltins(target: PluginRegistry): void {
-  target.registerTagmaPlugin(BuiltinTagmaPlugin);
-}

package/src/completions/exit-code.ts

@@ -1,34 +0,0 @@
-import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
-
-export const ExitCodeCompletion: CompletionPlugin = {
-  name: 'exit_code',
-  schema: {
-    description: 'Mark the task successful when the exit code matches.',
-    fields: {
-      expect: {
-        type: 'number-or-list',
-        default: 0,
-        description: 'Expected exit code, or list of acceptable codes (e.g. 0 or [0, 2]).',
-        placeholder: '0',
-      },
-    },
-  },
-
-  async check(
-    config: Record<string, unknown>,
-    result: TaskResult,
-    _ctx: CompletionContext,
-  ): Promise<boolean> {
-    const expected = config.expect ?? 0;
-
-    if (typeof expected === 'number') {
-      return result.exitCode === expected;
-    }
-    if (Array.isArray(expected) && expected.every((v) => typeof v === 'number')) {
-      return expected.includes(result.exitCode);
-    }
-    throw new Error(
-      `exit_code completion: "expect" must be a number or number[], got ${typeof expected}`,
-    );
-  },
-};

package/src/completions/file-exists.ts

@@ -1,66 +0,0 @@
-import { stat } from 'node:fs/promises';
-import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
-import { validatePath } from '../utils';
-
-type Kind = 'file' | 'dir' | 'any';
-
-export const FileExistsCompletion: CompletionPlugin = {
-  name: 'file_exists',
-  schema: {
-    description: 'Mark the task successful when a target file or directory exists.',
-    fields: {
-      path: {
-        type: 'path',
-        required: true,
-        description: 'Path to check (relative to workDir or absolute).',
-      },
-      kind: {
-        type: 'enum',
-        enum: ['file', 'dir', 'any'],
-        default: 'any',
-        description: 'Restrict to a file, directory, or accept either.',
-      },
-      min_size: {
-        type: 'number',
-        min: 0,
-        description: 'Optional minimum size in bytes (files only).',
-      },
-    },
-  },
-
-  async check(
-    config: Record<string, unknown>,
-    _result: TaskResult,
-    ctx: CompletionContext,
-  ): Promise<boolean> {
-    const filePath = config.path as string;
-    if (!filePath) throw new Error('file_exists completion: "path" is required');
-
-    const safePath = validatePath(filePath, ctx.workDir);
-
-    const kind = (config.kind as Kind | undefined) ?? 'any';
-    if (kind !== 'file' && kind !== 'dir' && kind !== 'any') {
-      throw new Error(
-        `file_exists completion: "kind" must be "file" | "dir" | "any", got "${kind}"`,
-      );
-    }
-
-    const minSize = config.min_size;
-    if (minSize != null && (typeof minSize !== 'number' || minSize < 0)) {
-      throw new Error(`file_exists completion: "min_size" must be a non-negative number`);
-    }
-
-    try {
-      const st = await stat(safePath);
-      if (kind === 'file' && !st.isFile()) return false;
-      if (kind === 'dir' && !st.isDirectory()) return false;
-      if (typeof minSize === 'number' && st.isFile() && st.size < minSize) return false;
-      return true;
-    } catch (err: unknown) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code === 'ENOENT' || code === 'ENOTDIR') return false;
-      // Permission / IO errors should surface, not silently mean "missing"
-      throw err;
-    }
-  },
-};

package/src/completions/output-check.test.ts

@@ -1,50 +0,0 @@
-import { expect, test } from 'bun:test';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { OutputCheckCompletion } from './output-check';
-import type { TaskResult } from '../types';
-
-function taskResult(stdout = 'payload'): TaskResult {
-  return {
-    exitCode: 0,
-    stdout,
-    stderr: '',
-    stdoutPath: null,
-    stderrPath: null,
-    stdoutBytes: stdout.length,
-    stderrBytes: 0,
-    durationMs: 0,
-    sessionId: null,
-    normalizedOutput: null,
-    failureKind: null,
-  };
-}
-
-test(
-  'output_check drains verbose check stdout so the check process can exit',
-  async () => {
-    const dir = mkdtempSync(join(tmpdir(), 'tagma-output-check-'));
-    try {
-      const script = join(dir, 'verbose-check.js');
-      writeFileSync(
-        script,
-        'process.stdout.write("x".repeat(16 * 1024 * 1024));\n',
-      );
-
-      const passed = await OutputCheckCompletion.check(
-        {
-          check: `node "${script}"`,
-          timeout: '1s',
-        },
-        taskResult(),
-        { workDir: dir, signal: new AbortController().signal },
-      );
-
-      expect(passed).toBe(true);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  },
-  5_000,
-);

package/src/completions/output-check.ts

@@ -1,92 +0,0 @@
-import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
-import { shellArgs, parseDuration } from '../utils';
-
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-export const OutputCheckCompletion: CompletionPlugin = {
-  name: 'output_check',
-  schema: {
-    description:
-      'Pipe the task output into a shell command; mark success when that command exits 0. For AI driver tasks the driver-normalized text is piped (not the raw NDJSON); command tasks see their raw stdout.',
-    fields: {
-      check: {
-        type: 'string',
-        required: true,
-        description:
-          'Shell command to run. The task output is piped to its stdin — normalizedOutput when the driver provides one, otherwise raw stdout.',
-        placeholder: "grep -q 'PASS'",
-      },
-      timeout: {
-        type: 'duration',
-        default: '30s',
-        description: 'Maximum time to wait for the check command.',
-        placeholder: '30s',
-      },
-    },
-  },
-
-  async check(
-    config: Record<string, unknown>,
-    result: TaskResult,
-    ctx: CompletionContext,
-  ): Promise<boolean> {
-    const checkCmd = config.check as string;
-    if (!checkCmd) throw new Error('output_check completion: "check" is required');
-
-    const timeoutMs =
-      config.timeout != null ? parseDuration(String(config.timeout)) : DEFAULT_TIMEOUT_MS;
-
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-
-    // Wire pipeline abort signal into the check process so external abort
-    // terminates the child instead of leaving it running undetected.
-    const onAbort = () => controller.abort();
-    if (ctx.signal) {
-      if (ctx.signal.aborted) {
-        controller.abort();
-      } else {
-        ctx.signal.addEventListener('abort', onAbort, { once: true });
-      }
-    }
-
-    const proc = Bun.spawn(shellArgs(checkCmd) as string[], {
-      cwd: ctx.workDir,
-      stdin: 'pipe',
-      stdout: 'pipe',
-      stderr: 'pipe',
-      signal: controller.signal,
-    });
-
-    try {
-      if (proc.stdin) {
-        try {
-          // Prefer driver-normalized text (e.g. concatenated message text for
-          // AI drivers that emit NDJSON). Falling back to raw stdout keeps
-          // command tasks and drivers without parseResult working.
-          const payload = result.normalizedOutput ?? result.stdout;
-          proc.stdin.write(payload);
-          proc.stdin.end(); // no await — consistent with runner.ts; proc.exited handles sync
-        } catch (err: unknown) {
-          // EPIPE is expected when the check process exits before reading all of stdin
-          // (e.g. `grep -q` exits on first match). Anything else is a real failure.
-          const code = (err as NodeJS.ErrnoException)?.code;
-          if (code !== 'EPIPE') throw err;
-        }
-      }
-
-      // Consume stderr concurrently with waiting for exit to prevent pipe-buffer
-      // deadlock when check script emits more than ~64 KB of stderr output.
-      const [exitCode, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
-
-      if (exitCode !== 0 && stderr.trim()) {
-        console.warn(`[output_check] "${checkCmd}" exit=${exitCode}: ${stderr.trim()}`);
-      }
-
-      return exitCode === 0;
-    } finally {
-      clearTimeout(timer);
-      if (ctx.signal) ctx.signal.removeEventListener('abort', onAbort);
-    }
-  },
-};