@tagma/sdk 0.7.3 → 0.7.5

package/src/drivers/opencode.ts

@@ -1,410 +0,0 @@
-import type {
-  DriverPlugin,
-  DriverCapabilities,
-  DriverResultMeta,
-  TaskConfig,
-  TrackConfig,
-  DriverContext,
-  SpawnSpec,
-} from '../types';
-
-const DEFAULT_MODEL = 'opencode/big-pickle';
-
-// NOTE on Windows multi-line prompts: `opencode` resolves to `opencode.cmd`,
-// an npm-generated batch wrapper. cmd.exe silently truncates argv elements
-// at the first newline, so a multi-line prompt reaches the model as only
-// its first line. The SDK's runner auto-unwraps npm .cmd shims into direct
-// `node <js-entry>` invocations so newlines survive, and this driver can
-// keep using the bare `opencode` name on every platform.
-
-// tagma uses a provider-neutral reasoning_effort vocabulary (low|medium|high)
-// but opencode's `--variant` is provider-specific (e.g. high|max|minimal).
-// Map the tagma values to the closest opencode variant:
-//   low    → minimal  (least thinking)
-//   medium → <no flag, provider default>
-//   high   → high     (most thinking)
-// Unknown values pass through unchanged so users who target a specific
-// opencode variant (e.g. "max") still work.
-const EFFORT_TO_VARIANT: Record<string, string | null> = {
-  low: 'minimal',
-  medium: null,
-  high: 'high',
-};
-
-// ── Auto-install + free-model picker ───────────────────────────────────────
-//
-// The opencode driver is SDK-built-in, but the `opencode` CLI isn't. Two
-// provisioning paths:
-//
-//   1. Desktop app — the Electron shell ships a platform-matched opencode
-//      binary under resources/opencode/bin/, prepended to the sidecar's PATH
-//      at launch (see apps/electron/src/runtime-paths.ts). In-app updates
-//      drop a newer copy into userData/opencode/bin/ which wins via PATH
-//      precedence. That path resolves on the first `opencode --version`
-//      probe below; no auto-install ever fires.
-//
-//   2. SDK direct use — when bun is on PATH we fall through to
-//      `bun install -g opencode-ai`, identical to the pre-desktop behavior.
-//
-// When BOTH paths are unavailable (no bundled binary, no bun) we fail with
-// an actionable error pointing at the desktop Settings panel instead of
-// silently letting `opencode run` ENOENT later — the old behavior swallowed
-// the root cause in runCapture's catch and left the user staring at an
-// opaque "exit code -1". The result is process-memoized so subsequent
-// tasks in the same run surface the same error without re-probing.
-
-interface OpencodeModelInfo {
-  id?: string;
-  providerID?: string;
-  status?: string;
-  cost?: { input?: number; output?: number };
-  limit?: { context?: number };
-}
-
-// Memoize BOTH success and failure. On failure we stash the message so every
-// subsequent ensureOpencodeInstalled() throws the identical error — re-running
-// the bun-install probe for each task of a failed run would just be slow and
-// produce confusing interleaved stderr.
-let opencodeReady: boolean | undefined;
-let opencodeReadyError: string | undefined;
-let cachedDefaultModel: string | undefined;
-
-async function runCapture(
-  args: string[],
-): Promise<{ code: number; stdout: string; stderr: string }> {
-  try {
-    const proc = Bun.spawn(args, { stdout: 'pipe', stderr: 'pipe' });
-    const [stdout, stderr, code] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-      proc.exited,
-    ]);
-    return { code, stdout, stderr };
-  } catch {
-    return { code: -1, stdout: '', stderr: '' };
-  }
-}
-
-// Shared tail for every failure message — the Tagma desktop app exposes a
-// one-click installer at the same npm source path this driver would reach
-// for, so point users there first. Users running the SDK as a library still
-// see the manual bun/npm hint.
-const SETUP_HINT =
-  'If you are using the Tagma desktop app, open Editor Settings → OpenCode CLI to install or update the bundled binary. ' +
-  'Otherwise install it manually: `bun install -g opencode-ai` or `npm install -g opencode-ai`.';
-
-async function ensureOpencodeInstalled(): Promise<void> {
-  if (opencodeReady === true) return;
-  if (opencodeReady === false && opencodeReadyError) {
-    throw new Error(opencodeReadyError);
-  }
-
-  // Probe existing install first — this is the hot path for desktop users
-  // (bundled binary in PATH) and for anyone who already has opencode.
-  const probe = await runCapture(['opencode', '--version']);
-  if (probe.code === 0) {
-    opencodeReady = true;
-    return;
-  }
-
-  // Distinguish "bun is missing" from "bun is here but install failed" so
-  // the error we surface points at the right next step. If bun is absent we
-  // skip the install attempt entirely — spawning with `bun` as argv[0]
-  // would just ENOENT inside runCapture's catch and look identical to a
-  // failed install.
-  const bunProbe = await runCapture(['bun', '--version']);
-  if (bunProbe.code !== 0) {
-    opencodeReady = false;
-    opencodeReadyError = `OpenCode CLI is not available and \`bun\` is not installed. ${SETUP_HINT}`;
-    throw new Error(opencodeReadyError);
-  }
-
-  console.error(
-    '[driver:opencode] opencode CLI not found — installing via `bun install -g opencode-ai`... (this may take up to a minute)',
-  );
-  // Use inherit here so the user sees bun's own progress during the one-time
-  // install; runCapture would swallow it.
-  const install = Bun.spawn(['bun', 'install', '-g', 'opencode-ai'], {
-    stdout: 'inherit',
-    stderr: 'inherit',
-  });
-  const installCode = await install.exited;
-  if (installCode !== 0) {
-    opencodeReady = false;
-    opencodeReadyError = `\`bun install -g opencode-ai\` failed (exit code ${installCode}). ${SETUP_HINT}`;
-    throw new Error(opencodeReadyError);
-  }
-
-  // Bun installs globals under `~/.bun/bin` (or `%USERPROFILE%\.bun\bin`),
-  // which isn't on this process's cached PATH unless the user already has
-  // bun set up. Ask bun for the directory and prepend it so bare `opencode`
-  // resolves in this process without requiring a shell reload.
-  const bin = await runCapture(['bun', 'pm', 'bin', '-g']);
-  if (bin.code === 0) {
-    const dir = bin.stdout.trim();
-    const sep = process.platform === 'win32' ? ';' : ':';
-    const current = process.env.PATH ?? '';
-    if (dir && !current.split(sep).includes(dir)) {
-      process.env.PATH = `${dir}${sep}${current}`;
-    }
-  }
-
-  const verify = await runCapture(['opencode', '--version']);
-  if (verify.code !== 0) {
-    opencodeReady = false;
-    opencodeReadyError =
-      '`opencode` is not resolvable after `bun install -g opencode-ai` completed. ' +
-      "Bun's global bin directory is probably not on PATH — add it manually or restart the app.";
-    throw new Error(opencodeReadyError);
-  }
-  opencodeReady = true;
-}
-
-// `opencode models --verbose` emits "<provider>/<id>\n{...json...}\n" pairs.
-// Walk balanced braces rather than split on newlines so we survive any
-// whitespace oddities in the JSON payload.
-function parseVerboseModels(stdout: string): OpencodeModelInfo[] {
-  const out: OpencodeModelInfo[] = [];
-  let depth = 0;
-  let start = -1;
-  for (let i = 0; i < stdout.length; i++) {
-    const c = stdout[i];
-    if (c === '{') {
-      if (depth === 0) start = i;
-      depth++;
-    } else if (c === '}') {
-      depth--;
-      if (depth === 0 && start !== -1) {
-        try {
-          out.push(JSON.parse(stdout.slice(start, i + 1)) as OpencodeModelInfo);
-        } catch {
-          /* skip malformed block */
-        }
-        start = -1;
-      }
-    }
-  }
-  return out;
-}
-
-function pickFreeModel(models: OpencodeModelInfo[]): string | null {
-  const fullId = (m: OpencodeModelInfo): string =>
-    `${m.providerID ?? 'opencode'}/${m.id ?? ''}`;
-  const eligible = models.filter((m) => {
-    if (!m.id || m.id === 'big-pickle') return false;
-    if (m.status && m.status !== 'active') return false;
-    const cost = m.cost;
-    if (!cost || cost.input !== 0 || cost.output !== 0) return false;
-    const ctx = m.limit?.context;
-    if (typeof ctx !== 'number' || ctx <= 128000) return false;
-    return true;
-  });
-  // Prefer models explicitly labelled "-free" by the provider — those are
-  // a stronger stability signal than "cost happens to be 0 right now".
-  const preferred = eligible.filter((m) => m.id?.endsWith('-free'));
-  const pool = preferred.length > 0 ? preferred : eligible;
-  if (pool.length === 0) return null;
-  // Deterministic pick: sort by full id so upstream model-list reordering
-  // doesn't flip our choice between runs.
-  pool.sort((a, b) => fullId(a).localeCompare(fullId(b)));
-  return fullId(pool[0]);
-}
-
-async function resolveDefaultModel(): Promise<string> {
-  if (cachedDefaultModel !== undefined) return cachedDefaultModel;
-  // ensureOpencodeInstalled now throws with an actionable message when the
-  // CLI can't be provisioned, so we let the error bubble up to the task
-  // runner instead of silently falling back to DEFAULT_MODEL (which would
-  // produce a second confusing ENOENT a few lines later in `opencode run`).
-  await ensureOpencodeInstalled();
-  console.error('[driver:opencode] resolving free opencode model...');
-  const { code, stdout } = await runCapture(['opencode', 'models', '--verbose']);
-  if (code !== 0) {
-    cachedDefaultModel = DEFAULT_MODEL;
-    return cachedDefaultModel;
-  }
-  const picked = pickFreeModel(parseVerboseModels(stdout));
-  cachedDefaultModel = picked ?? DEFAULT_MODEL;
-  console.error(`[driver:opencode] default model: ${cachedDefaultModel}`);
-  return cachedDefaultModel;
-}
-
-export const OpenCodeDriver: DriverPlugin = {
-  name: 'opencode',
-
-  capabilities: {
-    sessionResume: true, // supports --session
-    systemPrompt: false, // no --system-prompt flag; prepend to prompt instead
-    outputFormat: true, // supports --format json
-  } satisfies DriverCapabilities,
-
-  resolveModel(): string {
-    return DEFAULT_MODEL;
-  },
-
-  async buildCommand(task: TaskConfig, track: TrackConfig, ctx: DriverContext): Promise<SpawnSpec> {
-    const explicitModel = task.model ?? track.model;
-    // Always make sure the opencode CLI is usable before we spawn it — even
-    // when the user pinned a model. ensureOpencodeInstalled throws with an
-    // actionable message when the binary is neither present on PATH (desktop
-    // bundles it there via runtime-paths.ts) nor installable via bun.
-    if (explicitModel) await ensureOpencodeInstalled();
-    // Otherwise resolveDefaultModel both ensures the CLI and picks a free
-    // model from `opencode models --verbose` (cached per-process).
-    const model = explicitModel ?? (await resolveDefaultModel());
-    // Resolve reasoning_effort → opencode --variant. SDK schema layer already
-    // resolved task → track → pipeline inheritance, so we only need to read
-    // task.reasoning_effort here.
-    const rawEffort = task.reasoning_effort ?? track.reasoning_effort;
-    const variant = rawEffort
-      ? rawEffort in EFFORT_TO_VARIANT
-        ? EFFORT_TO_VARIANT[rawEffort]
-        : rawEffort
-      : null;
-
-    let prompt = task.prompt!;
-
-    // agent_profile has no dedicated flag; prepend to prompt
-    const profile = task.agent_profile ?? track.agent_profile;
-    if (profile) {
-      prompt = `[Role]\n${profile}\n\n[Task]\n${prompt}`;
-    }
-
-    // continue_from: prefer session resume, fall back to text injection
-    let sessionId: string | null = null;
-    if (task.continue_from) {
-      sessionId = ctx.sessionMap.get(task.continue_from) ?? null;
-      if (!sessionId) {
-        // no session — degrade to text context passthrough
-        let prev: string | null = null;
-        if (ctx.normalizedMap.has(task.continue_from)) {
-          prev = ctx.normalizedMap.get(task.continue_from)!;
-        }
-        if (prev !== null) {
-          prompt = `[Previous Output]\n${prev}\n\n[Current Task]\n${prompt}`;
-        }
-      }
-    }
-
-    // opencode run does not support stdin (no `-` placeholder like codex exec).
-    // Prompt is always a positional argument. Flags must be declared before `--`;
-    // the prompt follows after so that leading `--flag` content cannot be
-    // misread by opencode's argument parser (flag-injection mitigation).
-    // Shell-level injection is already prevented by Bun.spawn's direct argv array.
-    // Windows cmd.exe argv truncation on the `.cmd` wrapper is handled by the
-    // SDK runner's shim unwrapping — see note at the top of this file.
-    const args: string[] = [
-      'opencode',
-      'run',
-      '--model',
-      model,
-      '--format',
-      'json', // JSON output for parseResult
-    ];
-
-    // `--variant` must precede `--` like every other flag. opencode rejects
-    // unknown variant names with a clear error, so we don't pre-validate.
-    if (variant) {
-      args.push('--variant', variant);
-    }
-
-    // session resume (must appear before --)
-    if (sessionId) {
-      args.push('--session', sessionId);
-    }
-
-    // `--` (POSIX end-of-options) isolates prompt from flag parsing
-    args.push('--', prompt);
-
-    return { args, cwd: task.cwd ?? ctx.workDir };
-  },
-
-  parseResult(stdout: string): DriverResultMeta {
-    // opencode --format json emits NDJSON — one JSON object per line
-    // (step_start / text / step_finish / …). The previous single
-    // `JSON.parse(stdout)` always threw on this shape and fell through to
-    // the catch, returning sessionId:null and losing session resume.
-    // Walk line-by-line, pick up the first sessionID we see, concatenate
-    // any text-type parts into normalizedOutput, and bail early on error
-    // payloads.
-    const lines = stdout.split(/\r?\n/);
-    let sessionId: string | undefined;
-    const textParts: string[] = [];
-    let sawAnyJson = false;
-    let errorReason: string | null = null;
-
-    for (const raw of lines) {
-      const line = raw.trim();
-      if (!line) continue;
-      let json: Record<string, unknown>;
-      try {
-        json = JSON.parse(line) as Record<string, unknown>;
-      } catch {
-        continue; // tolerate interleaved non-JSON noise
-      }
-      sawAnyJson = true;
-
-      // M12: opencode sometimes emits {type:"error", error:{...}} with
-      // exit 0 for transient API failures. Force-fail so downstream
-      // skip_downstream / stop_all kicks in.
-      if (json.type === 'error') {
-        const err = json.error as { message?: unknown } | string | undefined;
-        const msg =
-          typeof err === 'object' && err !== null && typeof err.message === 'string'
-            ? err.message
-            : typeof err === 'string'
-              ? err
-              : null;
-        errorReason = msg
-          ? `opencode reported error: ${msg}`
-          : 'opencode emitted an error JSON payload';
-        // D21: stop at the first error. Continuing meant subsequent text
-        // lines got accumulated into `textParts` only to be discarded by
-        // the error-return below, and a later `{type:"error"}` would
-        // silently overwrite the original cause — operators then debugged
-        // a downstream symptom while the root-cause line scrolled past.
-        break;
-      }
-
-      // Session id — opencode uses `sessionID` (camelCase with capital D).
-      // Keep `session_id` / `sessionId` as fallbacks for forward/backward
-      // compatibility with other shapes.
-      if (!sessionId) {
-        const sid =
-          (json.sessionID as string | undefined) ??
-          (json.session_id as string | undefined) ??
-          (json.sessionId as string | undefined) ??
-          null;
-        if (typeof sid === 'string' && sid.length > 0) sessionId = sid;
-      }
-
-      // Extract human-readable text from text-type parts.
-      if (json.type === 'text') {
-        const part = json.part as { text?: unknown } | undefined;
-        if (part && typeof part.text === 'string') {
-          textParts.push(part.text);
-        }
-      } else if (typeof json.result === 'string') {
-        textParts.push(json.result);
-      } else if (typeof json.content === 'string') {
-        textParts.push(json.content);
-      }
-    }
-
-    if (errorReason) {
-      return { forceFailure: true, forceFailureReason: errorReason };
-    }
-
-    // If nothing parsed as JSON, treat stdout as plain text.
-    const normalizedOutput = !sawAnyJson
-      ? stdout
-      : textParts.length > 0
-        ? textParts.join('\n')
-        : stdout;
-
-    return {
-      sessionId,
-      normalizedOutput,
-    };
-  },
-};

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

