stageflow 0.3.0 → 0.9.0

package/skills/stageflow-run/scripts/mcp-call.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+const DEFAULT_BASE_URL = "http://127.0.0.1:3847";
+const ALLOWED_TOOLS = new Set([
+  "list_pipelines",
+  "list_tasks",
+  "start_run",
+  "get_run",
+  "wait_run",
+  "list_waiting",
+  "answer_gate",
+  "get_health",
+]);
+const PROTOCOL_VERSION = "2025-03-26";
+const INIT_TIMEOUT_MS = 10_000;
+const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+const WAIT_RUN_DEFAULT_MS = 60_000;
+const WAIT_RUN_BUFFER_MS = 5_000;
+const WAIT_RUN_CAP_MS = 250_000;
+
+function usage() {
+  return "Usage: mcp-call.mjs --base-url URL --tool NAME --args JSON [--stateless]";
+}
+
+function parseArgs(argv) {
+  let baseUrl = DEFAULT_BASE_URL;
+  let tool;
+  let argsText = "{}";
+  let stateless = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (arg === "--stateless") {
+      stateless = true;
+      continue;
+    }
+    if (arg === "--base-url") {
+      const value = argv[i + 1];
+      if (!value) {
+        console.error("mcp-call: --base-url requires a URL");
+        console.error(usage());
+        process.exit(2);
+      }
+      baseUrl = value.replace(/\/$/, "");
+      i += 1;
+      continue;
+    }
+    if (arg === "--tool") {
+      const value = argv[i + 1];
+      if (!value) {
+        console.error("mcp-call: --tool requires a name");
+        console.error(usage());
+        process.exit(2);
+      }
+      tool = value;
+      i += 1;
+      continue;
+    }
+    if (arg === "--args") {
+      const value = argv[i + 1];
+      if (value === undefined) {
+        console.error("mcp-call: --args requires JSON");
+        console.error(usage());
+        process.exit(2);
+      }
+      argsText = value;
+      i += 1;
+      continue;
+    }
+    console.error(`mcp-call: unknown argument: ${arg}`);
+    console.error(usage());
+    process.exit(2);
+  }
+  return { baseUrl, tool, argsText, stateless };
+}
+
+function parseToolArgs(argsText) {
+  try {
+    const value = JSON.parse(argsText);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      console.error("mcp-call: --args must be a JSON object");
+      process.exit(2);
+    }
+    return value;
+  } catch {
+    console.error("mcp-call: --args is not valid JSON");
+    process.exit(2);
+  }
+}
+
+function toolTimeoutMs(tool, toolArgs) {
+  if (tool !== "wait_run") return DEFAULT_TOOL_TIMEOUT_MS;
+  const budget =
+    typeof toolArgs.timeout_ms === "number" && toolArgs.timeout_ms > 0
+      ? toolArgs.timeout_ms
+      : WAIT_RUN_DEFAULT_MS;
+  return Math.min(budget + WAIT_RUN_BUFFER_MS, WAIT_RUN_CAP_MS);
+}
+
+function parseMcpMessage(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return undefined;
+  const looksSse =
+    /(?:^|\n)(?:event:|data:)/.test(trimmed) || trimmed.startsWith("event:") || trimmed.startsWith("data:");
+  if (looksSse) {
+    const payloads = [];
+    for (const line of trimmed.split(/\r?\n/)) {
+      if (!line.startsWith("data:")) continue;
+      const raw = line.slice(line.startsWith("data: ") ? 6 : 5).trim();
+      if (!raw || raw === "[DONE]") continue;
+      try {
+        payloads.push(JSON.parse(raw));
+      } catch {}
+    }
+    return (
+      payloads.find((item) => item && (item.result !== undefined || item.error !== undefined)) ??
+      payloads.at(-1)
+    );
+  }
+  return JSON.parse(trimmed);
+}
+
+function extractToolPayload(message) {
+  if (message.error) {
+    return { payload: message.error, isError: true };
+  }
+  const result = message.result;
+  if (!result || typeof result !== "object") {
+    return { payload: message, isError: true };
+  }
+  const text = result.content?.[0]?.text;
+  let payload;
+  if (typeof text === "string" && text.length > 0) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { text };
+    }
+  } else if (result.structuredContent !== undefined) {
+    payload = result.structuredContent;
+  } else {
+    payload = result;
+  }
+  return { payload, isError: result.isError === true };
+}
+
+async function postMcp(mcpUrl, { body, sessionId, timeoutMs }) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+    };
+    if (sessionId) headers["mcp-session-id"] = sessionId;
+    const res = await fetch(mcpUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: ac.signal,
+    });
+    const text = await res.text();
+    return { res, text };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function failTransport(detail, extra) {
+  if (extra !== undefined) {
+    process.stdout.write(`${JSON.stringify(extra)}\n`);
+  }
+  console.error(`mcp-call: ${detail}`);
+}
+
+async function initializeSession(mcpUrl) {
+  const { res, text } = await postMcp(mcpUrl, {
+    body: {
+      jsonrpc: "2.0",
+      id: 0,
+      method: "initialize",
+      params: {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "stageflow-run", version: "1.0.0" },
+      },
+    },
+    timeoutMs: INIT_TIMEOUT_MS,
+  });
+  if (res.status < 200 || res.status >= 300) {
+    let extra;
+    try {
+      extra = parseMcpMessage(text) ?? { status: res.status, body: text };
+    } catch {
+      extra = { status: res.status, body: text };
+    }
+    failTransport(`initialize failed (${res.status})`, extra.error ?? extra);
+    throw new Error("initialize failed");
+  }
+  const sessionId = res.headers.get("mcp-session-id") ?? undefined;
+  try {
+    await postMcp(mcpUrl, {
+      body: { jsonrpc: "2.0", method: "notifications/initialized" },
+      sessionId,
+      timeoutMs: INIT_TIMEOUT_MS,
+    });
+  } catch {}
+  return sessionId;
+}
+
+async function closeSession(mcpUrl, sessionId) {
+  if (!sessionId) return;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), INIT_TIMEOUT_MS);
+  try {
+    await fetch(mcpUrl, {
+      method: "DELETE",
+      headers: { "mcp-session-id": sessionId },
+      signal: ac.signal,
+    });
+  } catch {
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function handleToolResponse(res, text) {
+  let message;
+  try {
+    message = parseMcpMessage(text);
+  } catch {
+    failTransport(`unreadable response (${res.status})`, { status: res.status, body: text });
+    return 1;
+  }
+  if (res.status < 200 || res.status >= 300) {
+    failTransport(`HTTP ${res.status}`, message?.error ?? message ?? { status: res.status, body: text });
+    return 1;
+  }
+  if (!message) {
+    failTransport(`empty response (${res.status})`, { status: res.status });
+    return 1;
+  }
+  const { payload, isError } = extractToolPayload(message);
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+  return isError ? 1 : 0;
+}
+
+const { baseUrl, tool, argsText, stateless } = parseArgs(process.argv.slice(2));
+
+if (!tool) {
+  console.error("mcp-call: --tool is required");
+  console.error(usage());
+  process.exit(2);
+}
+
+if (!ALLOWED_TOOLS.has(tool)) {
+  console.error(`mcp-call: unknown tool: ${tool}`);
+  console.error(`allowed: ${[...ALLOWED_TOOLS].join(", ")}`);
+  process.exit(2);
+}
+
+const toolArgs = parseToolArgs(argsText);
+const mcpUrl = `${baseUrl}/mcp`;
+const timeoutMs = toolTimeoutMs(tool, toolArgs);
+
+let sessionId;
+let exitCode = 1;
+try {
+  if (!stateless) {
+    sessionId = await initializeSession(mcpUrl);
+  }
+  const { res, text } = await postMcp(mcpUrl, {
+    body: {
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name: tool, arguments: toolArgs },
+    },
+    sessionId,
+    timeoutMs,
+  });
+  exitCode = handleToolResponse(res, text);
+} catch (err) {
+  if (err instanceof Error && err.message === "initialize failed") {
+    exitCode = 1;
+  } else {
+    const aborted = err && typeof err === "object" && err.name === "AbortError";
+    failTransport(aborted ? "request timed out" : err instanceof Error ? err.message : String(err));
+    exitCode = 1;
+  }
+} finally {
+  if (sessionId) {
+    await closeSession(mcpUrl, sessionId);
+  }
+}
+process.exit(exitCode);

