@tagma/sdk 0.7.4 → 0.7.5

package/src/prompt-doc.test.ts

@@ -1,174 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import {
-  appendContext,
-  prependContext,
-  promptDocumentFromString,
-  renderInputsBlock,
-  renderOutputSchemaBlock,
-  serializePromptDocument,
-} from './prompt-doc';
-import type { PortDef, PromptContextBlock, PromptDocument } from './types';
-
-// ─── renderInputsBlock ────────────────────────────────────────────────
-
-describe('renderInputsBlock', () => {
-  test('returns null when no inputs declared', () => {
-    expect(renderInputsBlock(undefined, {})).toBeNull();
-    expect(renderInputsBlock([], { any: 'x' })).toBeNull();
-  });
-
-  test('returns null when declared inputs have no resolved values', () => {
-    const ports: PortDef[] = [{ name: 'city', type: 'string' }];
-    // values missing entirely — block is noise, omit it
-    expect(renderInputsBlock(ports, {})).toBeNull();
-  });
-
-  test('renders name: value per declared input', () => {
-    const ports: PortDef[] = [
-      { name: 'city', type: 'string' },
-      { name: 'id', type: 'number' },
-    ];
-    const block = renderInputsBlock(ports, { city: 'Shanghai', id: 42 });
-    expect(block).not.toBeNull();
-    expect(block!.label).toBe('Inputs');
-    expect(block!.content).toBe('city: "Shanghai"\nid: 42');
-  });
-
-  test('appends # description comment when provided', () => {
-    const ports: PortDef[] = [
-      { name: 'city', type: 'string', description: 'Target city' },
-    ];
-    const block = renderInputsBlock(ports, { city: 'Shanghai' })!;
-    expect(block.content).toBe('city: "Shanghai"  # Target city');
-  });
-
-  test('preserves declaration order, not input-map iteration order', () => {
-    const ports: PortDef[] = [
-      { name: 'b', type: 'string' },
-      { name: 'a', type: 'string' },
-    ];
-    // Values object has 'a' first, 'b' second — block should still emit 'b' first.
-    const block = renderInputsBlock(ports, { a: 'x', b: 'y' })!;
-    expect(block.content).toBe('b: "y"\na: "x"');
-  });
-
-  test('skips ports whose values were not resolved', () => {
-    const ports: PortDef[] = [
-      { name: 'a', type: 'string' },
-      { name: 'b', type: 'string' },
-    ];
-    const block = renderInputsBlock(ports, { a: 'x' })!;
-    expect(block.content).toBe('a: "x"');
-  });
-
-  test('JSON-encodes non-primitive values', () => {
-    const ports: PortDef[] = [{ name: 'payload', type: 'json' }];
-    const block = renderInputsBlock(ports, { payload: { a: 1, b: [2, 3] } })!;
-    expect(block.content).toBe('payload: {"a":1,"b":[2,3]}');
-  });
-
-  test('booleans render verbatim, not quoted', () => {
-    const ports: PortDef[] = [{ name: 'flag', type: 'boolean' }];
-    const block = renderInputsBlock(ports, { flag: true })!;
-    expect(block.content).toBe('flag: true');
-  });
-});
-
-// ─── renderOutputSchemaBlock ──────────────────────────────────────────
-
-describe('renderOutputSchemaBlock', () => {
-  test('returns null when no outputs declared', () => {
-    expect(renderOutputSchemaBlock(undefined)).toBeNull();
-    expect(renderOutputSchemaBlock([])).toBeNull();
-  });
-
-  test('instructs the model to emit final-line JSON', () => {
-    const ports: PortDef[] = [{ name: 'city', type: 'string' }];
-    const block = renderOutputSchemaBlock(ports)!;
-    expect(block.label).toBe('Output Format');
-    expect(block.content).toMatch(/final line/i);
-  });
-
-  test('lists each port with its type', () => {
-    const ports: PortDef[] = [
-      { name: 'city', type: 'string', description: 'Target city' },
-      { name: 'temp', type: 'number' },
-    ];
-    const block = renderOutputSchemaBlock(ports)!;
-    expect(block.content).toContain('- city (string): Target city');
-    expect(block.content).toContain('- temp (number)');
-  });
-
-  test('includes enum values in the type hint', () => {
-    const ports: PortDef[] = [
-      { name: 'color', type: 'enum', enum: ['red', 'green', 'blue'] },
-    ];
-    const block = renderOutputSchemaBlock(ports)!;
-    expect(block.content).toContain('color (enum (one of: "red", "green", "blue"))');
-  });
-
-  test('example object uses declared defaults when present', () => {
-    const ports: PortDef[] = [
-      { name: 'score', type: 'number', default: 0.5 },
-      { name: 'note', type: 'string', default: 'n/a' },
-    ];
-    const block = renderOutputSchemaBlock(ports)!;
-    // The example line is `Example final line: {"score":0.5,"note":"n/a"}`.
-    expect(block.content).toContain('"score":0.5');
-    expect(block.content).toContain('"note":"n/a"');
-  });
-
-  test('example uses type-appropriate placeholders when no default', () => {
-    const ports: PortDef[] = [
-      { name: 's', type: 'string' },
-      { name: 'n', type: 'number' },
-      { name: 'b', type: 'boolean' },
-      { name: 'j', type: 'json' },
-    ];
-    const block = renderOutputSchemaBlock(ports)!;
-    expect(block.content).toContain('"s":"..."');
-    expect(block.content).toContain('"n":0');
-    expect(block.content).toContain('"b":false');
-    expect(block.content).toContain('"j":null');
-  });
-
-  test('example uses first enum value when present', () => {
-    const ports: PortDef[] = [
-      { name: 'tier', type: 'enum', enum: ['low', 'high'] },
-    ];
-    const block = renderOutputSchemaBlock(ports)!;
-    expect(block.content).toContain('"tier":"low"');
-  });
-});
-
-// ─── prependContext / appendContext ──────────────────────────────────
-
-describe('prependContext / appendContext', () => {
-  const block: PromptContextBlock = { label: 'X', content: 'x' };
-
-  test('prependContext puts block at front without mutating input', () => {
-    const doc: PromptDocument = { contexts: [{ label: 'Y', content: 'y' }], task: 't' };
-    const next = prependContext(doc, block);
-    expect(next.contexts.map((c) => c.label)).toEqual(['X', 'Y']);
-    // Original untouched — immutability is part of the contract for
-    // middleware safety (the engine compares doc identity to detect
-    // changes in some paths).
-    expect(doc.contexts).toHaveLength(1);
-    expect(doc.contexts[0]!.label).toBe('Y');
-    expect(next.task).toBe('t');
-  });
-
-  test('appendContext puts block at end without mutating input', () => {
-    const doc: PromptDocument = { contexts: [{ label: 'Y', content: 'y' }], task: 't' };
-    const next = appendContext(doc, block);
-    expect(next.contexts.map((c) => c.label)).toEqual(['Y', 'X']);
-    expect(doc.contexts).toHaveLength(1);
-  });
-
-  test('prepend + serialize produces [X] block above the task', () => {
-    const doc = promptDocumentFromString('do the thing');
-    const next = prependContext(doc, { label: 'Inputs', content: 'city: "Shanghai"' });
-    const text = serializePromptDocument(next);
-    expect(text).toBe('[Inputs]\ncity: "Shanghai"\n\ndo the thing');
-  });
-});

