@jskit-ai/assistant-core 0.2.7 → 0.2.8

package/src/server/conversation/conversationRefusals.js

@@ -0,0 +1,58 @@
+// The refusals the conversation runtime gives its callers, and the error texts its saved state keeps.
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+
+/**
+ * A refusal for the caller. code is its own value, or one a client branches on
+ * shared with other sentences; messageCode names this sentence so a client can
+ * show it in the user's language.
+ */
+function failure(message, code, statusCode = 409, { messageCode, messageParams } = {}) {
+  return new AppError(statusCode, message, { code, ...(messageCode ? { messageCode, messageParams } : {}) });
+}
+
+/** A native delivery result keeps its own sentence and messageCode when it has one. */
+function deliveryFailure(delivered) {
+  const code = delivered?.code || "conversation_delivery_uncertain";
+  return delivered?.error
+    ? failure(delivered.error, code, 409, delivered)
+    : failure("Native delivery could not be confirmed.", code, 409, { messageCode: "assistant.conversation.deliveryUnconfirmed" });
+}
+
+// Error texts that conversation state keeps, including saved records written by
+// earlier releases and the API engine's turn failures. A snapshot or event names
+// them so a client can show them in the user's language; any other error text is
+// shown as sent.
+const STATE_ERROR_MESSAGES = Object.freeze([
+  { message: "This conversation exceeds the configured API history limit. Start another conversation or increase the limit.",
+    messageCode: "assistant.conversation.apiHistoryLimit" },
+  { message: "The model reached its output token limit before completing the answer. Increase maxOutputTokens in the conversation limits.",
+    messageCode: "assistant.conversation.outputTokenLimit" },
+  { message: "The model stream ended without confirming its application tool calls.", messageCode: "assistant.conversation.toolCallsUnconfirmed" },
+  { message: "The model stream ended without confirming a completed answer.", messageCode: "assistant.conversation.answerUnconfirmed" },
+  { message: "Application tool progress text exceeds the configured API limit.", messageCode: "assistant.conversation.toolProgressLimit" },
+  { message: "The assistant exceeded the configured final reply limit.", messageCode: "assistant.conversation.finalReplyLimit" },
+  { message: "Conversation updates exceed the configured history budget. Renew the context with a continuity briefing before continuing.",
+    messageCode: "assistant.conversation.historyBudgetExceeded" },
+  { message: "The continuity briefing exceeds the configured history budget.", messageCode: "assistant.conversation.briefingBudgetExceeded" },
+  { message: "Assistant provider is not configured.", messageCode: "assistant.provider.notConfigured" },
+  { message: "The previous submission was interrupted. Check delivery before submitting it again.",
+    messageCode: "assistant.conversation.submissionInterrupted" },
+  { message: "The application restarted before this answer completed. The request was not replayed.",
+    messageCode: "assistant.conversation.restartInterrupted" },
+  { message: "Copied into a stopped development environment. This request was not replayed.",
+    messageCode: "assistant.conversation.copiedInterrupted" },
+  { message: "The application operation result could not be saved. Restore storage access and retry saving.",
+    messageCode: "assistant.conversation.operationResultUnsaved" },
+  { message: "Conversation progress could not be saved. Restore access to its storage before continuing.",
+    messageCode: "assistant.conversation.progressUnsaved" },
+  { message: "The conversation request exceeded its time limit.", messageCode: "assistant.conversation.requestTimedOut" },
+  { message: "Work stopped.", messageCode: "assistant.conversation.workStopped" },
+  { message: "Stopped by user.", messageCode: "assistant.conversation.stoppedByUser" }
+]);
+
+function stateErrorFields(error) {
+  const known = STATE_ERROR_MESSAGES.find(entry => entry.message === error);
+  return known ? { errorMessageCode: known.messageCode, errorMessageParams: {} } : {};
+}
+
+export { deliveryFailure, failure, stateErrorFields };

package/src/server/conversation/conversationReplacement.js

