stageflow 0.32.0 → 0.33.0

package/README.md

@@ -254,6 +254,7 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 |-----|-------------|
 | [docs/README.md](docs/README.md) | Documentation index |
 | [docs/architecture.md](docs/architecture.md) | Runtime components, execution flow, persistence, and design decisions |
+| [docs/hosted.md](docs/hosted.md) | Embed Stageflow from another application and receive ordered run events |
 | [docs/quickstart.md](docs/quickstart.md) | Expanded quick start |
 | [docs/yaml-catalog.md](docs/yaml-catalog.md) | Pipelines, stages, tasks schema |
 | [docs/cli-reference.md](docs/cli-reference.md) | `sf init`, `sf run`, `sf run-stage`, `sf graph`, `sf validate`, `sf ui`, `sf mcp`, `sf envelope`, `sf export-run`, `sf artifact`, `sf skills`, `sf providers` |

package/dist/agent/fakeAgent.js

@@ -113,12 +113,6 @@ export class FakeAgent {
                 armWait();
             }
         }
-        if (sessionMode === "feedback_resume" && behavior.type === "wait_then_emit") {
-            behavior = {
-                type: "emit",
-                envelope: behavior.envelope,
-            };
-        }
         const emitStartActivity = () => {
             if (started)
                 return;

package/dist/agent/providerAuth.d.ts

@@ -82,6 +82,12 @@ export declare function statusForProvider(runtime: ProviderAuthRuntime, provider
 export declare function listProviders(cwd: string, ctx?: ProviderAuthContext): Promise<ProvidersListResult>;
 export declare function getAuthStatus(cwd: string, providerId?: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus | ProviderAuthStatus[]>;
 export declare function loginWithApiKey(cwd: string, providerId: string, apiKey: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus>;
+/** Write a provider API key into an existing Pi auth file. Does not create the operator home. */
+export declare function configurePiProviderApiKey(options: {
+    authPath: string;
+    providerId: string;
+    apiKey: string;
+}, ctx?: ProviderAuthContext): Promise<void>;
 export type OauthLoginResult = {
     provider: ProviderAuthStatus;
     warning?: string;

package/dist/agent/providerAuth.js

@@ -1,3 +1,5 @@
+import { mkdir, writeFile, chmod, access } from "node:fs/promises";
+import path from "node:path";
 import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
 import { parseCredentialSource, resolveCredentialBinding, writeCredentialSourceToContext, isUsableAuthFile, } from "../runtime/credentialBinding.js";
 import { getCursorHostStatus } from "./cursorProvider.js";
@@ -22,6 +24,23 @@ export class ProviderAuthError extends Error {
     }
 }
 const defaultCreateRuntime = async (authPath) => ModelRuntime.create({ authPath, refreshOnCreate: false });
+async function ensurePiAuthFile(authPath) {
+    const resolved = path.resolve(authPath);
+    await mkdir(path.dirname(resolved), { recursive: true });
+    try {
+        await access(resolved);
+    }
+    catch {
+        await writeFile(resolved, "{}\n", { encoding: "utf8", mode: 0o600 });
+    }
+    try {
+        await chmod(resolved, 0o600);
+    }
+    catch {
+        // best-effort on non-POSIX
+    }
+    return resolved;
+}
 export const defaultContext = {
     createRuntime: defaultCreateRuntime,
     lock: makeMutationLock(),
@@ -159,26 +178,43 @@ function mapLoginError(err, providerId) {
     }
     throw new ProviderAuthError("Provider login failed", 500);
 }
+async function loginApiKeyOnRuntime(runtime, providerId, apiKey) {
+    if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+        throw new ProviderAuthError("apiKey is required", 400);
+    }
+    const provider = runtime.getProvider(providerId);
+    if (!provider) {
+        throw new ProviderAuthError("Provider not found", 404);
+    }
+    if (typeof provider.auth.apiKey?.login !== "function") {
+        throw new ProviderAuthError("Provider does not support api_key login", 400);
+    }
+    try {
+        await runtime.login(providerId, "api_key", apiKeyInteraction(apiKey));
+    }
+    catch (err) {
+        mapLoginError(err, providerId);
+    }
+    return statusForProvider(runtime, providerId);
+}
 export async function loginWithApiKey(cwd, providerId, apiKey, ctx = defaultContext) {
     if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
         throw new ProviderAuthError("apiKey is required", 400);
     }
     return ctx.lock.withMutationLock(async () => {
         const runtime = await openRuntime(cwd, ctx);
-        const provider = runtime.getProvider(providerId);
-        if (!provider) {
-            throw new ProviderAuthError("Provider not found", 404);
-        }
-        if (typeof provider.auth.apiKey?.login !== "function") {
-            throw new ProviderAuthError("Provider does not support api_key login", 400);
-        }
-        try {
-            await runtime.login(providerId, "api_key", apiKeyInteraction(apiKey));
-        }
-        catch (err) {
-            mapLoginError(err, providerId);
-        }
-        return statusForProvider(runtime, providerId);
+        return loginApiKeyOnRuntime(runtime, providerId, apiKey);
+    });
+}
+/** Write a provider API key into an existing Pi auth file. Does not create the operator home. */
+export async function configurePiProviderApiKey(options, ctx = defaultContext) {
+    if (typeof options.authPath !== "string" || options.authPath.trim() === "") {
+        throw new ProviderAuthError("authPath is required", 400);
+    }
+    const authPath = await ensurePiAuthFile(options.authPath);
+    await ctx.lock.withMutationLock(async () => {
+        const runtime = await ctx.createRuntime(authPath);
+        await loginApiKeyOnRuntime(runtime, options.providerId, options.apiKey);
     });
 }
 export async function loginWithOauth(cwd, providerId, interaction, ctx = defaultContext) {

package/dist/agent/resolveAgentPort.d.ts

@@ -11,6 +11,8 @@ export type AgentSelection = {
 };
 /** stage > pipeline > global > "pi", with stage gated off for now. */
 export declare function resolveAgentBackend(selection?: AgentSelection): AgentBackendId;
+/** Existing Pi AgentPort. Hosted runs pass this into createHostedRuntime. */
+export declare function createPiAgentPort(): AgentPort;
 export declare function resolveAgentPort(selection?: AgentSelection): AgentPort;
 /** The global tier's backend id from an already-loaded manifest, or undefined for missing/invalid/unset. */
 export declare function globalAgentBackendFromManifest(manifest: LoadedManifest | null): AgentBackendId | undefined;

package/dist/agent/resolveAgentPort.js

@@ -9,11 +9,15 @@ export function resolveAgentBackend(selection = {}) {
     }
     return selection.pipeline ?? selection.global ?? "pi";
 }
+/** Existing Pi AgentPort. Hosted runs pass this into createHostedRuntime. */
+export function createPiAgentPort() {
+    return new PiAgentAdapter();
+}
 export function resolveAgentPort(selection = {}) {
     const backend = resolveAgentBackend(selection);
     switch (backend) {
         case "pi":
-            return new PiAgentAdapter();
+            return createPiAgentPort();
         case "claude":
             return new ClaudeAgentAdapter();
     }

package/dist/config/listConfig.d.ts

@@ -1,28 +1,12 @@
-import type { StageGateKind } from "../types/stage.js";
 import type { LoadedManifest } from "../types/stageflowManifest.js";
 import { type PipelineListing, type TaskListing } from "./browseCatalog.js";
 import { type StageflowContext } from "../project/resolveStageflowContext.js";
 import { type CatalogContext } from "./resolveCatalogContext.js";
 export type { PipelineListing, PipelineStageListing, TaskListing } from "./browseCatalog.js";
-export type ValidStageListing = {
-    path: string;
-    id: string;
-    used_by_pipeline_ids: string[];
-    gate_kinds?: StageGateKind[];
-};
-export type BrokenStageListing = {
-    path: string;
-    error: string;
-    id?: string;
-    model?: string;
-    gate_kinds?: StageGateKind[];
-};
-export type StageListing = ValidStageListing | BrokenStageListing;
 export type CatalogListOptions = {
     projectRoot: string;
     manifest: LoadedManifest;
 };
 export declare function listTasks(options: CatalogListOptions): Promise<TaskListing[]>;
 export declare function listPipelines(options: CatalogListOptions): Promise<PipelineListing[]>;
-export declare function listStages(_options?: unknown): Promise<StageListing[]>;
 export declare function listModels(cwdOrContext: string | CatalogContext | StageflowContext): Promise<string[]>;

package/dist/config/listConfig.js

@@ -17,9 +17,6 @@ export async function listPipelines(options) {
         issues: [],
     });
 }
-export async function listStages(_options) {
-    return [];
-}
 export async function listModels(cwdOrContext) {
     const ctx = typeof cwdOrContext === "string"
         ? catalogContextFromStageflow(await resolveStageflowContext(cwdOrContext))

package/dist/hosted/containment.d.ts

@@ -0,0 +1,3 @@
+export declare function isContained(rootReal: string, candidateReal: string): boolean;
+export declare function resolveDirectory(root: string): Promise<string>;
+export declare function containedRealPath(rootReal: string, target: string): Promise<string>;

package/dist/hosted/containment.js

@@ -0,0 +1,36 @@
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+export function isContained(rootReal, candidateReal) {
+    const relative = path.relative(rootReal, candidateReal);
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${path.sep}`) &&
+            !path.isAbsolute(relative)));
+}
+export async function resolveDirectory(root) {
+    const absolute = path.resolve(root);
+    let info;
+    try {
+        info = await stat(absolute);
+    }
+    catch {
+        throw new Error(`package root does not exist: ${absolute}`);
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`package root is not a directory: ${absolute}`);
+    }
+    return realpath(absolute);
+}
+export async function containedRealPath(rootReal, target) {
+    let real;
+    try {
+        real = await realpath(target);
+    }
+    catch {
+        throw new Error(`path is not readable: ${target}`);
+    }
+    if (!isContained(rootReal, real)) {
+        throw new Error(`path escapes package root: ${target}`);
+    }
+    return real;
+}

package/dist/hosted/errors.d.ts

@@ -0,0 +1,21 @@
+export declare const HOSTED_ERROR_CODES: readonly ["invalid_input", "package_invalid", "agent_failed", "event_sink_failed", "cancelled", "timed_out", "hitl_unsupported", "internal"];
+export type HostedErrorCode = (typeof HOSTED_ERROR_CODES)[number];
+export type HostedRuntimeErrorDetails = {
+    code: HostedErrorCode;
+    externalRunId: string;
+    externalAttemptId: string;
+    runId?: string;
+    eventType?: string;
+    sequence?: number;
+    localResult?: import("./types.js").HostedPipelineResult;
+};
+export declare class HostedRuntimeError extends Error {
+    readonly code: HostedErrorCode;
+    readonly externalRunId: string;
+    readonly externalAttemptId: string;
+    readonly runId?: string;
+    readonly eventType?: string;
+    readonly sequence?: number;
+    readonly localResult?: import("./types.js").HostedPipelineResult;
+    constructor(message: string, details: HostedRuntimeErrorDetails);
+}

package/dist/hosted/errors.js

@@ -0,0 +1,30 @@
+export const HOSTED_ERROR_CODES = [
+    "invalid_input",
+    "package_invalid",
+    "agent_failed",
+    "event_sink_failed",
+    "cancelled",
+    "timed_out",
+    "hitl_unsupported",
+    "internal",
+];
+export class HostedRuntimeError extends Error {
+    code;
+    externalRunId;
+    externalAttemptId;
+    runId;
+    eventType;
+    sequence;
+    localResult;
+    constructor(message, details) {
+        super(message);
+        this.name = "HostedRuntimeError";
+        this.code = details.code;
+        this.externalRunId = details.externalRunId;
+        this.externalAttemptId = details.externalAttemptId;
+        this.runId = details.runId;
+        this.eventType = details.eventType;
+        this.sequence = details.sequence;
+        this.localResult = details.localResult;
+    }
+}

package/dist/hosted/packageSkills.d.ts

@@ -0,0 +1,3 @@
+import { type SkillsPayload } from "../runtime/runSkills.js";
+/** Skills shipped with a hosted package live at `<packageRoot>/.pi/skills/<name>/`. */
+export declare function loadPackageSkills(packageRoot: string): Promise<SkillsPayload | undefined>;

package/dist/hosted/packageSkills.js

@@ -0,0 +1,80 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { assertValidSkillName, assertValidSkillRelativePath, validateSkillsPayload, } from "../runtime/runSkills.js";
+import { isContained } from "./containment.js";
+/** Skills shipped with a hosted package live at `<packageRoot>/.pi/skills/<name>/`. */
+export async function loadPackageSkills(packageRoot) {
+    const skillsRoot = path.join(packageRoot, ".pi", "skills");
+    let entries;
+    try {
+        entries = await readdir(skillsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const skillsRootReal = await realpath(skillsRoot);
+    if (!isContained(packageRoot, skillsRootReal)) {
+        throw new Error("package skills directory escapes the package root");
+    }
+    const skills = {};
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const nameCheck = assertValidSkillName(entry.name);
+        if (!nameCheck.ok)
+            throw new Error(nameCheck.reason);
+        const skillDir = path.join(skillsRoot, entry.name);
+        let info;
+        try {
+            info = await stat(skillDir);
+        }
+        catch {
+            continue;
+        }
+        if (!info.isDirectory())
+            continue;
+        const skillReal = await realpath(skillDir);
+        if (!isContained(skillsRootReal, skillReal)) {
+            throw new Error(`package skill "${entry.name}" escapes the package root`);
+        }
+        const files = await readSkillFiles(skillDir, skillReal);
+        if (files["SKILL.md"] === undefined)
+            continue;
+        skills[entry.name] = files;
+    }
+    if (Object.keys(skills).length === 0)
+        return undefined;
+    const validated = validateSkillsPayload(skills);
+    if (!validated.ok)
+        throw new Error(validated.reason);
+    return validated.skills;
+}
+async function readSkillFiles(skillDir, skillReal) {
+    const files = {};
+    await walk(skillDir);
+    return files;
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = path.join(dir, entry.name);
+            const rel = path.relative(skillDir, abs);
+            const real = await realpath(abs);
+            if (!isContained(skillReal, real)) {
+                throw new Error(`package skill file "${rel}" escapes the package root`);
+            }
+            const target = await stat(real);
+            if (target.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (!target.isFile())
+                continue;
+            const pathCheck = assertValidSkillRelativePath(rel);
+            if (!pathCheck.ok)
+                throw new Error(pathCheck.reason);
+            files[rel] = await readFile(real, "utf8");
+        }
+    }
+}

package/dist/hosted/runtime.d.ts

@@ -0,0 +1,12 @@
+import type { AgentPort } from "../agent/port.js";
+import type { RunStore } from "../runstore/port.js";
+import { type HostedEventSink, type HostedPipelineInput, type HostedPipelineResult } from "./types.js";
+export type HostedRuntime = {
+    run(input: HostedPipelineInput): Promise<HostedPipelineResult>;
+};
+export declare function createHostedRuntime(dependencies: {
+    agent: AgentPort;
+    localStore: RunStore;
+    eventSink: HostedEventSink;
+    eventDeliveryTimeoutMs?: number;
+}): HostedRuntime;