negotium 0.1.7 → 0.1.9

package/dist/runtime/src/media/file-events.ts

@@ -0,0 +1,33 @@
+import { FILE_TAG_REGEX } from "#platform/config";
+import type { UnifiedEvent } from "#types";
+
+/**
+ * Yield `file` events for explicit [FILE:...] tags in `text`.
+ * Shared between provider implementations (claude.ts, codex.ts, maestro) so the
+ * fallback tag recognition rule stays in one place.
+ */
+export function* extractFileEvents(text: string, source: string): Generator<UnifiedEvent> {
+  const tagRegex = new RegExp(FILE_TAG_REGEX.source, "gi");
+  let match: RegExpExecArray | null = tagRegex.exec(text);
+  while (match !== null) {
+    yield { type: "file", path: match[1], source, origin: "tag" };
+    match = tagRegex.exec(text);
+  }
+}
+
+/** Absolute paths referenced by explicit `[FILE:/abs/path]` tags, deduped,
+ *  in order of first appearance. Channel adapters use this to send produced
+ *  files alongside the text. */
+export function extractFileTagPaths(text: string): string[] {
+  const seen = new Set<string>();
+  for (const event of extractFileEvents(text, "tag")) {
+    if (event.type === "file") seen.add(event.path);
+  }
+  return [...seen];
+}
+
+/** Remove `[FILE:...]` tags from outbound text — the files are delivered as
+ *  real attachments by the channel, so the raw tags are just noise. */
+export function stripFileTags(text: string): string {
+  return text.replace(new RegExp(FILE_TAG_REGEX.source, "gi"), "").trim();
+}

package/dist/runtime/src/media/text-extractor.ts