package/src/prompt-doc.ts

@@ -1,169 +0,0 @@
-import type { PortDef, PromptContextBlock, PromptDocument } 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 };
-}
-
-/**
- * Helper: return a new document with the given block PREPENDED. The
- * engine uses this to place port-related context blocks (`[Inputs]`,
- * `[Output Format]`) at the top of the document so middlewares that
- * assemble retrieval context against the task's inputs see them.
- */
-export function prependContext(
-  doc: PromptDocument,
-  block: PromptContextBlock,
-): PromptDocument {
-  return { contexts: [block, ...doc.contexts], task: doc.task };
-}
-
-/**
- * Build an `[Inputs]` context block from a map of resolved port inputs.
- * Each input is rendered on its own line as `name: <value>` with an
- * optional trailing `# <description>` comment so the model has both the
- * value and the reason it matters.
- *
- * The block is *only* useful for AI tasks; command tasks consume inputs
- * through `{{inputs.X}}` substitution in their command line and do not
- * need this context.
- *
- * Returns null when there are no inputs to render — callers can forward
- * that nullish value to `prependContext` via an `if (block)` check so
- * empty-input tasks don't grow a noise block in their prompt.
- */
-export function renderInputsBlock(
-  inputsDecl: readonly PortDef[] | undefined,
-  values: Readonly<Record<string, unknown>>,
-): PromptContextBlock | null {
-  if (!inputsDecl || inputsDecl.length === 0) return null;
-  const lines: string[] = [];
-  for (const port of inputsDecl) {
-    if (!(port.name in values)) continue;
-    const raw = values[port.name];
-    const rendered = renderInputValue(raw);
-    const descr = port.description?.trim();
-    lines.push(descr ? `${port.name}: ${rendered}  # ${descr}` : `${port.name}: ${rendered}`);
-  }
-  if (lines.length === 0) return null;
-  return { label: 'Inputs', content: lines.join('\n') };
-}
-
-function renderInputValue(value: unknown): string {
-  if (value === null || value === undefined) return '';
-  if (typeof value === 'string') return JSON.stringify(value);
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}
-
-/**
- * Build an `[Output Format]` context block from a task's declared output
- * ports. The block instructs the model to emit a final-line JSON object
- * matching the declared schema so `extractTaskOutputs` can pick it up
- * without fragile heuristics. Returns null when the task declares no
- * outputs.
- *
- * The instruction is deliberately short and explicit — a terse "emit
- * this object as JSON on the final line" beats a long schema dump
- * because shorter prompts compose better with downstream middlewares.
- */
-export function renderOutputSchemaBlock(
-  outputsDecl: readonly PortDef[] | undefined,
-): PromptContextBlock | null {
-  if (!outputsDecl || outputsDecl.length === 0) return null;
-  const lines: string[] = [];
-  lines.push(
-    'After your response, emit a single JSON object on the FINAL line with these keys:',
-  );
-  for (const port of outputsDecl) {
-    const descr = port.description?.trim();
-    const enumHint =
-      port.type === 'enum' && port.enum?.length
-        ? ` (one of: ${port.enum.map((v) => JSON.stringify(v)).join(', ')})`
-        : '';
-    lines.push(
-      descr
-        ? `  - ${port.name} (${port.type}${enumHint}): ${descr}`
-        : `  - ${port.name} (${port.type}${enumHint})`,
-    );
-  }
-  const example = buildExampleObject(outputsDecl);
-  lines.push('');
-  lines.push(`Example final line: ${JSON.stringify(example)}`);
-  return { label: 'Output Format', content: lines.join('\n') };
-}
-
-function buildExampleObject(outputsDecl: readonly PortDef[]): Record<string, unknown> {
-  const example: Record<string, unknown> = {};
-  for (const port of outputsDecl) {
-    if (port.default !== undefined) {
-      example[port.name] = port.default;
-      continue;
-    }
-    switch (port.type) {
-      case 'string':
-        example[port.name] = '...';
-        break;
-      case 'number':
-        example[port.name] = 0;
-        break;
-      case 'boolean':
-        example[port.name] = false;
-        break;
-      case 'enum':
-        example[port.name] = port.enum?.[0] ?? '...';
-        break;
-      case 'json':
-      default:
-        example[port.name] = null;
-    }
-  }
-  return example;
-}

