@tagma/sdk 0.1.8 → 0.1.9

package/src/hooks.ts

@@ -1,138 +1,147 @@
-import type { HooksConfig, HookCommand } from './types';
-import { shellArgs } from './utils';
-
-type HookEvent =
-  | 'pipeline_start' | 'task_start' | 'task_success'
-  | 'task_failure' | 'pipeline_complete' | 'pipeline_error';
-
-const GATE_HOOKS: ReadonlySet<HookEvent> = new Set(['pipeline_start', 'task_start']);
-
-export interface HookResult {
-  readonly allowed: boolean;  // for gate hooks: true = proceed, false = block
-  readonly exitCode: number;
-}
-
-function normalizeCommands(cmd: HookCommand | undefined): readonly string[] {
-  if (!cmd) return [];
-  if (typeof cmd === 'string') return [cmd];
-  return cmd;
-}
-
-async function runSingleHook(command: string, context: unknown, cwd?: string): Promise<number> {
-  const jsonInput = JSON.stringify(context, null, 2);
-
-  const proc = Bun.spawn(shellArgs(command) as string[], {
-    stdin: 'pipe',
-    stdout: 'pipe',
-    stderr: 'pipe',
-    ...(cwd ? { cwd } : {}),
-  });
-
-  if (proc.stdin) {
-    try {
-      proc.stdin.write(jsonInput);
-      proc.stdin.end();
-    } catch {
-      // Process may exit before reading stdin (e.g. `exit 1`), ignore EPIPE
-    }
-  }
-
-  const exitCode = await proc.exited;
-  const stderr = await new Response(proc.stderr).text();
-
-  if (stderr.trim()) {
-    console.error(`[hook: ${command}] stderr: ${stderr.trim()}`);
-  }
-
-  return exitCode;
-}
-
-export async function executeHook(
-  hooks: HooksConfig | undefined,
-  event: HookEvent,
-  context: unknown,
-  workDir?: string,
-): Promise<HookResult> {
-  if (!hooks) return { allowed: true, exitCode: 0 };
-
-  const commands = normalizeCommands(hooks[event]);
-  if (commands.length === 0) return { allowed: true, exitCode: 0 };
-
-  const isGate = GATE_HOOKS.has(event);
-
-  for (const cmd of commands) {
-    const exitCode = await runSingleHook(cmd, context, workDir);
-
-    if (isGate && exitCode === 1) {
-      // Only exit code 1 has gate semantics (block execution)
-      return { allowed: false, exitCode };
-    }
-
-    if (exitCode !== 0) {
-      // Non-zero but not 1: hook itself had an error, log but don't block
-      console.warn(`[hook: ${event}] "${cmd}" exited with code ${exitCode}`);
-    }
-  }
-
-  return { allowed: true, exitCode: 0 };
-}
-
-// ═══ Context Builders ═══
-
-export interface PipelineInfo {
-  readonly name: string;
-  readonly run_id: string;
-  readonly started_at: string;
-  readonly finished_at?: string;
-  readonly duration_ms?: number;
-}
-
-export interface TrackInfo {
-  readonly id: string;
-  readonly name: string;
-}
-
-export interface TaskInfo {
-  readonly id: string;
-  readonly name: string;
-  readonly type: 'ai' | 'command';
-  readonly status: string;
-  readonly exit_code: number | null;
-  readonly duration_ms: number | null;
-  readonly output_path: string | null;
-  readonly stderr_path: string | null;
-  readonly session_id: string | null;
-  readonly started_at: string | null;
-  readonly finished_at: string | null;
-}
-
-export function buildPipelineStartContext(pipeline: PipelineInfo) {
-  return { event: 'pipeline_start', pipeline };
-}
-
-export function buildTaskContext(
-  event: 'task_start' | 'task_success' | 'task_failure',
-  pipeline: PipelineInfo,
-  track: TrackInfo,
-  task: TaskInfo,
-) {
-  return { event, pipeline, track, task };
-}
-
-export function buildPipelineCompleteContext(
-  pipeline: PipelineInfo & { finished_at: string; duration_ms: number },
-  summary: {
-    total: number; success: number; failed: number;
-    skipped: number; timeout: number; blocked: number;
-  },
-) {
-  return { event: 'pipeline_complete', pipeline, summary };
-}
-
-export function buildPipelineErrorContext(
-  pipeline: PipelineInfo,
-  error: string,
-  eventType?: string,
-) {
-  return { event: eventType ?? 'pipeline_error', pipeline, error };
-}
+import type { HooksConfig, HookCommand } from './types';
+import { shellArgs } from './utils';
+
+type HookEvent =
+  | 'pipeline_start' | 'task_start' | 'task_success'
+  | 'task_failure' | 'pipeline_complete' | 'pipeline_error';
+
+const GATE_HOOKS: ReadonlySet<HookEvent> = new Set(['pipeline_start', 'task_start']);
+
+export interface HookResult {
+  readonly allowed: boolean;  // for gate hooks: true = proceed, false = block
+  readonly exitCode: number;
+}
+
+function normalizeCommands(cmd: HookCommand | undefined): readonly string[] {
+  if (!cmd) return [];
+  if (typeof cmd === 'string') return [cmd];
+  return cmd;
+}
+
+async function runSingleHook(command: string, context: unknown, cwd?: string): Promise<number> {
+  const jsonInput = JSON.stringify(context, null, 2);
+
+  const proc = Bun.spawn(shellArgs(command) as string[], {
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    ...(cwd ? { cwd } : {}),
+  });
+
+  if (proc.stdin) {
+    try {
+      proc.stdin.write(jsonInput);
+      proc.stdin.end();
+    } catch {
+      // Process may exit before reading stdin (e.g. `exit 1`), ignore EPIPE
+    }
+  }
+
+  // Consume stdout and stderr concurrently with waiting for exit.
+  // Sequential reads after proc.exited risk a pipe-buffer deadlock when
+  // hook output exceeds the ~64 KB kernel buffer.
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+
+  if (stdout.trim()) {
+    console.log(`[hook: ${command}] stdout: ${stdout.trim()}`);
+  }
+  if (stderr.trim()) {
+    console.error(`[hook: ${command}] stderr: ${stderr.trim()}`);
+  }
+
+  return exitCode;
+}
+
+export async function executeHook(
+  hooks: HooksConfig | undefined,
+  event: HookEvent,
+  context: unknown,
+  workDir?: string,
+): Promise<HookResult> {
+  if (!hooks) return { allowed: true, exitCode: 0 };
+
+  const commands = normalizeCommands(hooks[event]);
+  if (commands.length === 0) return { allowed: true, exitCode: 0 };
+
+  const isGate = GATE_HOOKS.has(event);
+
+  for (const cmd of commands) {
+    const exitCode = await runSingleHook(cmd, context, workDir);
+
+    if (isGate && exitCode === 1) {
+      // Only exit code 1 has gate semantics (block execution)
+      return { allowed: false, exitCode };
+    }
+
+    if (exitCode !== 0) {
+      // Non-zero but not 1: hook itself had an error, log but don't block
+      console.warn(`[hook: ${event}] "${cmd}" exited with code ${exitCode}`);
+    }
+  }
+
+  return { allowed: true, exitCode: 0 };
+}
+
+// ═══ Context Builders ═══
+
+export interface PipelineInfo {
+  readonly name: string;
+  readonly run_id: string;
+  readonly started_at: string;
+  readonly finished_at?: string;
+  readonly duration_ms?: number;
+}
+
+export interface TrackInfo {
+  readonly id: string;
+  readonly name: string;
+}
+
+export interface TaskInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly type: 'ai' | 'command';
+  readonly status: string;
+  readonly exit_code: number | null;
+  readonly duration_ms: number | null;
+  readonly output_path: string | null;
+  readonly stderr_path: string | null;
+  readonly session_id: string | null;
+  readonly started_at: string | null;
+  readonly finished_at: string | null;
+}
+
+export function buildPipelineStartContext(pipeline: PipelineInfo) {
+  return { event: 'pipeline_start', pipeline };
+}
+
+export function buildTaskContext(
+  event: 'task_start' | 'task_success' | 'task_failure',
+  pipeline: PipelineInfo,
+  track: TrackInfo,
+  task: TaskInfo,
+) {
+  return { event, pipeline, track, task };
+}
+
+export function buildPipelineCompleteContext(
+  pipeline: PipelineInfo & { finished_at: string; duration_ms: number },
+  summary: {
+    total: number; success: number; failed: number;
+    skipped: number; timeout: number; blocked: number;
+  },
+) {
+  return { event: 'pipeline_complete', pipeline, summary };
+}
+
+export function buildPipelineErrorContext(
+  pipeline: PipelineInfo,
+  error: string,
+  eventType?: string,
+) {
+  return { event: eventType ?? 'pipeline_error', pipeline, error };
+}

