stageflow 0.25.0 → 0.30.0

package/dist/workshop/chatTurn.d.ts

@@ -0,0 +1,232 @@
+import type { DraftPackage } from "../config/draftPackage.js";
+import { type OperatorAgentHost, type OperatorAgentProposal, type OperatorAgentSession, type OperatorAgentSessionEvent, type ProposalArtifactDiff, type WorkshopToolActivityUpdate } from "../operatorAgent/index.js";
+import { WorkshopSessionStoreError } from "./sessionStore.js";
+import { type WorkshopPointerChange } from "./workshopPin.js";
+export type { WorkshopPointerChange };
+type LiveTurnBinding = {
+    storeRoot: string;
+    onPointerChange?: (frame: WorkshopPointerChange) => void;
+};
+/**
+ * Accept-card / soft-undo payload for a mutation that is **already applied**
+ * to the in-memory draft. `nextDraft` is current; `baseDraft` + fingerprint
+ * are the undo restore target when Reject is safe. Not a gated propose→Accept
+ * patch — create/edit tools mutate immediately.
+ */
+export type WorkshopChatProposalPayload = {
+    id: string;
+    summary: string;
+    nextDraft: DraftPackage;
+    baseDraft: DraftPackage;
+    baseFingerprint: string;
+    artifacts: ProposalArtifactDiff[];
+    affectedStageIds: string[];
+};
+export type WorkshopChatWireEvent = {
+    type: "message";
+    role: "assistant" | "user" | "system";
+    text: string;
+}
+/** Mutation receipt for Accept/Reject UX (draft already mutated). */
+ | {
+    type: "proposal";
+    proposal: WorkshopChatProposalPayload;
+} | {
+    type: "tool_result";
+    name: string;
+    result: unknown;
+} | {
+    type: "validation";
+    result: unknown;
+} | {
+    type: "error";
+    message: string;
+};
+/**
+ * Chat requires an existing Workshop session id (created via New /
+ * POST /api/workshop/sessions). Unknown ids return workshop_session_not_found
+ * — no create-on-missing.
+ */
+export type WorkshopChatTurnInput = {
+    sessionId: string;
+    draft: DraftPackage;
+    message: string;
+    /** @deprecated Ignored — mutations apply immediately (Accept = soft undo). */
+    autoApply?: boolean;
+    /** Session model override from Workshop chrome. */
+    model?: string | null;
+    /** Settings default from factory settings /api/settings. */
+    settingsDefault?: string | null;
+    /**
+     * Injected host (tests / fake). When omitted, uses the registry's host
+     * (or a process-default Workshop fake Author host).
+     */
+    host?: OperatorAgentHost;
+    /** Live host-session map; defaults to the process registry. */
+    registry?: WorkshopChatSessionRegistry;
+    /** Session store root; defaults to `$STAGEFLOW_HOME`. */
+    storeRoot?: string;
+    /**
+     * Mid-turn assistant text callback. Invoked as model deltas arrive (before
+     * the turn promise resolves). HTTP uses this to flush NDJSON `delta` frames.
+     */
+    onDelta?: (text: string) => void;
+    /** Mid-turn tool status. HTTP flushes this as an NDJSON activity frame. */
+    onActivity?: (update: WorkshopToolActivityUpdate) => void;
+    /** Fired when this turn changes the session pointer. */
+    onPointerChange?: (frame: WorkshopPointerChange) => void;
+};
+export type WorkshopChatTurnResult = {
+    sessionId: string;
+    events: WorkshopChatWireEvent[];
+    /** Draft left on the host after this turn. Pinned turns use the build, not the posted body. */
+    draft: DraftPackage;
+    /**
+     * Latest undoable mutation card (already applied), or null after
+     * Accept/undo. Name is historical — not a pending gated apply.
+     */
+    pending: WorkshopChatProposalPayload | null;
+    /** Always false — auto-apply chrome removed; mutations apply immediately. */
+    autoApply: boolean;
+    model: string;
+    /** Build this turn edited. Null when the chat stayed unlinked. */
+    buildId: string | null;
+};
+export type WorkshopChatStreamFrame = {
+    type: "delta";
+    text: string;
+} | ({
+    type: "activity";
+} & WorkshopToolActivityUpdate) | {
+    type: "pointer-change";
+    buildId: string;
+    draft: DraftPackage;
+} | {
+    type: "event";
+    event: WorkshopChatWireEvent;
+} | {
+    type: "done";
+    sessionId: string;
+    events: WorkshopChatWireEvent[];
+    draft: DraftPackage;
+    pending: WorkshopChatProposalPayload | null;
+    autoApply: boolean;
+    model: string;
+    buildId: string | null;
+};
+export type WorkshopLiveSessionHandle = {
+    sessionId: string;
+    agentSession: OperatorAgentSession;
+};
+export declare class WorkshopChatSessionRegistry {
+    readonly host: OperatorAgentHost;
+    private readonly sessions;
+    private readonly turnsInFlight;
+    private readonly turnChains;
+    private readonly pins;
+    private readonly liveTurns;
+    constructor(host: OperatorAgentHost);
+    runExclusive<T>(sessionId: string, fn: () => Promise<T>): Promise<T>;
+    bindTurn(sessionId: string, binding: LiveTurnBinding, pinnedBuildId: string | null): void;
+    getLiveTurn(sessionId: string): LiveTurnBinding | undefined;
+    getPinnedBuildId(sessionId: string): string | null;
+    setPinnedBuildId(sessionId: string, buildId: string | null): void;
+    clearLive(sessionId: string): void;
+    has(sessionId: string): boolean;
+    get(sessionId: string): OperatorAgentSession | undefined;
+    isTurnInFlight(sessionId: string): boolean;
+    beginTurn(sessionId: string): void;
+    endTurn(sessionId: string): void;
+    /**
+     * Interrupt the open host session's in-flight prompt.
+     * Returns false when this session has no turn running.
+     */
+    abortTurn(sessionId: string): Promise<boolean>;
+    /**
+     * Reuse the open host session when present; otherwise open a new one.
+     * Rebinds the draft argument. Pinned turns pass the stored build draft.
+     * Returns whether this call created a new host session (restart / first open).
+     */
+    getOrOpen(sessionId: string, draft: DraftPackage): {
+        session: OperatorAgentSession;
+        created: boolean;
+    };
+    close(sessionId: string): void;
+    clear(): void;
+}
+/** Test helper — drop process-default live sessions between cases. */
+export declare function resetWorkshopChatSessionsForTests(): void;
+export declare function serializeWorkshopProposal(proposal: OperatorAgentProposal, fallbackDraft: DraftPackage): WorkshopChatProposalPayload;
+export declare function toWorkshopChatWireEvent(event: OperatorAgentSessionEvent, fallbackDraft: DraftPackage): WorkshopChatWireEvent;
+/**
+ * One Workshop Author turn on a durable Operator Agent Host session.
+ * Requires an existing session store record (New / POST sessions first).
+ * Does not close the host session after the turn.
+ * A pinned build's stored draft is the source of truth. An unlinked turn
+ * still binds the client draft, and draft tools fail until a build is pinned.
+ * A second turn for the same session waits until this one finishes.
+ */
+export declare function runWorkshopChatTurn(input: WorkshopChatTurnInput): Promise<WorkshopChatTurnResult>;
+/** Stop the in-flight Author prompt and return the draft it left behind. */
+export declare function stopWorkshopChatTurn(registry: WorkshopChatSessionRegistry, sessionId: string): Promise<{
+    stopped: boolean;
+    draft: DraftPackage | null;
+    pending: WorkshopChatProposalPayload | null;
+    buildId: string | null;
+}>;
+/** Chunk assistant text for NDJSON stream frames (fake/live coherent turns). */
+export declare function chunkAssistantText(text: string, chunkSize?: number): string[];
+export declare function iterateWorkshopChatStreamFrames(result: WorkshopChatTurnResult, options?: {
+    chunkAssistantText?: boolean;
+}): Generator<WorkshopChatStreamFrame>;
+export type WorkshopSessionUndoInput = {
+    sessionId: string;
+    draft: DraftPackage;
+    mutationId?: string;
+    host?: OperatorAgentHost;
+    registry?: WorkshopChatSessionRegistry;
+    storeRoot?: string;
+};
+export type WorkshopSessionUndoResult = {
+    ok: true;
+    sessionId: string;
+    draft: DraftPackage;
+    pending: WorkshopChatProposalPayload | null;
+} | {
+    ok: false;
+    sessionId: string;
+    draft: DraftPackage;
+    pending: WorkshopChatProposalPayload | null;
+    reason: "none" | "id_mismatch" | "conflict";
+    notice?: string;
+};
+export type WorkshopSessionAcceptInput = {
+    sessionId: string;
+    draft: DraftPackage;
+    mutationId?: string;
+    host?: OperatorAgentHost;
+    registry?: WorkshopChatSessionRegistry;
+    storeRoot?: string;
+};
+export type WorkshopSessionAcceptResult = {
+    ok: true;
+    sessionId: string;
+    draft: DraftPackage;
+    pending: WorkshopChatProposalPayload | null;
+} | {
+    ok: false;
+    sessionId: string;
+    draft: DraftPackage;
+    pending: WorkshopChatProposalPayload | null;
+    reason: "none" | "id_mismatch" | "conflict";
+    notice?: string;
+};
+/**
+ * Soft-undo a mutation on a durable Workshop host session.
+ * Rebinds the client draft first (R9), then undoes when fingerprint matches.
+ * Fail-closed during an in-flight chat turn: no rebind, conflict.
+ */
+export declare function undoWorkshopSessionMutation(input: WorkshopSessionUndoInput): Promise<WorkshopSessionUndoResult>;
+/** Accept acknowledges a mutation card; draft is already applied. */
+export declare function acceptWorkshopSessionMutation(input: WorkshopSessionAcceptInput): Promise<WorkshopSessionAcceptResult>;
+export { WorkshopSessionStoreError };

