stageflow 0.27.0 → 0.30.0

package/dist/operatorAgent/piModel.js

@@ -0,0 +1,528 @@
+/**
+ * Live Pi-backed OperatorAgentModel for Workshop Author.
+ *
+ * Uses the shared Pi session factory (not AgentPort). Workshop tools only —
+ * resolveWorkshopToolNames / assertWorkshopToolsExcludeDiskShell. Durable Pi
+ * session per host tool-context (R7). Restart: new Pi + transcript replay (KTD7).
+ */
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { defineTool, ModelRuntime, resolveCliModel, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { createPiAgentSession, createSealedResourceLoader, resolveWorkshopToolNames, } from "../agent/piSessionFactory.js";
+import { cursorBridgePrompt } from "../agent/cursorProvider.js";
+import { findProviderSupport } from "../agent/providerSupport.js";
+import "../agent/cursorProvider.js";
+import { logger as rootLogger } from "../logging/logger.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { isUsableAuthFile, resolveCredentialBinding, } from "../runtime/credentialBinding.js";
+import { resolveWorkshopModel } from "../workshop/modelSettings.js";
+import { createOperatorAgentHost, invokeProfileTool, } from "./host.js";
+import { createWorkshopAuthorProfile, } from "./profiles/workshopAuthor.js";
+import { readDraftFromContext } from "./draftContext.js";
+export function sessionNeedsExtensionReload(loaded, needed) {
+    if (loaded === undefined)
+        return false;
+    const have = new Set(loaded);
+    return needed.some((extensionPath) => !have.has(extensionPath));
+}
+function extensionPathsForModel(modelId) {
+    const provider = findProviderSupport(modelId);
+    if (!provider)
+        return [];
+    const prepared = provider.prepare(modelId);
+    if (prepared.error)
+        return [];
+    return prepared.extensionPaths;
+}
+const FLEX_PARAMS = Type.Object({}, { additionalProperties: true });
+const workshopLog = rootLogger.child({ component: "workshop" });
+export function workshopToolLogFields(args, result) {
+    const body = args.body;
+    const fields = {
+        argKeys: Object.keys(args),
+        id: typeof args.id === "string" ? args.id : undefined,
+        bodyType: body === undefined ? "missing" : Array.isArray(body) ? "array" : typeof body,
+    };
+    if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+        fields.bodyKeys = Object.keys(body);
+    }
+    if (typeof body === "string") {
+        fields.bodyChars = body.length;
+        fields.bodyIgnored = true;
+    }
+    if (result) {
+        fields.ok = result.ok;
+        if (result.error)
+            fields.error = result.error;
+        try {
+            fields.resultBytes = JSON.stringify(result).length;
+        }
+        catch {
+            fields.resultBytes = -1;
+        }
+    }
+    return fields;
+}
+export function workshopToolActivity(id, name, phase, args, result) {
+    const target = typeof args.id === "string" ? args.id : undefined;
+    const base = { id, name, ...(target ? { target } : {}) };
+    if (phase === "start")
+        return { ...base, status: "running" };
+    if (!result?.ok) {
+        return {
+            ...base,
+            status: "error",
+            errorMessage: result?.error ?? "unknown error",
+        };
+    }
+    return { ...base, status: "complete" };
+}
+function workshopContextBuildId(context) {
+    if (context !== null &&
+        typeof context === "object" &&
+        "buildId" in context &&
+        typeof context.buildId === "string") {
+        const buildId = context.buildId.trim();
+        return buildId || undefined;
+    }
+    return undefined;
+}
+function workshopAgentDir() {
+    return path.join(globalStageflowHome(), "workshop", "agent");
+}
+function toolResultContent(result) {
+    const text = JSON.stringify(result);
+    return {
+        content: [{ type: "text", text }],
+        details: result,
+        ...(result.ok ? {} : { isError: true }),
+    };
+}
+function buildWorkshopCustomTools(profileTools, getProfile, getTools, onToolResult, reportActivity) {
+    return profileTools.map((tool) => defineTool({
+        name: tool.name,
+        label: tool.name,
+        description: tool.description,
+        parameters: FLEX_PARAMS,
+        execute: async (_toolCallId, params) => {
+            const args = params !== null && typeof params === "object" && !Array.isArray(params)
+                ? params
+                : {};
+            workshopLog.info("workshop.tool.start", tool.name, workshopToolLogFields(args));
+            const callId = typeof _toolCallId === "string" && _toolCallId
+                ? _toolCallId
+                : `${tool.name}-${Date.now()}`;
+            const pinnedBuildId = workshopContextBuildId(getTools().getContext());
+            reportActivity({
+                ...workshopToolActivity(callId, tool.name, "start", args),
+                ...(pinnedBuildId ? { buildId: pinnedBuildId } : {}),
+            });
+            const result = await invokeProfileTool(getProfile(), tool.name, args, getTools());
+            const fields = workshopToolLogFields(args, result);
+            if (result.ok) {
+                workshopLog.info("workshop.tool.done", tool.name, fields);
+            }
+            else {
+                workshopLog.warn("workshop.tool.done", tool.name, fields);
+            }
+            const update = workshopToolActivity(callId, tool.name, "done", args, result);
+            const doneBuildId = workshopContextBuildId(getTools().getContext());
+            if (result.ok) {
+                const draft = readDraftFromContext(getTools().getContext());
+                reportActivity({
+                    ...update,
+                    draft,
+                    ...(doneBuildId ? { buildId: doneBuildId } : {}),
+                });
+            }
+            else {
+                reportActivity({
+                    ...update,
+                    ...(doneBuildId ? { buildId: doneBuildId } : {}),
+                });
+            }
+            onToolResult(tool.name, result);
+            return toolResultContent(result);
+        },
+    }));
+}
+function formatTranscriptReplay(transcript) {
+    const lines = transcript
+        .filter((m) => typeof m.text === "string" && m.text.trim())
+        .map((m) => `${m.role}: ${m.text.trim()}`);
+    return [
+        "Prior Workshop Author conversation (restored after host restart).",
+        "Continue from this context; do not re-ask questions already answered.",
+        "",
+        ...lines,
+    ].join("\n");
+}
+function authNotConfiguredError(authPath) {
+    return new Error(`Workshop Author provider auth is not configured (auth file missing or empty: ${authPath}). Configure credentials via \`sf providers\` / the operator console Providers page, then retry.`);
+}
+function syncAgentMessages(session, sessionManager) {
+    if (session.agent?.state) {
+        session.agent.state.messages = sessionManager.buildSessionContext().messages;
+    }
+}
+function extractAssistantText(message) {
+    if (message.role !== "assistant")
+        return undefined;
+    const content = message.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    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);
+    }
+    return parts.length > 0 ? parts.join("") : undefined;
+}
+async function openDefaultPiSession(input) {
+    if (!isUsableAuthFile(input.authPath)) {
+        throw authNotConfiguredError(input.authPath);
+    }
+    const provider = findProviderSupport(input.modelId);
+    const additionalExtensionPaths = [];
+    let restoreProvider;
+    if (provider) {
+        const prepared = provider.prepare(input.modelId);
+        if (prepared.error) {
+            throw new Error(prepared.error);
+        }
+        additionalExtensionPaths.push(...prepared.extensionPaths);
+        restoreProvider = prepared.restore;
+    }
+    await mkdir(input.agentDir, { recursive: true });
+    if (input.piSessionDir) {
+        await mkdir(input.piSessionDir, { recursive: true });
+    }
+    const modelRuntime = await ModelRuntime.create({
+        authPath: input.authPath,
+        modelsPath: path.join(path.dirname(input.authPath), "models.json"),
+    });
+    const settingsManager = SettingsManager.inMemory({
+        compaction: { enabled: false },
+    });
+    const loader = createSealedResourceLoader({
+        cwd: input.cwd,
+        agentDir: input.agentDir,
+        settingsManager,
+        systemPrompt: input.systemPrompt,
+        ...(additionalExtensionPaths.length > 0
+            ? { additionalExtensionPaths }
+            : {}),
+    });
+    await loader.reload();
+    const extensionErrors = loader.getExtensions().errors;
+    if (extensionErrors.length > 0) {
+        restoreProvider?.();
+        throw new Error(`Failed to load Pi extension(s): ${extensionErrors
+            .map((e) => `${e.path}: ${e.error}`)
+            .join("; ")}`);
+    }
+    const sessionManager = input.piSessionDir
+        ? SessionManager.create(input.cwd, input.piSessionDir)
+        : SessionManager.inMemory(input.cwd);
+    let session;
+    try {
+        const created = await createPiAgentSession({
+            cwd: input.cwd,
+            agentDir: input.agentDir,
+            modelRuntime,
+            sessionManager,
+            settingsManager,
+            resourceLoader: loader,
+            tools: input.toolNames,
+            customTools: input.customTools,
+        });
+        session = created.session;
+        await session.bindExtensions({});
+        const resolved = resolveCliModel({
+            cliModel: input.modelId,
+            modelRuntime,
+        });
+        if (resolved.error || !resolved.model) {
+            throw new Error(resolved.error ?? `Model not found: ${input.modelId}`);
+        }
+        await session.setModel(resolved.model);
+        if (resolved.thinkingLevel) {
+            session.setThinkingLevel(resolved.thinkingLevel);
+        }
+        const live = session;
+        let currentModelId = input.modelId;
+        const applyModel = async (modelId) => {
+            if (modelId === currentModelId)
+                return;
+            const provider = findProviderSupport(modelId);
+            if (provider) {
+                const prepared = provider.prepare(modelId);
+                if (prepared.error) {
+                    throw new Error(prepared.error);
+                }
+            }
+            const next = resolveCliModel({
+                cliModel: modelId,
+                modelRuntime,
+            });
+            if (next.error || !next.model) {
+                throw new Error(next.error ?? `Model not found: ${modelId}`);
+            }
+            await live.setModel(next.model);
+            if (next.thinkingLevel) {
+                live.setThinkingLevel(next.thinkingLevel);
+            }
+            currentModelId = modelId;
+        };
+        return {
+            session: live,
+            sessionManager,
+            restoreProvider,
+            piSessionId: sessionManager.getSessionId(),
+            extensionPaths: additionalExtensionPaths,
+            applyModel,
+            shutdown: async () => {
+                try {
+                    live.dispose();
+                }
+                catch {
+                    // best-effort
+                }
+                restoreProvider?.();
+            },
+        };
+    }
+    catch (err) {
+        try {
+            session?.dispose();
+        }
+        catch {
+            // best-effort
+        }
+        restoreProvider?.();
+        throw err;
+    }
+}
+/**
+ * Pi OperatorAgentModel: durable session per host tool-context, Workshop tools only.
+ */
+export function createPiOperatorAgentModel(options) {
+    const cwd = options.cwd;
+    const agentDir = options.agentDir ?? workshopAgentDir();
+    const openPiSession = options.openPiSession ?? openDefaultPiSession;
+    const bindings = new WeakMap();
+    const activeTools = new Set();
+    function resolveAuthPath() {
+        if (options.authPath)
+            return options.authPath;
+        return resolveCredentialBinding(cwd).authPath;
+    }
+    function resolveModelId() {
+        if (options.resolveModelId)
+            return options.resolveModelId();
+        return resolveWorkshopModel({
+            sessionOverride: options.model,
+            settingsDefault: options.settingsDefault,
+            profileDefault: options.profileDefault,
+        });
+    }
+    async function ensureBound(profile, tools, modelId) {
+        const existing = bindings.get(tools);
+        if (existing && existing.profileId === profile.id) {
+            const reload = modelId !== undefined &&
+                sessionNeedsExtensionReload(existing.handle.extensionPaths, extensionPathsForModel(modelId));
+            if (!reload) {
+                existing.profile = profile;
+                existing.tools = tools;
+                if (modelId)
+                    await existing.handle.applyModel?.(modelId);
+                return existing;
+            }
+        }
+        if (existing) {
+            await existing.handle.shutdown();
+            bindings.delete(tools);
+        }
+        const bindingHolder = { current: null };
+        const toolNames = resolveWorkshopToolNames(profile.tools.map((t) => t.name));
+        const customTools = buildWorkshopCustomTools(profile.tools, () => {
+            if (!bindingHolder.current) {
+                throw new Error("Workshop Pi profile not bound");
+            }
+            return bindingHolder.current.profile;
+        }, () => {
+            if (!bindingHolder.current) {
+                throw new Error("Workshop Pi tool context not bound");
+            }
+            return bindingHolder.current.tools;
+        }, (name, result) => {
+            if (!bindingHolder.current)
+                return;
+            bindingHolder.current.toolEvents.push({
+                type: "tool_result",
+                name,
+                result,
+            });
+        }, (status) => {
+            bindingHolder.current?.reportActivity?.(status);
+        });
+        const handle = await openPiSession({
+            cwd,
+            agentDir,
+            systemPrompt: profile.playbook,
+            toolNames,
+            customTools,
+            modelId: modelId ?? resolveModelId(),
+            authPath: resolveAuthPath(),
+            ...(options.piSessionDir ? { piSessionDir: options.piSessionDir } : {}),
+        });
+        const binding = {
+            handle,
+            profileId: profile.id,
+            profile,
+            tools,
+            toolEvents: [],
+            started: true,
+            replayed: false,
+        };
+        bindingHolder.current = binding;
+        bindings.set(tools, binding);
+        activeTools.add(tools);
+        return binding;
+    }
+    async function releaseTools(tools) {
+        const state = bindings.get(tools);
+        if (!state)
+            return;
+        bindings.delete(tools);
+        activeTools.delete(tools);
+        await state.handle.shutdown();
+    }
+    const model = {
+        async prepareRestart({ tools, profile, transcript }) {
+            const state = await ensureBound(profile, tools);
+            if (state.replayed || transcript.length === 0)
+                return;
+            state.handle.sessionManager.appendCustomMessageEntry("stageflow.workshop_transcript_replay", formatTranscriptReplay(transcript), true, { messageCount: transcript.length });
+            syncAgentMessages(state.handle.session, state.handle.sessionManager);
+            state.replayed = true;
+        },
+        async complete({ profile, message, tools, onDelta, onActivity, modelId }) {
+            let state;
+            try {
+                state = await ensureBound(profile, tools, modelId);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    events: [{ type: "error", message: msg }],
+                };
+            }
+            state.profile = profile;
+            state.tools = tools;
+            state.toolEvents = [];
+            state.reportActivity = onActivity;
+            workshopLog.info("workshop.turn.start", "prompt", {
+                modelId,
+                chars: message.length,
+            });
+            const events = [];
+            let assistantText = "";
+            const unsubscribe = state.handle.session.subscribe((event) => {
+                const e = event;
+                if (e.type === "message_update") {
+                    const ame = e.assistantMessageEvent;
+                    if (ame?.type === "text_delta" && typeof ame.delta === "string") {
+                        assistantText += ame.delta;
+                        onDelta?.(ame.delta);
+                    }
+                    return;
+                }
+                if (e.type === "message_end" && e.message) {
+                    const text = extractAssistantText(e.message);
+                    if (text && !assistantText) {
+                        assistantText = text;
+                    }
+                }
+            });
+            try {
+                await state.handle.session.prompt(cursorBridgePrompt(message, modelId, profile.tools.map((tool) => tool.name)));
+            }
+            catch (err) {
+                unsubscribe();
+                const msg = err instanceof Error ? err.message : String(err);
+                workshopLog.error("workshop.turn.done", msg, { modelId });
+                return {
+                    events: [
+                        ...state.toolEvents,
+                        { type: "error", message: msg },
+                    ],
+                };
+            }
+            unsubscribe();
+            workshopLog.info("workshop.turn.done", "prompt", {
+                modelId,
+                toolCalls: state.toolEvents.length,
+                textChars: assistantText.length,
+            });
+            for (const toolEvent of state.toolEvents) {
+                events.push(toolEvent);
+            }
+            if (assistantText.trim()) {
+                events.push({
+                    type: "message",
+                    role: "assistant",
+                    text: assistantText,
+                });
+            }
+            return { events };
+        },
+        releaseTools,
+        async dispose() {
+            const pending = [...activeTools];
+            activeTools.clear();
+            for (const tools of pending) {
+                const state = bindings.get(tools);
+                bindings.delete(tools);
+                if (state)
+                    await state.handle.shutdown();
+            }
+        },
+        getPiSessionId(tools) {
+            return bindings.get(tools)?.handle.piSessionId;
+        },
+        async abort(tools) {
+            const session = bindings.get(tools)?.handle.session;
+            if (!session?.abort)
+                return;
+            workshopLog.info("workshop.turn.abort", "abort");
+            await session.abort();
+        },
+    };
+    return model;
+}
+export function createLiveWorkshopOperatorHost(options) {
+    const { cwd, agentDir, authPath, model, settingsDefault, profileDefault, piSessionDir, openPiSession, resolveModelId, retriever, projectRoot, } = options;
+    return createOperatorAgentHost(createPiOperatorAgentModel({
+        cwd,
+        ...(agentDir !== undefined ? { agentDir } : {}),
+        ...(authPath !== undefined ? { authPath } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(settingsDefault !== undefined ? { settingsDefault } : {}),
+        ...(profileDefault !== undefined ? { profileDefault } : {}),
+        ...(piSessionDir !== undefined ? { piSessionDir } : {}),
+        ...(openPiSession !== undefined ? { openPiSession } : {}),
+        ...(resolveModelId !== undefined ? { resolveModelId } : {}),
+    }), [
+        createWorkshopAuthorProfile({
+            retriever,
+            projectRoot: projectRoot ?? cwd,
+        }),
+    ]);
+}

package/dist/operatorAgent/profiles/workshopAuthor.d.ts

@@ -0,0 +1,23 @@
+import { type DraftPackage } from "../../config/draftPackage.js";
+import { type DocsRetriever } from "../docsRetrieval.js";
+import type { OperatorAgentProfile, OperatorAgentProposal, OperatorAgentTool, OperatorAgentToolContext } from "../types.js";
+import { WORKSHOP_AUTHOR_PLAYBOOK } from "./workshopAuthorPlaybook.js";
+import { type WorkshopAuthorToolOptions } from "./workshopAuthorTools.js";
+export declare const WORKSHOP_AUTHOR_PROFILE_ID = "workshop-author";
+export { WORKSHOP_AUTHOR_PLAYBOOK };
+export { WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, buildCreateStageDraft, buildCreateTaskDraft, buildEditStageDraft, buildEditTaskDraft, buildCreatePipelineDraft, buildEditPipelineDraft, createSaveTool, createWorkshopAuthorMutatingTools, } from "./workshopAuthorTools.js";
+export declare function buildStageAddProposal(draft: DraftPackage, userText: string): OperatorAgentProposal;
+export declare function isTaskProposalIntent(message: string): boolean;
+export declare function buildTaskAddProposal(draft: DraftPackage, userText: string): OperatorAgentProposal;
+export type WorkshopAuthorProfileOptions = WorkshopAuthorToolOptions & {
+    retriever?: DocsRetriever;
+};
+export declare function createWorkshopAuthorTools(retriever?: DocsRetriever, options?: WorkshopAuthorToolOptions): OperatorAgentTool[];
+/** Default tool list with filesystem docs/examples retrieval. */
+export declare const workshopAuthorTools: OperatorAgentTool[];
+export declare function createWorkshopAuthorProfile(options?: WorkshopAuthorProfileOptions): OperatorAgentProfile;
+export declare function proposeStageFromUserMessage(ctx: OperatorAgentToolContext, message: string): OperatorAgentProposal;
+export declare function proposeTaskFromUserMessage(ctx: OperatorAgentToolContext, message: string): OperatorAgentProposal;
+export declare function assertWorkshopAuthorToolsExcludeDiskShell(tools: readonly {
+    name: string;
+}[]): void;