lilflow 0.1.0

package/src/agents/index.js

@@ -0,0 +1,228 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { runOpencode } from "./opencode.js";
+import { runClaudeCode } from "./claude-code.js";
+import { resolvePromptInput } from "./prompt.js";
+import { getSessionId, loadSessionStore, saveSessionId } from "./session-store.js";
+
+const PROVIDERS = {
+  opencode: {
+    defaultBin: "opencode",
+    configKey: "agent.opencode.bin",
+    run: runOpencode
+  },
+  "claude-code": {
+    defaultBin: "claude",
+    configKey: "agent.claude.bin",
+    run: runClaudeCode
+  }
+};
+
+/**
+ * Return the list of supported agent providers.
+ *
+ * @returns {string[]} Provider names.
+ */
+export function getSupportedProviders() {
+  return Object.keys(PROVIDERS);
+}
+
+/**
+ * Execute an agent step. Resolves the binary, loads any prior session for
+ * `session: continue`, resolves the prompt input, delegates to the provider
+ * adapter, and persists any new session ID returned by the agent.
+ *
+ * @param {object} options - Dispatch options.
+ * @param {{name: string, agent: object}} options.step - Normalized step definition.
+ * @param {string} options.cwd - Workflow working directory.
+ * @param {object} options.env - Step environment.
+ * @param {number} options.timeoutMs - Step timeout in milliseconds.
+ * @param {object} options.config - Flow config (used to resolve binary overrides).
+ * @param {string} options.runId - Current workflow run ID.
+ * @param {(message: string) => void} options.warn - Warning sink used when session continue fails.
+ * @param {typeof import("node:child_process").spawn} [options.spawnProcess] - Child process factory (tests).
+ * @param {{isCancelled: () => boolean, getReason: () => string | null, trackChild: (child: import("node:child_process").ChildProcess) => () => void}} [options.cancellation] - Cancellation controller.
+ * @returns {Promise<{exitCode: number, stdout: string, stderr: string, combinedOutput: string, costUsd: number | null, sessionId: string | null}>} Agent run result.
+ */
+export async function executeAgentStep(options) {
+  const {
+    step,
+    cwd,
+    env,
+    timeoutMs,
+    config,
+    runId,
+    warn,
+    spawnProcess,
+    cancellation = null,
+    templateFn = (value) => value
+  } = options;
+  const agentSpec = step.agent;
+  const providerName = agentSpec.provider;
+  const provider = PROVIDERS[providerName];
+
+  if (!provider) {
+    throw new AgentDispatchError(
+      `Unknown agent provider '${providerName}'. Supported: ${getSupportedProviders().join(", ")}.`,
+      "AGENT_UNKNOWN_PROVIDER"
+    );
+  }
+
+  const binary = await resolveAgentBinary(providerName, config, env);
+
+  let sessionId = null;
+
+  if (agentSpec.session === "continue") {
+    const store = await loadSessionStore(cwd, runId);
+    sessionId = getSessionId(store, step.name);
+
+    if (sessionId === null && typeof warn === "function") {
+      warn(
+        `Agent step '${step.name}' requested session: continue but no prior session exists for this step; starting fresh.`
+      );
+    }
+  }
+
+  // Resolve prompt input from the RAW (untemplated) value first, then template
+  // the resolved text. This prevents templated content (e.g. a `{{steps.x.stdout}}`
+  // that happens to start with `./`) from being mis-interpreted as a file path.
+  const rawPrompt = agentSpec.prompt;
+  const promptText = await resolvePromptInput(rawPrompt, cwd);
+  const templatedPrompt = templateFn(promptText);
+
+  if (typeof templatedPrompt !== "string" || templatedPrompt.trim() === "") {
+    throw new AgentDispatchError(
+      `Agent step '${step.name}' resolved to an empty prompt after templating; refusing to invoke ${providerName} with no input.`,
+      "AGENT_EMPTY_PROMPT"
+    );
+  }
+
+  const templatedAppendSystemPrompt = agentSpec.append_system_prompt === undefined
+    ? undefined
+    : templateFn(agentSpec.append_system_prompt);
+  const result = await provider.run({
+    bin: binary,
+    prompt: templatedPrompt,
+    model: agentSpec.model,
+    sessionId,
+    timeoutMs,
+    cwd,
+    env,
+    interactive: agentSpec.interactive === true,
+    plugins: agentSpec.plugins ?? [],
+    allowTools: agentSpec.allow_tools ?? [],
+    appendSystemPrompt: templatedAppendSystemPrompt,
+    sourceAccess: agentSpec.source_access !== false,
+    spawnProcess,
+    cancellation
+  });
+
+  if (result.sessionId) {
+    if (isSafeSessionId(result.sessionId)) {
+      await saveSessionId(cwd, runId, step.name, providerName, result.sessionId);
+    } else if (typeof warn === "function") {
+      warn(
+        `Agent step '${step.name}' returned an unsafe session_id; not persisting (would risk CLI flag injection on resume).`
+      );
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validate that a session ID is safe to pass back to a CLI as a `--continue`
+ * or `--resume` argument value on the next run.
+ *
+ * @param {string} sessionId - Session identifier captured from agent output.
+ * @returns {boolean} True when the ID is alphanumeric/dash/underscore/dot only.
+ */
+export function isSafeSessionId(sessionId) {
+  return typeof sessionId === "string"
+    && sessionId.length > 0
+    && sessionId.length <= 256
+    && /^[A-Za-z0-9_.][A-Za-z0-9_.-]*$/.test(sessionId);
+}
+
+/**
+ * Resolve the absolute path (or bare command name) used to launch an agent.
+ *
+ * Resolution order:
+ *   1. `config.agent.<provider>.bin` override
+ *   2. `$PATH` lookup for the provider's default binary
+ *
+ * @param {string} providerName - Provider name (e.g. `opencode`).
+ * @param {object} config - Flow config.
+ * @param {object} env - Process environment used for PATH lookup.
+ * @returns {Promise<string>} Resolved binary path.
+ */
+export async function resolveAgentBinary(providerName, config, env) {
+  const provider = PROVIDERS[providerName];
+
+  if (!provider) {
+    throw new AgentDispatchError(
+      `Unknown agent provider '${providerName}'.`,
+      "AGENT_UNKNOWN_PROVIDER"
+    );
+  }
+
+  const configKey = providerName === "claude-code" ? "claude" : providerName;
+  const override = config?.agent?.[configKey]?.bin;
+
+  if (typeof override === "string" && override.trim() !== "") {
+    return override;
+  }
+
+  const found = await findOnPath(provider.defaultBin, env);
+
+  if (found === null) {
+    throw new AgentDispatchError(
+      `Could not find '${provider.defaultBin}' on PATH. Set '${provider.configKey}' in flow config or install the CLI.`,
+      "AGENT_BINARY_NOT_FOUND"
+    );
+  }
+
+  return found;
+}
+
+/**
+ * Locate a binary on `$PATH`. Returns the absolute path or `null` when absent.
+ *
+ * @param {string} binary - Bare binary name.
+ * @param {object} env - Environment providing `PATH`.
+ * @returns {Promise<string | null>} Resolved path or null.
+ */
+async function findOnPath(binary, env) {
+  const pathValue = env?.PATH ?? "";
+  const separator = process.platform === "win32" ? ";" : ":";
+  const segments = pathValue.split(separator).filter((segment) => segment !== "");
+
+  for (const segment of segments) {
+    const candidate = path.join(segment, binary);
+
+    try {
+      await access(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Error thrown when an agent step cannot be dispatched.
+ */
+export class AgentDispatchError extends Error {
+  /**
+   * @param {string} message - Human-readable error message.
+   * @param {string} code - Stable machine-readable error code.
+   */
+  constructor(message, code) {
+    super(message);
+    this.name = "AgentDispatchError";
+    this.code = code;
+  }
+}

package/src/agents/ndjson.js

@@ -0,0 +1,67 @@
+/**
+ * Line-buffered NDJSON parser that tolerates malformed lines and chunk splits.
+ *
+ * Usage:
+ *   const buffer = createNdjsonBuffer();
+ *   for (const chunk of stdoutChunks) {
+ *     const events = buffer.push(chunk);
+ *     for (const event of events) { ... }
+ *   }
+ *   const trailingEvents = buffer.flush();
+ *
+ * Malformed lines are surfaced as `{ __malformed: "<raw line>" }` so callers
+ * can log or ignore without losing the stream.
+ *
+ * @returns {{push: (chunk: string) => object[], flush: () => object[]}} Buffer API.
+ */
+export function createNdjsonBuffer() {
+  let pending = "";
+
+  return {
+    push(chunk) {
+      if (chunk === undefined || chunk === null) {
+        return [];
+      }
+
+      pending += String(chunk);
+      const lines = pending.split("\n");
+      pending = lines.pop() ?? "";
+
+      return parseLines(lines);
+    },
+    flush() {
+      if (pending.trim() === "") {
+        pending = "";
+        return [];
+      }
+
+      const events = parseLines([pending]);
+      pending = "";
+      return events;
+    }
+  };
+}
+
+/**
+ * @param {string[]} lines - Raw NDJSON lines.
+ * @returns {object[]} Parsed objects; malformed lines surfaced as `{__malformed}`.
+ */
+function parseLines(lines) {
+  const events = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "") {
+      continue;
+    }
+
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+      events.push({ __malformed: trimmed });
+    }
+  }
+
+  return events;
+}

package/src/agents/opencode.js

@@ -0,0 +1,290 @@
+import { spawn } from "node:child_process";
+import { createNdjsonBuffer } from "./ndjson.js";
+
+/**
+ * Run the `opencode` CLI as a headless or interactive agent step.
+ *
+ * In headless mode, output is captured and NDJSON events are parsed to
+ * extract `cost_usd` and `session_id` from the final `result` event. The
+ * assistant's final text (if present) becomes the step stdout.
+ *
+ * In interactive mode, stdio is inherited so the user can drive the
+ * agent directly from the terminal. No NDJSON parsing occurs.
+ *
+ * @param {object} options - Invocation options.
+ * @param {string} options.bin - Resolved binary path for the `opencode` CLI.
+ * @param {string} options.prompt - Final prompt text (already templated and resolved).
+ * @param {string} [options.model] - Optional model identifier.
+ * @param {string | null} [options.sessionId] - Prior session ID to continue, or null for fresh.
+ * @param {number} options.timeoutMs - Step timeout in milliseconds.
+ * @param {string} options.cwd - Working directory.
+ * @param {object} options.env - Process environment.
+ * @param {boolean} [options.interactive=false] - Whether to run with TTY passthrough.
+ * @param {string[]} [options.plugins] - Optional plugin names passed with `--plugin`.
+ * @param {typeof spawn} [options.spawnProcess=spawn] - Child process factory (for tests).
+ * @param {{isCancelled: () => boolean, getReason: () => string | null, trackChild: (child: import("node:child_process").ChildProcess) => () => void}} [options.cancellation] - Cancellation controller.
+ * @returns {Promise<{exitCode: number, stdout: string, stderr: string, combinedOutput: string, costUsd: number | null, sessionId: string | null}>} Agent run result.
+ */
+export function runOpencode(options) {
+  const {
+    bin,
+    prompt,
+    model,
+    sessionId = null,
+    timeoutMs,
+    cwd,
+    env,
+    interactive = false,
+    plugins = [],
+    spawnProcess = spawn,
+    cancellation = null
+  } = options;
+
+  const args = ["run", "--format", "json"];
+
+  if (model) {
+    args.push("--model", model);
+  }
+
+  if (sessionId) {
+    args.push("--continue", sessionId);
+  }
+
+  for (const plugin of plugins) {
+    args.push("--plugin", plugin);
+  }
+
+  // `--` separator ensures a prompt starting with `-` is not parsed as a flag.
+  args.push("--", prompt);
+
+  if (interactive) {
+    return spawnInteractive({ bin, args, cwd, env, timeoutMs, cancellation, spawnProcess });
+  }
+
+  return spawnHeadless({ bin, args, cwd, env, timeoutMs, cancellation, spawnProcess });
+}
+
+/**
+ * @param {object} options - Spawn options.
+ * @returns {Promise<{exitCode: number, stdout: string, stderr: string, combinedOutput: string, costUsd: number | null, sessionId: string | null}>} Result.
+ */
+function spawnHeadless(options) {
+  const { bin, args, cwd, env, timeoutMs, cancellation, spawnProcess } = options;
+
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(bin, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const untrackChild = cancellation?.trackChild(child) ?? (() => {});
+    const ndjson = createNdjsonBuffer();
+    let stdoutCapture = "";
+    let stderrCapture = "";
+    let combinedOutput = "";
+    let costUsd = null;
+    let sessionId = null;
+    let finalText = "";
+    let settled = false;
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      const text = chunk.toString();
+      stdoutCapture += text;
+      combinedOutput += text;
+
+      for (const event of ndjson.push(text)) {
+        const captured = captureOpencodeEvent(event);
+
+        if (captured.costUsd !== undefined) {
+          costUsd = captured.costUsd;
+        }
+
+        if (captured.sessionId !== undefined) {
+          sessionId = captured.sessionId;
+        }
+
+        if (captured.text !== undefined) {
+          finalText = captured.text;
+        }
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderrCapture += text;
+      combinedOutput += text;
+    });
+
+    child.on("error", (error) => {
+      if (settled) return;
+
+      settled = true;
+      clearTimeout(timer);
+      untrackChild();
+      reject(new Error(`Failed to start opencode agent: ${error.message}`));
+    });
+
+    child.on("close", (code, signal) => {
+      if (settled) return;
+
+      settled = true;
+      clearTimeout(timer);
+      untrackChild();
+
+      for (const event of ndjson.flush()) {
+        const captured = captureOpencodeEvent(event);
+
+        if (captured.costUsd !== undefined) {
+          costUsd = captured.costUsd;
+        }
+
+        if (captured.sessionId !== undefined) {
+          sessionId = captured.sessionId;
+        }
+
+        if (captured.text !== undefined) {
+          finalText = captured.text;
+        }
+      }
+
+      if (timedOut) {
+        reject(Object.assign(new Error("opencode agent timed out"), { code: "STEP_TIMEOUT" }));
+        return;
+      }
+
+      if (signal) {
+        if (cancellation?.isCancelled()) {
+          const reason = cancellation.getReason();
+
+          reject(Object.assign(new Error(`opencode agent cancelled (${reason})`), {
+            code: reason === "STEP_FAILURE" ? "STEP_CANCELLED" : "WORKFLOW_CANCELLED"
+          }));
+          return;
+        }
+
+        reject(new Error(`opencode agent exited due to signal ${signal}`));
+        return;
+      }
+
+      resolve({
+        exitCode: code ?? 1,
+        stdout: finalText !== "" ? finalText : stdoutCapture,
+        stderr: stderrCapture,
+        combinedOutput,
+        costUsd,
+        sessionId
+      });
+    });
+  });
+}
+
+/**
+ * @param {object} options - Spawn options for interactive mode.
+ * @returns {Promise<{exitCode: number, stdout: string, stderr: string, combinedOutput: string, costUsd: null, sessionId: null}>} Result.
+ */
+function spawnInteractive(options) {
+  const { bin, args, cwd, env, timeoutMs, cancellation, spawnProcess } = options;
+  // Strip headless-only flags (`--format json`) and the `--` separator that
+  // only matters when the prompt is a positional arg in headless mode.
+  const interactiveArgs = args.filter((arg, index, array) => {
+    if (arg === "--format" || arg === "--") {
+      return false;
+    }
+
+    if (array[index - 1] === "--format") {
+      return false;
+    }
+
+    return true;
+  });
+
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(bin, interactiveArgs, {
+      cwd,
+      env,
+      stdio: "inherit"
+    });
+    const untrackChild = cancellation?.trackChild(child) ?? (() => {});
+    let settled = false;
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+    }, timeoutMs);
+
+    child.on("error", (error) => {
+      if (settled) return;
+
+      settled = true;
+      clearTimeout(timer);
+      untrackChild();
+      reject(new Error(`Failed to start opencode agent: ${error.message}`));
+    });
+
+    child.on("close", (code, signal) => {
+      if (settled) return;
+
+      settled = true;
+      clearTimeout(timer);
+      untrackChild();
+
+      if (timedOut) {
+        reject(Object.assign(new Error("opencode agent timed out"), { code: "STEP_TIMEOUT" }));
+        return;
+      }
+
+      if (signal) {
+        reject(new Error(`opencode agent exited due to signal ${signal}`));
+        return;
+      }
+
+      resolve({
+        exitCode: code ?? 1,
+        stdout: "",
+        stderr: "",
+        combinedOutput: "",
+        costUsd: null,
+        sessionId: null
+      });
+    });
+  });
+}
+
+/**
+ * @param {object} event - Parsed NDJSON event from opencode.
+ * @returns {{costUsd?: number, sessionId?: string, text?: string}} Captured fields.
+ */
+function captureOpencodeEvent(event) {
+  const captured = {};
+
+  if (event == null || typeof event !== "object") {
+    return captured;
+  }
+
+  if (event.type === "result") {
+    if (typeof event.cost_usd === "number") {
+      captured.costUsd = event.cost_usd;
+    } else if (typeof event.total_cost_usd === "number") {
+      captured.costUsd = event.total_cost_usd;
+    }
+
+    if (typeof event.session_id === "string" && event.session_id !== "") {
+      captured.sessionId = event.session_id;
+    }
+
+    if (typeof event.text === "string") {
+      captured.text = event.text;
+    } else if (typeof event.result === "string") {
+      captured.text = event.result;
+    }
+  }
+
+  return captured;
+}