package/src/registry.ts

@@ -1,7 +0,0 @@
-export {
-  isValidPluginName,
-  PluginRegistry,
-  PLUGIN_NAME_RE,
-  readPluginManifest,
-} from '@tagma/core';
-export type { RegisteredCapability, RegisterResult } from '@tagma/core';

package/src/runner.test.ts

@@ -1,142 +0,0 @@
-import { test, expect } from 'bun:test';
-import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { runSpawn } from './runner';
-
-// Portable output producer — node is guaranteed in the bun dev env. Using a
-// known runtime avoids shell-quoting differences between platforms.
-function nodeArg(script: string): string[] {
-  return ['node', '-e', script];
-}
-
-test('runSpawn: small output is returned whole, persisted byte-identical', async () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'tagma-runner-small-'));
-  const stdoutPath = join(tmp, 'out');
-  const stderrPath = join(tmp, 'err');
-  try {
-    const result = await runSpawn(
-      { args: nodeArg('process.stdout.write("hello world"); process.stderr.write("oops")') },
-      null,
-      { stdoutPath, stderrPath },
-    );
-    expect(result.exitCode).toBe(0);
-    expect(result.stdout).toBe('hello world');
-    expect(result.stderr).toBe('oops');
-    expect(result.stdoutBytes).toBe(11);
-    expect(result.stderrBytes).toBe(4);
-    expect(result.stdoutPath).toBe(stdoutPath);
-    expect(result.stderrPath).toBe(stderrPath);
-    expect(readFileSync(stdoutPath, 'utf8')).toBe('hello world');
-    expect(readFileSync(stderrPath, 'utf8')).toBe('oops');
-  } finally {
-    rmSync(tmp, { recursive: true, force: true });
-  }
-});
-
-test('runSpawn: oversized output — bounded tail in memory, full bytes on disk', async () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'tagma-runner-big-'));
-  const stdoutPath = join(tmp, 'out');
-  try {
-    // Produce 3 MB of output against a 512 KB cap. The child writes in one
-    // shot; the runner should slice the single chunk's tail rather than
-    // evicting (the "pathological one-chunk-over-cap" branch).
-    const cap = 512 * 1024;
-    const totalBytes = 3 * 1024 * 1024;
-    const result = await runSpawn(
-      {
-        args: nodeArg(
-          `process.stdout.write("a".repeat(${totalBytes}))`,
-        ),
-      },
-      null,
-      { stdoutPath, maxStdoutTailBytes: cap },
-    );
-    expect(result.exitCode).toBe(0);
-    // Total bytes reported match reality
-    expect(result.stdoutBytes).toBe(totalBytes);
-    // In-memory tail bounded above (tail + truncation marker header is a
-    // couple hundred bytes at most; give it slack). No lower bound — chunk
-    // boundaries are platform-dependent so the exact retained size varies.
-    expect(result.stdout.length).toBeLessThan(cap + 1024);
-    // Truncation breadcrumb present and points at the full output
-    expect(result.stdout).toContain('truncated from head');
-    expect(result.stdout).toContain(stdoutPath);
-    // The tail ends with the trailing bytes the child wrote ('a')
-    expect(result.stdout.endsWith('a')).toBe(true);
-    // Disk copy is byte-exact and full-length
-    const onDiskBytes = statSync(stdoutPath).size;
-    expect(onDiskBytes).toBe(totalBytes);
-  } finally {
-    rmSync(tmp, { recursive: true, force: true });
-  }
-});
-
-test('runSpawn: chunked output — tail eviction keeps retained <= cap', async () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'tagma-runner-chunked-'));
-  const stdoutPath = join(tmp, 'out');
-  try {
-    // Emit 8 chunks × 64 KB with sync drains between them, so the runner
-    // receives them as distinct chunks rather than one blob. Cap at 128 KB
-    // forces eviction of older chunks.
-    const cap = 128 * 1024;
-    const chunkSize = 64 * 1024;
-    const nChunks = 8;
-    const script = `
-      const chunk = 'b'.repeat(${chunkSize});
-      (async () => {
-        for (let i = 0; i < ${nChunks}; i++) {
-          process.stdout.write(chunk);
-          await new Promise(r => setImmediate(r));
-        }
-      })();
-    `;
-    const result = await runSpawn(
-      { args: nodeArg(script) },
-      null,
-      { stdoutPath, maxStdoutTailBytes: cap },
-    );
-    expect(result.exitCode).toBe(0);
-    expect(result.stdoutBytes).toBe(nChunks * chunkSize);
-    // Retained tail should be strictly bounded by cap (eviction case, no
-    // single-chunk slice). Allow small overhead for the truncation marker.
-    expect(result.stdout.length).toBeLessThan(cap + 1024);
-    expect(result.stdout).toContain('truncated from head');
-    // Full stream on disk
-    expect(statSync(stdoutPath).size).toBe(nChunks * chunkSize);
-  } finally {
-    rmSync(tmp, { recursive: true, force: true });
-  }
-});
-
-test('runSpawn: no path configured — memory-only tail, returns null paths', async () => {
-  const result = await runSpawn(
-    { args: nodeArg('process.stdout.write("inline only")') },
-    null,
-    {},
-  );
-  expect(result.exitCode).toBe(0);
-  expect(result.stdout).toBe('inline only');
-  expect(result.stdoutPath).toBeNull();
-  expect(result.stderrPath).toBeNull();
-});
-
-test('runSpawn: pre-spawn failure (bad executable) — no paths leak on disk', async () => {
-  const tmp = mkdtempSync(join(tmpdir(), 'tagma-runner-bad-'));
-  const stdoutPath = join(tmp, 'out');
-  try {
-    const result = await runSpawn(
-      { args: ['this-command-definitely-does-not-exist-xyz123'] },
-      null,
-      { stdoutPath },
-    );
-    expect(result.exitCode).toBe(-1);
-    expect(result.failureKind).toBe('spawn_error');
-    // On pre-spawn failure the runner never opened the file, so stdoutPath
-    // is null (not the unopened path). Callers can rely on this to decide
-    // whether a disk file exists to read.
-    expect(result.stdoutPath).toBeNull();
-  } finally {
-    rmSync(tmp, { recursive: true, force: true });
-  }
-});