package/skills/stageflow-run/scripts/mcp-call.test.mjs

@@ -0,0 +1,271 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "mcp-call.mjs");
+
+function run(args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [script, ...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolve({ status: -1, stdout, stderr: `${stderr}\ntimed out` });
+    }, opts.timeoutMs ?? 8000);
+    child.on("close", (status) => {
+      clearTimeout(timer);
+      resolve({ status, stdout, stderr });
+    });
+  });
+}
+
+function listen(handler) {
+  return new Promise((resolve) => {
+    const server = createServer(handler);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      resolve({ server, baseUrl: `http://127.0.0.1:${addr.port}` });
+    });
+  });
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (chunks.length === 0) {
+        resolve(undefined);
+        return;
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function writeToolResult(res, id, payload, isError = false) {
+  const message = {
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text: JSON.stringify(payload) }],
+      ...(isError ? { isError: true } : {}),
+    },
+  };
+  const data = `event: message\ndata: ${JSON.stringify(message)}\n\n`;
+  res.writeHead(200, { "content-type": "text/event-stream" });
+  res.end(data);
+}
+
+const HEALTH = {
+  ok: true,
+  activeRunIds: [],
+  activeCount: 0,
+  maxConcurrent: 3,
+  slotsAvailable: 3,
+  activeStageProcesses: 0,
+  maxActiveStageProcesses: null,
+};
+
+test("get_health against a mock stateless host returns health JSON, exit 0", async () => {
+  const { server, baseUrl } = await listen(async (req, res) => {
+    if (req.method !== "POST" || req.url !== "/mcp") {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+    const body = await readJsonBody(req);
+    if (body?.method !== "tools/call" || body?.params?.name !== "get_health") {
+      res.writeHead(400, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "unexpected call" }));
+      return;
+    }
+    writeToolResult(res, body.id, HEALTH);
+  });
+  try {
+    const result = await run([
+      "--base-url",
+      baseUrl,
+      "--tool",
+      "get_health",
+      "--args",
+      "{}",
+      "--stateless",
+    ]);
+    assert.equal(result.status, 0);
+    assert.deepEqual(JSON.parse(result.stdout), HEALTH);
+  } finally {
+    server.close();
+  }
+});
+
+test("answer_gate with a well-formed free_text answer returns { ok: true }", async () => {
+  const { server, baseUrl } = await listen(async (req, res) => {
+    const body = await readJsonBody(req);
+    const args = body?.params?.arguments ?? {};
+    const answer = args.answer ?? {};
+    if (
+      body?.params?.name !== "answer_gate" ||
+      args.runId !== "run-1" ||
+      args.stageId !== "clarify" ||
+      answer.kind !== "free_text" ||
+      answer.text !== "payments"
+    ) {
+      writeToolResult(res, body?.id ?? 1, { error: "bad answer", status: 400 }, true);
+      return;
+    }
+    writeToolResult(res, body.id, { ok: true });
+  });
+  try {
+    const result = await run([
+      "--base-url",
+      baseUrl,
+      "--tool",
+      "answer_gate",
+      "--args",
+      JSON.stringify({
+        runId: "run-1",
+        stageId: "clarify",
+        answer: { promptId: "prompt-1", kind: "free_text", text: "payments" },
+      }),
+      "--stateless",
+    ]);
+    assert.equal(result.status, 0);
+    assert.deepEqual(JSON.parse(result.stdout), { ok: true });
+  } finally {
+    server.close();
+  }
+});
+
+test("wait_run timeout_ms returns reason timeout with exit 0", async () => {
+  const { server, baseUrl } = await listen(async (req, res) => {
+    const body = await readJsonBody(req);
+    writeToolResult(res, body.id, {
+      reason: "timeout",
+      elapsed_ms: 1,
+      until: "any",
+      run: { id: "run-1", status: "running" },
+    });
+  });
+  try {
+    const result = await run([
+      "--base-url",
+      baseUrl,
+      "--tool",
+      "wait_run",
+      "--args",
+      JSON.stringify({ runId: "run-1", timeout_ms: 1, until: "any" }),
+      "--stateless",
+    ]);
+    assert.equal(result.status, 0);
+    assert.equal(JSON.parse(result.stdout).reason, "timeout");
+  } finally {
+    server.close();
+  }
+});
+
+test("malformed JSON args fail before any network call", async () => {
+  let hits = 0;
+  const { server, baseUrl } = await listen((_req, res) => {
+    hits += 1;
+    res.writeHead(204);
+    res.end();
+  });
+  try {
+    const result = await run([
+      "--base-url",
+      baseUrl,
+      "--tool",
+      "get_health",
+      "--args",
+      "{not-json",
+      "--stateless",
+    ]);
+    assert.equal(result.status, 2);
+    assert.match(result.stderr, /json|parse|args/i);
+    assert.equal(hits, 0);
+  } finally {
+    server.close();
+  }
+});
+
+test("isError true exits non-zero and prints the payload", async () => {
+  const payload = { error: "stage not waiting", status: 409 };
+  const { server, baseUrl } = await listen(async (req, res) => {
+    const body = await readJsonBody(req);
+    writeToolResult(res, body.id, payload, true);
+  });
+  try {
+    const result = await run([
+      "--base-url",
+      baseUrl,
+      "--tool",
+      "answer_gate",
+      "--args",
+      JSON.stringify({
+        runId: "run-1",
+        stageId: "clarify",
+        answer: { promptId: "p", kind: "free_text", text: "x" },
+      }),
+      "--stateless",
+    ]);
+    assert.notEqual(result.status, 0);
+    assert.notEqual(result.status, 2);
+    assert.deepEqual(JSON.parse(result.stdout), payload);
+  } finally {
+    server.close();
+  }
+});
+
+test("--stateless against a session-mode-only mock errors without hanging", async () => {
+  const { server, baseUrl } = await listen((_req, res) => {
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "Bad Request: Session ID required" },
+        id: null,
+      }),
+    );
+  });
+  try {
+    const result = await run(
+      [
+        "--base-url",
+        baseUrl,
+        "--tool",
+        "get_health",
+        "--args",
+        "{}",
+        "--stateless",
+      ],
+      { timeoutMs: 4000 },
+    );
+    assert.notEqual(result.status, 0);
+    assert.notEqual(result.status, -1);
+    assert.match(`${result.stdout}\n${result.stderr}`, /session|required|400/i);
+  } finally {
+    server.close();
+  }
+});