@@ -0,0 +1,254 @@
+import { isDeepStrictEqual } from "node:util";
+import { randomUUID } from "node:crypto";
+import { normalizeConversationConfiguration } from "./configuration.js";
+import { hasUnfinishedConversationRewind, createConversationRuntimeReplacement,
+  releaseConversationRuntimeBinding, finishConversationRuntimeReplacement,
+  conversationNativeIdentity } from "./runtimeStateUpgrade.js";
+import { createConversationChangeover, conversationContinuity, conversationHistoryVersions } from "./continuity.js";
+import { failure } from "./conversationRefusals.js";
+import { pendingSuccessor, retainedSegments } from "./conversationReads.js";
+
+/** @typedef {import("./conversationEntries.js").ConversationEntry} ConversationEntry */
+
+/**
+ * Replacing an open conversation's native conversation: a renewal, an engine or model change,
+ * or a selection, with its continuity briefing and the predecessor it retains.
+ * @param {object} dependencies
+ * @param {import("../types.js").ReentrantConversationStorage | null} dependencies.storage
+ * @param {import("./provider.js").ConversationProviderFactory} dependencies.providers
+ * @param {import("./conversationEvents.js").ConversationEvents} dependencies.events
+ * @param {import("./conversationEntries.js").ConversationEntries} dependencies.entries
+ * @param {import("./conversationReads.js").ConversationReads} dependencies.reads
+ * @param {import("./conversationDelivery.js").ConversationDelivery} dependencies.delivery
+ * @param {boolean} dependencies.completedEnvelope
+ * @param {string | undefined} dependencies.defaultIntegrationId
+ * @param {number} dependencies.maximumContinuity
+ */
+function createConversationReplacement({ storage, providers, events, entries, reads, delivery, completedEnvelope, defaultIntegrationId,
+  maximumContinuity }) {
+  /**
+   * @param {ConversationEntry} entry
+   * @param {object} context
+   * @param {object} input
+   * @param {boolean} selection Whether this selects an engine or model instead of replacing the native conversation.
+   * @param {string} representation
+   */
+  async function replace(entry, context, input, selection, representation) {
+    const operation = selection ? "select" : "replace";
+    if (completedEnvelope && input?.engine === "api") throw failure("Completed envelopes require a native engine.", "conversation_completed_envelopes_need_native_engine", 400, { messageCode: "assistant.conversation.completedEnvelopesNeedNativeEngine" });
+    await events.access(context, entry.id, operation, entry);
+    if (entry.conversation?.commands) {
+      if (!selection) throw failure("This conversation retains its original replacement policy.", "conversation_replacement_policy_retained", 400, { messageCode: "assistant.conversation.replacementPolicyRetained" });
+      return entry.conversation.commands.select(input, context);
+    }
+    if (entry.conversation?.native?.scoped) throw failure("This scoped conversation retains its original selected profile.", "conversation_selected_profile_retained", 409, { messageCode: "assistant.conversation.selectedProfileRetained" });
+    const keys = selection ? ["operationId", "expectedSegmentId", "engine", "configuration", "retireNative"]
+      : ["operationId", "expectedSegmentId", "reason", "engine", "configuration", "briefing"];
+    if (!input || !/^[\w-]{1,128}$/u.test(input.operationId || "") || typeof input.expectedSegmentId !== "string" ||
+        !input.expectedSegmentId || (selection ? typeof input.engine !== "string" : !["engine-change", "model-change", "renewal"].includes(input.reason)) ||
+        input.briefing !== undefined && typeof input.briefing !== "string" ||
+        input.retireNative !== undefined && typeof input.retireNative !== "boolean" ||
+        Object.keys(input).some(key => !keys.includes(key))) {
+      throw failure("Replacement needs an operationId, exact predecessor segment, and an engine-change, model-change or renewal reason.", "conversation_replacement_request_invalid", 400, { messageCode: "assistant.conversation.replacementRequestInvalid" });
+    }
+    if (entry.active) throw failure("Stop the current turn before replacing its native conversation.", "conversation_busy", 409, { messageCode: "assistant.conversation.stopBeforeReplace" });
+    if (entry.storageFailure) throw entry.storageFailure;
+    if (entry.conversation) {
+      const state = await entries.readState(entry);
+      const saved = await entry.conversation.state.read();
+      const retry = saved?.replacement?.operationId === input.operationId;
+      let nativeResult;
+      if (state.segmentId !== input.expectedSegmentId && !retry) throw failure("The native predecessor has changed. Read the conversation before replacing it.", "conversation_predecessor_changed", 409, { messageCode: "assistant.conversation.predecessorChanged" });
+      if (selection) {
+        if (!entry.conversation.selection?.write) throw failure("This host requires its authorized assistant selection operation.", "conversation_host_selection_required", 409, { messageCode: "assistant.conversation.hostSelectionRequired" });
+        await entry.conversation.selection.write(input, context);
+      } else {
+        if (!input.briefing?.trim()) throw failure("Native replacement requires a continuity briefing.", "conversation_replacement_briefing_required", 400, { messageCode: "assistant.conversation.replacementBriefingRequired" });
+        const replacement = createConversationChangeover({ state: entry.conversation.state,
+          identity: entry.conversation.identity, presentation: entry.conversation.presentation,
+          agent: { async closeSession() { await entry.provider.dispose({ changeover: true, forgetConversationBinding: true }); return { ok: true }; } } });
+        nativeResult = await replacement.replace({ engineId: entry.engine, messages: await entry.conversation.transcript.history(),
+          operationId: input.operationId, expectedId: input.expectedSegmentId.startsWith(`${entry.engine}:`)
+            ? input.expectedSegmentId.slice(entry.engine.length + 1) : "", handover: input.briefing || "" });
+        if (retry && saved.replacement.status === "accepted") {
+          return representation === "native" ? nativeResult : { operationId: input.operationId, segmentId: entry.segmentId, duplicate: true };
+        }
+      }
+      await entries.rebindHostConversation(entry, context);
+      entry.goal = null;
+      const receipt = { operationId: input.operationId, segmentId: entry.segmentId, ...(retry ? { duplicate: true } : {}) };
+      await events.emit(entry, { type: "replaced", reason: input.reason || "model-change", engine: entry.engine, ...receipt });
+      return representation === "native" ? nativeResult : receipt;
+    }
+    const request = { ...structuredClone(input), operation };
+    // Receipt identity must survive JSON storage without picking up a later
+    // runtime's connection default when the same operation is retried.
+    if (request.engine === undefined) delete request.engine;
+    if (request.briefing === undefined) delete request.briefing;
+    if (request.configuration === undefined) delete request.configuration;
+    else if (request.configuration) request.configuration = normalizeConversationConfiguration(request.configuration);
+    let state = await entries.readState(entry);
+    if (hasUnfinishedConversationRewind(state)) {
+      throw failure("This conversation has an unfinished Undo operation from an earlier runtime. Inspect its saved native and local history offline before replacing it; no history was changed.", "conversation_rewind_inspection_before_replace", 409, { messageCode: "assistant.conversation.rewindInspectionBeforeReplace" });
+    }
+    const completed = state.predecessors.find(item => item.replacement?.operationId === input.operationId);
+    if (completed) {
+      if (!isDeepStrictEqual(completed.replacement, request)) throw failure("This replacement operationId already belongs to another request.", "conversation_replacement_operation_conflict", 409, { messageCode: "assistant.conversation.replacementOperationConflict" });
+      return { operationId: input.operationId, segmentId: completed.successorId, duplicate: true };
+    }
+    let pending = state.replacement;
+    if (pending && !isDeepStrictEqual(pending.request, request)) throw failure("Retry the unfinished native replacement before starting another one.", "conversation_replacement_unfinished", 409, { messageCode: "assistant.conversation.replacementUnfinished" });
+    if (state.segmentId !== input.expectedSegmentId) throw failure("The native predecessor has changed. Read the conversation before replacing it.", "conversation_predecessor_changed", 409, { messageCode: "assistant.conversation.predecessorChanged" });
+    if (!selection && retainedSegments(state).some(segment => segment.request)) throw failure("Resolve pending delivery before replacing native history. Another engine may be selected while its receipt stays pending.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.pendingDeliveryBeforeReplace" });
+    if (!selection && !pending && pendingSuccessor(state)) throw failure("Deliver the previous replacement's briefing before replacing native history again.", "conversation_briefing_before_replacement", 409, { messageCode: "assistant.conversation.briefingBeforeReplacement" });
+    if (entry.executionFailure && !pending) throw entry.executionFailure;
+    const engine = pending?.engine || input.engine || state.engine;
+    const configuration = pending?.configuration || (input.configuration
+      ? normalizeConversationConfiguration(input.configuration, { engine, defaultIntegrationId }) : state.configuration);
+    const driver = providers.createDriver(engine, entry.host);
+    driver.validateConfiguration(configuration);
+    const predecessorId = conversationNativeIdentity(state);
+    const nativeReplacement = !selection && state.engine !== "api" && predecessorId &&
+      (state.engine !== "claude" || state.binding.sent);
+    const retainNativeBinding = input.retireNative !== true && engine === state.engine &&
+      (engine !== "opencode" || configuration.integrationId === state.configuration.integrationId);
+    if (selection && engine !== "api" && retainNativeBinding && !pending) {
+      // The production native owners apply compatible settings to the running
+      // conversation themselves. Selecting a model is not process retirement.
+      await storage.write(entry.id, async transaction => {
+        const metadata = await transaction.readMetadata();
+        const current = metadata.runtime;
+        current.predecessors.push({ segmentId: current.segmentId, engine: current.engine,
+          configuration: current.configuration, binding: current.binding, seen: current.seen,
+          request: current.request, successorId: current.segmentId, replacement: request });
+        current.configuration = structuredClone(configuration);
+        await transaction.writeMetadata(metadata);
+      });
+      const receipt = { operationId: input.operationId, segmentId: state.segmentId };
+      await events.emit(entry, { type: "replaced", reason: "model-change", engine, ...receipt });
+      return receipt;
+    }
+    if (!pending) {
+      const history = (await reads.readTranscript(entry)).filter(turn => !turn.metadata?.runtime?.supersededBy);
+      let destination = null;
+      if (selection) {
+        if (retainNativeBinding) destination = state;
+        else if (input.retireNative !== true && engine !== state.engine && driver.createBinding) {
+          destination = retainedSegments(state).findLast(segment => segment.engine === engine &&
+            (engine !== "opencode" || segment.configuration.integrationId === configuration.integrationId));
+        }
+      }
+      if (engine !== "api" && (input.briefing || "").length > maximumContinuity) throw new Error("The continuity briefing exceeds the configured history budget.");
+      const continuity = destination ? { text: destination.continuity, attachments: destination.continuityAttachments || [] }
+        : engine === "api" ? conversationContinuity({ history, briefing: input.briefing, maximumCharacters: maximumContinuity })
+          : { text: undefined, attachments: [] };
+      pending = createConversationRuntimeReplacement({ request, engine, configuration: structuredClone(configuration),
+        reason: selection ? state.engine === engine ? "model-change" : "engine-change" : input.reason,
+        segmentId: destination?.segmentId || randomUUID(), continuity,
+        seen: destination ? destination.seen : engine === "api" ? conversationHistoryVersions(history) : {}, destination });
+    }
+
+    function saveReplacement() {
+      return storage.write(entry.id, async transaction => {
+        const metadata = await transaction.readMetadata();
+        if (metadata.runtime.segmentId !== input.expectedSegmentId || metadata.runtime.replacement &&
+            !isDeepStrictEqual(metadata.runtime.replacement.request, request)) {
+          throw failure("The saved replacement changed before it could be written.", "conversation_replacement_changed_before_write", 409, { messageCode: "assistant.conversation.replacementChangedBeforeWrite" });
+        }
+        metadata.runtime.replacement = pending;
+        await transaction.writeMetadata(metadata);
+      });
+    }
+
+    async function closeSession() {
+      try { await entry.provider.dispose(); }
+      catch (error) { entry.executionFailure = error; entry.error = error.message; throw error; }
+      return { ok: true };
+    }
+
+    let provider;
+    const bindingOwner = {};
+    async function replacementTransaction(callback) {
+      // These common storage/host facilities allocate an inert successor handle.
+      // Native process/thread creation stays in ordinary Send, after this commit.
+      await events.access(context, entry.id, operation, entry);
+      if (pending.segmentId === state.segmentId) {
+        pending.binding = (await entries.readState(entry)).binding || null;
+      }
+      if (!Object.hasOwn(pending, "binding")) {
+        pending.binding = driver.createBinding ? await driver.createBinding() : null;
+        await saveReplacement();
+      }
+      provider = await entries.openProvider(entry, driver, pending.binding, pending.segmentId, bindingOwner);
+      try {
+        await events.access(context, entry.id, operation, entry);
+        await storage.write(entry.id, async transaction => {
+          const metadata = await transaction.readMetadata();
+          state = metadata.runtime;
+          if (state.segmentId !== input.expectedSegmentId || !isDeepStrictEqual(state.replacement?.request, request)) {
+            throw failure("The saved replacement changed before its binding was released.", "conversation_replacement_changed_before_release", 409, { messageCode: "assistant.conversation.replacementChangedBeforeRelease" });
+          }
+          await callback({
+            async releaseBinding(replacement) {
+              if (replacement && conversationNativeIdentity(state) !== replacement.previous.conversationId) {
+                throw failure("The native predecessor identity changed before its binding was released.", "conversation_predecessor_changed_before_release", 409, { messageCode: "assistant.conversation.predecessorChangedBeforeRelease" });
+              }
+              releaseConversationRuntimeBinding(state, pending, request, engine);
+            },
+            async write(value) {
+              finishConversationRuntimeReplacement(state, { engine, selection, retireNative: input.retireNative, pending, value });
+              await transaction.writeMetadata(metadata);
+            }
+          });
+        });
+      } catch (error) { await provider.dispose(); throw error; }
+    }
+
+    if (nativeReplacement) {
+      const replacement = createConversationChangeover({
+        state: {
+          read: delivery.changeoverState(entry).read,
+          async write(value) {
+            pending.preparedAt = value.replacement.preparedAt;
+            await saveReplacement();
+          },
+          transaction: replacementTransaction
+        },
+        identity: {
+          async inspect(expectedId) {
+            const { runtime } = await storage.read(entry.id, transaction => transaction.readMetadata());
+            if (runtime.segmentId !== input.expectedSegmentId || conversationNativeIdentity(runtime) !== expectedId) {
+              throw failure("The native predecessor identity changed or is incomplete.", "conversation_predecessor_incomplete", 409, { messageCode: "assistant.conversation.predecessorIncomplete" });
+            }
+            return { bindingNames: ["binding"], previous: { engineId: runtime.engine, conversationId: expectedId } };
+          }
+        },
+        agent: { closeSession }
+      });
+      await replacement.replace({ engineId: engine, messages: [], operationId: input.operationId,
+        expectedId: predecessorId, handover: input.briefing || "" });
+    } else {
+      // API conversations, retained-engine selection and unstarted native handles
+      // have no native predecessor replacement. Keep their common facilities.
+      if (!state.replacement) await saveReplacement();
+      await closeSession();
+      await replacementTransaction(async transaction => {
+        await transaction.releaseBinding();
+        await transaction.write();
+      });
+    }
+    entries.adoptBinding(entry, { engine, driver, provider, bindingOwner, segmentId: pending.segmentId });
+    Object.assign(entry, { goal: null, executionFailure: null, error: pending.submission?.error || "" });
+    const receipt = { operationId: input.operationId, segmentId: pending.segmentId };
+    await events.emit(entry, { type: "replaced", reason: pending.reason, engine, ...receipt });
+    return receipt;
+  }
+
+  return Object.freeze({
+    replace
+  });
+}
+
+/** @typedef {ReturnType<typeof createConversationReplacement>} ConversationReplacement */
+
+export { createConversationReplacement };

