stageflow 0.1.0

package/dist/agent/port.d.ts

@@ -0,0 +1,63 @@
+import type { StageEnvelope } from "../types/envelope.js";
+import type { StageConfig } from "../types/stage.js";
+import type { TaskFile } from "../types/task.js";
+import type { StageActivityEvent } from "./activity.js";
+import type { StageRoots } from "../runtime/stageRoots.js";
+/** Opaque to runtime; adapters interpret. */
+export type StageResumeToken = string;
+export type StageRunInput = {
+    roots: StageRoots;
+    stage: StageConfig;
+    task: TaskFile;
+    priorEnvelope: StageEnvelope | null;
+    timeoutMs?: number;
+    resumeToken?: StageResumeToken;
+    /** Optional observe hook; HITL wait/answer uses openStage beside this. */
+    onActivity?: (event: StageActivityEvent) => void;
+    skillFilePath?: string;
+};
+export type StageRunResult = {
+    ok: true;
+    envelope: StageEnvelope;
+} | {
+    ok: false;
+    reason: string;
+    envelope?: StageEnvelope;
+};
+/** Opaque wait-request blob; T2 owns concrete prompt shapes later. */
+export type OpaqueWaitRequest = unknown;
+/** Opaque answer blob; T2 owns concrete answer shapes later. */
+export type OpaqueAnswer = unknown;
+export type StageHandleCloseOptions = {
+    /** Keep an in-flight ask_operator tool call open for cross-process resume. */
+    park?: boolean;
+};
+export type StageHandleEvent = {
+    status: "waiting_for_input";
+    request: OpaqueWaitRequest;
+} | {
+    status: "completed";
+    result: StageRunResult;
+};
+/**
+ * Live stage session handle. Runtime pulls wait-or-complete via `next()`,
+ * unblocks with `deliverAnswer`, and releases with `close`.
+ */
+export interface StageHandle {
+    readonly stageId: string;
+    next(): Promise<StageHandleEvent>;
+    deliverAnswer(answer: OpaqueAnswer): void;
+    close(options?: StageHandleCloseOptions): Promise<void>;
+}
+export interface AgentPort {
+    openStage(input: StageRunInput): StageHandle;
+    runStage(input: StageRunInput): Promise<StageRunResult>;
+}
+/** Thin non-HITL wrapper: open → next; unexpected wait fails closed. */
+export declare function runStageViaOpen(port: Pick<AgentPort, "openStage">, input: StageRunInput): Promise<StageRunResult>;
+/** Wrap a single-shot runner as a handle that never waits (Pi U2 shim). */
+export declare function createCompletedOnlyStageHandle(options: {
+    stageId: string;
+    run: () => Promise<StageRunResult>;
+}): StageHandle;
+export declare const DEFAULT_STAGE_TIMEOUT_MS: number;

package/dist/agent/port.js

