@springbrand/agent-runtime 0.2.0-alpha.71 → 0.3.0-alpha.1

package/src/submission/admission.ts

@@ -0,0 +1,275 @@
+import type { UIMessage } from "ai";
+import { validateRuntimeAssemblyPin, type RuntimeAssemblyPin } from "../config/pinning";
+import type {
+  RuntimeSubmissionAdmissionHook,
+  RuntimeSubmissionAdmissionResult,
+} from "../config/ports";
+import type { PiCanonicalUserInput } from "../conversation/message/contract";
+import type { SubmissionAdmissionRepository } from "./admission-repository";
+import type { SteerRepository } from "./steer-repository";
+import {
+  MAX_PENDING_SUBMISSIONS,
+  SubmissionQueueFullError,
+  type SubmissionInput,
+} from "./lifecycle";
+import { isTerminalSubmissionStatus, submissionAbortReason, type StoredSubmission, type SubmissionRepository } from "./repository";
+
+// Pending records retain identity indefinitely; only recent attempts reserve capacity.
+const ADMISSION_ATTEMPT_WINDOW_MS = 60_000;
+
+export interface SubmitMessageOptions {
+  requestId: string;
+  idempotencyKey?: string;
+  userMessageId?: string;
+  userMessage?: UIMessage & { role: "user" };
+  regenerate?: boolean;
+  /** Internal transfer of a durable accepted steer; never a public message option. */
+  steerHandoff?: { submissionId: string; steerId: string };
+}
+
+interface SubmissionAdmissionOptions {
+  admissions: SubmissionAdmissionRepository;
+  submissions: SubmissionRepository;
+  steers: SteerRepository;
+  transaction<T>(run: () => T): T;
+  prepareRuntime(): Promise<{
+    runtimeKey: string;
+    admission?: RuntimeSubmissionAdmissionHook;
+  }>;
+  findUserMessage(messageId: string): Promise<PiCanonicalUserInput | undefined>;
+  /** Called inside the admission transaction, after the Submission is inserted. */
+  onAdmitted(submission: StoredSubmission, hostAccepted: boolean): void;
+  onRejected(submission: StoredSubmission): void;
+  cancelHandoff(submissionId: string, reason: string): StoredSubmission;
+}
+
+function validateAdmissionResult(
+  result: RuntimeSubmissionAdmissionResult,
+): RuntimeSubmissionAdmissionResult {
+  if (!result || typeof result !== "object" || typeof result.accepted !== "boolean") {
+    throw new Error("Runtime admission result is invalid");
+  }
+  if (!result.accepted && (
+    typeof result.code !== "string" || !result.code.trim() ||
+    (result.retryable !== undefined && typeof result.retryable !== "boolean")
+  )) {
+    throw new Error("Runtime admission rejection is invalid");
+  }
+  return result;
+}
+
+function userContentKey(message: PiCanonicalUserInput): string {
+  return JSON.stringify(
+    typeof message.content === "string"
+      ? [{ type: "text", text: message.content }]
+      : message.content,
+  );
+}
+
+/** Owns Host admission identity, in-flight coalescing and atomic Submission creation. */
+export class SubmissionAdmission {
+  private readonly inFlight = new Map<
+    string,
+    Promise<RuntimeSubmissionAdmissionResult>
+  >();
+
+  constructor(private readonly options: SubmissionAdmissionOptions) {}
+
+  input(
+    userMessage: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): SubmissionInput<StoredSubmission> {
+    if (options.steerHandoff) {
+      const { submissionId, steerId } = options.steerHandoff;
+      const steer = options.userMessageId
+        ? this.options.steers.findByMessageId(options.userMessageId)
+        : null;
+      const identity = `${submissionId}:steer:${steerId}`;
+      if (!steer || steer.submissionId !== submissionId || steer.steerId !== steerId ||
+        options.requestId !== identity || options.idempotencyKey !== identity ||
+        userContentKey(JSON.parse(steer.canonicalJson) as PiCanonicalUserInput) !== userContentKey(userMessage)) {
+        throw new Error("Steer handoff must reference an accepted message");
+      }
+    }
+    return {
+      requestId: options.requestId,
+      ...(options.steerHandoff ? { isSteerHandoff: true as const } : {}),
+      ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+      prepareAdmission: async () => {
+        const runtime = await this.options.prepareRuntime();
+        if (options.regenerate) {
+          const original = options.userMessageId
+            ? await this.options.findUserMessage(options.userMessageId)
+            : undefined;
+          if (!original || userContentKey(original) !== userContentKey(userMessage)) {
+            throw new Error("Regenerate request must match an existing user message");
+          }
+        }
+        const identity = runtime.admission
+          ? this.reserve(options)
+          : undefined;
+        const runId = identity?.runId ?? crypto.randomUUID();
+        const requestId = identity?.requestId ?? options.requestId;
+        const idempotencyKey = identity
+          ? identity.idempotencyKey ?? undefined
+          : options.idempotencyKey;
+        const key = idempotencyKey
+          ? `idempotency:${idempotencyKey}`
+          : `request:${requestId}`;
+        let admission: RuntimeSubmissionAdmissionResult | undefined;
+        if (identity?.status === "accepted") {
+          admission = { accepted: true };
+        } else if (identity?.status === "rejected") {
+          admission = {
+            accepted: false,
+            code: identity.code ?? "admission_rejected",
+            retryable: identity.retryable ?? false,
+          };
+        } else if (runtime.admission) {
+          let pending = this.inFlight.get(key);
+          if (!pending) {
+            pending = runtime.admission({
+              requestId,
+              ...(idempotencyKey ? { idempotencyKey } : {}),
+              runId,
+            }).then(validateAdmissionResult).catch((error) => {
+              this.inFlight.delete(key);
+              throw error;
+            });
+            this.inFlight.set(key, pending);
+          }
+          admission = await pending;
+        }
+        return () => {
+          if (admission && !admission.accepted) {
+            this.options.admissions.saveRejected(
+              requestId,
+              runId,
+              admission.code,
+              admission.retryable ?? false,
+            );
+            const rejected = this.skip({
+              submissionId: runId,
+              requestId,
+              idempotencyKey: idempotencyKey ?? null,
+              createdAt: userMessage.timestamp,
+              code: admission.code,
+              retryable: admission.retryable ?? false,
+              userMessageId: options.userMessageId,
+              assistantMessageId: crypto.randomUUID(),
+            });
+            this.inFlight.delete(key);
+            return { ...rejected, admissionRejected: true };
+          }
+          if (admission?.accepted) {
+            this.options.admissions.saveAccepted(requestId, runId);
+          }
+          this.options.submissions.insert({
+            submissionId: runId,
+            requestId,
+            idempotencyKey: idempotencyKey ?? null,
+            createdAt: userMessage.timestamp,
+            assemblyRevision: "",
+            assemblyDescriptor: "",
+            runtimeKey: runtime.runtimeKey,
+            assistantMessageId: crypto.randomUUID(),
+            queuedInputJson: JSON.stringify(userMessage),
+            queuedUiMessageJson: options.userMessage
+              ? JSON.stringify(options.userMessage)
+              : null,
+            userMessageId: options.userMessageId ?? crypto.randomUUID(),
+            regenerateMessageId: options.regenerate
+              ? options.userMessageId ?? null
+              : null,
+            runId,
+          });
+          const admitted = this.options.submissions.find(runId)!;
+          this.options.onAdmitted(admitted, admission?.accepted === true);
+          this.inFlight.delete(key);
+          const abortReason = options.steerHandoff
+            ? submissionAbortReason(this.options.submissions.find(options.steerHandoff.submissionId))
+            : undefined;
+          if (abortReason) {
+            this.options.submissions.updateAbortReason(runId, abortReason);
+            return this.options.cancelHandoff(runId, abortReason);
+          }
+          return admitted;
+        };
+      },
+    };
+  }
+
+  /** Validate before loading capabilities, then reuse or atomically persist the first-run pin. */
+  async pin(
+    submission: StoredSubmission,
+    preparePin: () => Promise<RuntimeAssemblyPin>,
+    restoreRuntime?: (runtimeKey: string) => Promise<void>,
+  ): Promise<StoredSubmission> {
+    const current = this.options.submissions.find(submission.submissionId);
+    if (!current) throw new Error(`Unknown SpringBrand submission: ${submission.submissionId}`);
+    const hasPin = await validateRuntimeAssemblyPin(current.runtimeKey, {
+      revision: current.assemblyRevision,
+      descriptor: current.assemblyDescriptor,
+    });
+    await restoreRuntime?.(current.runtimeKey);
+    const restored = this.options.submissions.find(current.submissionId);
+    if (!restored || isTerminalSubmissionStatus(restored.status)) {
+      throw new Error("Submission ended before Runtime assembly was pinned");
+    }
+    if (hasPin) return restored;
+    const pin = await preparePin();
+    if (!await validateRuntimeAssemblyPin(current.runtimeKey, pin)) {
+      throw new Error("Submission assembly pin is incomplete");
+    }
+    this.options.submissions.pinAssembly(current.submissionId, pin.revision, pin.descriptor);
+    const pinned = this.options.submissions.find(current.submissionId);
+    if (!pinned?.assemblyRevision || !pinned.assemblyDescriptor || isTerminalSubmissionStatus(pinned.status)) {
+      throw new Error("Submission ended before Runtime assembly was pinned");
+    }
+    await validateRuntimeAssemblyPin(pinned.runtimeKey, {
+      revision: pinned.assemblyRevision,
+      descriptor: pinned.assemblyDescriptor,
+    });
+    return pinned;
+  }
+
+  /** The caller shares this synchronous write with its admission/timeout transaction. */
+  skip(input: Parameters<SubmissionRepository["insertRejected"]>[0]): StoredSubmission {
+    this.options.submissions.insertRejected(input);
+    const skipped = this.options.submissions.find(input.submissionId)!;
+    this.options.onRejected(skipped);
+    return skipped;
+  }
+
+  private reserve(options: SubmitMessageOptions) {
+    const attemptedAt = Date.now();
+    return this.options.transaction(() => {
+      const existing = this.options.admissions.find(
+        options.requestId,
+        options.idempotencyKey,
+      );
+      const attemptedSince = attemptedAt - ADMISSION_ATTEMPT_WINDOW_MS;
+      const needsCapacity = !existing ||
+        (existing.status === "pending" && existing.attemptedAt < attemptedSince);
+      if (needsCapacity && !options.steerHandoff &&
+        this.options.submissions.countPending() +
+            this.options.admissions.countPending(attemptedSince) >=
+          MAX_PENDING_SUBMISSIONS
+      ) {
+        throw new SubmissionQueueFullError();
+      }
+      if (existing) {
+        if (existing.status === "pending") {
+          this.options.admissions.recordAttempt(existing.requestId, attemptedAt);
+        }
+        return existing;
+      }
+      return this.options.admissions.begin(
+        options.requestId,
+        options.idempotencyKey ?? null,
+        crypto.randomUUID(),
+        attemptedAt,
+      );
+    });
+  }
+}