package/src/server/conversation/conversationSending.js

@@ -0,0 +1,273 @@
+import { isDeepStrictEqual } from "node:util";
+import { createConversationDeliveryTiming, recordNoDeliveryTiming } from "./deliveryTiming.js";
+import { codexAppServerTurnStateFromAgentRun } from "./codexTurn.js";
+import { conversationAttachmentIds } from "./attachments.js";
+import { failure } from "./conversationRefusals.js";
+import { retainedSegments, submittedMessage } from "./conversationReads.js";
+import { serial } from "./conversationEvents.js";
+
+/** @typedef {import("./conversationEntries.js").ConversationEntry} ConversationEntry */
+
+/**
+ * One message an open conversation sends: its validated input, who sent it and how, and its
+ * admission as the turn delivers it. admitSend creates it.
+ * @typedef {object} ConversationRequest
+ * @property {{ messageId: string, text: string, origin: string, attachments: object[], data?: object, goal?: object }} input
+ * @property {any} [originalInput] A native caller's own input, kept for the native representation.
+ * @property {string} operation The operation it is authorized as: send, steer, wake or goal.
+ * @property {object} context
+ * @property {string} at
+ * @property {(stage: string) => void} deliveryTiming
+ * @property {boolean} [completedEnvelope]
+ * @property {string[]} [excludedMessageIds]
+ * @property {boolean} [nativeToolAttempt]
+ * @property {boolean} steering Whether it steers a running native turn.
+ * @property {PromiseWithResolvers<any>} admission Resolves with its receipt once the turn admits it.
+ * @property {Map<string, object>} progress Its completed commentary and thinking, by message id.
+ * @property {ReturnType<typeof import("./tools.js").createConversationTools>} [tools]
+ * @property {string} [turnId]
+ * @property {string} [nativeTurnId]
+ * @property {string} [nativeThreadId]
+ * @property {string} [goalMessageId]
+ * @property {string} [continuedBy] The message whose admission sealed it.
+ * @property {object | null} [answer]
+ * @property {boolean} [accepted]
+ * @property {boolean} [admissionSettled]
+ * @property {boolean} [admissionPublished]
+ * @property {boolean} [sealed] Its output is final; late native snapshots no longer change it.
+ * @property {boolean} [finished]
+ * @property {Promise<void>} [deliveryCommitted]
+ * @property {object} [recovered] The saved state of a turn a duplicate delivery recovered.
+ */
+
+/** Whether a saved request and a new message carry the same content. */
+const sameRequest = (left, right) => left.text === right.text && (left.origin || "user") === right.origin &&
+  isDeepStrictEqual(left.goal, right.goal) && isDeepStrictEqual(left.data, right.data) &&
+  isDeepStrictEqual((left.attachments || []).map(file => file.attachmentId), right.attachments.map(file => file.attachmentId));
+
+/**
+ * Sending a message: its validation, its admission into the conversation queue, and the
+ * turn it starts or the running turn it steers.
+ * @param {object} dependencies
+ * @param {import("../types.js").ReentrantConversationStorage | null} dependencies.storage
+ * @param {import("./conversationEvents.js").ConversationEvents} dependencies.events
+ * @param {import("./conversationEntries.js").ConversationEntries} dependencies.entries
+ * @param {import("./conversationReads.js").ConversationReads} dependencies.reads
+ * @param {import("./conversationTurns.js").ConversationTurns} dependencies.turns
+ * @param {import("../types.js").ConversationDeliveryTimingObserver | undefined} dependencies.onDeliveryTiming
+ * @param {readonly string[]} dependencies.deliveryHostStages
+ * @param {boolean} dependencies.completedEnvelope
+ * @param {number} dependencies.maximumInput
+ */
+function createConversationSending({ storage, events, entries, reads, turns, onDeliveryTiming, deliveryHostStages, completedEnvelope, maximumInput }) {
+  /**
+   * @param {ConversationEntry} entry
+   * @param {object} context
+   * @param {object} input
+   * @param {string} [origin]
+   * @param {object} [goal]
+   * @param {string} [representation]
+   * @param {object} [wakeOptions]
+   */
+  async function send(entry, context, input, origin = "user", goal, representation, wakeOptions) {
+    const deliveryTiming = createConversationDeliveryTiming({ engine: entry.engine,
+      conversationId: entry.id, messageId: input?.messageId, report: onDeliveryTiming, hostStages: deliveryHostStages });
+    deliveryTiming("received");
+    const grant = new Set();
+    try {
+      await events.access(context, entry.id, goal ? "goal" : input?.steer === true ? "steer" : origin === "application" ? "wake" : "send", entry, grant);
+      if (entry.conversation?.commands) {
+        if (origin !== "user" || goal) throw failure("This conversation supports its original application Send operation.", "conversation_original_send_only", 400, { messageCode: "assistant.conversation.originalSendOnly" });
+        return entry.conversation.commands.send(input, context);
+      }
+      if (entry.conversation?.native?.scoped) return entry.provider.sendNative({ input, context });
+      const originalInput = representation === "native" ? input : undefined;
+      const message = originalInput ? { ...input, text: input.displayMessage ?? input.message ?? input.text ?? "" } : input;
+      const admission = await serial(entry, () => admitSend(entry, context, message, origin, goal, originalInput, wakeOptions, deliveryTiming, grant));
+      const result = await (admission.receipt || admission.promise);
+      if (!entry.conversation) return result;
+      if (representation === "native") return result.nativeResult;
+      if (result.error) throw result.error;
+      return result.receipt;
+    } catch (error) {
+      deliveryTiming("failed");
+      throw error;
+    }
+  }
+
+  /**
+   * Called while holding the conversation queue, including Claude's stop-then-Send goal commands.
+   * Every command keeps the ordinary receipt path.
+   * @param {ConversationEntry} entry
+   * @param {object} context
+   * @param {object} input
+   * @param {string} [origin]
+   * @param {object} [goal]
+   * @param {object} [originalInput]
+   * @param {object} [wakeOptions]
+   * @param {(stage: string) => void} [deliveryTiming]
+   * @param {Set<string>} [grant]
+   */
+  async function admitSend(entry, context, input, origin = "user", goal, originalInput, wakeOptions, deliveryTiming = recordNoDeliveryTiming, grant) {
+    deliveryTiming("preparation-started");
+    const operation = goal ? "goal" : input?.steer === true ? "steer" : origin === "application" ? "wake" : "send";
+    await events.access(context, entry.id, operation, entry, grant);
+    if (entry.cancelledMessages.has(input?.messageId)) {
+      throw Object.assign(failure("This message was cancelled. Send it again as a new message.", "conversation_message_cancelled", 409,
+        { messageCode: "assistant.conversation.messageCancelled" }), { delivery: "not-sent" });
+    }
+    await entry.conversation?.admission(context, operation);
+    deliveryTiming("authorized");
+    if (goal) context?.signal?.throwIfAborted();
+    let suppliedExclusions;
+    if (wakeOptions !== undefined) {
+      if (!completedEnvelope || entry.conversation || origin !== "application" || goal ||
+          !wakeOptions || typeof wakeOptions !== "object" || Array.isArray(wakeOptions) ||
+          Object.keys(wakeOptions).some(name => name !== "excludedMessageIds") ||
+          !Array.isArray(wakeOptions.excludedMessageIds) ||
+          wakeOptions.excludedMessageIds.some(id => typeof id !== "string" || !id.trim() || id.length > 128) ||
+          new Set(wakeOptions.excludedMessageIds).size !== wakeOptions.excludedMessageIds.length) {
+        throw failure("Native history exclusions require a server-owned completed application wake and exact message IDs.", "conversation_invalid_message", 400, { messageCode: "assistant.conversation.historyExclusionsInvalid" });
+      }
+      suppliedExclusions = [...wakeOptions.excludedMessageIds];
+    }
+    const attachmentIds = conversationAttachmentIds(input?.attachmentIds);
+    if (!input || typeof input.messageId !== "string" || !input.messageId.trim() || input.messageId.length > 128 ||
+        entry.engine !== "api" && !/^[\w-]{1,128}$/u.test(input.messageId) ||
+        typeof input.text !== "string" || !input.text.trim() && !attachmentIds.length || input.text.length > maximumInput) {
+      throw failure("Bounded text or attachment IDs and a stable messageId are required.", "conversation_invalid_message", 400, { messageCode: "assistant.conversation.messageContentRequired" });
+    }
+    if (!originalInput && input.attachments?.length) throw failure("Supply attachmentIds; only the application's resolver can supply file content.", "conversation_attachment_ids_only", 400, { messageCode: "assistant.conversation.attachmentIdsOnly" });
+    if (attachmentIds.length && !reads.capabilities(entry).attachments) throw failure("File attachments are not configured for this conversation.", "conversation_attachments_not_configured", 400, { messageCode: "assistant.conversation.attachmentsNotConfigured" });
+    if (input.steer !== undefined && typeof input.steer !== "boolean") throw failure("steer must be a boolean.", "conversation_invalid_message", 400, { messageCode: "assistant.conversation.steerNotBoolean" });
+    if (input.steer && !entry.driver.capabilities.steering) throw failure("This connection does not support steering.", "conversation_steering_unsupported", 400, { messageCode: "assistant.conversation.steeringUnsupported" });
+    let data;
+    if (input.data !== undefined) {
+      try {
+        if (!input.data || typeof input.data !== "object" || Array.isArray(input.data)) throw new TypeError();
+        const encoded = JSON.stringify(input.data);
+        if (input.text.length + encoded.length > maximumInput) throw new TypeError();
+        data = JSON.parse(encoded);
+        if (!data || typeof data !== "object" || Array.isArray(data)) throw new TypeError();
+      } catch {
+        throw failure("Application data must be a JSON object within the conversation input limit.", "conversation_invalid_message", 400, { messageCode: "assistant.conversation.applicationDataInvalid" });
+      }
+    }
+    const message = { messageId: input.messageId, text: input.text.trim(), origin,
+      attachments: attachmentIds.map(attachmentId => ({ attachmentId })), ...(data !== undefined ? { data } : {}), ...(goal ? { goal } : {}) };
+    if (entry.storageFailure) throw entry.storageFailure;
+    if (entry.executionFailure) throw entry.executionFailure;
+    if (goal && goal.expectedSegmentId !== entry.segmentId) throw failure("The conversation changed before this goal command was sent.", "conversation_goal_changed", 409, { messageCode: "assistant.conversation.goalConversationChanged" });
+    const pending = entry.active?.requests.get(message.messageId);
+    if (pending && entry.engine !== "api" && !pending.admissionSettled) {
+      if (suppliedExclusions && !isDeepStrictEqual(pending.excludedMessageIds || [], suppliedExclusions)) throw failure("This messageId already belongs to different native history exclusions.", "conversation_message_id_exclusions_conflict", 409, { messageCode: "assistant.conversation.messageIdExclusionsConflict" });
+      if (!entry.conversation && !sameRequest(pending.input, message)) throw failure("This messageId already belongs to different content.", "conversation_message_id_content_conflict", 409, { messageCode: "assistant.conversation.messageIdContentConflict" });
+      return { promise: pending.admission.promise };
+    }
+    const existing = await reads.findSubmittedTurn(entry, message.messageId);
+    deliveryTiming("history-read");
+    const nativeState = entry.engine !== "api" && (await entries.readState(entry));
+    deliveryTiming("state-read");
+    const nativePending = nativeState?.request;
+    if (existing) {
+      const previous = submittedMessage(existing);
+      if (!entry.conversation && !sameRequest(previous, message)) {
+        throw failure("This messageId already belongs to different content.", "conversation_message_id_content_conflict", 409, { messageCode: "assistant.conversation.messageIdContentConflict" });
+      }
+      if (!entry.conversation && !nativePending) return { receipt: { status: "accepted", messageId: message.messageId, turnId: existing.turnId, origin, duplicate: true } };
+    }
+    if (pending && !entry.conversation) {
+      if (!sameRequest(pending.input, message)) throw failure("This messageId already belongs to different content.", "conversation_message_id_content_conflict", 409, { messageCode: "assistant.conversation.messageIdContentConflict" });
+      if (suppliedExclusions && !isDeepStrictEqual(pending.excludedMessageIds || [], suppliedExclusions)) throw failure("This messageId already belongs to different native history exclusions.", "conversation_message_id_exclusions_conflict", 409, { messageCode: "assistant.conversation.messageIdExclusionsConflict" });
+      return { promise: pending.admission.promise };
+    }
+    const working = entry.active;
+    if (entry.conversation && ["codex", "opencode", "claude"].includes(entry.engine) && ["send", "goal"].includes(operation) && working?.finishing) {
+      // No native dispatch has occurred for this request. Finish the previous
+      // waiter before reserving the same authored message or goal request.
+      await working.done;
+      return admitSend(entry, context, input, origin, goal, originalInput, wakeOptions, deliveryTiming, grant);
+    }
+    const nativeSteering = !working && (nativeState.nativeTurn?.active || entry.driver.canonicalTranscript && nativeState.binding?.codexAppServerRun &&
+      codexAppServerTurnStateFromAgentRun(nativeState.binding.codexAppServerRun).active);
+    if (completedEnvelope && entry.engine === "claude" &&
+        (working?.request.completedEnvelope || nativePending?.completedEnvelope === true || origin === "application" && !goal) &&
+        (working || input.steer || nativeSteering)) {
+      throw failure("Completed Claude responses cannot share a native steering turn. Wait for the response or stop it.", "conversation_not_steerable", 409, { messageCode: "assistant.conversation.completedClaudeNotSteerable" });
+    }
+    if (working && !input.steer && !goal && !entry.conversation) throw failure("Wait for this answer or use steer to send another instruction.", "conversation_busy", 409, { messageCode: "assistant.conversation.waitForAnswer" });
+    if (input.steer && (!working && !nativeSteering || working?.finishing) && !(nativePending?.attempted || nativePending?.inspectionOnly)) {
+      const previousState = nativeState?.nativeTurn?.runState || nativeState?.nativeTurn?.state ||
+        (await reads.lastTranscriptTurn(entry))?.metadata?.runtime?.status;
+      const completed = working ? !working.controller.signal.aborted && !working.timedOut : ["complete", "completed"].includes(previousState);
+      throw Object.assign(failure("There is no active native turn to steer. Send a new message.",
+        completed ? "conversation_steer_turn_finished" : "conversation_not_steerable", 409, { messageCode: "assistant.conversation.noActiveTurnToSteer" }), { delivery: "not-sent" });
+    }
+    if (goal && working?.finishing) throw failure("Wait for the current turn to finish saving before starting the goal.", "conversation_busy", 409, { messageCode: "assistant.conversation.waitForTurnSaving" });
+    if (working && (!working.request.admissionSettled || working.steering)) throw failure("Wait for the pending instruction to be admitted before steering again.", "conversation_busy", 409, { messageCode: "assistant.conversation.waitForInstructionAdmission" });
+    const barrier = working ? Promise.withResolvers() : null;
+    if (barrier) working.steering = barrier.promise;
+    const release = () => {
+      barrier?.resolve();
+      if (working && working.steering === barrier?.promise) working.steering = null;
+    };
+    let configuration;
+    let markedResponse = false;
+    let nativeToolAttempt;
+    let excludedMessageIds;
+    let requestAt = new Date().toISOString();
+    // The bound state was read above unless this is an API conversation.
+    try { configuration = entry.conversation ? (nativeState || await entries.readState(entry)).configuration : await storage.write(entry.id, async transaction => {
+      const metadata = await transaction.readMetadata();
+      if (metadata.runtime.replacement) throw failure("Finish the pending native replacement before sending another message.", "conversation_replacement_pending_before_send", 409, { messageCode: "assistant.conversation.replacementPendingBeforeSend" });
+      if (retainedSegments(metadata.runtime).some(segment => segment.segmentId !== entry.segmentId && segment.request?.messageId === message.messageId)) {
+        throw failure("This message has uncertain delivery in a retained conversation. Select that engine and check its receipt before submitting it again.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.retainedDeliveryUncertain" });
+      }
+      if (metadata.runtime.request) {
+        if (suppliedExclusions && metadata.runtime.request.messageId !== message.messageId) {
+          throw failure("Check delivery of the previous instruction before preparing another completed response.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.previousInstructionUnchecked" });
+        }
+        if (entry.engine === "api") throw failure("The previous submission has uncertain delivery. It will not be resent automatically.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.previousSubmissionUncertain" });
+        if (metadata.runtime.request.messageId === message.messageId) {
+          if (!sameRequest(metadata.runtime.request, message)) throw failure("This messageId already belongs to different content.", "conversation_message_id_content_conflict", 409, { messageCode: "assistant.conversation.messageIdContentConflict" });
+          if (suppliedExclusions && !isDeepStrictEqual(metadata.runtime.request.excludedMessageIds || [], suppliedExclusions)) {
+            throw failure("This messageId already belongs to different native history exclusions.", "conversation_message_id_exclusions_conflict", 409, { messageCode: "assistant.conversation.messageIdExclusionsConflict" });
+          }
+          requestAt = metadata.runtime.request.at;
+        }
+      } else metadata.runtime.request = { ...message, at: requestAt,
+        ...(completedEnvelope && origin === "application" && !goal ? { completedEnvelope: true, excludedMessageIds: suppliedExclusions || [],
+          ...(entry.engine === "claude" ? { nativeToolAttempt: false } : {}) } : {}),
+        ...(entry.engine !== "api" ? { attempted: false } : {}), ...(input.steer ? { steering: true } : {}) };
+      markedResponse = origin === "application" && !goal && metadata.runtime.request?.messageId === message.messageId &&
+        metadata.runtime.request.completedEnvelope === true;
+      if (markedResponse) excludedMessageIds = structuredClone(metadata.runtime.request.excludedMessageIds || []);
+      if (entry.engine === "claude" && markedResponse && typeof metadata.runtime.request.nativeToolAttempt === "boolean") nativeToolAttempt = metadata.runtime.request.nativeToolAttempt;
+      await transaction.writeMetadata(metadata);
+      return metadata.runtime.configuration;
+    }); } catch (error) { release(); throw error; }
+    deliveryTiming("request-saved");
+    /** @type {ConversationRequest} */
+    const request = { input: message, originalInput, operation, context, at: requestAt, deliveryTiming,
+      ...(markedResponse ? { completedEnvelope: true, excludedMessageIds } : {}),
+      ...(typeof nativeToolAttempt === "boolean" ? { nativeToolAttempt } : {}), steering: Boolean(working || input.steer && nativeSteering),
+      admission: Promise.withResolvers(), progress: new Map() };
+    request.admission.promise.catch(() => {});
+    if (working) {
+      working.requests.set(message.messageId, request);
+      working.submit(request).catch(error => request.admission.reject(error)).finally(release);
+      return { promise: request.admission.promise };
+    }
+    turns.start(entry, request, configuration);
+    return { promise: request.admission.promise };
+  }
+
+  return Object.freeze({
+    send,
+    admitSend
+  });
+}
+
+/** @typedef {ReturnType<typeof createConversationSending>} ConversationSending */
+
+export { createConversationSending };