@@ -0,0 +1,46 @@
+/** Thin non-HITL wrapper: open → next; unexpected wait fails closed. */
+export async function runStageViaOpen(port, input) {
+    const handle = port.openStage(input);
+    try {
+        const event = await handle.next();
+        if (event.status === "waiting_for_input") {
+            return {
+                ok: false,
+                reason: "stage requested wait; use openStage/deliverAnswer",
+            };
+        }
+        return event.result;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Wrap a single-shot runner as a handle that never waits (Pi U2 shim). */
+export function createCompletedOnlyStageHandle(options) {
+    let settled;
+    let closed = false;
+    const runPromise = options.run().then((result) => {
+        settled = { status: "completed", result };
+        return settled;
+    });
+    return {
+        stageId: options.stageId,
+        async next() {
+            if (closed) {
+                return {
+                    status: "completed",
+                    result: { ok: false, reason: "stage handle closed" },
+                };
+            }
+            if (settled)
+                return settled;
+            return runPromise;
+        },
+        deliverAnswer() { },
+        async close() {
+            closed = true;
+            await runPromise.catch(() => undefined);
+        },
+    };
+}
+export const DEFAULT_STAGE_TIMEOUT_MS = 15 * 60 * 1000;

package/dist/agent/providerAuth.d.ts

@@ -0,0 +1,101 @@
+import type { AuthInteraction, Provider } from "@earendil-works/pi-ai";
+import type { CredentialSource } from "../runtime/settingsFile.js";
+export type ProviderSummary = {
+    id: string;
+    name: string;
+    supportsApiKey: boolean;
+    supportsOauth: boolean;
+    oauthLabel?: string;
+};
+export type LoginCapableProvider = {
+    id: string;
+    name: string;
+    apiKeyLogin: boolean;
+    oauth: boolean;
+    oauthLabel?: string;
+};
+export type ProviderAuthStatus = {
+    providerId: string;
+    configured: boolean;
+    authKind?: "api_key" | "oauth" | "none";
+    source?: string;
+};
+export type ProvidersListResult = {
+    authShell: "pi";
+    via: "pi";
+    providers: ProviderSummary[];
+};
+export type PiHomeDetectResult = {
+    piHomeUsable: boolean;
+    credentialSource?: CredentialSource;
+    provisional: boolean;
+    source: CredentialSource;
+};
+export type ProviderAuthRuntime = {
+    getProviders(): readonly Provider[];
+    getProvider(providerId: string): Provider | undefined;
+    getProviderAuthStatus(providerId: string): {
+        configured: boolean;
+        source?: string;
+        label?: string;
+    };
+    listCredentials(): Promise<readonly {
+        providerId: string;
+        type: "api_key" | "oauth";
+    }[]>;
+    checkAuth(providerId: string): Promise<{
+        source?: string;
+        type: "api_key" | "oauth";
+    } | undefined>;
+    login(providerId: string, type: "api_key" | "oauth", interaction: AuthInteraction): Promise<unknown>;
+    logout(providerId: string): Promise<void>;
+};
+export type CreateProviderAuthRuntime = (authPath: string) => Promise<ProviderAuthRuntime>;
+export type MutationLock = {
+    withMutationLock<T>(fn: () => Promise<T>): Promise<T>;
+};
+export type ProviderAuthContext = {
+    createRuntime: CreateProviderAuthRuntime;
+    lock: MutationLock;
+};
+export declare function makeMutationLock(): MutationLock;
+export declare class ProviderAuthError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare const defaultContext: ProviderAuthContext;
+export declare function openRuntime(cwd: string, ctx?: ProviderAuthContext): Promise<ProviderAuthRuntime>;
+export declare function isLoginCapable(provider: {
+    auth?: {
+        oauth?: unknown;
+        apiKey?: {
+            login?: unknown;
+        };
+    };
+}): boolean;
+export declare function listLoginCapableProviders(runtime: Pick<ProviderAuthRuntime, "getProviders">): LoginCapableProvider[];
+export declare function statusForProvider(runtime: ProviderAuthRuntime, providerId: string): Promise<ProviderAuthStatus>;
+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>;
+export type OauthLoginResult = {
+    provider: ProviderAuthStatus;
+    warning?: string;
+};
+export declare function loginWithOauth(cwd: string, providerId: string, interaction: AuthInteraction, ctx?: ProviderAuthContext): Promise<OauthLoginResult>;
+export declare function logoutProvider(cwd: string, providerId: string, ctx?: ProviderAuthContext): Promise<ProviderAuthStatus>;
+export declare function detectPiHome(cwd: string): PiHomeDetectResult;
+export declare function getCredentialSourceSettings(cwd: string): {
+    credentialSource?: CredentialSource;
+    binding: {
+        source: CredentialSource;
+        provisional: boolean;
+    };
+};
+export declare function setCredentialSource(cwd: string, credentialSource: unknown): {
+    credentialSource: CredentialSource;
+    binding: {
+        source: CredentialSource;
+        provisional: boolean;
+    };
+};

package/dist/agent/providerAuth.js

@@ -0,0 +1,282 @@
+import { CredentialSynchronizationError, ModelRuntime, } from "@earendil-works/pi-coding-agent";
+import { isUsableAuthFile, parseCredentialSource, piHomeAuthPath, readCredentialSourceFromFile, resolveCredentialBinding, writeCredentialSourceToFile, } from "../runtime/credentialBinding.js";
+export function makeMutationLock() {
+    let tail = Promise.resolve();
+    return {
+        withMutationLock(fn) {
+            const run = tail.then(fn, fn);
+            tail = run.then(() => undefined, () => undefined);
+            return run;
+        },
+    };
+}
+export class ProviderAuthError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "ProviderAuthError";
+        this.status = status;
+    }
+}
+const defaultCreateRuntime = async (authPath) => ModelRuntime.create({ authPath, refreshOnCreate: false });
+export const defaultContext = {
+    createRuntime: defaultCreateRuntime,
+    lock: makeMutationLock(),
+};
+export async function openRuntime(cwd, ctx = defaultContext) {
+    const binding = resolveCredentialBinding(cwd);
+    return ctx.createRuntime(binding.authPath);
+}
+export function isLoginCapable(provider) {
+    return (provider.auth?.oauth != null || provider.auth?.apiKey?.login != null);
+}
+export function listLoginCapableProviders(runtime) {
+    return runtime
+        .getProviders()
+        .filter(isLoginCapable)
+        .map((provider) => {
+        const apiKeyLogin = provider.auth?.apiKey?.login != null;
+        const oauth = provider.auth?.oauth != null;
+        const oauthName = oauth && provider.auth?.oauth && "name" in provider.auth.oauth
+            ? provider.auth.oauth.name
+            : undefined;
+        return {
+            id: provider.id,
+            name: provider.name,
+            apiKeyLogin,
+            oauth,
+            ...(typeof oauthName === "string" && oauthName.length > 0
+                ? { oauthLabel: oauthName }
+                : {}),
+        };
+    });
+}
+function mapProvider(provider) {
+    const supportsApiKey = provider.auth.apiKey?.login != null;
+    const supportsOauth = provider.auth.oauth !== undefined;
+    const oauthLabel = supportsOauth && typeof provider.auth.oauth?.name === "string"
+        ? provider.auth.oauth.name
+        : undefined;
+    return {
+        id: provider.id,
+        name: provider.name,
+        supportsApiKey,
+        supportsOauth,
+        ...(oauthLabel !== undefined && oauthLabel.length > 0
+            ? { oauthLabel }
+            : {}),
+    };
+}
+function safeStatus(providerId, status, authKind) {
+    const out = {
+        providerId,
+        configured: status.configured,
+    };
+    if (authKind !== undefined) {
+        out.authKind = authKind;
+    }
+    if (typeof status.source === "string" && status.source.length > 0) {
+        out.source = status.source;
+    }
+    else if (typeof status.label === "string" && status.label.length > 0) {
+        out.source = status.label;
+    }
+    return out;
+}
+export async function statusForProvider(runtime, providerId) {
+    const status = runtime.getProviderAuthStatus(providerId);
+    const creds = await runtime.listCredentials();
+    const stored = creds.find((c) => c.providerId === providerId);
+    let authKind = "none";
+    if (stored) {
+        authKind = stored.type;
+    }
+    else {
+        try {
+            const checked = await runtime.checkAuth(providerId);
+            if (checked?.type === "api_key" || checked?.type === "oauth") {
+                authKind = checked.type;
+            }
+        }
+        catch {
+            // ignore check failures for status DTO
+        }
+    }
+    const configured = Boolean(stored) || status.configured;
+    const mapped = safeStatus(providerId, {
+        configured,
+        source: stored ? (status.source ?? "stored") : status.source,
+        label: status.label,
+    }, authKind);
+    return mapped;
+}
+export async function listProviders(cwd, ctx = defaultContext) {
+    const runtime = await openRuntime(cwd, ctx);
+    return {
+        authShell: "pi",
+        via: "pi",
+        providers: runtime
+            .getProviders()
+            .filter(isLoginCapable)
+            .map(mapProvider),
+    };
+}
+export async function getAuthStatus(cwd, providerId, ctx = defaultContext) {
+    const runtime = await openRuntime(cwd, ctx);
+    if (providerId !== undefined) {
+        if (!runtime.getProvider(providerId)) {
+            throw new ProviderAuthError("Provider not found", 404);
+        }
+        return statusForProvider(runtime, providerId);
+    }
+    const providers = runtime.getProviders();
+    const out = [];
+    for (const provider of providers) {
+        out.push(await statusForProvider(runtime, provider.id));
+    }
+    return out;
+}
+function apiKeyInteraction(apiKey) {
+    return {
+        async prompt(prompt) {
+            if (prompt.type === "secret") {
+                return apiKey;
+            }
+            throw new ProviderAuthError("Unexpected auth prompt for api_key login", 400);
+        },
+        notify() { },
+    };
+}
+function mapLoginError(err, providerId) {
+    if (err instanceof ProviderAuthError) {
+        throw err;
+    }
+    if (err instanceof CredentialSynchronizationError) {
+        throw new ProviderAuthError(`Credential sync failed for provider ${providerId}`, 502);
+    }
+    throw new ProviderAuthError("Provider login failed", 500);
+}
+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);
+    });
+}
+export async function loginWithOauth(cwd, providerId, interaction, ctx = defaultContext) {
+    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 (provider.auth.oauth === undefined) {
+            throw new ProviderAuthError("Provider does not support oauth login", 400);
+        }
+        try {
+            await runtime.login(providerId, "oauth", interaction);
+            return { provider: await statusForProvider(runtime, providerId) };
+        }
+        catch (err) {
+            if (err instanceof CredentialSynchronizationError) {
+                let status;
+                try {
+                    status = await statusForProvider(runtime, providerId);
+                }
+                catch {
+                    status = {
+                        providerId,
+                        configured: true,
+                        authKind: "oauth",
+                    };
+                }
+                return {
+                    provider: status.configured
+                        ? status
+                        : {
+                            ...status,
+                            configured: true,
+                            authKind: status.authKind ?? "oauth",
+                        },
+                    warning: "Connected, but model catalog sync failed. Credentials were saved — you can retry later without disconnecting.",
+                };
+            }
+            if (interaction.signal?.aborted) {
+                throw new ProviderAuthError("Login cancelled", 400);
+            }
+            if (err instanceof Error && /cancel/i.test(err.message)) {
+                throw new ProviderAuthError("Login cancelled", 400);
+            }
+            mapLoginError(err, providerId);
+        }
+    });
+}
+export async function logoutProvider(cwd, providerId, ctx = defaultContext) {
+    return ctx.lock.withMutationLock(async () => {
+        const runtime = await openRuntime(cwd, ctx);
+        if (!runtime.getProvider(providerId)) {
+            throw new ProviderAuthError("Provider not found", 404);
+        }
+        try {
+            await runtime.logout(providerId);
+        }
+        catch (err) {
+            if (err instanceof CredentialSynchronizationError) {
+                throw new ProviderAuthError(`Credential sync failed for provider ${providerId}`, 502);
+            }
+            throw new ProviderAuthError("Provider logout failed", 500);
+        }
+        return statusForProvider(runtime, providerId);
+    });
+}
+export function detectPiHome(cwd) {
+    const binding = resolveCredentialBinding(cwd);
+    const persisted = readCredentialSourceFromFile(cwd);
+    return {
+        piHomeUsable: isUsableAuthFile(piHomeAuthPath()),
+        ...(persisted !== undefined ? { credentialSource: persisted } : {}),
+        provisional: binding.provisional,
+        source: binding.source,
+    };
+}
+export function getCredentialSourceSettings(cwd) {
+    const persisted = readCredentialSourceFromFile(cwd);
+    const binding = resolveCredentialBinding(cwd);
+    return {
+        ...(persisted !== undefined ? { credentialSource: persisted } : {}),
+        binding: {
+            source: binding.source,
+            provisional: binding.provisional,
+        },
+    };
+}
+export function setCredentialSource(cwd, credentialSource) {
+    const parsed = parseCredentialSource(credentialSource);
+    if (parsed === undefined) {
+        throw new ProviderAuthError('credentialSource must be "pi_home" or "sf_owned"', 400);
+    }
+    writeCredentialSourceToFile(cwd, parsed);
+    const binding = resolveCredentialBinding(cwd);
+    return {
+        credentialSource: parsed,
+        binding: {
+            source: binding.source,
+            provisional: binding.provisional,
+        },
+    };
+}