package/skills/stageflow-session-capture/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: stageflow-session-capture
+description: >-
+  Turns a coding session or pasted transcript into reusable Stageflow stages
+  and a pipeline in the project catalog. Use when the user wants to capture
+  this chat or a past session so the same loop can be rerun later.
+compatibility: Requires Node.js >= 20 and the sf CLI on PATH
+disable-model-invocation: true
+---
+
+# Stageflow session capture
+
+Extract what happened and what worked from the current session, an explicit file, or a pasted transcript. Write stages and a pipeline into the catalog. `stageflow-run` owns throwaway tasks and starting a run.
+
+This job talks to Stageflow through the `sf` CLI. Talking jobs cite [`../stageflow/references/control-surface.md`](../stageflow/references/control-surface.md) for MCP-vs-CLI; do not run the host probe in that file from this job.
+
+Shape reference: [`assets/example-pipeline/example.pipeline.yaml`](assets/example-pipeline/example.pipeline.yaml), [`assets/example-pipeline/research.yaml`](assets/example-pipeline/research.yaml), [`assets/example-pipeline/implement.yaml`](assets/example-pipeline/implement.yaml).
+
+## Preconditions
+
+**Done when** `sf` is on PATH and `stageflow.yaml` exists at the catalog root (git top-level when `git rev-parse --show-toplevel` succeeds, otherwise the current directory).
+
+If either is missing, stop and name `stageflow-setup`. Do not scaffold the manifest or install the CLI here.
+
+## Session source
+
+Pick one mode. **Done when** you have the history you will extract from.
+
+1. **Live context (default).** The work is already in this conversation. Draft from context. Do not read a transcript file.
+2. **Explicit pointer.** The human passed `--path`, a file path, or pasted text. Use that directly. For a path, run:
+
+   `node scripts/locate-session-transcript.mjs --path <file>`
+
+   `{"ok":true,"source":"explicit"}` → read that path. `{"ok":false,"reason":"unreadable"}` → ask for another path or a paste.
+3. **Past session, no pointer.** Run one lookup:
+
+   `node scripts/locate-session-transcript.mjs`
+
+   `{"ok":true}` → show `path` to the human, then extract from that file. `{"ok":false,"reason":"not_found"}` → ask the human to point at a file or paste the history.
+
+Stores, encoding, and the point-or-paste fallback: [`references/transcript-sources.md`](references/transcript-sources.md). Do not open Cursor or OpenCode SQLite databases.
+
+## Provider gate
+
+Run before any catalog write:
+
+```
+node scripts/check-provider-gate.mjs
+```
+
+`--sf-bin <path>` defaults to `sf`. Stdout is JSON.
+
+| stdout | next |
+|---|---|
+| `{"ok":true}` | continue |
+| `{"ok":false,"reason":"no_provider_configured"}` | stop; name `stageflow-setup` |
+| `{"ok":false,"reason":"sf_not_found"}` | stop; name `stageflow-setup` |
+
+Do not run `sf providers login`.
+
+## Extract
+
+From the chosen source, list the phases that happened and what worked in each. Drop one-off paths, secrets, and chat noise. Keep a human-review checkpoint as prose in that stage's approach, not as a HITL gate.
+
+**Done when** you have an ordered phase list and a one-line pipeline purpose.
+
+## Author
+
+Read [`references/catalog-authoring.md`](references/catalog-authoring.md) before writing.
+
+1. Open `stageflow.yaml`. Write under a `catalog.pipelines` root (a new subdirectory is fine). If the manifest is missing or unreadable, stop and name `stageflow-setup`.
+2. For the pipeline and each stage, resolve an id:
+
+   `node scripts/resolve-catalog-id.mjs --text "<phrase>" --dir <write-dir> --kind pipeline|stage`
+
+   Use the printed `{"id":"..."}`.
+3. Write one external stage YAML per phase (`id`, `system_prompt`, `model`). End every `system_prompt` with an `emit_stage_envelope` footer. Omit `gate_kinds`. Filename stem must match `id`.
+4. Write one pipeline YAML that wires the stages with `uses:` and `needs:` in dependency order.
+
+Do not write a `*.task.yaml`.
+
+**Done when** the pipeline file and every stage file exist on disk.
+
+## Validate
+
+```
+sf validate --pipeline <pipeline-path> --strict
+```
+
+**Done when** the command exits 0. If it fails, delete every file this invocation wrote, report the finding, and stop.
+
+## Report
+
+Print the pipeline path and each stage path. Name `stageflow-run` if the human wants to execute the pipeline.

package/skills/stageflow-session-capture/assets/example-pipeline/example.pipeline.yaml

@@ -0,0 +1,7 @@
+id: example
+stages:
+  - id: research
+    uses: ./research.yaml
+  - id: implement
+    uses: ./implement.yaml
+    needs: research

package/skills/stageflow-session-capture/assets/example-pipeline/implement.yaml

@@ -0,0 +1,8 @@
+id: implement
+system_prompt: |
+  Take the prior stage envelope and produce the concrete deliverable described
+  there. Prefer what already worked in the source session.
+
+  When finished, call emit_stage_envelope once with status, summary, artifacts,
+  and a payload describing what you produced.
+model: anthropic/claude-sonnet-4-5

package/skills/stageflow-session-capture/assets/example-pipeline/research.yaml

@@ -0,0 +1,8 @@
+id: research
+system_prompt: |
+  Review the incoming goal and prior notes. Identify what is known, what is
+  unknown, and the next useful work.
+
+  When finished, call emit_stage_envelope once with status, summary, artifacts,
+  and a payload the next stage can use.
+model: anthropic/claude-sonnet-4-5