package/src/logger.ts

@@ -1,107 +1,112 @@
-import { resolve, dirname } from 'node:path';
-import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
-
-/**
- * Dual-channel logger.
- *
- *   - `info/warn/error` → console AND file (brief, user-visible events)
- *   - `debug`           → file ONLY (verbose diagnostics)
- *   - `section`         → file ONLY (visual separators)
- *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
- *
- * Log file path: <workDir>/tmp/pipeline.log (one file per pipeline run,
- * truncated on construction).
- */
-export class Logger {
-  private readonly filePath: string;
-  private readonly runDir: string;
-
-  constructor(workDir: string, runId: string) {
-    this.runDir = resolve(workDir, 'logs', runId);
-    this.filePath = resolve(this.runDir, 'pipeline.log');
-    mkdirSync(dirname(this.filePath), { recursive: true });
-    writeFileSync(
-      this.filePath,
-      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
-      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
-      `# Work dir: ${workDir}\n\n`,
-    );
-  }
-
-  info(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} ${message}`;
-    console.log(line);
-    this.append(line);
-  }
-
-  warn(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} WARN: ${message}`;
-    console.warn(line);
-    this.append(line);
-  }
-
-  error(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} ERROR: ${message}`;
-    console.error(line);
-    this.append(line);
-  }
-
-  /** File-only diagnostic log line. */
-  debug(prefix: string, message: string): void {
-    this.append(`${timestamp()} ${prefix} DEBUG: ${message}`);
-  }
-
-  /** File-only visual separator with title. */
-  section(title: string): void {
-    this.append(`\n━━━ ${title} ━━━`);
-  }
-
-  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
-  quiet(message: string): void {
-    this.append(message);
-  }
-
-  private append(line: string): void {
-    try {
-      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
-    } catch {
-      // Swallow log write failures; engine correctness shouldn't depend on logging.
-    }
-  }
-
-  get path(): string {
-    return this.filePath;
-  }
-
-  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
-  get dir(): string {
-    return this.runDir;
-  }
-}
-
-function timestamp(): string {
-  const d = new Date();
-  const hh = String(d.getHours()).padStart(2, '0');
-  const mm = String(d.getMinutes()).padStart(2, '0');
-  const ss = String(d.getSeconds()).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${hh}:${mm}:${ss}.${ms}`;
-}
-
-/** Return the last `n` non-empty lines of `text`, joined with newlines. */
-export function tailLines(text: string, n: number): string {
-  if (!text) return '';
-  const lines = text.split(/\r?\n/).filter(l => l.length > 0);
-  return lines.slice(-n).join('\n');
-}
-
-/**
- * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
- * appending a marker when truncation occurred.
- */
-export function clip(text: string, maxBytes = 16 * 1024): string {
-  if (!text) return '';
-  if (text.length <= maxBytes) return text;
-  const omitted = text.length - maxBytes;
-  return text.slice(0, maxBytes) + `\n…[truncated ${omitted} chars]`;
-}
+import { resolve, dirname } from 'node:path';
+import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * Dual-channel logger.
+ *
+ *   - `info/warn/error` → console AND file (brief, user-visible events)
+ *   - `debug`           → file ONLY (verbose diagnostics)
+ *   - `section`         → file ONLY (visual separators)
+ *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
+ *
+ * Log file path: <workDir>/.tagma/logs/<runId>/pipeline.log (one file per pipeline run,
+ * truncated on construction).
+ */
+export class Logger {
+  private readonly filePath: string;
+  private readonly runDir: string;
+
+  constructor(workDir: string, runId: string) {
+    this.runDir = resolve(workDir, '.tagma', 'logs', runId);
+    this.filePath = resolve(this.runDir, 'pipeline.log');
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(
+      this.filePath,
+      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
+      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
+      `# Work dir: ${workDir}\n\n`,
+    );
+  }
+
+  info(prefix: string, message: string): void {
+    const line = `${timestamp()} ${prefix} ${message}`;
+    console.log(line);
+    this.append(line);
+  }
+
+  warn(prefix: string, message: string): void {
+    const line = `${timestamp()} ${prefix} WARN: ${message}`;
+    console.warn(line);
+    this.append(line);
+  }
+
+  error(prefix: string, message: string): void {
+    const line = `${timestamp()} ${prefix} ERROR: ${message}`;
+    console.error(line);
+    this.append(line);
+  }
+
+  /** File-only diagnostic log line. */
+  debug(prefix: string, message: string): void {
+    this.append(`${timestamp()} ${prefix} DEBUG: ${message}`);
+  }
+
+  /** File-only visual separator with title. */
+  section(title: string): void {
+    this.append(`\n━━━ ${title} ━━━`);
+  }
+
+  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
+  quiet(message: string): void {
+    this.append(message);
+  }
+
+  private append(line: string): void {
+    try {
+      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
+    } catch {
+      // Swallow log write failures; engine correctness shouldn't depend on logging.
+    }
+  }
+
+  get path(): string {
+    return this.filePath;
+  }
+
+  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
+  get dir(): string {
+    return this.runDir;
+  }
+}
+
+function timestamp(): string {
+  const d = new Date();
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mm = String(d.getMinutes()).padStart(2, '0');
+  const ss = String(d.getSeconds()).padStart(2, '0');
+  const ms = String(d.getMilliseconds()).padStart(3, '0');
+  return `${hh}:${mm}:${ss}.${ms}`;
+}
+
+/** Return the last `n` non-empty lines of `text`, joined with newlines. */
+export function tailLines(text: string, n: number): string {
+  if (!text) return '';
+  const lines = text.split(/\r?\n/).filter(l => l.length > 0);
+  return lines.slice(-n).join('\n');
+}
+
+/**
+ * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
+ * appending a marker when truncation occurred.
+ * Uses TextEncoder so CJK and emoji (multi-byte) characters are counted correctly.
+ */
+export function clip(text: string, maxBytes = 16 * 1024): string {
+  if (!text) return '';
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(text);
+  if (bytes.length <= maxBytes) return text;
+  const omittedBytes = bytes.length - maxBytes;
+  // TextDecoder handles partial code-point boundaries safely (replacement char insertion)
+  const truncated = new TextDecoder().decode(bytes.slice(0, maxBytes));
+  return truncated + `\n…[truncated ${omittedBytes} bytes]`;
+}