package/src/{kernel/receipts.ts → submission/contracts.ts}

@@ -1,5 +1,6 @@
 import type { UIMessage } from "ai";
 import type { ExecutionLevel } from "../lib/execution-level";
+import type { StoredSubmission } from "./repository";
 
 export type ApprovalDecision =
   | { decision: "deny"; reason?: string }
@@ -93,6 +94,19 @@ export interface SubmissionReceipt {
   completedAt?: number;
 }
 
+/** Public receipts expose lifecycle facts without queued input or runtime configuration. */
+export function projectSubmissionReceipt(submission: StoredSubmission): SubmissionReceipt {
+  return {
+    submissionId: submission.submissionId,
+    status: submission.status,
+    accepted: submission.accepted,
+    createdAt: submission.createdAt,
+    ...(submission.error !== null ? { error: submission.error } : {}),
+    ...(submission.retryable !== undefined ? { retryable: submission.retryable } : {}),
+    ...(submission.completedAt !== null ? { completedAt: submission.completedAt } : {}),
+  };
+}
+
 /** Shared discriminator keeps the Stop control and durable transcript semantics aligned. */
 export const USER_STOP_REASON = "Stopped by user";
 

package/src/submission/delivery.ts

@@ -0,0 +1,212 @@
+import type { UIMessage } from "ai";
+import type { PiCanonicalUserInput } from "../conversation/message/contract";
+import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
+import type { RuntimeTurnEvents } from "../telemetry/turn-events";
+import type { HarnessHumanDecisions } from "../tools/human-decisions";
+import type { SubmitMessageOptions } from "./admission";
+import {
+  projectSubmissionReceipt,
+  type MessageDelivery,
+  type MessageDispatchReceipt,
+} from "./contracts";
+import {
+  SubmissionQueueFullError,
+  type SubmissionHandle,
+  type SubmissionLifecycle,
+} from "./lifecycle";
+import type { StoredSubmission, SubmissionRepository } from "./repository";
+import type { PendingSteer, SteerRepository } from "./steer-repository";
+
+interface ActiveSteerTarget {
+  submissionId: string;
+  agent: {
+    steer(message: PiCanonicalUserInput, messageId: string): Promise<void>;
+  };
+}
+
+interface SubmissionDeliveryOptions {
+  submissions: SubmissionRepository;
+  steers: SteerRepository;
+  transaction<T>(run: () => T): T;
+  lifecycle: Pick<
+    SubmissionLifecycle<StoredSubmission, ActiveSteerTarget>,
+    "currentActive" | "continueAfterCurrent"
+  >;
+  decisions: Pick<
+    HarnessHumanDecisions,
+    "isWaitingForApproval" | "isWaitingForInteraction" | "cancelInteractions"
+  >;
+  telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
+  events: Pick<RuntimeTurnEvents, "submissionTerminal" | "drain">;
+  normalize(message: UIMessage & { role: "user" }): Promise<PiCanonicalUserInput>;
+  submit(
+    message: PiCanonicalUserInput,
+    options: SubmitMessageOptions,
+  ): Promise<SubmissionHandle<StoredSubmission>>;
+  onChanged(): Promise<void>;
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/** Chooses FIFO submission or durable steering before waking an execution. */
+export class SubmissionDelivery {
+  constructor(private readonly options: SubmissionDeliveryOptions) {}
+
+  async dispatch(message: UIMessage, delivery: MessageDelivery): Promise<MessageDispatchReceipt> {
+    if (message.role !== "user" || !message.id || !Array.isArray(message.parts) ||
+      (delivery !== "steer" && delivery !== "enqueue")) {
+      return this.reject("invalid_message", "A valid user message is required");
+    }
+    let canonical: PiCanonicalUserInput;
+    try {
+      canonical = await this.options.normalize(message as UIMessage & { role: "user" });
+    } catch (error) {
+      return this.reject("invalid_message", error instanceof Error ? error.message : String(error));
+    }
+    const running = this.options.submissions.findRunning();
+    const parked = running && this.options.decisions.isWaitingForInteraction(running.submissionId)
+      ? running
+      : undefined;
+    const active = this.options.lifecycle.currentActive();
+    // Enqueue cannot unblock a Turn waiting for an answer; the new message supersedes it.
+    if (parked || delivery === "steer") {
+      const target = parked ?? active ?? running ?? this.options.submissions.findNextPending();
+      if (target) {
+        if (this.options.decisions.isWaitingForApproval(target.submissionId)) {
+          return this.reject("not_steerable", "The current Turn is waiting for approval");
+        }
+        const inserted = this.options.transaction(() => this.insertSteer({
+          steerId: crypto.randomUUID(),
+          submissionId: target.submissionId,
+          messageId: message.id,
+          harnessEntryId: null,
+          canonicalJson: JSON.stringify(canonical),
+          uiMessageJson: JSON.stringify(message),
+          createdAt: canonical.timestamp,
+        }, canonical));
+        if (inserted) {
+          await this.deliverActive(active, target.submissionId, canonical, message.id);
+          await this.options.onChanged();
+        }
+        this.resumeInteraction(target.submissionId);
+        return { kind: "accepted", submissionId: target.submissionId, messageId: message.id };
+      }
+    }
+
+    try {
+      const submitted = await this.options.submit(canonical, {
+        requestId: message.id,
+        idempotencyKey: message.id,
+        userMessageId: message.id,
+        userMessage: message as UIMessage & { role: "user" },
+      });
+      this.options.waitUntil(submitted.completion);
+      const position = this.options.submissions.listPending()
+        .findIndex(({ submissionId }) => submissionId === submitted.receipt.submissionId) + 1;
+      return position > 0
+        ? { kind: "queued", submission: projectSubmissionReceipt(submitted.receipt), position }
+        : { kind: "accepted", submissionId: submitted.receipt.submissionId, messageId: message.id };
+    } catch (error) {
+      if (error instanceof SubmissionQueueFullError) return this.reject("queue_full", error.message);
+      throw error;
+    }
+  }
+
+  async steerQueued(submissionId: string): Promise<MessageDispatchReceipt> {
+    const active = this.options.lifecycle.currentActive();
+    const target = active ?? this.options.submissions.findRunning() ??
+      this.options.submissions.findNextPending();
+    if (!target || this.options.decisions.isWaitingForApproval(target.submissionId)) {
+      return this.reject("not_steerable", "The current Turn is not accepting steering");
+    }
+    const queued = this.options.submissions.find(submissionId);
+    if (!queued || queued.submissionId === target.submissionId || queued.status !== "pending" ||
+      !queued.queuedInputJson || !queued.userMessageId) {
+      return this.reject("invalid_message", "The queued message is no longer available");
+    }
+    let canonical: PiCanonicalUserInput;
+    let uiMessage: UIMessage | undefined;
+    try {
+      canonical = JSON.parse(queued.queuedInputJson) as PiCanonicalUserInput;
+      uiMessage = queued.queuedUiMessageJson ? JSON.parse(queued.queuedUiMessageJson) as UIMessage : undefined;
+      if (canonical?.role !== "user" ||
+        (uiMessage && (uiMessage.role !== "user" || uiMessage.id !== queued.userMessageId))) {
+        return this.reject("invalid_message", "The queued message is invalid");
+      }
+    } catch {
+      return this.reject("invalid_message", "The queued message is invalid");
+    }
+    const messageId = queued.userMessageId;
+    const moved = this.options.transaction(() => {
+      const latest = this.options.submissions.find(submissionId);
+      const current = this.options.submissions.findRunning() ?? this.options.submissions.findNextPending();
+      if (latest?.status !== "pending" || current?.submissionId !== target.submissionId) return false;
+      if (!this.insertSteer({
+        steerId: crypto.randomUUID(),
+        submissionId: target.submissionId,
+        messageId,
+        harnessEntryId: null,
+        canonicalJson: queued.queuedInputJson!,
+        uiMessageJson: queued.queuedUiMessageJson,
+        createdAt: queued.createdAt,
+      }, canonical)) return false;
+      const reason = "Moved to active Turn";
+      this.options.submissions.updateAbortReason(submissionId, reason);
+      this.options.submissions.updateTerminal(submissionId, "aborted", reason, Date.now());
+      this.options.events.submissionTerminal(this.options.submissions.find(submissionId)!);
+      return true;
+    });
+    if (!moved) return this.reject("invalid_message", "The queued message is no longer available");
+    try {
+      await this.deliverActive(active, target.submissionId, canonical, messageId);
+      this.resumeInteraction(target.submissionId);
+    } finally {
+      await this.options.events.drain();
+      await this.options.onChanged();
+    }
+    return {
+      kind: "steered",
+      submissionId: target.submissionId,
+      messageId,
+      ...(uiMessage ? { message: uiMessage } : {}),
+    };
+  }
+
+  private insertSteer(steer: PendingSteer, message: PiCanonicalUserInput): boolean {
+    if (this.options.steers.findByMessageId(steer.messageId)) return false;
+    this.options.steers.insert(steer);
+    this.options.telemetry.capture("turnSteered", {
+      submissionId: steer.submissionId,
+      steerId: steer.steerId,
+      messageId: steer.messageId,
+      content: message,
+      occurredAt: steer.createdAt,
+    });
+    return true;
+  }
+
+  private async deliverActive(
+    active: ActiveSteerTarget | undefined,
+    submissionId: string,
+    message: PiCanonicalUserInput,
+    messageId: string,
+  ): Promise<void> {
+    if (active?.submissionId === submissionId) {
+      // Receipt persistence is authoritative; a failed live delivery is retried on recovery.
+      await active.agent.steer(message, messageId).catch(() => undefined);
+    }
+  }
+
+  private resumeInteraction(submissionId: string): void {
+    if (!this.options.decisions.isWaitingForInteraction(submissionId)) return;
+    // The steer must be durable before cancelling the Tool that wakes the original Turn.
+    this.options.decisions.cancelInteractions(submissionId, "Superseded by a new message");
+    this.options.waitUntil(this.options.lifecycle.continueAfterCurrent(submissionId));
+  }
+
+  private reject(
+    code: "invalid_message" | "not_steerable" | "queue_full",
+    message: string,
+  ): MessageDispatchReceipt {
+    return { kind: "rejected", code, message };
+  }
+}

package/src/submission/finalization.ts

@@ -0,0 +1,111 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { CancelQueuedResult } from "@earendil-works/pi-agent-core";
+import type { ConversationHistory } from "../conversation/history";
+import type { MessageUiRepository } from "../conversation/repository";
+import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
+import type { RuntimeTurnEvents } from "../telemetry/turn-events";
+import type { HarnessHumanDecisions } from "../tools/human-decisions";
+import { USER_STOP_REASON } from "./contracts";
+import type { SubmissionOutcome } from "./lifecycle";
+import { isTerminalSubmissionStatus, type StoredSubmission, type SubmissionRepository } from "./repository";
+import { finishPendingSteers } from "./steer-delivery";
+import type { SteerRepository } from "./steer-repository";
+
+/** Commits the Submission outcome and human/Host facts after accepted steering is preserved. */
+export class SubmissionFinalizer {
+  constructor(private readonly options: {
+    submissions: SubmissionRepository;
+    steers: SteerRepository;
+    messageUi: MessageUiRepository;
+    transaction<T>(run: () => T): T;
+    conversation: Pick<ConversationHistory, "append" | "appendTurnAbortedMarker" | "storedMessages">;
+    decisions: Pick<HarnessHumanDecisions, "cancelForSubmission">;
+    events: Pick<RuntimeTurnEvents, "submissionTerminal">;
+    telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
+    releaseAbortedHarness(): Promise<void>;
+    cancelQueued(entryId: string): Promise<CancelQueuedResult | undefined>;
+    submit: Parameters<typeof finishPendingSteers>[0]["submit"];
+    waitUntil(promise: Promise<unknown>): void;
+  }) {}
+
+  async finish(
+    submissionId: string,
+    outcome: SubmissionOutcome,
+    message?: string,
+  ): Promise<StoredSubmission> {
+    const initial = this.read(submissionId);
+    if (isTerminalSubmissionStatus(initial.status)) return initial;
+    const aborted = Boolean(initial.abortReason) || outcome === "aborted";
+    if (aborted) await this.options.releaseAbortedHarness();
+    await finishPendingSteers({
+      submissionId,
+      aborted,
+      submissions: this.options.submissions,
+      cancelHandoff: (id, reason) => this.commit(id, "aborted", reason),
+      steers: this.options.steers,
+      messageUi: this.options.messageUi,
+      transaction: (run) => this.options.transaction(run),
+      conversation: this.options.conversation,
+      cancelQueued: (id) => this.options.cancelQueued(id),
+      submit: this.options.submit,
+      waitUntil: this.options.waitUntil,
+    });
+    const output = (await this.options.conversation.storedMessages())
+      .filter((entry) => entry.submissionId === submissionId && entry.message.role === "assistant")
+      .at(-1)?.message;
+    return this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+  }
+
+  /** Shares atomic terminal facts with an admitted handoff cancelled before execution. */
+  commit(
+    submissionId: string,
+    outcome: SubmissionOutcome,
+    message?: string,
+    output?: AssistantMessage,
+  ): StoredSubmission {
+    return this.options.transaction(() => {
+      // Host admission and history reads can await while an explicit stop wins.
+      const latest = this.read(submissionId);
+      if (isTerminalSubmissionStatus(latest.status)) return latest;
+      const effectiveOutcome = latest.abortReason ? "aborted" : outcome;
+      const reason = latest.abortReason ?? message;
+      this.options.decisions.cancelForSubmission(submissionId, reason ?? "Turn ended before the decision");
+      if (effectiveOutcome === "aborted") {
+        this.options.telemetry.capture("turnCancelled", {
+          submissionId,
+          ...(reason ? { reason } : {}),
+        });
+      }
+      const status = effectiveOutcome === "succeeded" ? "completed" : effectiveOutcome === "aborted" ? "aborted" : "error";
+      this.options.submissions.updateTerminal(submissionId, status, reason, Date.now());
+      const completed = this.read(submissionId);
+      if (effectiveOutcome === "aborted" && reason === USER_STOP_REASON) {
+        if (completed.completedAt === null) {
+          throw new Error(
+            `Aborted SpringBrand submission has no completion time: ${submissionId}`,
+          );
+        }
+        this.options.conversation.appendTurnAbortedMarker(
+          submissionId,
+          completed.completedAt,
+        );
+      }
+      this.options.events.submissionTerminal(completed);
+      this.options.telemetry.capture("turnFinished", {
+        submissionId,
+        outcome: effectiveOutcome === "succeeded" ? "completed" : effectiveOutcome === "aborted" ? "cancelled" : "failed",
+        durationMs: Math.max(0, (completed.completedAt ?? Date.now()) - latest.createdAt),
+        ...(output === undefined ? {} : { output }),
+        ...(reason ? { error: reason } : {}),
+        occurredAt: completed.completedAt ?? Date.now(),
+      });
+      return completed;
+    });
+  }
+
+  private read(submissionId: string): StoredSubmission {
+    const submission = this.options.submissions.find(submissionId);
+    if (!submission) throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
+    return submission;
+  }
+}

package/src/submission/index.ts

@@ -0,0 +1,9 @@
+export * from "./admission";
+export * from "./admission-repository";
+export * from "./contracts";
+export * from "./lifecycle";
+export * from "./repository";
+export * from "./steer-repository";
+export * from "./steer-delivery";
+export * from "./delivery";
+export * from "./finalization";