stageflow 0.2.0 → 0.3.0

package/dist/agent/piAdapter.js

@@ -41,8 +41,8 @@ import { createAskOperatorTool, } from "../tools/askOperator.js";
 import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
 import "./cursorProvider.js";
 import { findProviderSupport } from "./providerSupport.js";
-import { mapSessionEventToActivity } from "./activity.js";
-import { createStageActivityObserver } from "./activityObserver.js";
+import { mapSessionEventToActivity, readActivityVerbose } from "./activity.js";
+import { createStageActivityObserver, } from "./activityObserver.js";
 import { DEFAULT_STAGE_TIMEOUT_MS, runStageViaOpen } from "./port.js";
 /**
  * Stage tool allowlist for sealed Pi sessions.
@@ -260,31 +260,98 @@ export function createConnectedAskWaitStageHandle(options) {
         },
     };
 }
+/**
+ * Extract display text from a Pi tool_execution_update partialResult.
+ * Prefers content[].text blocks; otherwise JSON-stringifies.
+ */
+export function extractPartialResultText(partialResult) {
+    if (partialResult === undefined || partialResult === null) {
+        return "";
+    }
+    if (typeof partialResult === "string") {
+        return partialResult;
+    }
+    if (typeof partialResult === "object") {
+        const content = partialResult.content;
+        if (Array.isArray(content)) {
+            const parts = [];
+            for (const block of content) {
+                if (!block || typeof block !== "object")
+                    continue;
+                const b = block;
+                if (b.type === "text" && typeof b.text === "string") {
+                    parts.push(b.text);
+                }
+            }
+            if (parts.length > 0) {
+                return parts.join("");
+            }
+        }
+        try {
+            return JSON.stringify(partialResult);
+        }
+        catch {
+            return String(partialResult);
+        }
+    }
+    return String(partialResult);
+}
+/**
+ * Adapter-edge routing: stream deltas to the observer, map milestones to
+ * StageActivityEvent. Verbose thinking / live tool partials go to observer
+ * hooks (stderr streams + coalesced/throttled persist via onActivity).
+ */
+export function routeSessionEventToProgress(event, options) {
+    const { observer, verbose } = options;
+    if (event.type === "message_update") {
+        const ame = event.assistantMessageEvent;
+        if (ame && typeof ame === "object") {
+            const update = ame;
+            if (update.type === "text_delta") {
+                observer.onAssistantTextDelta(update.delta ?? "");
+                return;
+            }
+            if (verbose && update.type === "thinking_delta") {
+                observer.onThinkingDelta(update.delta ?? "");
+                return;
+            }
+        }
+        return;
+    }
+    if (verbose &&
+        event.type === "tool_execution_update") {
+        const text = extractPartialResultText(event.partialResult);
+        if (text) {
+            observer.onToolPartialResult(text);
+        }
+        return;
+    }
+    if (event.type === "message_end" || event.type === "agent_end") {
+        observer.onStreamBoundary();
+    }
+    if (event.type === "agent_start" ||
+        event.type === "turn_start" ||
+        event.type === "tool_execution_start") {
+        observer.onStreamBoundary();
+    }
+    const activity = mapSessionEventToActivity(event);
+    if (!activity) {
+        return;
+    }
+    observer.onActivity(activity);
+}
 /**
  * Map Pi session events to StageActivityEvent at the adapter edge, then
  * forward to the activity observer (stderr + onActivity).
  */
 function attachStageProgress(session, onActivity) {
     const observer = createStageActivityObserver({ onActivity, writeStderr: true });
+    const verbose = readActivityVerbose();
     const unsubscribe = session.subscribe((event) => {
-        if (event.type === "message_update" &&
-            event.assistantMessageEvent.type === "text_delta") {
-            observer.onAssistantTextDelta(event.assistantMessageEvent.delta ?? "");
-            return;
-        }
-        if (event.type === "message_end" || event.type === "agent_end") {
-            observer.onStreamBoundary();
-        }
-        if (event.type === "agent_start" ||
-            event.type === "turn_start" ||
-            event.type === "tool_execution_start") {
-            observer.onStreamBoundary();
-        }
-        const activity = mapSessionEventToActivity(event);
-        if (!activity) {
-            return;
-        }
-        observer.onActivity(activity);
+        routeSessionEventToProgress(event, {
+            observer,
+            verbose,
+        });
     });
     return () => {
         unsubscribe();
@@ -616,7 +683,7 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
     const provider = findProviderSupport(input.stage.model);
     const capture = {};
     const askWaitChannel = existingAskWaitChannel ?? new AskOperatorWaitChannel();
-    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema);
+    const emitDef = createEmitStageEnvelopeTool(capture, input.stage.payload_schema, input.forkEmitContext);
     const emitTool = defineTool(emitDef);
     const askDef = createAskOperatorTool({
         requestWait: (prompt) => askWaitChannel.requestWait(prompt),

package/dist/agent/port.d.ts

@@ -1,4 +1,5 @@
 import type { StageEnvelope } from "../types/envelope.js";
+import type { ForkEmitContext } from "../types/forkChoice.js";
 import type { StageConfig } from "../types/stage.js";
 import type { TaskFile } from "../types/task.js";
 import type { StageActivityEvent } from "./activity.js";
@@ -15,6 +16,7 @@ export type StageRunInput = {
     /** Optional observe hook; HITL wait/answer uses openStage beside this. */
     onActivity?: (event: StageActivityEvent) => void;
     skillFilePath?: string;
+    forkEmitContext?: ForkEmitContext;
 };
 export type StageRunResult = {
     ok: true;

package/dist/agent/providerAuth.js

@@ -1,5 +1,7 @@
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
-import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, readCredentialSourceFromFile, resolveCredentialBinding, writeCredentialSourceToFile, } from "../runtime/credentialBinding.js";
+import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, resolveCredentialBinding, writeCredentialSourceToContext, } from "../runtime/credentialBinding.js";
+import { readPersistedCredentialSourceFromContext, } from "../runtime/settingsFile.js";
+import { resolveProjectContext } from "../project/resolveProjectContext.js";
 export function makeMutationLock() {
     let tail = Promise.resolve();
     return {
@@ -245,8 +247,9 @@ export async function logoutProvider(cwd, providerId, ctx = defaultContext) {
     });
 }
 export function detectPiHome(cwd) {
-    const binding = resolveCredentialBinding(cwd);
-    const persisted = readCredentialSourceFromFile(cwd);
+    const projectCtx = resolveProjectContext(cwd);
+    const binding = resolveCredentialBinding(projectCtx);
+    const persisted = readPersistedCredentialSourceFromContext(projectCtx);
     return {
         piHomeUsable: isUsableAuthFile(piHomeAuthPath()),
         ...(persisted !== undefined ? { credentialSource: persisted } : {}),
@@ -255,8 +258,9 @@ export function detectPiHome(cwd) {
     };
 }
 export function getCredentialSourceSettings(cwd) {
-    const persisted = readCredentialSourceFromFile(cwd);
-    const binding = resolveCredentialBinding(cwd);
+    const projectCtx = resolveProjectContext(cwd);
+    const persisted = readPersistedCredentialSourceFromContext(projectCtx);
+    const binding = resolveCredentialBinding(projectCtx);
     return {
         ...(persisted !== undefined ? { credentialSource: persisted } : {}),
         binding: {
@@ -270,8 +274,9 @@ export function setCredentialSource(cwd, credentialSource) {
     if (parsed === undefined) {
         throw new ProviderAuthError('credentialSource must be "pi_home" or "sf_owned"', 400);
     }
-    writeCredentialSourceToFile(cwd, parsed);
-    const binding = resolveCredentialBinding(cwd);
+    const projectCtx = resolveProjectContext(cwd);
+    writeCredentialSourceToContext(projectCtx, parsed);
+    const binding = resolveCredentialBinding(projectCtx);
     return {
         credentialSource: parsed,
         binding: {

package/dist/catalog/displayCatalogPath.d.ts

@@ -0,0 +1,12 @@
+export declare function displayCatalogPath(absPath: string, projectRoot?: string): string;
+export declare function normalizeCatalogSlashes(pathValue: string): string;
+export type PipelinePathMatchInput = {
+    pipeline_id: string;
+    pipeline_path?: string;
+    project_root?: string;
+};
+export type PipelineListingPath = {
+    id: string;
+    path: string;
+};
+export declare function matchPipelineRun(run: PipelinePathMatchInput, pipeline: PipelineListingPath): boolean;

package/dist/catalog/displayCatalogPath.js

@@ -0,0 +1,28 @@
+export function displayCatalogPath(absPath, projectRoot) {
+    if (projectRoot) {
+        const root = projectRoot.replace(/\\/g, "/").replace(/\/$/, "");
+        const normalized = absPath.replace(/\\/g, "/");
+        if (normalized === root)
+            return ".";
+        const prefix = `${root}/`;
+        if (normalized.startsWith(prefix)) {
+            return normalized.slice(prefix.length);
+        }
+    }
+    const parts = absPath.replace(/\\/g, "/").split("/");
+    return parts[parts.length - 1] ?? absPath;
+}
+export function normalizeCatalogSlashes(pathValue) {
+    return pathValue.replace(/\\/g, "/");
+}
+export function matchPipelineRun(run, pipeline) {
+    if (run.pipeline_id === pipeline.id)
+        return true;
+    if (run.pipeline_path && run.project_root) {
+        const rel = displayCatalogPath(run.pipeline_path, run.project_root);
+        if (normalizeCatalogSlashes(rel) === normalizeCatalogSlashes(pipeline.path)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/cli/initCommand.d.ts

@@ -0,0 +1,9 @@
+export declare const INIT_USAGE = "Usage:\n  sf init";
+export type InitCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+export declare function runInitCommand(args: string[], options?: {
+    cwd?: string;
+    io?: Partial<InitCommandIo>;
+}): Promise<number>;

package/dist/cli/initCommand.js

@@ -0,0 +1,71 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { findProjectRoot } from "../project/findProjectRoot.js";
+import { ensureGlobalHome } from "../project/globalHome.js";
+import { HELLO_PIPELINE_YAML, HELLO_TASK_YAML, STAGEFLOW_YAML, } from "./initTemplates.js";
+export const INIT_USAGE = `Usage:
+  sf init`;
+const defaultIo = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+const INIT_TARGETS = [
+    { relPath: "stageflow.yaml", content: STAGEFLOW_YAML },
+    { relPath: "pipelines/hello.pipeline.yaml", content: HELLO_PIPELINE_YAML },
+    { relPath: "tasks/hello.task.yaml", content: HELLO_TASK_YAML },
+];
+async function fileExists(absPath) {
+    try {
+        await access(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseInitArgs(args) {
+    if (args.length === 0) {
+        return { help: false };
+    }
+    if (args[0] === "--help" || args[0] === "-h") {
+        return { help: true };
+    }
+    if (args[0].startsWith("-")) {
+        throw new Error(`Unknown flag: ${args[0]}`);
+    }
+    throw new Error(`Unexpected argument: ${args[0]}`);
+}
+export async function runInitCommand(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const out = { ...defaultIo, ...options.io };
+    try {
+        const parsed = parseInitArgs(args);
+        if (parsed.help) {
+            out.error(INIT_USAGE);
+            return 0;
+        }
+        const initRoot = findProjectRoot(cwd) ?? path.resolve(cwd);
+        ensureGlobalHome();
+        for (const target of INIT_TARGETS) {
+            const absPath = path.join(initRoot, target.relPath);
+            if (await fileExists(absPath)) {
+                out.log(`Skipped ${target.relPath} (exists)`);
+                continue;
+            }
+            await mkdir(path.dirname(absPath), { recursive: true });
+            await writeFile(absPath, target.content, "utf8");
+            out.log(`Created ${target.relPath}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error
+            ? err.message
+            : typeof err === "string"
+                ? err
+                : "Init command failed";
+        out.error(message);
+        out.error(INIT_USAGE);
+        return 1;
+    }
+}

package/dist/cli/initTemplates.d.ts

@@ -0,0 +1,3 @@
+export declare const STAGEFLOW_YAML = "version: 1\ncatalog:\n  pipelines:\n    - pipelines\n  tasks:\n    - tasks\n  patterns:\n    pipeline: \"*.pipeline.yaml\"\n    task: \"*.task.yaml\"\n";
+export declare const HELLO_PIPELINE_YAML = "id: hello\nstages:\n  - id: hello\n    system_prompt: Say hello and emit a success envelope.\n    model: anthropic/claude-sonnet-4-5\n";
+export declare const HELLO_TASK_YAML = "id: hello\ngoal: Run the hello pipeline scaffold.\n";

package/dist/cli/initTemplates.js

@@ -0,0 +1,19 @@
+export const STAGEFLOW_YAML = `version: 1
+catalog:
+  pipelines:
+    - pipelines
+  tasks:
+    - tasks
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+`;
+export const HELLO_PIPELINE_YAML = `id: hello
+stages:
+  - id: hello
+    system_prompt: Say hello and emit a success envelope.
+    model: anthropic/claude-sonnet-4-5
+`;
+export const HELLO_TASK_YAML = `id: hello
+goal: Run the hello pipeline scaffold.
+`;

package/dist/cli/operatorCatalog.d.ts

@@ -0,0 +1,10 @@
+import type { OperatorCatalog } from "../runtime/stageAttemptBootstrap.js";
+export type OperatorCatalogFlags = {
+    operatorCwd?: string;
+    operatorAgentDir?: string;
+};
+export declare function resolveOperatorCatalog(input: {
+    flags: OperatorCatalogFlags;
+    env: Record<string, string | undefined>;
+    defaultCwd: string;
+}): OperatorCatalog;

package/dist/cli/operatorCatalog.js

@@ -0,0 +1,16 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+function nonempty(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+export function resolveOperatorCatalog(input) {
+    const cwd = nonempty(input.flags.operatorCwd) ??
+        nonempty(input.env.STAGEFLOW_OPERATOR_CWD) ??
+        input.defaultCwd;
+    const agentDir = nonempty(input.flags.operatorAgentDir) ??
+        nonempty(input.env.STAGEFLOW_OPERATOR_AGENT_DIR) ??
+        getAgentDir();
+    return { cwd, agentDir };
+}

package/dist/cli/runCommand.d.ts

@@ -1,6 +1,6 @@
 import { type StartRunResult } from "../runtime/runManager.js";
 import { type CliRunReportIo } from "./runOutput.js";
-export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <name-or-path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>]";
+export declare const RUN_USAGE = "Usage:\n  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]";
 export type RunCommandIo = CliRunReportIo;
 export type StartRunFn = (input: {
     task: string;
@@ -18,6 +18,8 @@ export declare function completeCliRun(started: Extract<StartRunResult, {
 }): Promise<number>;
 export declare function runRunCommand(args: string[], options?: {
     cwd?: string;
+    projectRoot?: string;
+    isGitProject?: boolean;
     io?: Partial<RunCommandIo>;
     startRun?: StartRunFn;
     env?: Record<string, string | undefined>;

package/dist/cli/runCommand.js

@@ -1,4 +1,3 @@
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { PiAgentAdapter } from "../agent/piAdapter.js";
 import { createRunStore } from "../runstore/createStore.js";
 import { PipelineValidationError } from "../runtime/pipelineRunner.js";
@@ -6,9 +5,10 @@ import { RunManager } from "../runtime/runManager.js";
 import { readStageExecutionMode } from "../runtime/stageConcurrency.js";
 import { reportCliRun, } from "./runOutput.js";
 import { resolveCiIdentity } from "./ciIdentity.js";
+import { resolveOperatorCatalog } from "./operatorCatalog.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const RUN_USAGE = `Usage:
-  sf run --task <path> --pipeline <name-or-path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>]`;
+  sf run --task <path> --pipeline <path> [--checkout <path>] [--json] [--skip-gates] [--git-sha <sha>] [--ci-pr-url <url>] [--ci-job-url <url>] [--operator-cwd <path>] [--operator-agent-dir <path>]`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -26,6 +26,8 @@ function parseRunArgs(args) {
     let gitSha;
     let ciPrUrl;
     let ciJobUrl;
+    let operatorCwd;
+    let operatorAgentDir;
     let json = false;
     let skipGates = false;
     let help = false;
@@ -76,6 +78,20 @@ function parseRunArgs(args) {
             }
             ciJobUrl = value;
         }
+        else if (arg === "--operator-cwd") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --operator-cwd");
+            }
+            operatorCwd = value;
+        }
+        else if (arg === "--operator-agent-dir") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --operator-agent-dir");
+            }
+            operatorAgentDir = value;
+        }
         else if (arg === "--json") {
             json = true;
         }
@@ -89,16 +105,30 @@ function parseRunArgs(args) {
             throw new Error(`Unexpected argument: ${arg}`);
         }
     }
-    return { help, json, skipGates, task, pipeline, checkout, gitSha, ciPrUrl, ciJobUrl };
+    return {
+        help,
+        json,
+        skipGates,
+        task,
+        pipeline,
+        checkout,
+        gitSha,
+        ciPrUrl,
+        ciJobUrl,
+        operatorCwd,
+        operatorAgentDir,
+    };
 }
-function defaultStartRun(cwd) {
+function defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog) {
     return async (input) => {
-        const store = createRunStore({ rootDir: cwd });
+        const store = createRunStore({ rootDir: projectRoot });
         const manager = new RunManager({
             agent: new PiAgentAdapter(),
             store,
             cwd,
-            operatorCatalog: { cwd, agentDir: getAgentDir() },
+            projectRoot,
+            isGitProject,
+            operatorCatalog,
             executionMode: readStageExecutionMode(process.env, "process"),
         });
         return manager.startRun(input);
@@ -110,6 +140,8 @@ export async function completeCliRun(started, io = defaultIo, options = {}) {
 }
 export async function runRunCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
+    const isGitProject = options.isGitProject ?? false;
     const out = { ...defaultIo, ...options.io };
     let parsed;
     try {
@@ -130,7 +162,16 @@ export async function runRunCommand(args, options = {}) {
         out.error(RUN_USAGE);
         return 1;
     }
-    const startRun = options.startRun ?? defaultStartRun(cwd);
+    const operatorCatalog = resolveOperatorCatalog({
+        flags: {
+            operatorCwd: parsed.operatorCwd,
+            operatorAgentDir: parsed.operatorAgentDir,
+        },
+        env: options.env ?? process.env,
+        defaultCwd: cwd,
+    });
+    const startRun = options.startRun ??
+        defaultStartRun(cwd, projectRoot, isGitProject, operatorCatalog);
     const identity = resolveCiIdentity({
         flags: {
             gitSha: parsed.gitSha,

package/dist/cli/validateCommand.d.ts

@@ -1,5 +1,5 @@
 import { validateCatalog as defaultValidateCatalog, type ValidationResult } from "../config/validateCatalog.js";
-export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--pipeline <name-or-path>] [--strict] [--json]";
+export declare const VALIDATE_USAGE = "Usage:\n  sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]\n\n  With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).\n  --pipeline validates one pipeline file (includes uses:/include: transitively).\n  --task validates one task file.";
 export type ValidateCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/validateCommand.js

@@ -1,7 +1,11 @@
 import { validateCatalog as defaultValidateCatalog, } from "../config/validateCatalog.js";
 import { exitCodeForValidation, formatValidationHuman, formatValidationJson, } from "./validateOutput.js";
 export const VALIDATE_USAGE = `Usage:
-  sf validate [--pipeline <name-or-path>] [--strict] [--json]`;
+  sf validate [--pipeline <path>] [--task <path>] [--strict] [--json]
+
+  With no flags, validates all pipelines and tasks declared in stageflow.yaml (manifest-all).
+  --pipeline validates one pipeline file (includes uses:/include: transitively).
+  --task validates one task file.`;
 const defaultIo = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -14,6 +18,7 @@ function parseValidateArgs(args) {
         return { help: true, strict: false, json: false };
     }
     let pipeline;
+    let task;
     let strict = false;
     let json = false;
     let help = false;
@@ -29,6 +34,13 @@ function parseValidateArgs(args) {
             }
             pipeline = value;
         }
+        else if (arg === "--task") {
+            const value = args[++i];
+            if (value === undefined || value.length === 0) {
+                throw new Error("Missing value for --task");
+            }
+            task = value;
+        }
         else if (arg === "--strict") {
             strict = true;
         }
@@ -42,7 +54,10 @@ function parseValidateArgs(args) {
             throw new Error(`Unexpected argument: ${arg}`);
         }
     }
-    return { help, pipeline, strict, json };
+    if (pipeline !== undefined && task !== undefined) {
+        throw new Error("Use at most one of --pipeline or --task");
+    }
+    return { help, pipeline, task, strict, json };
 }
 export async function runValidateCommand(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -54,10 +69,12 @@ export async function runValidateCommand(args, options = {}) {
             out.error(VALIDATE_USAGE);
             return 0;
         }
+        const scope = parsed.pipeline ? "pipeline" : parsed.task ? "task" : "full";
         const result = await validateCatalogFn({
-            scope: parsed.pipeline ? "pipeline" : "full",
+            scope,
             cwd,
             pipeline: parsed.pipeline,
+            task: parsed.task,
             strict: parsed.strict,
         });
         if (parsed.json) {

package/dist/cli.d.ts

@@ -10,3 +10,4 @@ export declare function parseRunStageArgs(argv: string[]): {
     operatorCatalog?: OperatorCatalog;
     skipGates?: boolean;
 };
+export declare function sameCliEntry(a: string, b: string): boolean;