@@ -0,0 +1,312 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { promisify } from "node:util";
+import {
+  FASTER_WHISPER_WRAPPER,
+  FFMPEG_BIN as FFMPEG_BIN_ENV,
+  PDFTOTEXT_BIN,
+  PYTHON_BIN,
+  TESSERACT_BIN,
+  WHISPER_MODEL,
+} from "#platform/config";
+import { errMsg } from "#platform/error";
+import { logger } from "#platform/logger";
+
+const execFileAsync = promisify(execFile);
+
+// FFMPEG_BIN은 이 모듈에서 필수 — 미설정 시 기존처럼 spawn 시점에 실패한다.
+const FFMPEG_BIN = FFMPEG_BIN_ENV as string;
+
+/** Text-readable file extensions */
+const TEXT_EXTENSIONS = new Set([
+  ".txt",
+  ".md",
+  ".csv",
+  ".tsv",
+  ".json",
+  ".jsonl",
+  ".xml",
+  ".html",
+  ".htm",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".cfg",
+  ".conf",
+  ".log",
+  ".env",
+  ".js",
+  ".ts",
+  ".jsx",
+  ".tsx",
+  ".py",
+  ".rb",
+  ".go",
+  ".java",
+  ".c",
+  ".cpp",
+  ".h",
+  ".hpp",
+  ".rs",
+  ".swift",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".fish",
+  ".ps1",
+  ".sql",
+  ".graphql",
+  ".proto",
+  ".css",
+  ".scss",
+  ".less",
+  ".sass",
+  ".r",
+  ".R",
+  ".m",
+  ".pl",
+  ".lua",
+  ".dart",
+]);
+
+/** Image extensions for OCR */
+const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".tif", ".webp"]);
+
+export interface ExtractionResult {
+  text: string | null;
+  method: "text-read" | "pdf" | "ocr" | "whisper" | "unsupported";
+  error?: string;
+}
+
+/** Extract text from a file based on its type */
+export async function extractText(filePath: string): Promise<ExtractionResult> {
+  const ext = extname(filePath).toLowerCase();
+
+  // Text files — direct read
+  if (TEXT_EXTENSIONS.has(ext)) {
+    return extractFromTextFile(filePath);
+  }
+
+  // PDF — pdftotext
+  if (ext === ".pdf") {
+    return extractFromPdf(filePath);
+  }
+
+  // Images — OCR
+  if (IMAGE_EXTENSIONS.has(ext)) {
+    return extractFromImage(filePath);
+  }
+
+  // Audio/Video — whisper
+  if (
+    [
+      ".mp3",
+      ".wav",
+      ".ogg",
+      ".m4a",
+      ".flac",
+      ".aac",
+      ".wma",
+      ".mp4",
+      ".webm",
+      ".mkv",
+      ".avi",
+      ".mov",
+    ].includes(ext)
+  ) {
+    return extractFromAudio(filePath);
+  }
+
+  // Try reading as text (might work for unknown text formats)
+  try {
+    const buf = await readFile(filePath);
+    if (buf.length === 0) {
+      return { text: null, method: "unsupported", error: "Empty file" };
+    }
+    // Check first 8KB for binary content (non-printable chars)
+    const sample = buf.subarray(0, 8192);
+    let nonPrintable = 0;
+    for (let i = 0; i < sample.length; i++) {
+      const b = sample[i];
+      if (b < 32 && b !== 9 && b !== 10 && b !== 13) nonPrintable++;
+    }
+    if (nonPrintable / sample.length > 0.1) {
+      return { text: null, method: "unsupported", error: "Binary file, cannot extract text" };
+    }
+    return { text: buf.toString("utf-8"), method: "text-read" };
+  } catch (e) {
+    logger.warn({ err: e, filePath, ext }, "Text extraction failed");
+    return { text: null, method: "unsupported", error: `Unsupported file type: ${ext}` };
+  }
+}
+
+/** Read a text file directly */
+function extractFromTextFile(filePath: string): ExtractionResult {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return { text: content, method: "text-read" };
+  } catch (e) {
+    return {
+      text: null,
+      method: "text-read",
+      error: `Failed to read: ${errMsg(e)}`,
+    };
+  }
+}
+
+/** Extract text from PDF using pdftotext */
+async function extractFromPdf(filePath: string): Promise<ExtractionResult> {
+  try {
+    const { stdout } = await execFileAsync(PDFTOTEXT_BIN, ["-layout", filePath, "-"], {
+      timeout: 30000,
+    });
+    const text = stdout.trim();
+    if (!text) {
+      // PDF might be image-based, try OCR approach
+      return {
+        text: null,
+        method: "pdf",
+        error: "PDF contains no extractable text (may be image-based)",
+      };
+    }
+    return { text, method: "pdf" };
+  } catch (e) {
+    logger.debug({ err: e, filePath }, "pdftotext failed");
+    return {
+      text: null,
+      method: "pdf",
+      error: `pdftotext failed: ${errMsg(e)}`,
+    };
+  }
+}
+
+/** Extract text from image using tesseract OCR */
+async function extractFromImage(filePath: string): Promise<ExtractionResult> {
+  try {
+    const { stdout } = await execFileAsync(
+      TESSERACT_BIN,
+      [filePath, "stdout", "-l", "kor+eng", "--psm", "3"],
+      { timeout: 60000 },
+    );
+    const text = stdout.trim();
+    if (!text) {
+      return { text: null, method: "ocr", error: "OCR produced no text" };
+    }
+    return { text, method: "ocr" };
+  } catch (e) {
+    logger.debug({ err: e, filePath }, "tesseract OCR failed");
+    return {
+      text: null,
+      method: "ocr",
+      error: `OCR failed: ${errMsg(e)}`,
+    };
+  }
+}
+
+/** Injectable binaries/paths for {@link transcribeAudio} — defaults come from
+ *  `#platform/config` env (PYTHON_BIN / FASTER_WHISPER_WRAPPER / FFMPEG_BIN /
+ *  WHISPER_MODEL_FILE); overrides exist for custom hosts and token-free tests. */
+export interface TranscribeAudioOptions {
+  ffmpegBin?: string;
+  pythonBin?: string;
+  wrapperPath?: string;
+  model?: string;
+  language?: string;
+}
+
+/** True when the local faster-whisper pipeline can run: an ffmpeg binary is
+ *  configured and the Python wrapper script exists on disk. */
+export function isTranscriptionConfigured(opts: TranscribeAudioOptions = {}): boolean {
+  const ffmpeg = opts.ffmpegBin ?? FFMPEG_BIN_ENV;
+  const wrapper = opts.wrapperPath ?? FASTER_WHISPER_WRAPPER;
+  return Boolean(ffmpeg) && existsSync(wrapper);
+}
+
+/**
+ * Transcribe an audio/voice file with the local faster-whisper pipeline.
+ * Returns `null` when transcription is not configured on this node (missing
+ * ffmpeg/wrapper) or when the pipeline fails/produces no text — callers treat
+ * null as "no transcript available", never as an error.
+ */
+export async function transcribeAudio(
+  filePath: string,
+  opts: TranscribeAudioOptions = {},
+): Promise<string | null> {
+  if (!isTranscriptionConfigured(opts)) return null;
+  const result = await extractFromAudio(filePath, opts);
+  return result.text;
+}
+
+/** Extract text from audio/video using whisper */
+async function extractFromAudio(
+  filePath: string,
+  opts: TranscribeAudioOptions = {},
+): Promise<ExtractionResult> {
+  const tmpDir = `${filePath}_whisper_tmp`;
+  try {
+    mkdirSync(tmpDir, { recursive: true });
+
+    // Convert to mp3 first
+    const mp3Path = join(tmpDir, "audio.mp3");
+    await execFileAsync(
+      opts.ffmpegBin ?? FFMPEG_BIN,
+      [
+        "-y",
+        "-i",
+        filePath,
+        "-acodec",
+        "libmp3lame",
+        "-q:a",
+        "4",
+        "-ac",
+        "1",
+        "-ar",
+        "16000",
+        mp3Path,
+      ],
+      { timeout: 60000 },
+    );
+
+    // Run faster-whisper via Python wrapper
+    await execFileAsync(
+      opts.pythonBin ?? PYTHON_BIN,
+      [
+        opts.wrapperPath ?? FASTER_WHISPER_WRAPPER,
+        mp3Path,
+        "--model",
+        opts.model ?? WHISPER_MODEL,
+        "--language",
+        opts.language ?? "ko",
+        "--output-dir",
+        tmpDir,
+        "--output-format",
+        "txt",
+      ],
+      { timeout: 120000 },
+    );
+
+    const txtPath = join(tmpDir, "audio.txt");
+    const text = existsSync(txtPath) ? readFileSync(txtPath, "utf-8").trim() : null;
+
+    if (!text) {
+      return { text: null, method: "whisper", error: "Whisper produced no text" };
+    }
+    return { text, method: "whisper" };
+  } catch (e) {
+    logger.debug({ err: e, filePath }, "whisper extraction failed");
+    return {
+      text: null,
+      method: "whisper",
+      error: `Whisper failed: ${errMsg(e)}`,
+    };
+  } finally {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch (e) {
+      logger.warn({ err: e, tmpDir }, "Failed to cleanup whisper tmpDir");
+    }
+  }
+}