package/src/agents/prompt.js

@@ -0,0 +1,91 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+const FILE_EXTENSION_WHITELIST = new Set([".md", ".txt", ".prompt"]);
+
+/**
+ * Resolve a prompt input value to its raw text.
+ *
+ * A value is treated as a file path when:
+ *   1. It starts with `./`, `../`, or `/`, OR its extension is in the whitelist
+ *      (`.md`, `.txt`, `.prompt`)
+ *   2. AND the resolved path exists on disk as a regular file
+ *
+ * Otherwise the value is treated as an inline string and returned as-is.
+ *
+ * @param {string} value - Inline prompt text or a path to a prompt file.
+ * @param {string} cwd - Working directory used to resolve relative paths.
+ * @returns {Promise<string>} Raw prompt text (caller applies flow templating).
+ */
+export async function resolvePromptInput(value, cwd) {
+  if (typeof value !== "string") {
+    throw new TypeError("resolvePromptInput requires a string value");
+  }
+
+  if (!looksLikeFilePath(value)) {
+    return value;
+  }
+
+  const absolute = path.resolve(cwd, value);
+
+  let stats;
+
+  try {
+    stats = await stat(absolute);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if (isUnambiguousFilePath(value)) {
+        throw new Error(`Prompt file not found: ${value}`);
+      }
+
+      return value;
+    }
+
+    throw error;
+  }
+
+  if (!stats.isFile()) {
+    if (isUnambiguousFilePath(value)) {
+      throw new Error(`Prompt path is not a regular file: ${value}`);
+    }
+
+    return value;
+  }
+
+  return readFile(absolute, "utf8");
+}
+
+/**
+ * @param {string} value - Candidate prompt value.
+ * @returns {boolean} True when the value has file-path markers.
+ *
+ * Rules:
+ *   - Unambiguous prefix (`./`, `../`, `/`) → always treated as a path
+ *   - Single-token value (no whitespace, no newlines) with whitelisted extension
+ *     → treated as a path
+ *   - Anything else → inline text
+ *
+ * The single-token requirement prevents inline prompts like "see notes.txt for
+ * details" from being mis-detected as file paths.
+ */
+function looksLikeFilePath(value) {
+  if (isUnambiguousFilePath(value)) {
+    return true;
+  }
+
+  if (/\s/.test(value)) {
+    return false;
+  }
+
+  const extension = path.extname(value).toLowerCase();
+
+  return FILE_EXTENSION_WHITELIST.has(extension);
+}
+
+/**
+ * @param {string} value - Candidate prompt value.
+ * @returns {boolean} True when the value is clearly intended as a path.
+ */
+function isUnambiguousFilePath(value) {
+  return value.startsWith("./") || value.startsWith("../") || value.startsWith("/");
+}