package/src/runner.ts

@@ -1 +0,0 @@
-export { runCommand, runSpawn } from '@tagma/runtime-bun';

package/src/runtime/adapters/stdin-approval.ts

@@ -1 +0,0 @@
-export * from '@tagma/runtime-bun/adapters/stdin-approval';

package/src/runtime/adapters/websocket-approval.ts

@@ -1 +0,0 @@
-export * from '@tagma/runtime-bun/adapters/websocket-approval';

package/src/runtime/bun-process-runner.ts

@@ -1 +0,0 @@
-export { runCommand, runSpawn } from '@tagma/runtime-bun';

package/src/runtime-adapters.test.ts

@@ -1,10 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { attachStdinApprovalAdapter } from './runtime/adapters/stdin-approval';
-import { attachWebSocketApprovalAdapter } from './runtime/adapters/websocket-approval';
-
-describe('runtime approval adapters', () => {
-  test('approval adapters live under the runtime boundary', () => {
-    expect(typeof attachStdinApprovalAdapter).toBe('function');
-    expect(typeof attachWebSocketApprovalAdapter).toBe('function');
-  });
-});

package/src/runtime.ts

@@ -1,12 +0,0 @@
-export * from '@tagma/runtime-bun';
-export type {
-  OpenRunLogOptions,
-  PruneLogOptions,
-  RunOptions,
-  RuntimeLogSink,
-  RuntimeLogStore,
-  RuntimeWatchEvent,
-  RuntimeWatchOptions,
-  TagmaRuntime,
-  TaskOutputPathOptions,
-} from '@tagma/core';