package/dist/runtime/src/media/video.ts

@@ -0,0 +1,92 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { FFMPEG_BIN, FFPROBE_BIN } from "#platform/config";
+import { logger } from "#platform/logger";
+
+const FFMPEG = FFMPEG_BIN ?? "ffmpeg";
+const FFPROBE = FFPROBE_BIN ?? "ffprobe";
+
+interface VideoPreview {
+  thumbnail: string | null; // path to single thumbnail image
+  duration: number; // seconds
+  outputDir: string; // dir for agent to use for further extraction
+}
+
+/** Get video duration in seconds */
+function getDurationSeconds(videoPath: string): number {
+  try {
+    const out = execFileSync(
+      FFPROBE,
+      [
+        "-v",
+        "error",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=noprint_wrappers=1:nokey=1",
+        videoPath,
+      ],
+      { encoding: "utf-8" },
+    ).trim();
+    return parseFloat(out) || 0;
+  } catch (err) {
+    logger.warn({ err, videoPath }, "video: Failed to get duration");
+    return 0;
+  }
+}
+
+/** Extract single thumbnail from ~30% point of video */
+function extractThumbnail(videoPath: string, outputDir: string, duration: number): string | null {
+  const timestamp = duration * 0.3;
+  const outFile = join(outputDir, "thumbnail.jpg");
+  try {
+    execFileSync(
+      FFMPEG,
+      ["-y", "-ss", timestamp.toFixed(2), "-i", videoPath, "-vframes", "1", "-q:v", "2", outFile],
+      { timeout: 15000, stdio: "pipe" },
+    );
+    return existsSync(outFile) ? outFile : null;
+  } catch (err) {
+    logger.warn({ err, videoPath, outputDir }, "video: Failed to extract thumbnail");
+    return null;
+  }
+}
+
+/** Lightweight video preview: 1 thumbnail only. Agent handles the rest via skill. */
+export async function previewVideo(videoPath: string, uploadDir: string): Promise<VideoPreview> {
+  const baseName =
+    videoPath
+      .split("/")
+      .pop()
+      ?.replace(/\.[^.]+$/, "") || "video";
+  const outputDir = join(uploadDir, `${baseName}_analysis`);
+  mkdirSync(outputDir, { recursive: true });
+
+  const duration = getDurationSeconds(videoPath);
+  const thumbnail = duration > 0 ? extractThumbnail(videoPath, outputDir, duration) : null;
+
+  return { thumbnail, duration, outputDir };
+}
+
+/** Build prompt text for the video */
+export function buildVideoPrompt(videoPath: string, preview: VideoPreview): string {
+  const fileName = videoPath.split("/").pop() || "video";
+  const lines: string[] = [];
+
+  lines.push(`[Attached video: ${fileName} at path: ${videoPath}]`);
+  lines.push(
+    `(영상 길이: ${Math.round(preview.duration)}초, 분석용 디렉토리: ${preview.outputDir})`,
+  );
+
+  if (preview.thumbnail) {
+    lines.push(`\n미리보기 프레임 1장:`);
+    lines.push(`[Attached file: thumbnail.jpg at path: ${preview.thumbnail}]`);
+  }
+
+  lines.push(`\n⚠️ 동영상입니다. video-understanding 스킬을 참고하여 분석해주세요.`);
+  lines.push(`1단계: whisper로 음성 변환 → 텍스트 문맥 교정`);
+  lines.push(`2단계: 텍스트 기반으로 핵심 장면 타이밍에 ffmpeg 프레임 추출`);
+
+  return lines.join("\n");
+}