package/dist/agent/providerSupport.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Optional hooks for model providers that need more than Pi's built-in
+ * auth/models (typically an allowlisted extension that calls registerProvider).
+ *
+ * PiAgentAdapter stays provider-agnostic: it only consumes this interface.
+ * Concrete providers (Cursor today) live in their own modules and register here.
+ */
+export type ProviderPrepareResult = {
+    /** Absolute paths passed to DefaultResourceLoader.additionalExtensionPaths. */
+    extensionPaths: string[];
+    /** Optional env / process restore after the stage ends. */
+    restore?: () => void;
+    /** Failure before session create (missing extension, bad config, …). */
+    error?: string;
+};
+export type StageProviderSupport = {
+    /** Stable id for logs/docs (e.g. "cursor"). */
+    id: string;
+    matches(modelRef: string): boolean;
+    prepare(modelRef: string): ProviderPrepareResult;
+    /**
+     * Extra guidance for how the model must call emit_stage_envelope
+     * (e.g. MCP bridge name). When omitted, the generic Pi tool name is used.
+     */
+    emitToolHint?(toolName: string): string;
+};
+export declare function registerProviderSupport(support: StageProviderSupport): void;
+export declare function findProviderSupport(modelRef: string): StageProviderSupport | undefined;

package/dist/agent/providerSupport.js

