lilflow 0.1.0 → 0.2.0

package/src/agents/output-file.js

@@ -0,0 +1,204 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Error thrown when post-processing agent output fails (invalid JSON, write
+ * failure, etc.). The dispatcher converts these to step failures.
+ */
+export class AgentOutputError extends Error {
+  /**
+   * @param {string} message - Human-readable error.
+   * @param {string} code - Stable machine-readable code.
+   */
+  constructor(message, code) {
+    super(message);
+    this.name = "AgentOutputError";
+    this.code = code;
+  }
+}
+
+/**
+ * Write an agent step's captured stdout to disk.
+ *
+ * When `format === 'json'`, strip surrounding markdown fences / prose, extract
+ * the first balanced JSON object or array, validate it parses, and write the
+ * cleaned JSON. When `format === 'text'` (or omitted), write raw stdout.
+ *
+ * Failures (missing JSON, invalid JSON, unwritable path) throw AgentOutputError
+ * so the dispatcher can fail the step cleanly.
+ *
+ * @param {object} options - Write options.
+ * @param {string} options.outputFile - Target file path (relative or absolute).
+ * @param {"text" | "json"} [options.format="text"] - Output format.
+ * @param {string} options.stdout - Captured agent stdout.
+ * @param {string} options.cwd - Workflow working directory (for relative paths).
+ * @param {string} options.stepName - Step name used in error messages.
+ * @returns {Promise<{bytesWritten: number, path: string}>} Write result.
+ */
+export async function writeAgentOutput(options) {
+  const { outputFile, format = "text", stdout, cwd, stepName } = options;
+  const absolute = path.isAbsolute(outputFile) ? outputFile : path.join(cwd, outputFile);
+  const content = format === "json"
+    ? extractAndValidateJson(stdout, stepName)
+    : stdout;
+
+  try {
+    await mkdir(path.dirname(absolute), { recursive: true });
+    await writeFile(absolute, content, "utf8");
+  } catch (error) {
+    throw new AgentOutputError(
+      `Agent step '${stepName}' failed to write output_file '${outputFile}': ${error.message}`,
+      "AGENT_OUTPUT_WRITE_FAILED"
+    );
+  }
+
+  return { bytesWritten: Buffer.byteLength(content, "utf8"), path: absolute };
+}
+
+/**
+ * Strip markdown fences and prose, extract the first balanced JSON object or
+ * array, validate it parses, and return the cleaned JSON text.
+ *
+ * @param {string} raw - Captured agent stdout.
+ * @param {string} stepName - Step name used in error messages.
+ * @returns {string} Cleaned JSON text (guaranteed to JSON.parse).
+ */
+export function extractAndValidateJson(raw, stepName) {
+  if (typeof raw !== "string") {
+    throw new AgentOutputError(
+      `Agent step '${stepName}' produced no stdout to write as JSON.`,
+      "AGENT_OUTPUT_EMPTY"
+    );
+  }
+
+  const stripped = stripMarkdownFences(raw).trim();
+
+  if (stripped === "") {
+    throw new AgentOutputError(
+      `Agent step '${stepName}' produced empty stdout — no JSON to extract.`,
+      "AGENT_OUTPUT_EMPTY"
+    );
+  }
+
+  const extracted = extractBalancedJson(stripped);
+
+  if (extracted === null) {
+    throw new AgentOutputError(
+      `Agent step '${stepName}' stdout contains no balanced JSON object or array.`,
+      "AGENT_OUTPUT_NO_JSON"
+    );
+  }
+
+  try {
+    JSON.parse(extracted);
+  } catch (error) {
+    throw new AgentOutputError(
+      `Agent step '${stepName}' stdout is not valid JSON: ${error.message}`,
+      "AGENT_OUTPUT_INVALID_JSON"
+    );
+  }
+
+  return extracted;
+}
+
+/**
+ * Strip leading/trailing markdown fences (``` or ```json) from a string.
+ *
+ * @param {string} raw - Raw text.
+ * @returns {string} Text with outer fences removed.
+ */
+function stripMarkdownFences(raw) {
+  const fencePattern = /^```(?:json|JSON|jsonc)?\s*\n([\s\S]*?)\n```\s*$/;
+  const match = fencePattern.exec(raw.trim());
+
+  if (match) {
+    return match[1];
+  }
+
+  // Also handle fences that are anywhere in the string — take the content of the
+  // first fenced block.
+  const innerPattern = /```(?:json|JSON|jsonc)?\s*\n([\s\S]*?)\n```/;
+  const innerMatch = innerPattern.exec(raw);
+
+  if (innerMatch) {
+    return innerMatch[1];
+  }
+
+  return raw;
+}
+
+/**
+ * Find and return the first balanced `{...}` or `[...]` substring that parses.
+ *
+ * Scans left-to-right, tracking brace depth, respecting strings (including
+ * escape sequences) so that braces inside string literals don't affect depth.
+ *
+ * @param {string} input - Input text.
+ * @returns {string | null} Balanced JSON substring or null when absent.
+ */
+export function extractBalancedJson(input) {
+  const openers = /[{[]/g;
+  let match;
+
+  while ((match = openers.exec(input)) !== null) {
+    const start = match.index;
+    const end = findBalancedEnd(input, start);
+
+    if (end === -1) continue;
+
+    const candidate = input.slice(start, end + 1);
+
+    try {
+      JSON.parse(candidate);
+      return candidate;
+    } catch {
+      // try next opener
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find the index of the balanced closer for the opener at `startIndex`.
+ *
+ * @param {string} input - Input text.
+ * @param {number} startIndex - Index of the `{` or `[` opener.
+ * @returns {number} Index of the matching closer, or -1 if unbalanced.
+ */
+function findBalancedEnd(input, startIndex) {
+  const opener = input[startIndex];
+  const closer = opener === "{" ? "}" : "]";
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+
+  for (let i = startIndex; i < input.length; i += 1) {
+    const ch = input[i];
+
+    if (inString) {
+      if (escape) {
+        escape = false;
+      } else if (ch === "\\") {
+        escape = true;
+      } else if (ch === "\"") {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === "\"") {
+      inString = true;
+      continue;
+    }
+
+    if (ch === opener) {
+      depth += 1;
+    } else if (ch === closer) {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}

package/src/cli.js

@@ -29,6 +29,7 @@ import {
   runWorkflowSignalCommand,
   runWorkflowStatusCommand
 } from "./run-workflow.js";
+import { runSessionBridgeCommand, getSessionBridgeHelpText } from "./session-bridge.js";
 
 /**
  * Return the CLI help text for `flow`.
@@ -48,18 +49,20 @@ Usage:
   flow status
   flow list
   flow logs
+  flow session-bridge <subcommand>
   flow --help
 
 Commands:
-  init     Initialize flow in the current repository or from a reusable template
-  config   Show or initialize flow configuration
-  run      Execute a workflow from YAML
-  resume   Resume a failed persisted workflow run
-  set-step Manually set which persisted workflow step to resume from
-  signal   Deliver a signal to a waiting workflow step
-  status   Show the status of a persisted workflow run
-  list     List persisted workflow runs
-  logs     Show persisted logs for a workflow run`;
+  init           Initialize flow in the current repository or from a reusable template
+  config         Show or initialize flow configuration
+  run            Execute a workflow from YAML
+  resume         Resume a failed persisted workflow run
+  set-step       Manually set which persisted workflow step to resume from
+  signal         Deliver a signal to a waiting workflow step
+  status         Show the status of a persisted workflow run
+  list           List persisted workflow runs
+  logs           Show persisted logs for a workflow run
+  session-bridge Agent-facing bridge commands for session-mode workflows`;
 }
 
 /**
@@ -123,6 +126,10 @@ export async function runCli(argv, stdout = console.log, stderr = console.error,
     return runWorkflowSignalCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
   }
 
+  if (command === "session-bridge") {
+    return runSessionBridgeCommand(commandArgs, stdout, stderr, { cwd, env });
+  }
+
   stderr(`Unknown command: ${command}`);
   stderr("Run 'flow --help' to see available commands.");
   return 1;
@@ -193,6 +200,7 @@ export {
   getLogsHelpText,
   getResumeHelpText,
   getRunHelpText,
+  getSessionBridgeHelpText,
   getSetStepHelpText,
   getSignalHelpText,
   getStatusHelpText

package/src/run-workflow.js

@@ -8,6 +8,7 @@ import readline from "node:readline/promises";
 import yaml from "js-yaml";
 import { ConfigError, loadConfig } from "./config.js";
 import { AgentDispatchError, executeAgentStep } from "./agents/index.js";
+import { executeSessionWorkflow } from "./session-runner.js";
 
 const ANSI_RESET = "\u001B[0m";
 const ANSI_RED = "\u001B[31m";
@@ -596,6 +597,8 @@ export function parseWorkflowContent(content, sourceLabel) {
     throw new WorkflowError(`${sourceLabel} must define a non-empty steps array.`);
   }
 
+  const mode = validateWorkflowMode(parsed.mode, sourceLabel);
+  const session = validateWorkflowSession(parsed.session, mode, sourceLabel);
   const parameters = validateWorkflowParameters(parsed.parameters, sourceLabel);
   const defaults = validateWorkflowDefaults(parsed.defaults, sourceLabel);
   const authoredSteps = parsed.steps.map((step, index) => validateStep(step, index, sourceLabel));
@@ -607,12 +610,110 @@ export function parseWorkflowContent(content, sourceLabel) {
   return {
     name: parsed.name.trim(),
     version: parsed.version?.trim(),
+    mode,
+    ...(session === undefined ? {} : { session }),
     parameters,
     defaults,
     steps
   };
 }
 
+/**
+ * Validate the workflow-level `mode` field.
+ *
+ * @param {unknown} mode - Raw mode value from the YAML document.
+ * @param {string} sourceLabel - Error label.
+ * @returns {"classic" | "session"} Normalized mode, defaulting to "classic".
+ */
+function validateWorkflowMode(mode, sourceLabel) {
+  if (mode === undefined) {
+    return "classic";
+  }
+
+  if (mode !== "classic" && mode !== "session") {
+    throw new WorkflowError(`${sourceLabel} mode must be 'classic' or 'session' when provided.`);
+  }
+
+  return mode;
+}
+
+/**
+ * Validate and normalize the workflow-level `session` block. Required when
+ * `mode: session`; forbidden when `mode: classic`.
+ *
+ * @param {unknown} session - Raw session block from the YAML document.
+ * @param {"classic" | "session"} mode - Resolved workflow mode.
+ * @param {string} sourceLabel - Error label.
+ * @returns {object | undefined} Normalized session config or undefined in classic mode.
+ */
+function validateWorkflowSession(session, mode, sourceLabel) {
+  if (mode === "classic") {
+    if (session !== undefined) {
+      throw new WorkflowError(`${sourceLabel} session must be omitted when mode is 'classic'.`);
+    }
+
+    return undefined;
+  }
+
+  if (session === undefined) {
+    throw new WorkflowError(`${sourceLabel} session is required when mode is 'session'.`);
+  }
+
+  if (session == null || typeof session !== "object" || Array.isArray(session)) {
+    throw new WorkflowError(`${sourceLabel} session must be a YAML object.`);
+  }
+
+  if (session.provider !== "claude-code" && session.provider !== "opencode") {
+    throw new WorkflowError(`${sourceLabel} session.provider must be 'claude-code' or 'opencode'.`);
+  }
+
+  if (session.model !== undefined && (typeof session.model !== "string" || session.model.trim() === "")) {
+    throw new WorkflowError(`${sourceLabel} session.model must be a non-empty string when provided.`);
+  }
+
+  if (session.system_prompt !== undefined
+    && (typeof session.system_prompt !== "string" || session.system_prompt.trim() === "")) {
+    throw new WorkflowError(`${sourceLabel} session.system_prompt must be a non-empty string when provided.`);
+  }
+
+  if (session.compact_after !== undefined
+    && (typeof session.compact_after !== "number"
+      || !Number.isFinite(session.compact_after)
+      || session.compact_after <= 0
+      || !Number.isInteger(session.compact_after))) {
+    throw new WorkflowError(`${sourceLabel} session.compact_after must be a positive integer when provided.`);
+  }
+
+  if (session.allow_tools !== undefined) {
+    if (!Array.isArray(session.allow_tools) || session.allow_tools.some((entry) => typeof entry !== "string")) {
+      throw new WorkflowError(`${sourceLabel} session.allow_tools must be an array of strings when provided.`);
+    }
+
+    if (session.allow_tools.some((entry) => entry.startsWith("-"))) {
+      throw new WorkflowError(`${sourceLabel} session.allow_tools entries must not start with '-'.`);
+    }
+  }
+
+  if (session.plugins !== undefined) {
+    if (!Array.isArray(session.plugins) || session.plugins.some((entry) => typeof entry !== "string")) {
+      throw new WorkflowError(`${sourceLabel} session.plugins must be an array of strings when provided.`);
+    }
+
+    if (session.plugins.some((entry) => entry.startsWith("-"))) {
+      throw new WorkflowError(`${sourceLabel} session.plugins entries must not start with '-'.`);
+    }
+  }
+
+  return {
+    provider: session.provider,
+    ...(session.model === undefined ? {} : { model: session.model.trim() }),
+    ...(session.system_prompt === undefined ? {} : { systemPrompt: session.system_prompt.trim() }),
+    ...(session.compact_after === undefined ? {} : { compactAfter: session.compact_after }),
+    ...(session.allow_tools === undefined ? {} : { allowTools: [...session.allow_tools] }),
+    ...(session.plugins === undefined ? {} : { plugins: [...session.plugins] })
+  };
+}
+
 /**
  * Validate and normalize the workflow-level `defaults` block.
  *
@@ -722,6 +823,20 @@ export async function runWorkflowCommand(args, stdout, stderr, options = {}) {
       stdout("Warning: .flow/ directory not found. Running in standalone mode.");
     }
 
+    if (workflow.mode === "session") {
+      const sessionResult = await executeSessionWorkflow({
+        workflow,
+        workflowPath,
+        cwd,
+        env,
+        stdout,
+        stderr,
+        flowConfig: config,
+        eventLogger
+      });
+      return sessionResult.exitCode === 0 ? 0 : 1;
+    }
+
     await executeWorkflow({
       workflow,
       workflowPath,
@@ -2906,6 +3021,37 @@ function validateStep(step, index, sourceLabel) {
       throw new WorkflowError(`${sourceLabel} step '${step.name}' agent.interactive must be a boolean when provided.`);
     }
 
+    if (step.agent.mode !== undefined && step.agent.mode !== "autonomous" && step.agent.mode !== "conversational") {
+      throw new WorkflowError(`${sourceLabel} step '${step.name}' agent.mode must be 'autonomous' or 'conversational' when provided.`);
+    }
+
+    if (step.agent.mode !== undefined && step.agent.interactive !== undefined) {
+      throw new WorkflowError(
+        `${sourceLabel} step '${step.name}' cannot define both agent.mode and agent.interactive. Use agent.mode (agent.interactive is deprecated).`
+      );
+    }
+
+    if (step.agent.output_file !== undefined
+      && (typeof step.agent.output_file !== "string" || step.agent.output_file.trim() === "")) {
+      throw new WorkflowError(
+        `${sourceLabel} step '${step.name}' agent.output_file must be a non-empty string when provided.`
+      );
+    }
+
+    if (step.agent.output_format !== undefined
+      && step.agent.output_format !== "text"
+      && step.agent.output_format !== "json") {
+      throw new WorkflowError(
+        `${sourceLabel} step '${step.name}' agent.output_format must be 'text' or 'json' when provided.`
+      );
+    }
+
+    if (step.agent.output_format !== undefined && step.agent.output_file === undefined) {
+      throw new WorkflowError(
+        `${sourceLabel} step '${step.name}' agent.output_format requires agent.output_file.`
+      );
+    }
+
     if (step.agent.allow_tools !== undefined) {
       if (!Array.isArray(step.agent.allow_tools) || step.agent.allow_tools.some((entry) => typeof entry !== "string")) {
         throw new WorkflowError(`${sourceLabel} step '${step.name}' agent.allow_tools must be an array of strings when provided.`);
@@ -3119,9 +3265,18 @@ function resolveProviderDefaults(agentDefaults, providerName) {
  * @returns {object} Normalized agent spec with trimmed strings and defaults.
  */
 function normalizeAgentSpec(agent) {
+  // Back-compat: agent.interactive: true maps to agent.mode: conversational.
+  // Mutual exclusion is enforced earlier in validateStep.
+  const resolvedMode = agent.mode !== undefined
+    ? agent.mode
+    : agent.interactive === true
+      ? "conversational"
+      : "autonomous";
+
   return {
     provider: agent.provider,
     prompt: agent.prompt.trim(),
+    mode: resolvedMode,
     ...(agent.session === undefined ? {} : { session: agent.session }),
     ...(agent.model === undefined ? {} : { model: agent.model.trim() }),
     ...(agent.source_access === undefined ? {} : { source_access: agent.source_access }),
@@ -3129,7 +3284,9 @@ function normalizeAgentSpec(agent) {
     ...(agent.allow_tools === undefined ? {} : { allow_tools: [...agent.allow_tools] }),
     ...(agent.plugins === undefined ? {} : { plugins: [...agent.plugins] }),
     ...(agent.append_system_prompt === undefined ? {} : { append_system_prompt: agent.append_system_prompt.trim() }),
-    ...(agent.max_budget_usd === undefined ? {} : { max_budget_usd: agent.max_budget_usd })
+    ...(agent.max_budget_usd === undefined ? {} : { max_budget_usd: agent.max_budget_usd }),
+    ...(agent.output_file === undefined ? {} : { output_file: agent.output_file.trim() }),
+    ...(agent.output_format === undefined ? {} : { output_format: agent.output_format })
   };
 }
 
@@ -3906,6 +4063,50 @@ function quoteConditionLiteral(value) {
  * @param {Record<string, string | number | boolean | null>} [options.parameters={}] - Resolved workflow parameters.
  * @returns {{shouldRun: boolean, resolvedValues: {reference: string, value: string}[]}} Evaluation result.
  */
+/**
+ * Evaluate a gate step against persisted run events. Reconstructs the
+ * `completedStepOutputs` shape that `evaluateStepCondition` expects and returns
+ * a plain pass/fail result for the session bridge.
+ *
+ * @param {object} step - Normalized gate step (must have `stepType === 'gate'`).
+ * @param {object[]} events - All persisted run events.
+ * @param {object} env - Environment variables available to the gate expression.
+ * @returns {{passed: boolean, message: string | null}} Gate evaluation result.
+ */
+export function evaluateSessionGate(step, events, env) {
+  const completedStepOutputs = [];
+
+  for (const event of events) {
+    if (event.type === "step_completed" || event.type === "step_failed") {
+      completedStepOutputs.push({
+        name: event.step_name,
+        exitCode: event.exit_code ?? (event.type === "step_failed" ? 1 : 0),
+        stdout: event.stdout ?? "",
+        stderr: event.stderr ?? ""
+      });
+    }
+  }
+
+  try {
+    const { shouldRun } = evaluateStepCondition({
+      condition: step.gate,
+      stepName: step.name,
+      env: env ?? {},
+      completedStepOutputs,
+      parameters: {}
+    });
+
+    return {
+      passed: shouldRun,
+      message: shouldRun
+        ? (step.message ?? null)
+        : (step.message ?? `Gate '${step.name}' failed: ${step.gate}`)
+    };
+  } catch (error) {
+    return { passed: false, message: error.message };
+  }
+}
+
 function evaluateStepCondition(options) {
   const {
     condition,