stageflow 0.27.0 → 0.30.0

package/dist/operatorAgent/fakeHost.js

@@ -0,0 +1,92 @@
+import { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
+import { createWorkshopAuthorProfile, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PROFILE_ID, } from "./profiles/workshopAuthor.js";
+/**
+ * Deterministic Operator Agent Host for Workshop and tests.
+ * Does not call a live provider — scripted turns or auto stage/task mutations.
+ */
+export function createFakeOperatorAgentModel(script = [{ type: "propose_stage" }]) {
+    let index = 0;
+    return {
+        async complete({ profile, message, tools }) {
+            const turn = script[Math.min(index, script.length - 1)] ?? {
+                type: "propose_stage",
+            };
+            index += 1;
+            if (turn.type === "events") {
+                return { events: turn.events };
+            }
+            if (turn.type === "echo") {
+                return {
+                    events: [
+                        {
+                            type: "message",
+                            role: "assistant",
+                            text: `Got it: ${message}`,
+                        },
+                    ],
+                };
+            }
+            if (turn.type === "call_tool") {
+                const result = await invokeProfileTool(profile, turn.name, turn.args ?? {}, tools);
+                const events = [
+                    { type: "tool_result", name: turn.name, result },
+                ];
+                if (turn.message) {
+                    events.push({
+                        type: "message",
+                        role: "assistant",
+                        text: turn.message,
+                    });
+                }
+                else if (!result.ok) {
+                    events.push({
+                        type: "message",
+                        role: "assistant",
+                        text: `Retrieval unavailable (${result.error ?? "error"}). Continuing with the baked Workshop Author playbook.`,
+                    });
+                }
+                return { events };
+            }
+            if (turn.type === "propose") {
+                tools.emitProposal(turn.proposal);
+                return {
+                    events: [
+                        {
+                            type: "message",
+                            role: "assistant",
+                            text: turn.message ??
+                                `Applied to draft: ${turn.proposal.summary}. Accept confirms; Reject undoes when the draft is unchanged.`,
+                        },
+                        { type: "proposal", proposal: turn.proposal },
+                    ],
+                };
+            }
+            const proposal = turn.type === "propose_task" || isTaskProposalIntent(message)
+                ? proposeTaskFromUserMessage(tools, message)
+                : proposeStageFromUserMessage(tools, message);
+            return {
+                events: [
+                    {
+                        type: "message",
+                        role: "assistant",
+                        text: `Applied to draft: ${proposal.summary}. Accept confirms; Reject undoes when the draft is unchanged. Nothing was written to disk — Save when you are ready.`,
+                    },
+                    { type: "proposal", proposal },
+                ],
+            };
+        },
+    };
+}
+export function createWorkshopOperatorHost(scriptOrOptions) {
+    const options = Array.isArray(scriptOrOptions)
+        ? { script: scriptOrOptions }
+        : (scriptOrOptions ?? {});
+    const host = createOperatorAgentHost(options.model ?? createFakeOperatorAgentModel(options.script), [
+        createWorkshopAuthorProfile({
+            retriever: options.retriever,
+            projectRoot: options.projectRoot,
+        }),
+    ]);
+    return host;
+}
+export { WORKSHOP_AUTHOR_PROFILE_ID };

package/dist/operatorAgent/host.d.ts

@@ -0,0 +1,40 @@
+import type { OperatorAgentHost, OperatorAgentProfile, OperatorAgentSessionEvent, OperatorAgentToolContext, OperatorAgentToolResult, WorkshopToolActivityUpdate } from "./types.js";
+export type OperatorAgentModelTurn = {
+    events: OperatorAgentSessionEvent[];
+};
+export type OperatorAgentModelCompleteInput = {
+    profile: OperatorAgentProfile;
+    message: string;
+    contextSnapshot: unknown;
+    tools: OperatorAgentToolContext;
+    /**
+     * Optional mid-turn assistant text callback (Workshop progressive NDJSON).
+     * Invoked as Pi `text_delta` (or equivalent) arrives — before complete resolves.
+     */
+    onDelta?: (text: string) => void;
+    /** Mid-turn tool status for the Workshop chat column. */
+    onActivity?: (update: WorkshopToolActivityUpdate) => void;
+    /** Workshop composer model for this turn. Applied before the prompt. */
+    modelId?: string;
+};
+export type OperatorAgentModel = {
+    complete(input: OperatorAgentModelCompleteInput): Promise<OperatorAgentModelTurn>;
+    /**
+     * Optional restart seed (KTD7): inject prior transcript into a new backend
+     * session before the first complete for this host session.
+     */
+    prepareRestart?(input: {
+        tools: OperatorAgentToolContext;
+        profile: OperatorAgentProfile;
+        transcript: readonly {
+            role: string;
+            text: string;
+        }[];
+    }): Promise<void>;
+    /** Optional: dispose backend resources bound to this tool context. */
+    releaseTools?(tools: OperatorAgentToolContext): void | Promise<void>;
+    /** Interrupt the in-flight prompt for this tool context. */
+    abort?(tools: OperatorAgentToolContext): Promise<void>;
+};
+export declare function createOperatorAgentHost(model: OperatorAgentModel, seedProfiles?: OperatorAgentProfile[]): OperatorAgentHost;
+export declare function invokeProfileTool(profile: OperatorAgentProfile, name: string, args: Record<string, unknown>, ctx: OperatorAgentToolContext): Promise<OperatorAgentToolResult>;

package/dist/operatorAgent/host.js

@@ -0,0 +1,179 @@
+import { readDraftFromContext } from "./draftContext.js";
+import { draftFingerprint, enrichProposal, isMutationConflict, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
+import { rejectUnlinkedWorkshopDraftTool } from "../workshop/workshopPin.js";
+function createSession(profile, initialContext, model) {
+    let context = initialContext;
+    let closed = false;
+    const mutations = new Map();
+    let lastMutationId = null;
+    let lastEmitted = null;
+    const toolContext = {
+        getContext: () => context,
+        setContext: (next) => {
+            context = next;
+        },
+        emitProposal: (proposal) => {
+            const enriched = enrichProposal(proposal, context);
+            context = profile.contextAdapter.applyProposal(context, enriched);
+            const applied = {
+                ...enriched,
+                appliedFingerprint: draftFingerprint(readDraftFromContext(context)),
+            };
+            mutations.set(applied.id, applied);
+            lastMutationId = applied.id;
+            lastEmitted = applied;
+        },
+    };
+    function resolveMutation(mutationId) {
+        if (mutations.size === 0)
+            return { ok: false, reason: "none" };
+        const id = mutationId ?? lastMutationId;
+        if (!id)
+            return { ok: false, reason: "none" };
+        const mutation = mutations.get(id);
+        if (!mutation) {
+            if (mutationId !== undefined)
+                return { ok: false, reason: "id_mismatch" };
+            return { ok: false, reason: "none" };
+        }
+        return { ok: true, mutation };
+    }
+    function undoMutation(mutationId) {
+        const resolved = resolveMutation(mutationId);
+        if (!resolved.ok)
+            return resolved;
+        const { mutation } = resolved;
+        if (isMutationConflict(mutation, context)) {
+            return {
+                ok: false,
+                reason: "conflict",
+                notice: UNDO_MUTATION_CONFLICT_NOTICE,
+            };
+        }
+        if (mutation.baseContext !== undefined) {
+            context = mutation.baseContext;
+        }
+        mutations.delete(mutation.id);
+        if (lastMutationId === mutation.id) {
+            lastMutationId = [...mutations.keys()].at(-1) ?? null;
+        }
+        return { ok: true };
+    }
+    return {
+        profileId: profile.id,
+        profileTitle: profile.title,
+        getContext: () => context,
+        setContext: (next) => {
+            context = next;
+        },
+        getPendingProposal: () => {
+            if (!lastMutationId)
+                return null;
+            return mutations.get(lastMutationId) ?? null;
+        },
+        getMutation: (mutationId) => mutations.get(mutationId) ?? null,
+        async prepareRestart(transcript) {
+            if (closed)
+                return;
+            if (!model.prepareRestart)
+                return;
+            await model.prepareRestart({
+                profile,
+                tools: toolContext,
+                transcript,
+            });
+        },
+        async send(message, options) {
+            if (closed) {
+                return [{ type: "error", message: "session is closed" }];
+            }
+            lastEmitted = null;
+            const turn = await model.complete({
+                profile,
+                message,
+                contextSnapshot: profile.contextAdapter.serialize(context),
+                tools: toolContext,
+                onDelta: options?.onDelta,
+                onActivity: options?.onActivity,
+                modelId: options?.modelId,
+            });
+            const events = [];
+            let sawProposal = false;
+            for (const event of turn.events) {
+                if (event.type === "proposal") {
+                    sawProposal = true;
+                    events.push({
+                        type: "proposal",
+                        proposal: lastEmitted ?? enrichProposal(event.proposal, context),
+                    });
+                }
+                else {
+                    events.push(event);
+                }
+            }
+            if (!sawProposal && lastEmitted) {
+                events.push({ type: "proposal", proposal: lastEmitted });
+            }
+            return events;
+        },
+        async abort() {
+            if (closed)
+                return;
+            await model.abort?.(toolContext);
+        },
+        acceptProposal(proposalId) {
+            const resolved = resolveMutation(proposalId);
+            if (!resolved.ok)
+                return resolved;
+            mutations.delete(resolved.mutation.id);
+            if (lastMutationId === resolved.mutation.id) {
+                lastMutationId = [...mutations.keys()].at(-1) ?? null;
+            }
+            return { ok: true };
+        },
+        rejectProposal(proposalId) {
+            return undoMutation(proposalId);
+        },
+        undoMutation,
+        close() {
+            closed = true;
+            mutations.clear();
+            lastMutationId = null;
+            void model.releaseTools?.(toolContext);
+        },
+    };
+}
+export function createOperatorAgentHost(model, seedProfiles = []) {
+    const profiles = new Map();
+    for (const profile of seedProfiles) {
+        profiles.set(profile.id, profile);
+    }
+    return {
+        registerProfile(profile) {
+            profiles.set(profile.id, profile);
+        },
+        getProfile(id) {
+            return profiles.get(id);
+        },
+        listProfiles() {
+            return [...profiles.values()];
+        },
+        openSession({ profileId, context }) {
+            const profile = profiles.get(profileId);
+            if (!profile) {
+                throw new Error(`Unknown operator agent profile: ${profileId}`);
+            }
+            return createSession(profile, context, model);
+        },
+    };
+}
+export async function invokeProfileTool(profile, name, args, ctx) {
+    const tool = profile.tools.find((t) => t.name === name);
+    if (!tool) {
+        return { ok: false, content: null, error: `Unknown tool: ${name}` };
+    }
+    const blocked = rejectUnlinkedWorkshopDraftTool(ctx.getContext(), name);
+    if (blocked)
+        return blocked;
+    return tool.handler(args, ctx);
+}

package/dist/operatorAgent/index.d.ts

@@ -0,0 +1,9 @@
+export type { AcceptProposalResult, OperatorAgentContextAdapter, OperatorAgentHost, OperatorAgentProfile, OperatorAgentProposal, OperatorAgentSession, OperatorAgentSessionEvent, OperatorAgentTool, OperatorAgentToolContext, OperatorAgentToolResult, ProposalArtifactDiff, UndoMutationResult, WorkshopDraftContext, WorkshopToolActivityUpdate, } from "./types.js";
+export { createOperatorAgentHost, invokeProfileTool, type OperatorAgentModel, type OperatorAgentModelTurn, } from "./host.js";
+export { createFakeOperatorAgentModel, createWorkshopOperatorHost, type FakeOperatorTurn, type WorkshopOperatorHostOptions, } from "./fakeHost.js";
+export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, type LiveWorkshopOperatorHostOptions, type PiOperatorAgentModel, type PiOperatorAgentModelOptions, type PiOperatorOpenSessionInput, type PiOperatorSessionHandle, type WorkshopTranscriptSeedMessage, } from "./piModel.js";
+export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, type DocsRetrievalHit, type DocsRetrievalResult, type DocsRetriever, } from "./docsRetrieval.js";
+export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";
+export { affectedStageIds, diffDraftPackages, draftFingerprint, enrichProposal, isMutationConflict, STALE_PROPOSAL_NOTICE, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
+export { assertWorkshopAuthorToolsExcludeDiskShell, buildStageAddProposal, buildTaskAddProposal, createWorkshopAuthorProfile, createWorkshopAuthorTools, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PLAYBOOK, WORKSHOP_AUTHOR_PROFILE_ID, WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, workshopAuthorTools, type WorkshopAuthorProfileOptions, } from "./profiles/workshopAuthor.js";
+export { buildCreatePipelineDraft, buildCreateStageDraft, buildCreateTaskDraft, buildEditPipelineDraft, buildEditStageDraft, buildEditTaskDraft, createSaveTool, createWorkshopAuthorMutatingTools, WORKSHOP_AUTHOR_MUTATING_TOOLS, } from "./profiles/workshopAuthorTools.js";

package/dist/operatorAgent/index.js

@@ -0,0 +1,8 @@
+export { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
+export { createFakeOperatorAgentModel, createWorkshopOperatorHost, } from "./fakeHost.js";
+export { createLiveWorkshopOperatorHost, createPiOperatorAgentModel, } from "./piModel.js";
+export { createFailingDocsRetriever, createFilesystemDocsRetriever, createStubDocsRetriever, resolveWorkshopCatalogRoot, } from "./docsRetrieval.js";
+export { createWorkshopDraftContext, draftTrackStages, emptyDraftPackage, isWorkshopDraftContext, readDraftFromContext, withDestination, withDraft, withProjectRoot, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "./draftContext.js";
+export { affectedStageIds, diffDraftPackages, draftFingerprint, enrichProposal, isMutationConflict, STALE_PROPOSAL_NOTICE, UNDO_MUTATION_CONFLICT_NOTICE, } from "./proposals.js";
+export { assertWorkshopAuthorToolsExcludeDiskShell, buildStageAddProposal, buildTaskAddProposal, createWorkshopAuthorProfile, createWorkshopAuthorTools, isTaskProposalIntent, proposeStageFromUserMessage, proposeTaskFromUserMessage, WORKSHOP_AUTHOR_PLAYBOOK, WORKSHOP_AUTHOR_PROFILE_ID, WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, workshopAuthorTools, } from "./profiles/workshopAuthor.js";
+export { buildCreatePipelineDraft, buildCreateStageDraft, buildCreateTaskDraft, buildEditPipelineDraft, buildEditStageDraft, buildEditTaskDraft, createSaveTool, createWorkshopAuthorMutatingTools, WORKSHOP_AUTHOR_MUTATING_TOOLS, } from "./profiles/workshopAuthorTools.js";

package/dist/operatorAgent/piModel.d.ts

@@ -0,0 +1,80 @@
+import { type AgentSession, defineTool, SessionManager } from "@earendil-works/pi-coding-agent";
+import "../agent/cursorProvider.js";
+import { type OperatorAgentModel } from "./host.js";
+import { type WorkshopAuthorProfileOptions } from "./profiles/workshopAuthor.js";
+import type { OperatorAgentHost, OperatorAgentProfile, OperatorAgentToolContext, OperatorAgentToolResult, WorkshopToolActivityUpdate } from "./types.js";
+export type WorkshopTranscriptSeedMessage = {
+    role: string;
+    text: string;
+};
+export type PiOperatorAgentModelOptions = {
+    cwd: string;
+    /** Sealed Pi agent dir; defaults under `$STAGEFLOW_HOME/workshop/agent`. */
+    agentDir?: string;
+    /** Override credential auth.json; defaults via resolveCredentialBinding(cwd). */
+    authPath?: string;
+    /** Model id; defaults via resolveWorkshopModel. */
+    model?: string | null;
+    settingsDefault?: string | null;
+    profileDefault?: string | null;
+    /**
+     * Optional directory for durable Pi session JSONL (new file each process;
+     * restart still uses new Pi + replay — KTD7).
+     */
+    piSessionDir?: string;
+    /** Test seam: inject session construction. */
+    openPiSession?: (input: PiOperatorOpenSessionInput) => Promise<PiOperatorSessionHandle>;
+    /** Test seam: skip live auth / model resolution. */
+    resolveModelId?: () => string;
+};
+export type PiOperatorOpenSessionInput = {
+    cwd: string;
+    agentDir: string;
+    systemPrompt: string;
+    toolNames: string[];
+    customTools: ReturnType<typeof defineTool>[];
+    modelId: string;
+    authPath: string;
+    piSessionDir?: string;
+};
+export type PiOperatorSessionHandle = {
+    session: Pick<AgentSession, "prompt" | "subscribe" | "dispose" | "bindExtensions" | "setModel" | "setThinkingLevel"> & {
+        agent?: {
+            state: {
+                messages: unknown;
+            };
+        };
+        abort?: AgentSession["abort"];
+    };
+    sessionManager: {
+        appendCustomMessageEntry: SessionManager["appendCustomMessageEntry"];
+        buildSessionContext: SessionManager["buildSessionContext"];
+        getSessionId: SessionManager["getSessionId"];
+    };
+    restoreProvider?: () => void;
+    shutdown: () => Promise<void>;
+    piSessionId: string;
+    /** Extension paths loaded when this Pi session was opened. Absent on test doubles. */
+    extensionPaths?: readonly string[];
+    /** Switch the live Pi model before the next prompt. No-op when unchanged. */
+    applyModel?: (modelId: string) => Promise<void>;
+};
+export declare function sessionNeedsExtensionReload(loaded: readonly string[] | undefined, needed: readonly string[]): boolean;
+export type PiOperatorAgentModel = OperatorAgentModel & {
+    prepareRestart(input: {
+        tools: OperatorAgentToolContext;
+        profile: OperatorAgentProfile;
+        transcript: readonly WorkshopTranscriptSeedMessage[];
+    }): Promise<void>;
+    releaseTools(tools: OperatorAgentToolContext): Promise<void>;
+    dispose(): Promise<void>;
+    getPiSessionId(tools: OperatorAgentToolContext): string | undefined;
+};
+export declare function workshopToolLogFields(args: Record<string, unknown>, result?: OperatorAgentToolResult): Record<string, unknown>;
+export declare function workshopToolActivity(id: string, name: string, phase: "start" | "done", args: Record<string, unknown>, result?: OperatorAgentToolResult): WorkshopToolActivityUpdate;
+/**
+ * Pi OperatorAgentModel: durable session per host tool-context, Workshop tools only.
+ */
+export declare function createPiOperatorAgentModel(options: PiOperatorAgentModelOptions): PiOperatorAgentModel;
+export type LiveWorkshopOperatorHostOptions = WorkshopAuthorProfileOptions & PiOperatorAgentModelOptions;
+export declare function createLiveWorkshopOperatorHost(options: LiveWorkshopOperatorHostOptions): OperatorAgentHost;