@@ -1,156 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-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';
-
-const PERMS = { read: true, write: false, execute: false };
-
-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>) {
-  const reg = new PluginRegistry();
-  bootstrapBuiltins(reg);
-  const driver: DriverPlugin = {
-    name: 'mock',
-    capabilities: { sessionResume: false, systemPrompt: true, outputFormat: true },
-    async buildCommand(task) {
-      return {
-        args: ['node', script],
-        stdin: task.prompt ?? '',
-        env: {
-          MOCK_RESPONSE: JSON.stringify(responses[task.id] ?? {}),
-          MOCK_RECORD_PATH: records[task.id] ?? join(process.cwd(), 'prompt.txt'),
-        },
-      };
-    },
-    parseResult(stdout) {
-      return { normalizedOutput: stdout.trim() };
-    },
-  };
-  reg.registerPlugin('drivers', 'mock', driver);
-  return reg;
-}
-
-function task(overrides: Partial<TaskConfig> & { id: string }): TaskConfig {
-  return { name: overrides.id, permissions: PERMS, driver: 'mock', ...overrides };
-}
-
-function pipeline(tasks: TaskConfig[]): PipelineConfig {
-  return {
-    name: 'mixed-bindings-test',
-    tracks: [{ id: 't', name: 'T', permissions: PERMS, driver: 'mock', tasks }],
-  };
-}
-
-async function run(config: PipelineConfig, workDir: string, reg: PluginRegistry) {
-  const events: RunEventPayload[] = [];
-  const result = await runPipeline(config, workDir, {
-    registry: reg,
-    skipPluginLoading: true,
-    onEvent: (e) => events.push(e),
-  });
-  return { events, success: result.success };
-}
-
-function finalUpdateFor(events: RunEventPayload[], qid: string): RunEventPayload | undefined {
-  let last: RunEventPayload | undefined;
-  for (const ev of events) {
-    if (ev.type === 'task_update' && ev.taskId === qid) last = ev;
-  }
-  return last;
-}
-
-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 config = pipeline([
-        task({ id: 'plan', prompt: 'Pick a city' }),
-        task({
-          id: 'fetch',
-          driver: 'opencode',
-          depends_on: ['plan'],
-          command: `node "${echo}" "{{inputs.city}}"`,
-          inputs: { city: { from: 't.plan.outputs.city', type: 'string', required: true } },
-        }),
-      ]);
-
-      const { events, success } = await run(config, dir, reg);
-      expect(success).toBe(true);
-      expect(readFileSync(record, 'utf8')).toContain('[Output Format]');
-      expect(finalUpdateFor(events, 't.plan')?.outputs).toEqual({ city: 'Paris' });
-      expect(finalUpdateFor(events, 't.fetch')?.inputs).toEqual({ city: 'Paris' });
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  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 config = pipeline([
-        task({
-          id: 'up',
-          driver: 'opencode',
-          command: `node "${emit}"`,
-          outputs: { city: { type: 'string' } },
-        }),
-        task({ id: 'summarize', depends_on: ['up'], prompt: 'City is {{inputs.city}}' }),
-      ]);
-
-      const { events, success } = await run(config, dir, reg);
-      expect(success).toBe(true);
-      expect(readFileSync(record, 'utf8')).toContain('City is Berlin');
-      expect(finalUpdateFor(events, 't.summarize')?.inputs).toEqual({ city: 'Berlin' });
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});