@@ -0,0 +1,19 @@
+/**
+ * Optional hooks for model providers that need more than Pi's built-in
+ * auth/models (typically an allowlisted extension that calls registerProvider).
+ *
+ * PiAgentAdapter stays provider-agnostic: it only consumes this interface.
+ * Concrete providers (Cursor today) live in their own modules and register here.
+ */
+const registry = [];
+export function registerProviderSupport(support) {
+    const existing = registry.findIndex((entry) => entry.id === support.id);
+    if (existing >= 0) {
+        registry[existing] = support;
+        return;
+    }
+    registry.push(support);
+}
+export function findProviderSupport(modelRef) {
+    return registry.find((entry) => entry.matches(modelRef));
+}

package/dist/cli/providersCommand.d.ts

@@ -0,0 +1,11 @@
+import type { AuthInteraction } from "@earendil-works/pi-ai";
+import { type ProviderAuthContext } from "../agent/providerAuth.js";
+export declare const PROVIDERS_USAGE = "Usage:\n  sf providers list\n  sf providers status [--provider <id>]\n  sf providers detect\n  sf providers source [get | set <pi_home|sf_owned>]\n  sf providers login <providerId> [--type api_key|oauth] [--api-key-env <VAR>]\n  sf providers logout <providerId>";
+export type ProvidersCommandIo = {
+    log: (line: string) => void;
+    error: (line: string) => void;
+    env: NodeJS.ProcessEnv;
+    readSecret: (message: string) => Promise<string>;
+    createAuthInteraction: (signal: AbortSignal) => AuthInteraction;
+};
+export declare function runProvidersCommand(args: string[], cwd: string, io?: Partial<ProvidersCommandIo>, ctx?: ProviderAuthContext): Promise<number>;