package/dist/runtime/src/outbox/file-ops.ts

@@ -0,0 +1,210 @@
+import { appendFileSync, existsSync, readFileSync, renameSync, unlinkSync } from "node:fs";
+import { readJsonlLines } from "#platform/jsonl";
+import { logger } from "#platform/logger";
+
+const PROCESSING_SUFFIX = ".processing";
+
+/** True if `name` is an in-flight `.processing` claim file written by drainOutboxFile. */
+export function isProcessingFile(name: string): boolean {
+  return name.endsWith(PROCESSING_SUFFIX);
+}
+
+function tryUnlink(path: string, label: string, reason: string) {
+  try {
+    unlinkSync(path);
+  } catch (e) {
+    // ENOENT means another path already cleaned this up (e.g. concurrent
+    // drain, double-delete in a retry loop). Not worth warning about.
+    if ((e as NodeJS.ErrnoException)?.code === "ENOENT") {
+      logger.debug({ path }, `${label}: ${reason} (already gone)`);
+      return;
+    }
+    logger.warn({ err: e, path }, `${label}: ${reason}`);
+  }
+}
+
+/**
+ * Atomically claim a .jsonl outbox file for processing.
+ * Recovers leftover .processing files from crashes, renames the pending file
+ * to .processing to prevent race conditions, and returns the parsed lines.
+ * Returns null if the file doesn't exist or can't be claimed.
+ *
+ * Partial-failure edge case: when a crash leftover is merged back into pending,
+ * `readFileSync` → `appendFileSync` → `unlinkSync` runs sequentially. If
+ * `appendFileSync` throws mid-write (e.g. ENOSPC), the pending file receives a
+ * partial copy of the leftover and the catch branch still unlinks the leftover
+ * to avoid an infinite retry loop — so the tail of the leftover can be lost.
+ * In practice the next drain parses the partial line as invalid JSON and drops
+ * it via `parseOutboxLine`. This is a deliberate trade-off: we accept the rare
+ * partial loss instead of stalling the outbox when the disk is full.
+ */
+export function drainOutboxFile(
+  filePath: string,
+  label: string,
+): { lines: string[]; processingPath: string } | null {
+  const processingPath = filePath + PROCESSING_SUFFIX;
+  const hasPending = existsSync(filePath);
+  const hasLeftover = existsSync(processingPath);
+
+  // Merge leftover into pending before claim.
+  // hasPending=false: normal crash recovery — leftover is all we have.
+  // hasPending=true:  crash + writer race — without merge, the rename below
+  //                   would overwrite leftover and drop its lines.
+  if (hasLeftover) {
+    // warn on crash+race (rare), info on plain recovery (expected after crash)
+    const logMsg = `${label}: merging leftover .processing before claim`;
+    const logCtx = { filePath, processingPath, hadPending: hasPending };
+    if (hasPending) logger.warn(logCtx, logMsg);
+    else logger.info(logCtx, logMsg);
+    try {
+      const leftover = readFileSync(processingPath, "utf-8");
+      if (leftover) appendFileSync(filePath, leftover.endsWith("\n") ? leftover : `${leftover}\n`);
+      unlinkSync(processingPath);
+    } catch (e) {
+      logger.error(
+        { err: e, processingPath },
+        `${label}: failed to merge leftover — data may be lost`,
+      );
+      tryUnlink(processingPath, label, "failed to clean up leftover after merge error");
+    }
+  }
+
+  if (!existsSync(filePath)) return null;
+
+  // Atomically rename to prevent race condition with writer
+  try {
+    renameSync(filePath, processingPath);
+  } catch (e) {
+    logger.warn({ err: e, filePath }, `${label}: failed to rename for processing`);
+    return null;
+  }
+
+  // Read lines
+  try {
+    const lines = readJsonlLines(processingPath);
+    return { lines, processingPath };
+  } catch (e) {
+    logger.warn({ err: e, processingPath }, `${label}: failed to read processing file`);
+    tryUnlink(processingPath, label, "failed to delete corrupt processing file");
+    return null;
+  }
+}
+
+/**
+ * Delete the .processing file after all entries are consumed.
+ *
+ * Writer-race salvage: `appendFileSync` racing `drainOutboxFile`'s rename can
+ * land a line on the claimed inode AFTER the drainer already read it. Without
+ * a recheck, unlinking here would silently destroy that entry. When
+ * `consumedLines` is provided, any lines beyond it are appended back to the
+ * original pending file before the claim is deleted (at-least-once preserved).
+ */
+export function deleteProcessingFile(
+  processingPath: string,
+  label: string,
+  consumedLines?: number,
+) {
+  if (consumedLines !== undefined && processingPath.endsWith(PROCESSING_SUFFIX)) {
+    try {
+      const current = readJsonlLines(processingPath);
+      if (current.length > consumedLines) {
+        const pendingPath = processingPath.slice(0, -PROCESSING_SUFFIX.length);
+        const tail = current.slice(consumedLines).join("\n");
+        appendFileSync(pendingPath, `${tail}\n`);
+        logger.warn(
+          { processingPath, salvaged: current.length - consumedLines },
+          `${label}: writer raced the drain — salvaged late lines back to pending`,
+        );
+      }
+    } catch (e) {
+      logger.warn({ err: e, processingPath }, `${label}: writer-race recheck failed`);
+    }
+  }
+  tryUnlink(processingPath, label, "failed to delete processing file");
+}
+
+/**
+ * Parse a single JSONL line. Returns null (and logs an error) on invalid JSON.
+ * Keeps the parse + error-log pattern in one place instead of repeating it in
+ * every flush function.
+ */
+export function parseOutboxLine<T>(line: string, label: string): T | null {
+  try {
+    return JSON.parse(line) as T;
+  } catch {
+    logger.error({ label, line: line.slice(0, 120) }, `${label}: Invalid JSON, dropping`);
+    return null;
+  }
+}
+
+/**
+ * Drain an outbox file and invoke `handler` for each parsed entry.
+ * Handles drain → parse → process → delete-processing → write-back-failures in one call.
+ *
+ * `handler` should throw to signal a retryable failure.
+ * Failed entries are written back to `filePath` for the next flush cycle.
+ * Pass `maxRetries` to drop entries that have exceeded the retry budget.
+ *
+ * Delivery: at-least-once. The `.processing` claim is deleted only AFTER all
+ * entries were handled — a crash mid-processing leaves the claim on disk and
+ * the next drain's leftover-merge redelivers the whole batch (including
+ * already-handled entries). Handlers must therefore be idempotent or accept
+ * duplicates; deleting the claim up-front would instead silently lose every
+ * unprocessed entry on crash, which is worse for every queue using this path.
+ */
+export async function processOutboxFile<T extends Record<string, unknown>>(
+  filePath: string,
+  label: string,
+  handler: (entry: T) => Promise<void>,
+  opts: { maxRetries?: number } = {},
+): Promise<void> {
+  const drained = drainOutboxFile(filePath, label);
+  if (!drained) return;
+  const { lines, processingPath } = drained;
+
+  if (lines.length === 0) {
+    deleteProcessingFile(processingPath, label, 0);
+    return;
+  }
+
+  const MAX_RETRIES = opts.maxRetries ?? 0;
+  const failedLines: string[] = [];
+
+  for (const line of lines) {
+    const entry = parseOutboxLine<T>(line, label);
+    if (!entry) continue;
+
+    const retryCount = (entry.retryCount as number | undefined) ?? 0;
+    try {
+      await handler(entry);
+    } catch (err) {
+      if (MAX_RETRIES > 0) {
+        const next = retryCount + 1;
+        if (next >= MAX_RETRIES) {
+          logger.error({ err, label, retryCount: next }, `${label}: Max retries reached, dropping`);
+        } else {
+          logger.warn({ err, label, retryCount: next }, `${label}: Failed, will retry`);
+          failedLines.push(JSON.stringify({ ...entry, retryCount: next }));
+        }
+      } else {
+        logger.error({ err, label }, `${label}: Failed to process entry`);
+      }
+    }
+  }
+
+  // Drop the claim before writing failures back (same order as dm-queue):
+  // a crash between the two redelivers nothing extra, while the reverse
+  // order could double the failed entries (write-back + leftover merge).
+  deleteProcessingFile(processingPath, label, lines.length);
+
+  if (failedLines.length > 0) {
+    try {
+      appendFileSync(filePath, `${failedLines.join("\n")}\n`);
+    } catch (e) {
+      logger.error(
+        { err: e, label, count: failedLines.length },
+        `${label}: Failed to write back entries`,
+      );
+    }
+  }
+}

package/dist/runtime/src/outbox/index.ts

@@ -0,0 +1,8 @@
+export {
+  deleteProcessingFile,
+  drainOutboxFile,
+  isProcessingFile,
+  parseOutboxLine,
+  processOutboxFile,
+} from "./file-ops";
+export { debouncedFlush, FALLBACK_INTERVAL_MS, watchDir } from "./utils";