package/dist/workshop/chatTurn.js

@@ -0,0 +1,475 @@
+import { createWorkshopDraftContext, createWorkshopOperatorHost, isWorkshopDraftContext, readDraftFromContext, withDraft, WORKSHOP_AUTHOR_PROFILE_ID, } from "../operatorAgent/index.js";
+import { resolveWorkshopModel } from "./modelSettings.js";
+import { getWorkshopBuild, updateWorkshopBuild } from "./buildStore.js";
+import { appendWorkshopSessionMessages, getWorkshopSession, resolveWorkshopSessionStoreRoot, WorkshopSessionStoreError, } from "./sessionStore.js";
+import { bindPinnedBuildContext, enqueueSessionWrite, registerLiveWorkshopSession, resetWorkshopPinStateForTests, unregisterLiveWorkshopSession, } from "./workshopPin.js";
+function markUnlinkedChatContext(current, sessionId, draft) {
+    const base = isWorkshopDraftContext(current)
+        ? { ...current, draft }
+        : { draft };
+    delete base.buildId;
+    base.chatSessionId = sessionId;
+    base.draft = draft;
+    return base;
+}
+/**
+ * In-memory map of Workshop session id → open OperatorAgentSession.
+ * Survives across chat turns until process restart (disk transcript remains).
+ */
+const TURN_IN_FLIGHT_UNDO_NOTICE = "Cannot undo while a chat turn is in progress.";
+export class WorkshopChatSessionRegistry {
+    host;
+    sessions = new Map();
+    turnsInFlight = new Set();
+    turnChains = new Map();
+    pins = new Map();
+    liveTurns = new Map();
+    constructor(host) {
+        this.host = host;
+    }
+    runExclusive(sessionId, fn) {
+        const prev = this.turnChains.get(sessionId) ?? Promise.resolve();
+        const run = prev.then(fn, fn);
+        this.turnChains.set(sessionId, run.then(() => undefined, () => undefined));
+        return run;
+    }
+    bindTurn(sessionId, binding, pinnedBuildId) {
+        this.liveTurns.set(sessionId, binding);
+        this.pins.set(sessionId, pinnedBuildId);
+        registerLiveWorkshopSession(sessionId, {
+            storeRoot: binding.storeRoot,
+            registry: this,
+        });
+    }
+    getLiveTurn(sessionId) {
+        return this.liveTurns.get(sessionId);
+    }
+    getPinnedBuildId(sessionId) {
+        return this.pins.get(sessionId) ?? null;
+    }
+    setPinnedBuildId(sessionId, buildId) {
+        this.pins.set(sessionId, buildId);
+    }
+    clearLive(sessionId) {
+        this.liveTurns.delete(sessionId);
+        unregisterLiveWorkshopSession(sessionId);
+    }
+    has(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId)?.agentSession;
+    }
+    isTurnInFlight(sessionId) {
+        return this.turnsInFlight.has(sessionId);
+    }
+    beginTurn(sessionId) {
+        this.turnsInFlight.add(sessionId);
+    }
+    endTurn(sessionId) {
+        this.turnsInFlight.delete(sessionId);
+    }
+    /**
+     * Interrupt the open host session's in-flight prompt.
+     * Returns false when this session has no turn running.
+     */
+    async abortTurn(sessionId) {
+        if (!this.turnsInFlight.has(sessionId))
+            return false;
+        const session = this.sessions.get(sessionId)?.agentSession;
+        if (!session)
+            return false;
+        await session.abort();
+        return true;
+    }
+    /**
+     * Reuse the open host session when present; otherwise open a new one.
+     * Rebinds the draft argument. Pinned turns pass the stored build draft.
+     * Returns whether this call created a new host session (restart / first open).
+     */
+    getOrOpen(sessionId, draft) {
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            existing.agentSession.setContext(withDraft(existing.agentSession.getContext(), draft));
+            return { session: existing.agentSession, created: false };
+        }
+        const agentSession = this.host.openSession({
+            profileId: WORKSHOP_AUTHOR_PROFILE_ID,
+            context: createWorkshopDraftContext(draft),
+        });
+        this.sessions.set(sessionId, { sessionId, agentSession });
+        return { session: agentSession, created: true };
+    }
+    close(sessionId) {
+        const handle = this.sessions.get(sessionId);
+        if (!handle)
+            return;
+        handle.agentSession.close();
+        this.sessions.delete(sessionId);
+        this.turnsInFlight.delete(sessionId);
+    }
+    clear() {
+        for (const handle of this.sessions.values()) {
+            handle.agentSession.close();
+        }
+        this.sessions.clear();
+        this.turnsInFlight.clear();
+        this.turnChains.clear();
+        this.pins.clear();
+        this.liveTurns.clear();
+    }
+}
+let defaultHost;
+let defaultRegistry;
+function getDefaultRegistry(host) {
+    if (host) {
+        if (!defaultRegistry || defaultRegistry.host !== host) {
+            defaultRegistry?.clear();
+            defaultRegistry = new WorkshopChatSessionRegistry(host);
+        }
+        return defaultRegistry;
+    }
+    if (!defaultHost) {
+        defaultHost = createWorkshopOperatorHost();
+    }
+    if (!defaultRegistry || defaultRegistry.host !== defaultHost) {
+        defaultRegistry?.clear();
+        defaultRegistry = new WorkshopChatSessionRegistry(defaultHost);
+    }
+    return defaultRegistry;
+}
+/** Test helper — drop process-default live sessions between cases. */
+export function resetWorkshopChatSessionsForTests() {
+    defaultRegistry?.clear();
+    defaultRegistry = undefined;
+    defaultHost = undefined;
+    resetWorkshopPinStateForTests();
+}
+function isDraftPackage(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        "pipeline" in value &&
+        typeof value.pipeline === "object" &&
+        value.pipeline !== null);
+}
+function draftFromContextValue(value, fallback) {
+    if (isDraftPackage(value))
+        return value;
+    if (value !== null &&
+        typeof value === "object" &&
+        "draft" in value &&
+        isDraftPackage(value.draft)) {
+        return value.draft;
+    }
+    return fallback;
+}
+export function serializeWorkshopProposal(proposal, fallbackDraft) {
+    // Wire shape for Accept/Reject cards — mutation already applied on the host.
+    const nextDraft = draftFromContextValue(proposal.nextContext, fallbackDraft);
+    const baseDraft = draftFromContextValue(proposal.baseContext, fallbackDraft);
+    return {
+        id: proposal.id,
+        summary: proposal.summary,
+        nextDraft,
+        baseDraft,
+        baseFingerprint: typeof proposal.baseFingerprint === "string" && proposal.baseFingerprint
+            ? proposal.baseFingerprint
+            : JSON.stringify(baseDraft),
+        artifacts: Array.isArray(proposal.artifacts) ? proposal.artifacts : [],
+        affectedStageIds: Array.isArray(proposal.affectedStageIds)
+            ? proposal.affectedStageIds
+            : [],
+    };
+}
+export function toWorkshopChatWireEvent(event, fallbackDraft) {
+    if (event.type === "proposal") {
+        return {
+            type: "proposal",
+            proposal: serializeWorkshopProposal(event.proposal, fallbackDraft),
+        };
+    }
+    if (event.type === "message") {
+        return {
+            type: "message",
+            role: event.role,
+            text: event.text,
+        };
+    }
+    if (event.type === "tool_result") {
+        return {
+            type: "tool_result",
+            name: event.name,
+            result: event.result,
+        };
+    }
+    if (event.type === "validation") {
+        return { type: "validation", result: event.result };
+    }
+    return { type: "error", message: event.message };
+}
+function transcriptMessagesForTurn(userMessage, events) {
+    const messages = [
+        { role: "user", text: userMessage },
+    ];
+    for (const event of events) {
+        if (event.type === "message") {
+            messages.push({ role: event.role, text: event.text });
+        }
+    }
+    return messages;
+}
+/**
+ * One Workshop Author turn on a durable Operator Agent Host session.
+ * Requires an existing session store record (New / POST sessions first).
+ * Does not close the host session after the turn.
+ * A pinned build's stored draft is the source of truth. An unlinked turn
+ * still binds the client draft, and draft tools fail until a build is pinned.
+ * A second turn for the same session waits until this one finishes.
+ */
+export async function runWorkshopChatTurn(input) {
+    const sessionId = typeof input.sessionId === "string" ? input.sessionId.trim() : "";
+    if (!sessionId) {
+        throw new Error("sessionId is required");
+    }
+    const message = input.message.trim();
+    if (!message) {
+        throw new Error("message is required");
+    }
+    const storeRoot = input.storeRoot ?? resolveWorkshopSessionStoreRoot();
+    const model = resolveWorkshopModel({
+        sessionOverride: input.model,
+        settingsDefault: input.settingsDefault,
+    });
+    const registry = input.registry ?? getDefaultRegistry(input.host);
+    if (input.host && registry.host !== input.host) {
+        throw new Error("host does not match workshop chat session registry");
+    }
+    return registry.runExclusive(sessionId, async () => {
+        // Fail closed: chat never creates missing sessions (prefer New → create).
+        const storeRecord = getWorkshopSession(storeRoot, sessionId);
+        const pinnedBuild = storeRecord.activeBuildId
+            ? getWorkshopBuild(storeRoot, storeRecord.activeBuildId)
+            : null;
+        const draftForOpen = pinnedBuild?.draft ?? input.draft;
+        const { session: agentSession, created } = registry.getOrOpen(sessionId, draftForOpen);
+        if (pinnedBuild) {
+            agentSession.setContext(bindPinnedBuildContext(agentSession.getContext(), pinnedBuild, sessionId));
+        }
+        else {
+            agentSession.setContext(markUnlinkedChatContext(agentSession.getContext(), sessionId, draftForOpen));
+        }
+        registry.bindTurn(sessionId, {
+            storeRoot,
+            onPointerChange: input.onPointerChange,
+        }, pinnedBuild?.id ?? null);
+        registry.beginTurn(sessionId);
+        let rawEvents;
+        let resultBuildId = null;
+        try {
+            // KTD7: process restart → new host session; replay disk transcript into Pi.
+            if (created &&
+                storeRecord.transcript.length > 0 &&
+                typeof agentSession.prepareRestart === "function") {
+                await agentSession.prepareRestart(storeRecord.transcript);
+            }
+            rawEvents = await agentSession.send(message, {
+                onDelta: input.onDelta,
+                onActivity: (update) => {
+                    const buildId = registry.getPinnedBuildId(sessionId);
+                    input.onActivity?.({
+                        ...update,
+                        ...(buildId ? { buildId } : {}),
+                    });
+                },
+                modelId: model,
+            });
+        }
+        finally {
+            try {
+                resultBuildId = registry.getPinnedBuildId(sessionId);
+                if (resultBuildId) {
+                    updateWorkshopBuild(storeRoot, resultBuildId, {
+                        draft: readDraftFromContext(agentSession.getContext()),
+                    });
+                }
+            }
+            finally {
+                registry.endTurn(sessionId);
+                registry.clearLive(sessionId);
+            }
+        }
+        const draft = readDraftFromContext(agentSession.getContext());
+        const pendingRaw = agentSession.getPendingProposal();
+        const events = rawEvents.map((event) => toWorkshopChatWireEvent(event, draft));
+        await enqueueSessionWrite(sessionId, () => {
+            appendWorkshopSessionMessages(storeRoot, sessionId, transcriptMessagesForTurn(message, events));
+        });
+        return {
+            sessionId,
+            events,
+            draft,
+            pending: pendingRaw
+                ? serializeWorkshopProposal(pendingRaw, draft)
+                : null,
+            autoApply: false,
+            model,
+            buildId: resultBuildId,
+        };
+    });
+}
+/** Stop the in-flight Author prompt and return the draft it left behind. */
+export async function stopWorkshopChatTurn(registry, sessionId) {
+    const stopped = await registry.abortTurn(sessionId);
+    const buildId = registry.getPinnedBuildId(sessionId);
+    const session = registry.get(sessionId);
+    if (!session) {
+        return { stopped, draft: null, pending: null, buildId };
+    }
+    const draft = readDraftFromContext(session.getContext());
+    const pendingRaw = session.getPendingProposal();
+    return {
+        stopped,
+        draft,
+        pending: pendingRaw
+            ? serializeWorkshopProposal(pendingRaw, draft)
+            : null,
+        buildId,
+    };
+}
+/** Chunk assistant text for NDJSON stream frames (fake/live coherent turns). */
+export function chunkAssistantText(text, chunkSize = 28) {
+    if (!text)
+        return [];
+    const size = Math.max(1, chunkSize);
+    const chunks = [];
+    for (let i = 0; i < text.length; i += size) {
+        chunks.push(text.slice(i, i + size));
+    }
+    return chunks;
+}
+export function* iterateWorkshopChatStreamFrames(result, options) {
+    const chunkText = options?.chunkAssistantText !== false;
+    for (const event of result.events) {
+        if (chunkText &&
+            event.type === "message" &&
+            event.role === "assistant") {
+            for (const text of chunkAssistantText(event.text)) {
+                yield { type: "delta", text };
+            }
+        }
+        yield { type: "event", event };
+    }
+    yield {
+        type: "done",
+        sessionId: result.sessionId,
+        events: result.events,
+        draft: result.draft,
+        pending: result.pending,
+        autoApply: result.autoApply,
+        model: result.model,
+        buildId: result.buildId,
+    };
+}
+function snapshotLiveSession(registry, sessionId, fallbackDraft) {
+    const session = registry.get(sessionId);
+    if (!session) {
+        return { draft: fallbackDraft, pending: null };
+    }
+    const draft = readDraftFromContext(session.getContext());
+    const pendingRaw = session.getPendingProposal();
+    return {
+        draft,
+        pending: pendingRaw
+            ? serializeWorkshopProposal(pendingRaw, draft)
+            : null,
+    };
+}
+/**
+ * Soft-undo a mutation on a durable Workshop host session.
+ * Rebinds the client draft first (R9), then undoes when fingerprint matches.
+ * Fail-closed during an in-flight chat turn: no rebind, conflict.
+ */
+export async function undoWorkshopSessionMutation(input) {
+    const sessionId = typeof input.sessionId === "string" ? input.sessionId.trim() : "";
+    if (!sessionId) {
+        throw new Error("sessionId is required");
+    }
+    const storeRoot = input.storeRoot ?? resolveWorkshopSessionStoreRoot();
+    getWorkshopSession(storeRoot, sessionId);
+    const registry = input.registry ?? getDefaultRegistry(input.host);
+    if (input.host && registry.host !== input.host) {
+        throw new Error("host does not match workshop chat session registry");
+    }
+    if (registry.isTurnInFlight(sessionId)) {
+        const snap = snapshotLiveSession(registry, sessionId, input.draft);
+        return {
+            ok: false,
+            sessionId,
+            draft: snap.draft,
+            pending: snap.pending,
+            reason: "conflict",
+            notice: TURN_IN_FLIGHT_UNDO_NOTICE,
+        };
+    }
+    const { session } = registry.getOrOpen(sessionId, input.draft);
+    const undo = session.undoMutation(input.mutationId);
+    const draft = readDraftFromContext(session.getContext());
+    const pendingRaw = session.getPendingProposal();
+    const pending = pendingRaw
+        ? serializeWorkshopProposal(pendingRaw, draft)
+        : null;
+    if (undo.ok) {
+        return { ok: true, sessionId, draft, pending };
+    }
+    return {
+        ok: false,
+        sessionId,
+        draft,
+        pending,
+        reason: undo.reason,
+        ...(undo.notice !== undefined ? { notice: undo.notice } : {}),
+    };
+}
+/** Accept acknowledges a mutation card; draft is already applied. */
+export async function acceptWorkshopSessionMutation(input) {
+    const sessionId = typeof input.sessionId === "string" ? input.sessionId.trim() : "";
+    if (!sessionId) {
+        throw new Error("sessionId is required");
+    }
+    const storeRoot = input.storeRoot ?? resolveWorkshopSessionStoreRoot();
+    getWorkshopSession(storeRoot, sessionId);
+    const registry = input.registry ?? getDefaultRegistry(input.host);
+    if (input.host && registry.host !== input.host) {
+        throw new Error("host does not match workshop chat session registry");
+    }
+    if (registry.isTurnInFlight(sessionId)) {
+        const snap = snapshotLiveSession(registry, sessionId, input.draft);
+        return {
+            ok: false,
+            sessionId,
+            draft: snap.draft,
+            pending: snap.pending,
+            reason: "conflict",
+            notice: TURN_IN_FLIGHT_UNDO_NOTICE,
+        };
+    }
+    const { session } = registry.getOrOpen(sessionId, input.draft);
+    const accepted = session.acceptProposal(input.mutationId);
+    const draft = readDraftFromContext(session.getContext());
+    const pendingRaw = session.getPendingProposal();
+    const pending = pendingRaw
+        ? serializeWorkshopProposal(pendingRaw, draft)
+        : null;
+    if (accepted.ok) {
+        return { ok: true, sessionId, draft, pending };
+    }
+    return {
+        ok: false,
+        sessionId,
+        draft,
+        pending,
+        reason: accepted.reason,
+        ...(accepted.notice !== undefined ? { notice: accepted.notice } : {}),
+    };
+}
+export { WorkshopSessionStoreError };