narraeon 0.7.4 → 0.7.5

package/dist/node/runtime/play/PlayAdvanceLifecycle.js

@@ -0,0 +1,211 @@
+import { ModelHostBindingMismatchError, ModelHostCancelledError, ModelHostContinuationError, ModelHostFailureError, ModelHostOutcomeUnknownError, modelHostFailureRequiresFreshContext, } from "../model/ModelHost.js";
+import { classifyPlayFailure } from "./PlayFailure.js";
+const messages = {
+    playerCommitted: "The player message is committed; the frozen model request is ready to continue.",
+    toolStepSettled: "The completed tool response is settled; its frozen continuation request is ready.",
+    cancelledBeforeDispatch: "The player cancelled before the next Provider dispatch; the frozen request can be resumed without replaying a completed model result.",
+    followupsCancelled: "The player cancelled the remaining follow-up generation after the narrative was committed.",
+    noContinuation: "The complete model response has no provider-native continuation payload; use a fresh context.",
+    noOutput: "The model returned neither text nor a complete tool call.",
+    serviceStoppedAfterHead: "The service stopped after the world was updated; use a fresh context.",
+    serviceStoppedSavingPlayer: "The service stopped while saving the player message; use a fresh context.",
+    serviceStoppedRetryable: "The service stopped while the model request was in progress; retry to call the model again.",
+    serviceStoppedNoRequest: "The service stopped before preparing a model request; use a fresh context.",
+    dispatchInterrupted: "The model request was interrupted.",
+};
+export class PlayAdvanceLifecycle {
+    #ports;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    /**
+     * Marks a Provider dispatch as in progress. `running` is not an ending: it is
+     * the state that every dispatch replaces with an ending before it returns.
+     */
+    beginDispatch(session, request, attempt) {
+        session.status = "running";
+        session.canRetry = false;
+        session.lastFailure = null;
+        delete session.lastFailureKind;
+        session.lastRequest = structuredClone(request);
+        session.lastRequestAttempt = attempt;
+    }
+    /**
+     * Applies an ending, persists the session, then clears the advance marker
+     * and notifies. Every ending of an advance goes through here, so no path
+     * can persist without clearing the marker it settles.
+     */
+    async end(session, ending, advance, notify) {
+        applyEnding(session, ending);
+        await this.#ports.persist(session);
+        if (advance !== null)
+            await this.#ports.clearMarker(advance);
+        notify?.();
+    }
+    /**
+     * Ends an advance that a process exit cut off (ADR-0044). Nothing is
+     * replayed: the exchange is interrupted, and only the chain's own frozen
+     * request can be retried, and only while the world has not moved on.
+     */
+    async recoverAbandoned(session, advance, headMoved) {
+        const playerPhase = advance?.advanceKind === "player";
+        const streaming = playerPhase
+            ? undefined
+            : session.events.findLast((event) => event.kind === "assistant" &&
+                event.status === "streaming" &&
+                (advance === null || event.id === advance.eventId));
+        const canRetry = !headMoved && !playerPhase && session.lastRequest !== null;
+        const message = headMoved
+            ? messages.serviceStoppedAfterHead
+            : playerPhase
+                ? messages.serviceStoppedSavingPlayer
+                : canRetry
+                    ? messages.serviceStoppedRetryable
+                    : messages.serviceStoppedNoRequest;
+        await this.end(session, {
+            kind: "failed",
+            message,
+            failureKind: canRetry ? "retryable" : "other",
+            canRetry,
+            streamingEventId: streaming?.id,
+        }, advance);
+    }
+}
+/**
+ * The ending of an exchange that raised an error before its response was
+ * settled. Cancellation after dispatch is named explicitly here and is never
+ * a retry, even though `ModelHostCancelledError` is also an outcome-unknown
+ * error (ADR-0030).
+ */
+export function dispatchFailureEnding(error, streamingEventId) {
+    const message = errorMessage(error, messages.dispatchInterrupted);
+    if (error instanceof ModelHostCancelledError)
+        return { kind: "cancelled_after_dispatch", message, streamingEventId };
+    const requiresFreshContext = error instanceof ModelHostBindingMismatchError ||
+        error instanceof ModelHostContinuationError ||
+        error instanceof ModelHostOutcomeUnknownError ||
+        modelHostFailureRequiresFreshContext(error);
+    const canRetry = !requiresFreshContext && error instanceof ModelHostFailureError;
+    return {
+        kind: "failed",
+        message,
+        failureKind: classifyPlayFailure(error, canRetry),
+        canRetry,
+        streamingEventId,
+    };
+}
+/**
+ * The ending of an error raised after a response was read or a player message
+ * was written. These failures never grant a retry: Authority may already have
+ * moved past the frozen request.
+ */
+export function settlementFailureEnding(error, fallbackMessage) {
+    return {
+        kind: "failed",
+        message: errorMessage(error, fallbackMessage),
+        failureKind: classifyPlayFailure(error, false),
+        canRetry: false,
+    };
+}
+/** A settled response with no provider-native continuation payload (ADR-0035). */
+export function noContinuationEnding() {
+    return {
+        kind: "failed",
+        message: messages.noContinuation,
+        failureKind: "context_unavailable",
+        canRetry: false,
+    };
+}
+/** A settled response with neither text nor a complete tool call. */
+export function emptyResponseEnding() {
+    return {
+        kind: "failed",
+        message: messages.noOutput,
+        failureKind: "other",
+        canRetry: false,
+    };
+}
+/**
+ * Whether a chain's last ending was the player's cancellation. Every
+ * cancellation ending writes its event last, so the tail identifies it; callers
+ * read the projected flag instead of the event list.
+ */
+export function lastEndingCancelled(session) {
+    return session.events.at(-1)?.kind === "cancellation";
+}
+function applyEnding(session, ending) {
+    switch (ending.kind) {
+        case "ready":
+            if (ending.followupsCancelled === true)
+                session.events.push({
+                    id: session.nextEventId++,
+                    kind: "cancellation",
+                    message: messages.followupsCancelled,
+                });
+            session.status = "ready";
+            session.canRetry = false;
+            session.lastFailure = null;
+            delete session.lastFailureKind;
+            return;
+        case "resumable":
+            session.lastRequest = structuredClone(ending.request);
+            session.lastRequestAttempt = 0;
+            session.status = "interrupted";
+            session.canRetry = true;
+            session.lastFailure =
+                ending.reason === "player_committed"
+                    ? messages.playerCommitted
+                    : messages.toolStepSettled;
+            session.lastFailureKind = "retryable";
+            return;
+        case "cancelled_before_dispatch":
+            interruptStreamingEvent(session, ending.streamingEventId);
+            session.events.push({
+                id: session.nextEventId++,
+                kind: "cancellation",
+                message: messages.cancelledBeforeDispatch,
+            });
+            session.status = "interrupted";
+            session.canRetry = true;
+            session.lastRequest = structuredClone(ending.request);
+            session.lastRequestAttempt = Math.max(0, ending.attempt - 1);
+            session.lastFailure = messages.cancelledBeforeDispatch;
+            delete session.lastFailureKind;
+            return;
+        case "cancelled_after_dispatch":
+            interruptStreamingEvent(session, ending.streamingEventId);
+            session.status = "interrupted";
+            session.canRetry = false;
+            session.lastFailure = ending.message;
+            delete session.lastFailureKind;
+            session.events.push({
+                id: session.nextEventId++,
+                kind: "cancellation",
+                message: ending.message,
+            });
+            return;
+        case "failed":
+            interruptStreamingEvent(session, ending.streamingEventId);
+            session.status = "interrupted";
+            session.canRetry = ending.canRetry;
+            session.lastFailure = ending.message;
+            session.lastFailureKind = ending.failureKind;
+            session.events.push({
+                id: session.nextEventId++,
+                kind: "failure",
+                message: ending.message,
+                failureKind: ending.failureKind,
+            });
+            return;
+    }
+}
+function interruptStreamingEvent(session, eventId) {
+    if (eventId === undefined)
+        return;
+    const event = session.events.find(({ id }) => id === eventId);
+    if (event?.kind === "assistant")
+        event.status = "interrupted";
+}
+function errorMessage(error, fallback) {
+    return error instanceof Error ? error.message : fallback;
+}