lilflow 0.1.1 → 0.2.1

package/src/session-bridge.js

@@ -0,0 +1,644 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline/promises";
+import {
+  WorkflowError,
+  appendEventLogEntryWithLock,
+  evaluateSessionGate,
+  loadWorkflow,
+  readWorkflowRunEvents
+} from "./run-workflow.js";
+
+const SUBCOMMANDS = new Set(["next", "update", "gate", "ask", "wait", "status", "log", "compact", "help"]);
+const VALID_STATUSES = new Set(["completed", "failed", "deferred", "skipped"]);
+const DEFAULT_POLL_MS = 1000;
+const DEFAULT_WAIT_TIMEOUT_MS = 60 * 60 * 1000;
+
+/**
+ * Return the help text for `flow session-bridge`.
+ *
+ * @returns {string} Command help text.
+ */
+export function getSessionBridgeHelpText() {
+  return `flow session-bridge
+
+Usage:
+  flow session-bridge <subcommand> [args...]
+
+Subcommands:
+  next                             Return the next eligible step(s) as JSON
+  update <step> <status>           Mark a step as completed/failed/deferred/skipped
+                                   Options: --output <text>, --exit-code <n>
+  gate <step>                      Evaluate a gate step, return pass/fail result
+  ask <prompt>                     Read one line from stdin, return as response
+  wait <step>                      Block until wait step trigger fires
+  status                           Return full workflow state as JSON
+  log <message>                    Append a bridge_log event to the run log
+  compact                          Return a condensed summary of completed steps
+
+Environment:
+  FLOW_RUN_ID   Active workflow run ID (required for state-changing subcommands)
+
+Notes:
+  - Designed to be invoked from inside an agent session by the lilflow skill
+  - Outputs single-line JSON on stdout for the agent to consume
+  - State is read from / written to .flow/runs/<run-id>.jsonl`;
+}
+
+/**
+ * Execute `flow session-bridge <subcommand>`.
+ *
+ * @param {string[]} args - Command args after `session-bridge`.
+ * @param {(message: string) => void} stdout - Standard output writer.
+ * @param {(message: string) => void} stderr - Standard error writer.
+ * @param {object} options - Runtime overrides.
+ * @param {string} options.cwd - Working directory.
+ * @param {object} options.env - Process environment.
+ * @param {NodeJS.ReadableStream} [options.stdin] - Input stream used by `ask`.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function runSessionBridgeCommand(args, stdout, stderr, options) {
+  const [subcommand, ...subArgs] = args;
+
+  if (!subcommand || subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
+    stdout(getSessionBridgeHelpText());
+    return 0;
+  }
+
+  if (!SUBCOMMANDS.has(subcommand)) {
+    stderr(`Unknown session-bridge subcommand: ${subcommand}`);
+    stderr("Run 'flow session-bridge --help' to see available subcommands.");
+    return 1;
+  }
+
+  try {
+    switch (subcommand) {
+      case "next":
+        return await subcommandNext(subArgs, stdout, stderr, options);
+      case "update":
+        return await subcommandUpdate(subArgs, stdout, stderr, options);
+      case "gate":
+        return await subcommandGate(subArgs, stdout, stderr, options);
+      case "ask":
+        return await subcommandAsk(subArgs, stdout, stderr, options);
+      case "wait":
+        return await subcommandWait(subArgs, stdout, stderr, options);
+      case "status":
+        return await subcommandStatus(subArgs, stdout, stderr, options);
+      case "log":
+        return await subcommandLog(subArgs, stdout, stderr, options);
+      case "compact":
+        return await subcommandCompact(subArgs, stdout, stderr, options);
+      default:
+        return 1;
+    }
+  } catch (error) {
+    if (error instanceof WorkflowError) {
+      stderr(`Error: ${error.message}`);
+      if (Array.isArray(error.details)) {
+        for (const detail of error.details) {
+          stderr(detail);
+        }
+      }
+      return 1;
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Resolve the run ID from env or explicit flag.
+ *
+ * @param {string[]} args - Remaining CLI args.
+ * @param {object} env - Process environment.
+ * @returns {{runId: string, remaining: string[]}} Resolved run ID and remaining args.
+ */
+function resolveRunId(args, env) {
+  const remaining = [];
+  let flagged;
+
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--run-id") {
+      flagged = args[i + 1];
+      i += 1;
+      continue;
+    }
+    remaining.push(args[i]);
+  }
+
+  const runId = flagged ?? env.FLOW_RUN_ID;
+
+  if (!runId || typeof runId !== "string" || runId.trim() === "") {
+    throw new WorkflowError("FLOW_RUN_ID env var or --run-id flag is required.");
+  }
+
+  return { runId: runId.trim(), remaining };
+}
+
+/**
+ * Load the workflow associated with a run by reading workflow_path from run_started.
+ *
+ * @param {string} cwd - Working directory.
+ * @param {string} runId - Run identifier.
+ * @returns {Promise<{workflow: object, runStarted: object, events: object[], eventLogPath: string}>} Loaded context.
+ */
+async function loadRunContext(cwd, runId) {
+  const events = await readWorkflowRunEvents(cwd, runId);
+  const runStarted = events.find((event) => event.type === "run_started");
+
+  if (!runStarted) {
+    throw new WorkflowError(`Run ${runId} is missing its run_started event.`);
+  }
+
+  const workflowPath = path.isAbsolute(runStarted.workflow_path)
+    ? runStarted.workflow_path
+    : path.join(cwd, runStarted.workflow_path);
+
+  const workflow = await loadWorkflow(workflowPath);
+  const eventLogPath = path.join(cwd, ".flow", "runs", `${runId}.jsonl`);
+
+  return { workflow, runStarted, events, eventLogPath };
+}
+
+/**
+ * Compute which steps have been completed/failed/skipped from events.
+ *
+ * @param {object[]} events - All run events.
+ * @returns {Map<string, {status: string, exitCode: number, stdout: string, stderr: string}>} Step state by name.
+ */
+function computeStepStates(events) {
+  const states = new Map();
+
+  for (const event of events) {
+    if (event.type === "step_completed") {
+      states.set(event.step_name, {
+        status: "completed",
+        exitCode: event.exit_code ?? 0,
+        stdout: event.stdout ?? "",
+        stderr: event.stderr ?? ""
+      });
+    } else if (event.type === "step_failed") {
+      states.set(event.step_name, {
+        status: "failed",
+        exitCode: event.exit_code ?? 1,
+        stdout: event.stdout ?? "",
+        stderr: event.stderr ?? ""
+      });
+    } else if (event.type === "step_skipped") {
+      states.set(event.step_name, {
+        status: "skipped",
+        exitCode: 0,
+        stdout: "",
+        stderr: ""
+      });
+    }
+  }
+
+  return states;
+}
+
+/**
+ * Minimal serialization of a step suitable for the agent.
+ *
+ * @param {object} step - Runtime step.
+ * @param {number} index - Step index in the workflow.
+ * @returns {object} Plain object for JSON serialization.
+ */
+function serializeStep(step, index) {
+  const base = {
+    name: step.name,
+    type: step.stepType,
+    index
+  };
+
+  if (step.stepType === "run") {
+    base.command = step.run;
+  } else if (step.stepType === "gate") {
+    base.gate = step.gate;
+    base.gateAction = step.gateAction ?? "fail";
+    if (step.message) base.message = step.message;
+  } else if (step.stepType === "subflow") {
+    base.subflow = step.subflow;
+    if (step.with) base.with = step.with;
+  } else if (step.stepType === "interactive") {
+    base.command = step.interactive;
+  } else if (step.stepType === "wait") {
+    base.wait = step.wait;
+  } else if (step.stepType === "agent") {
+    base.agent = {
+      provider: step.agent.provider,
+      prompt: step.agent.prompt,
+      mode: step.agent.mode ?? "autonomous",
+      ...(step.agent.model ? { model: step.agent.model } : {}),
+      ...(step.agent.session ? { session: step.agent.session } : {})
+    };
+  }
+
+  return base;
+}
+
+/**
+ * Check whether a step is ready to execute given current state.
+ *
+ * @param {object} step - Runtime step.
+ * @param {Map<string, object>} stepStates - Completed/failed/skipped step states.
+ * @returns {boolean} True when depends_on is satisfied.
+ */
+function isStepReady(step, stepStates) {
+  if (!step.dependsOn || step.dependsOn.length === 0) return true;
+  return step.dependsOn.every((dep) => stepStates.get(dep)?.status === "completed");
+}
+
+/**
+ * Return the first-unresolved step plus any siblings that belong in the same
+ * parallel batch.
+ *
+ * @param {object} workflow - Loaded workflow.
+ * @param {Map<string, object>} stepStates - Current step states.
+ * @returns {object[]} Eligible step list (empty when workflow is done).
+ */
+function findEligibleSteps(workflow, stepStates) {
+  const firstPending = workflow.steps.findIndex((step) => !stepStates.has(step.name));
+
+  if (firstPending === -1) return [];
+
+  const head = workflow.steps[firstPending];
+
+  if (!isStepReady(head, stepStates)) return [];
+
+  if (head.parallel !== true && head.parallelGroup === undefined) {
+    return [{ step: head, index: firstPending }];
+  }
+
+  const group = head.parallelGroup;
+  const batch = [];
+
+  for (let i = firstPending; i < workflow.steps.length; i += 1) {
+    const step = workflow.steps[i];
+
+    if (stepStates.has(step.name)) continue;
+
+    const inGroup = group === undefined
+      ? step.parallel === true && step.parallelGroup === undefined
+      : step.parallelGroup === group;
+
+    if (!inGroup) break;
+    if (!isStepReady(step, stepStates)) continue;
+
+    batch.push({ step, index: i });
+  }
+
+  return batch;
+}
+
+/**
+ * `flow session-bridge next` — return the next eligible step(s).
+ */
+async function subcommandNext(args, stdout, stderr, options) {
+  const { runId } = resolveRunId(args, options.env);
+  const { workflow, events } = await loadRunContext(options.cwd, runId);
+  const stepStates = computeStepStates(events);
+  const eligible = findEligibleSteps(workflow, stepStates);
+  const remaining = workflow.steps.length - stepStates.size;
+
+  if (eligible.length === 0) {
+    stdout(JSON.stringify({
+      step: null,
+      steps: [],
+      remaining,
+      workflow_status: remaining === 0 ? "completed" : "blocked"
+    }));
+    return 0;
+  }
+
+  stdout(JSON.stringify({
+    step: eligible.length === 1 ? serializeStep(eligible[0].step, eligible[0].index) : null,
+    steps: eligible.map((entry) => serializeStep(entry.step, entry.index)),
+    remaining,
+    workflow_status: "running"
+  }));
+  return 0;
+}
+
+/**
+ * `flow session-bridge update <step> <status>` — persist a step result.
+ */
+async function subcommandUpdate(args, stdout, stderr, options) {
+  const { runId, remaining } = resolveRunId(args, options.env);
+  const [stepName, status, ...rest] = remaining;
+
+  if (!stepName || !status) {
+    throw new WorkflowError("flow session-bridge update requires <step-name> <status>.");
+  }
+
+  if (!VALID_STATUSES.has(status)) {
+    throw new WorkflowError(
+      `flow session-bridge update status must be one of: ${[...VALID_STATUSES].join(", ")}.`
+    );
+  }
+
+  let output = "";
+  let exitCode;
+  let reason;
+
+  for (let i = 0; i < rest.length; i += 1) {
+    if (rest[i] === "--output") {
+      output = rest[i + 1] ?? "";
+      i += 1;
+    } else if (rest[i] === "--exit-code") {
+      exitCode = Number.parseInt(rest[i + 1], 10);
+      if (!Number.isFinite(exitCode)) {
+        throw new WorkflowError("--exit-code must be an integer.");
+      }
+      i += 1;
+    } else if (rest[i] === "--reason") {
+      reason = rest[i + 1] ?? "";
+      i += 1;
+    } else {
+      throw new WorkflowError(`Unknown update flag: ${rest[i]}`);
+    }
+  }
+
+  const { workflow, eventLogPath } = await loadRunContext(options.cwd, runId);
+  const workflowStep = workflow.steps.find((step) => step.name === stepName);
+
+  if (!workflowStep) {
+    throw new WorkflowError(`Step '${stepName}' is not defined in workflow.`);
+  }
+
+  const stepIndex = workflow.steps.indexOf(workflowStep);
+  const resolvedExit = exitCode ?? (status === "completed" ? 0 : 1);
+  const eventType = status === "completed"
+    ? "step_completed"
+    : status === "skipped"
+      ? "step_skipped"
+      : status === "deferred"
+        ? "step_deferred"
+        : "step_failed";
+
+  await appendEventLogEntryWithLock(eventLogPath, {
+    type: eventType,
+    timestamp: new Date().toISOString(),
+    step_name: stepName,
+    step_index: stepIndex,
+    exit_code: resolvedExit,
+    stdout: output,
+    stderr: "",
+    via: "session-bridge",
+    ...(reason === undefined ? {} : { reason })
+  });
+
+  stdout(JSON.stringify({ ok: true, step: stepName, status, exit_code: resolvedExit }));
+  return 0;
+}
+
+/**
+ * `flow session-bridge gate <step>` — evaluate a gate step synchronously.
+ */
+async function subcommandGate(args, stdout, stderr, options) {
+  const { runId, remaining } = resolveRunId(args, options.env);
+  const [stepName] = remaining;
+
+  if (!stepName) {
+    throw new WorkflowError("flow session-bridge gate requires <step-name>.");
+  }
+
+  const { workflow, events, eventLogPath } = await loadRunContext(options.cwd, runId);
+  const step = workflow.steps.find((entry) => entry.name === stepName);
+
+  if (!step) {
+    throw new WorkflowError(`Step '${stepName}' not found.`);
+  }
+
+  if (step.stepType !== "gate") {
+    throw new WorkflowError(`Step '${stepName}' is not a gate step (type: ${step.stepType}).`);
+  }
+
+  const result = evaluateSessionGate(step, events, options.env);
+
+  await appendEventLogEntryWithLock(eventLogPath, {
+    type: result.passed ? "step_completed" : (step.gateAction === "warn" ? "step_completed" : "step_failed"),
+    timestamp: new Date().toISOString(),
+    step_name: stepName,
+    step_index: workflow.steps.indexOf(step),
+    exit_code: result.passed ? 0 : 1,
+    stdout: result.message ?? "",
+    stderr: "",
+    via: "session-bridge",
+    gate_passed: result.passed,
+    gate_action: step.gateAction ?? "fail"
+  });
+
+  stdout(JSON.stringify({
+    passed: result.passed,
+    action: step.gateAction ?? "fail",
+    message: result.message ?? null,
+    workflow_should_stop: !result.passed && (step.gateAction ?? "fail") === "fail"
+  }));
+  return 0;
+}
+
+/**
+ * `flow session-bridge ask <prompt>` — read one line from stdin.
+ */
+async function subcommandAsk(args, stdout, stderr, options) {
+  const { remaining } = resolveRunId(args, options.env);
+  const prompt = remaining.join(" ").trim();
+
+  if (prompt === "") {
+    throw new WorkflowError("flow session-bridge ask requires a prompt message.");
+  }
+
+  const rl = readline.createInterface({
+    input: options.stdin ?? process.stdin,
+    output: process.stderr,
+    terminal: false
+  });
+
+  try {
+    stderr(`${prompt}\n> `);
+    const response = await rl.question("");
+    stdout(JSON.stringify({ response: response.trim() }));
+    return 0;
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * `flow session-bridge wait <step>` — block until the wait step's trigger fires.
+ */
+async function subcommandWait(args, stdout, stderr, options) {
+  const { runId, remaining } = resolveRunId(args, options.env);
+  const [stepName] = remaining;
+
+  if (!stepName) {
+    throw new WorkflowError("flow session-bridge wait requires <step-name>.");
+  }
+
+  const { workflow, eventLogPath } = await loadRunContext(options.cwd, runId);
+  const step = workflow.steps.find((entry) => entry.name === stepName);
+
+  if (!step || step.stepType !== "wait") {
+    throw new WorkflowError(`Step '${stepName}' is not a wait step.`);
+  }
+
+  const timeoutMs = step.wait.timeout
+    ? parseDurationMs(step.wait.timeout)
+    : DEFAULT_WAIT_TIMEOUT_MS;
+  const pollMs = step.wait.pollInterval ? parseDurationMs(step.wait.pollInterval) : DEFAULT_POLL_MS;
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    if (step.wait.trigger === "file") {
+      const triggerPath = path.isAbsolute(step.wait.path)
+        ? step.wait.path
+        : path.join(options.cwd, step.wait.path);
+      try {
+        await readFile(triggerPath);
+        stdout(JSON.stringify({ fired: true, trigger: "file", path: step.wait.path }));
+        return await markWaitFired(eventLogPath, workflow, step);
+      } catch {
+        // not yet
+      }
+    } else if (step.wait.trigger === "signal") {
+      const events = await readWorkflowRunEvents(options.cwd, runId);
+      const signal = events.findLast((event) =>
+        event.type === "step_signaled" && event.step_name === stepName
+      );
+      if (signal) {
+        stdout(JSON.stringify({ fired: true, trigger: "signal", data: signal.data ?? null }));
+        return await markWaitFired(eventLogPath, workflow, step);
+      }
+    }
+
+    await new Promise((resolve) => { setTimeout(resolve, pollMs); });
+  }
+
+  stderr(`Wait step '${stepName}' timed out after ${step.wait.timeout ?? "1h"}.`);
+  return 1;
+}
+
+/**
+ * Mark a wait step as completed after its trigger fires.
+ */
+async function markWaitFired(eventLogPath, workflow, step) {
+  await appendEventLogEntryWithLock(eventLogPath, {
+    type: "step_completed",
+    timestamp: new Date().toISOString(),
+    step_name: step.name,
+    step_index: workflow.steps.indexOf(step),
+    exit_code: 0,
+    stdout: "",
+    stderr: "",
+    via: "session-bridge"
+  });
+  return 0;
+}
+
+/**
+ * `flow session-bridge status` — full state snapshot.
+ */
+async function subcommandStatus(args, stdout, stderr, options) {
+  const { runId } = resolveRunId(args, options.env);
+  const { workflow, events } = await loadRunContext(options.cwd, runId);
+  const stepStates = computeStepStates(events);
+
+  const stepSummary = workflow.steps.map((step, index) => {
+    const state = stepStates.get(step.name);
+    return {
+      name: step.name,
+      type: step.stepType,
+      index,
+      status: state?.status ?? "pending",
+      ...(state ? { exit_code: state.exitCode, stdout: state.stdout } : {})
+    };
+  });
+
+  stdout(JSON.stringify({
+    run_id: runId,
+    workflow_name: workflow.name,
+    mode: workflow.mode,
+    total_steps: workflow.steps.length,
+    completed: stepSummary.filter((entry) => entry.status === "completed").length,
+    failed: stepSummary.filter((entry) => entry.status === "failed").length,
+    pending: stepSummary.filter((entry) => entry.status === "pending").length,
+    steps: stepSummary
+  }));
+  return 0;
+}
+
+/**
+ * `flow session-bridge log <message>` — append a bridge_log event.
+ */
+async function subcommandLog(args, stdout, stderr, options) {
+  const { runId, remaining } = resolveRunId(args, options.env);
+  const message = remaining.join(" ");
+
+  if (!message.trim()) {
+    throw new WorkflowError("flow session-bridge log requires a non-empty message.");
+  }
+
+  const { eventLogPath } = await loadRunContext(options.cwd, runId);
+
+  await appendEventLogEntryWithLock(eventLogPath, {
+    type: "bridge_log",
+    timestamp: new Date().toISOString(),
+    message
+  });
+
+  stdout(JSON.stringify({ ok: true }));
+  return 0;
+}
+
+/**
+ * `flow session-bridge compact` — return a condensed summary of completed steps.
+ */
+async function subcommandCompact(args, stdout, stderr, options) {
+  const { runId } = resolveRunId(args, options.env);
+  const { workflow, events } = await loadRunContext(options.cwd, runId);
+  const stepStates = computeStepStates(events);
+
+  const summary = workflow.steps
+    .filter((step) => stepStates.get(step.name)?.status === "completed")
+    .map((step) => {
+      const state = stepStates.get(step.name);
+      return {
+        name: step.name,
+        type: step.stepType,
+        exit_code: state.exitCode,
+        output_preview: (state.stdout ?? "").slice(0, 200)
+      };
+    });
+
+  stdout(JSON.stringify({
+    workflow_name: workflow.name,
+    completed_steps: summary.length,
+    summary
+  }));
+  return 0;
+}
+
+/**
+ * Parse a duration string like "500ms", "30s", "5m", "1h" to milliseconds.
+ *
+ * @param {string} value - Duration string.
+ * @returns {number} Milliseconds.
+ */
+function parseDurationMs(value) {
+  const match = /^(\d+)(ms|s|m|h)$/.exec(value.trim());
+
+  if (!match) {
+    throw new WorkflowError(`Invalid duration: ${value}`);
+  }
+
+  const num = Number.parseInt(match[1], 10);
+  switch (match[2]) {
+    case "ms": return num;
+    case "s": return num * 1000;
+    case "m": return num * 60 * 1000;
+    case "h": return num * 60 * 60 * 1000;
+    default: throw new WorkflowError(`Invalid duration unit: ${match[2]}`);
+  }
+}

package/src/session-prompt.js

@@ -0,0 +1,59 @@
+/**
+ * Generate the system prompt injected into a session-mode claude spawn.
+ *
+ * The prompt teaches the agent the session protocol: always call
+ * `flow session-bridge next` to get the next step, execute it, and report
+ * back via `flow session-bridge update`. Covers step types, conversational
+ * mode, and failure handling.
+ *
+ * @param {object} workflow - Loaded workflow (must include `session` block).
+ * @param {string} runId - Run ID for this session.
+ * @returns {string} System prompt text.
+ */
+export function buildSessionSystemPrompt(workflow, runId) {
+  const custom = workflow.session?.systemPrompt?.trim();
+  const stepCount = workflow.steps.length;
+  const stepList = workflow.steps
+    .map((step, index) => {
+      const summary = step.stepType === "agent"
+        ? `agent(${step.agent.provider}, mode=${step.agent.mode ?? "autonomous"})`
+        : step.stepType;
+      return `  ${index + 1}. ${step.name} — ${summary}`;
+    })
+    .join("\n");
+
+  return `You are driving a lilflow workflow in session mode. Every step must be
+fetched, executed, and reported via the \`flow session-bridge\` CLI. The
+active run ID is already set in \`FLOW_RUN_ID\` — you do not need to pass it.
+
+Workflow: ${workflow.name}${workflow.version ? ` (v${workflow.version})` : ""}
+Steps (${stepCount}):
+${stepList}
+
+## Execution protocol
+
+1. Call \`flow session-bridge next\` to get the next step.
+2. Execute the step according to its \`type\`:
+   - \`run\`: execute \`command\` via the Bash tool.
+   - \`agent\` with \`mode: autonomous\`: execute the prompt yourself (you are the agent).
+   - \`agent\` with \`mode: conversational\`: work with the user iteratively; only
+     mark complete after they confirm satisfaction.
+   - \`agent\` with a foreign provider: mark the step \`deferred\` and continue.
+   - \`gate\`: call \`flow session-bridge gate <name>\`.
+   - \`interactive\`: call \`flow session-bridge ask <prompt>\`.
+   - \`wait\`: call \`flow session-bridge wait <name>\`.
+3. Report the result: \`flow session-bridge update <name> completed --output "..." --exit-code 0\`
+   or \`flow session-bridge update <name> failed --reason "..."\`.
+4. If a gate returns \`workflow_should_stop: true\`, stop and report to the user.
+5. Repeat until \`flow session-bridge next\` reports \`workflow_status: "completed"\`.
+
+## Rules
+
+- Never infer the workflow. Always ask the bridge.
+- Never fabricate step names or results. The event log is authoritative.
+- For \`mode: conversational\` steps, do not call \`update\` without user interaction.
+- If unsure about a step, call \`flow session-bridge status\` or \`flow session-bridge log "<note>"\`.
+${custom ? `\n## Workflow-specific instructions\n\n${custom}\n` : ""}
+The run ID for this session is: ${runId}
+Start by calling \`flow session-bridge next\`.`;
+}