package/src/middlewares/static-context.ts

@@ -1,29 +1,29 @@
-import { basename } from 'path';
-import type { MiddlewarePlugin, MiddlewareContext } from '../types';
-import { validatePath } from '../utils';
-
-export const StaticContextMiddleware: MiddlewarePlugin = {
-  name: 'static_context',
-
-  async enhance(
-    prompt: string,
-    config: Record<string, unknown>,
-    ctx: MiddlewareContext,
-  ): Promise<string> {
-    const filePath = config.file as string;
-    if (!filePath) throw new Error('static_context middleware: "file" is required');
-
-    const safePath = validatePath(filePath, ctx.workDir);
-    const file = Bun.file(safePath);
-
-    if (!(await file.exists())) {
-      console.warn(`static_context: file ${filePath} not found, skipping`);
-      return prompt;
-    }
-
-    const content = await file.text();
-    const label = (config.label as string) ?? `Reference: ${basename(filePath)}`;
-
-    return `[${label}]\n${content}\n\n[Task]\n${prompt}`;
-  },
-};
+import { basename } from 'path';
+import type { MiddlewarePlugin, MiddlewareContext } from '../types';
+import { validatePath } from '../utils';
+
+export const StaticContextMiddleware: MiddlewarePlugin = {
+  name: 'static_context',
+
+  async enhance(
+    prompt: string,
+    config: Record<string, unknown>,
+    ctx: MiddlewareContext,
+  ): Promise<string> {
+    const filePath = config.file as string;
+    if (!filePath) throw new Error('static_context middleware: "file" is required');
+
+    const safePath = validatePath(filePath, ctx.workDir);
+    const file = Bun.file(safePath);
+
+    if (!(await file.exists())) {
+      console.warn(`static_context: file ${filePath} not found, skipping`);
+      return prompt;
+    }
+
+    const content = await file.text();
+    const label = (config.label as string) ?? `Reference: ${basename(filePath)}`;
+
+    return `[${label}]\n${content}\n\n[Task]\n${prompt}`;
+  },
+};