@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/server/conversation/conversationGoals.js

@@ -0,0 +1,187 @@
+import { isDeepStrictEqual } from "node:util";
+import { conversationAttachmentIds } from "./attachments.js";
+import { failure } from "./conversationRefusals.js";
+import { pendingSuccessor, submittedMessage } from "./conversationReads.js";
+import { serial } from "./conversationEvents.js";
+
+/** @typedef {import("./conversationEntries.js").ConversationEntry} ConversationEntry */
+
+/**
+ * Reading and changing an open conversation's native goal.
+ * @param {object} dependencies
+ * @param {import("./conversationEvents.js").ConversationEvents} dependencies.events
+ * @param {import("./conversationEntries.js").ConversationEntries} dependencies.entries
+ * @param {import("./conversationReads.js").ConversationReads} dependencies.reads
+ * @param {import("./conversationSending.js").ConversationSending} dependencies.sending
+ * @param {import("./conversationStopping.js").ConversationStopping} dependencies.stopping
+ * @param {import("../types.js").ServiceToolCatalog | null} dependencies.catalog
+ */
+function createConversationGoals({ events, entries, reads, sending, stopping, catalog }) {
+  /**
+   * @param {ConversationEntry} entry
+   * @param {object} context
+   * @param {string} representation
+   */
+  async function readGoal(entry, context, representation) {
+    await events.access(context, entry.id, "readGoal", entry);
+    if (!reads.capabilities(entry).goals) return null;
+    const configuration = representation === "native" ? undefined : (await entries.readState(entry)).configuration;
+    const result = await entry.provider.readGoal({ context, configuration });
+    if (entry.conversation && representation !== "native" && result.nativeResult.status === "unavailable") {
+      throw failure("The native goal is unavailable. Try reading its status again.", "conversation_goal_unavailable", 503);
+    }
+    entry.goal = entry.conversation ? result.goal : result;
+    return representation === "native" ? result.nativeResult : structuredClone(entry.goal);
+  }
+
+  /**
+   * @param {ConversationEntry} entry
+   * @param {object} context
+   * @param {object} input
+   * @param {string} representation
+   * @param {boolean} [retryFinishedTurn] Whether a goal that Claude's completion refused may be admitted once more.
+   */
+  async function updateGoal(entry, context, input, representation, retryFinishedTurn = true) {
+    await events.access(context, entry.id, "goal", entry);
+    context?.signal?.throwIfAborted();
+    if (!reads.capabilities(entry).goals) throw failure("This connection does not support native goals.", "conversation_goals_unsupported", 400, { messageCode: "assistant.conversation.goalsUnsupported" });
+    if (representation === "native") {
+      const { operation } = await serial(entry, async () => {
+        await events.access(context, entry.id, "goal", entry);
+        // The original goal owner has its own admission. Its native message
+        // acknowledgement must not hold the common queue ahead of Stop.
+        return { operation: entry.provider.updateGoal({ context, input, representation }) };
+      });
+      const result = await operation;
+      if (result.nativeResult.ok !== false) {
+        entry.goal = result.goal;
+        await events.emit(entry, { type: "goal", goal: entry.goal });
+      }
+      return result.nativeResult;
+    }
+    if (!input || !["set", "resume", "pause", "cancel"].includes(input.action) ||
+        (typeof input.expectedSegmentId !== "string" && !(entry.conversation && input.expectedSegmentId === null)) ||
+        input.expectedGoalId != null && (typeof input.expectedGoalId !== "string" || !input.expectedGoalId)) {
+      throw failure("A goal action and current conversation segment are required.", "conversation_invalid_goal", 400, { messageCode: "assistant.conversation.goalActionRequired" });
+    }
+    const starting = input.action === "set" || input.action === "resume";
+    const goal = { action: input.action, expectedSegmentId: input.expectedSegmentId, expectedGoalId: input.expectedGoalId || null };
+    if (starting) {
+      if (input.action === "set") {
+        if (input.tokenBudget != null && !entry.driver.capabilities.goalBudgets) throw failure("This connection does not support goal token budgets.", "conversation_goal_token_budgets_unsupported", 400, { messageCode: "assistant.conversation.goalTokenBudgetsUnsupported" });
+        if (typeof input.objective !== "string" || !input.objective.trim() || input.objective.length > 4000 ||
+            input.tokenBudget != null && (!Number.isSafeInteger(input.tokenBudget) || input.tokenBudget < 1)) {
+          throw failure("A bounded objective and optional positive token budget are required.", "conversation_invalid_goal", 400, { messageCode: "assistant.conversation.goalObjectiveInvalid" });
+        }
+        goal.objective = input.objective.trim();
+        if (input.tokenBudget != null) goal.tokenBudget = input.tokenBudget;
+      } else if (!goal.expectedGoalId) throw failure("Select the goal to resume.", "conversation_invalid_goal", 400, { messageCode: "assistant.conversation.goalToResumeRequired" });
+    }
+    if (!starting && !input.expectedGoalId) throw failure("Select the goal to stop.", "conversation_invalid_goal", 400, { messageCode: "assistant.conversation.goalToStopRequired" });
+    const delivery = entry.driver.capabilities.goalCommands?.[input.action]?.delivery;
+    if (!["message", "control"].includes(delivery)) throw failure("This connection does not support that goal command.", "conversation_goal_command_unsupported", 400, { messageCode: "assistant.conversation.goalCommandUnsupported" });
+    const messageCommand = delivery === "message";
+    if (messageCommand && (typeof input.messageId !== "string" || !/^[\w-]{1,128}$/u.test(input.messageId))) {
+      throw failure("A stable messageId is required for this goal command.", "conversation_invalid_message", 400, { messageCode: "assistant.conversation.goalMessageIdRequired" });
+    }
+    if (conversationAttachmentIds(input.attachmentIds).length || input.attachments?.length) {
+      throw failure("This engine's native goal commands do not accept attachments.", "conversation_goal_attachments_unsupported", 400, { messageCode: "assistant.conversation.goalAttachmentsUnsupported" });
+    }
+    const result = await serial(entry, async () => {
+      await events.access(context, entry.id, "goal", entry);
+      if (entry.conversation) await entries.readState(entry);
+      if (entry.segmentId !== input.expectedSegmentId) throw failure("The conversation changed before this goal command was sent.", "conversation_goal_changed", 409, { messageCode: "assistant.conversation.goalConversationChanged" });
+      if (entry.conversation && input.expectedSegmentId === null && input.action !== "set") {
+        throw failure("This command requires an existing native conversation.", "conversation_goal_changed", 409, { messageCode: "assistant.conversation.goalNeedsNativeConversation" });
+      }
+      if (entry.storageFailure) throw entry.storageFailure;
+      if (entry.executionFailure) throw entry.executionFailure;
+      if (messageCommand) {
+        const history = await reads.readTranscript(entry);
+        const existing = history.find(turn => submittedMessage(turn)?.messageId === input.messageId);
+        if (existing) {
+          if (!entry.conversation && !isDeepStrictEqual(submittedMessage(existing).goal, goal)) throw failure("This messageId already belongs to different content.", "conversation_message_id_content_conflict", 409, { messageCode: "assistant.conversation.messageIdContentConflict" });
+          return { receipt: { status: "accepted", messageId: input.messageId, turnId: existing.turnId, origin: "user", duplicate: true } };
+        }
+      }
+      if (entry.active && !entry.active.request.accepted) throw failure("Wait for the goal command to be admitted.", "conversation_busy", 409, { messageCode: "assistant.conversation.waitForGoalCommand" });
+      const metadata = { runtime: await entries.readState(entry) };
+      if (metadata.runtime.request && (entry.engine === "api" || metadata.runtime.request.attempted || metadata.runtime.request.inspectionOnly)) {
+        throw failure("Check the uncertain command's delivery before changing the goal.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.goalCommandDeliveryUncertain" });
+      }
+      if (entry.driver.canonicalTranscript && metadata.runtime.binding?.goalRequest) {
+        throw failure("A goal command from an earlier runtime has unresolved delivery. Inspect its saved state before changing the goal.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.earlierGoalCommandUnresolved" });
+      }
+      if (starting && (metadata.runtime.replacement || !entry.conversation && pendingSuccessor(metadata.runtime) || metadata.runtime.lastEngine !== entry.engine)) {
+        throw failure("Send a message to catch this AI up before starting or resuming its goal.", "conversation_briefing_before_goal", 409, { messageCode: "assistant.conversation.briefingBeforeGoal" });
+      }
+      // Definitions keep native thread discovery stable. A control has no
+      // admitted request, application-tool actor or executor of its own.
+      const tools = catalog && entry.driver.toolDiscovery
+        ? { schemas: catalog.resolveToolSet(context, { discoveryOnly: true }).tools.map(catalog.toOpenAiToolSchema) } : undefined;
+      if (entry.conversation) {
+        let receipt;
+        // Preserve the original goal owner's acknowledgement wait outside the
+        // invocation queue so the same Stop command can still interrupt it.
+        const operation = entry.provider.updateGoal({ context, configuration: metadata.runtime.configuration,
+          input: { ...input, ...goal }, representation, tools, interrupt: () => stopping.stop(entry, context),
+          async send({ message }, { threadId }) {
+            const admission = await serial(entry, async () => {
+              const state = await entries.readState(entry);
+              const selectedSegment = `${entry.engine}:${threadId}`;
+              if (!threadId || state.segmentId !== selectedSegment ||
+                  input.expectedSegmentId !== null && input.expectedSegmentId !== selectedSegment) {
+                throw failure("The conversation changed before this goal command was sent.", "conversation_goal_changed", 409, { messageCode: "assistant.conversation.goalConversationChanged" });
+              }
+              return sending.admitSend(entry, context, { messageId: input.messageId, text: message }, "user",
+                { ...goal, expectedSegmentId: selectedSegment });
+            });
+            const accepted = await (admission.receipt || admission.promise);
+            if (accepted.error) throw accepted.error;
+            receipt = accepted.receipt;
+          }
+        }).then(async updated => {
+          if (updated.nativeResult.ok === false) throw Object.assign(new Error(updated.nativeResult.error), updated.nativeResult);
+          entry.goal = updated.goal;
+          await events.emit(entry, { type: "goal", goal: entry.goal });
+          return receipt ? { receipt } : { goal: structuredClone(entry.goal) };
+        });
+        return { operation };
+      }
+      let delivery;
+      const updated = await entry.provider.updateGoal({ context, configuration: metadata.runtime.configuration, input: { ...input, ...goal }, tools,
+        interrupt: () => stopping.stop(entry, context),
+        async send({ message }) {
+          delivery = await sending.admitSend(entry, context, { messageId: input.messageId, text: message }, "user", goal);
+        }
+      });
+      // Release the queue once Send is reserved, just as an ordinary message
+      // does. Stop remains available while native acknowledgement is pending.
+      if (delivery) return delivery;
+      entry.goal = updated;
+      await events.emit(entry, { type: "goal", goal: entry.goal });
+      return { goal: structuredClone(entry.goal) };
+    });
+    try {
+      const completed = result.operation ? await result.operation : result;
+      return await (completed.receipt || completed.promise || completed.goal);
+    } catch (error) {
+      if (!retryFinishedTurn || !entry.conversation || !starting || !messageCommand ||
+          error.code !== "conversation_steer_turn_finished" || error.delivery !== "not-sent") throw error;
+      // Completion can retire Claude's generation during asynchronous native
+      // preparation. Its exact pre-write rejection permits one re-admission of
+      // this same goal/message ID, after the original cleanup and save finish.
+      await entry.active?.done;
+      return updateGoal(entry, context, input, representation, false);
+    }
+  }
+
+  return Object.freeze({
+    readGoal,
+    updateGoal
+  });
+}
+
+/** @typedef {ReturnType<typeof createConversationGoals>} ConversationGoals */
+
+export { createConversationGoals };

package/src/server/conversation/conversationHandles.js

@@ -0,0 +1,237 @@
+import { isDeepStrictEqual } from "node:util";
+import { normalizeConversationConfiguration } from "./configuration.js";
+import { failure } from "./conversationRefusals.js";
+import { serial } from "./conversationEvents.js";
+
+/** @typedef {import("./conversationEntries.js").ConversationEntry} ConversationEntry */
+/** @typedef {import("./conversationEntries.js").HostConversation} HostConversation */
+
+/**
+ * Checks the conversation a host supplies before the runtime binds it: a logical conversation
+ * brings its command, read and stream owners; a scoped one its native representation, identity
+ * and operations; a bound native one its identity, store, preparation and native owners.
+ * @param {HostConversation | null} conversation
+ * @param {{ id: string, configuration: object | undefined, representation: string }} request
+ */
+function assertHostConversation(conversation, { id, configuration, representation }) {
+  // readable-check: allow method-probe - input validation: the conversation a host supplies is checked before the runtime binds it
+  const offers = (owner, names) => names.every(name => typeof owner?.[name] === "function");
+  const scoped = conversation?.native?.scoped;
+  const commands = conversation?.commands;
+  const owner = conversation?.native?.owner;
+  const preparation = conversation?.native?.preparation;
+  const invalidClaudeOwner = conversation?.engine === "claude" && (!owner || typeof owner !== "object" || !offers(owner, ["acquire"]) ||
+    !offers(preparation, ["cleanup"]));
+  const invalidOpenCodeOwner = conversation?.engine === "opencode" && (!owner || typeof owner !== "object" ||
+    !offers(preparation, ["cleanup", ...(scoped ? ["turn", "existing"] : ["message", "inspection", "interruption"])]) ||
+    !scoped && !offers(conversation.native, ["acquire"]));
+  if (commands && (representation !== "canonical" || configuration !== undefined ||
+      !offers(commands, ["send", "cancel", "select", "inspectDelivery"]) || !offers(conversation, ["read", "readStream"]))) {
+    throw new TypeError("A logical conversation requires its complete original command, read and stream owners.");
+  }
+  if (scoped && (representation !== "native" || configuration !== undefined || !["codex", "claude", "opencode"].includes(conversation.engine) ||
+      typeof scoped.conversationId !== "string" || !scoped.conversationId ||
+      (conversation.engine === "claude" ? invalidClaudeOwner : conversation.engine === "opencode" ? invalidOpenCodeOwner
+        : !offers(preparation, ["cleanup"]) ||
+          !offers(conversation.native.runOwner, ["startConversationTurn", "readConversation", "waitForConversationTurn", "stopConversation", "deleteConversation"])))) {
+    throw new TypeError("An original scoped conversation requires its native representation, identity and existing operations.");
+  }
+  if (conversation && (conversation.sessionId !== id || typeof conversation.namespace !== "string" || !conversation.namespace ||
+      !["codex", "claude", "opencode"].includes(conversation.engine) || !scoped && !commands && (
+      (conversation.engine === "codex" ? !conversation.native?.runOwner || !conversation.native?.providerOwner
+        : conversation.engine === "claude" ? invalidClaudeOwner
+          : invalidOpenCodeOwner) ||
+      !offers(conversation, ["prepareInput", "read"])))) {
+    throw new TypeError("A bound native conversation requires its original identity, store, preparation and native owners.");
+  }
+  if (conversation?.maximumHistoryBytes !== undefined && !offers(conversation, ["maximumHistoryBytes"])) {
+    throw new TypeError("A bound native history budget requires a server-owned resolver.");
+  }
+  if (!["canonical", "native"].includes(representation) || representation === "native" && !conversation) {
+    throw new TypeError("Native result representation requires an original bound conversation.");
+  }
+}
+
+/**
+ * Opening a conversation handle: the host's conversation is checked, its entry is created or
+ * reused, and the handle's operations are bound to that entry and caller context.
+ * @param {object} dependencies
+ * @param {import("./conversationEntries.js").ConversationEntries} dependencies.entries
+ * @param {import("../types.js").ReentrantConversationStorage | null} dependencies.storage
+ * @param {import("../types.js").ConversationHost | undefined} dependencies.defaultHost
+ * @param {import("./conversationEvents.js").ConversationEvents} dependencies.events
+ * @param {import("./conversationReads.js").ConversationReads} dependencies.reads
+ * @param {import("./conversationSending.js").ConversationSending} dependencies.sending
+ * @param {import("./conversationGoals.js").ConversationGoals} dependencies.goals
+ * @param {import("./conversationDelivery.js").ConversationDelivery} dependencies.delivery
+ * @param {import("./conversationStopping.js").ConversationStopping} dependencies.stopping
+ * @param {import("./conversationReplacement.js").ConversationReplacement} dependencies.replacement
+ * @param {import("./completedResponses.js").CompletedResponses} dependencies.completedResponses
+ * @param {boolean} dependencies.completedEnvelope
+ * @param {boolean} dependencies.persistCommentary
+ * @param {string | undefined} dependencies.defaultIntegrationId
+ */
+function createConversationHandles({ entries, storage, defaultHost, events, reads, sending, goals, delivery, stopping, replacement,
+  completedResponses, completedEnvelope, persistCommentary, defaultIntegrationId }) {
+  /**
+   * What a handle reads: a scoped conversation's own result, a bound conversation's native result,
+   * a logical conversation's snapshot from its own read, or the snapshot of its saved state.
+   * @param {ConversationEntry} entry
+   * @param {string} representation
+   * @param {object} context
+   * @param {object} [query]
+   */
+  async function readSnapshot(entry, representation, context, query) {
+    if (entry.conversation?.native?.scoped) return entry.provider.readNative({ input: query, context });
+    if (representation === "native") return reads.readNativeResult(entry, context);
+    if (entry.conversation?.commands) {
+      const logical = await entry.conversation.read(context, query);
+      entries.followEngine(entry, logical.engine);
+      return reads.logicalSnapshot(entry, logical);
+    }
+    return reads.snapshot(entry, await entries.readState(entry, context), query);
+  }
+
+  async function open({ id, context, configuration, engine, host, representation = "canonical" }) {
+    if (typeof id !== "string" || !id.trim()) throw new TypeError("A conversation id is required.");
+    await events.access(context, id, "open");
+    const selectedHost = host || defaultHost;
+    const conversation = selectedHost?.conversation ? await selectedHost.conversation({ id, context }) : null;
+    if (completedEnvelope && (conversation || representation !== "canonical")) {
+      throw failure("Completed envelopes require runtime-owned canonical storage.", "conversation_completed_envelopes_need_storage", 400, { messageCode: "assistant.conversation.completedEnvelopesNeedStorage" });
+    }
+    if (conversation && !persistCommentary) {
+      throw new TypeError("Transient commentary requires a runtime-owned transcript; supplied conversations retain their host's policy.");
+    }
+    assertHostConversation(conversation, { id, configuration, representation });
+    const entry = entries.acquire({ id, conversation, host: selectedHost, configuration, engine });
+    await entry.initializing;
+    if (entry.disposed) throw failure("This conversation handle is disposed.", "conversation_handle_disposed", 409, { messageCode: "assistant.conversation.handleDisposed" });
+    if (host && !isDeepStrictEqual(host, entry.host)) throw failure("This open conversation already belongs to another host scope. Dispose its handle before reopening it on the original host.", "conversation_host_scope_mismatch", 409, { messageCode: "assistant.conversation.hostScopeMismatch" });
+    if (engine && engine !== entry.engine) throw failure("Use replace() to change this conversation's engine.", "conversation_use_replace_for_engine", 409, { messageCode: "assistant.conversation.useReplaceForEngine" });
+    if (configuration) {
+      const state = await entries.readState(entry);
+      const supplied = entry.conversation ? configuration
+        : normalizeConversationConfiguration(configuration, { engine: entry.engine, defaultIntegrationId });
+      if (!isDeepStrictEqual(supplied, state.configuration)) {
+        throw failure("Use configure() to change a saved conversation's settings.", "conversation_configuration_mismatch");
+      }
+    }
+    return Object.freeze({
+      id,
+      get capabilities() { return reads.capabilities(entry); },
+      replace: input => serial(entry, () => replacement.replace(entry, context, input, false, representation)),
+      select: input => serial(entry, () => replacement.replace(entry, context, input, true, representation)),
+      async read(query) {
+        await events.access(context, id, "read", entry);
+        const result = await readSnapshot(entry, representation, context, query);
+        if (entry.conversation?.commands) await events.access(context, id, "read", entry);
+        return result;
+      },
+      send: input => sending.send(entry, context, input, "user", undefined, representation),
+      wake: (input, options) => sending.send(entry, context, input, "application", undefined, representation, options),
+      ...(completedEnvelope ? { prepareCompletedResponse: (input, options) =>
+        serial(entry, () => completedResponses.prepareCompletedResponse(entry, context, input, options)) } : {}),
+      readGoal: () => serial(entry, () => goals.readGoal(entry, context, representation)),
+      updateGoal: input => goals.updateGoal(entry, context, input, representation),
+      inspectDelivery({ messageId, threadId }) {
+        if (typeof messageId !== "string" || !messageId) throw new TypeError("A message id is required.");
+        return serial(entry, async () => {
+          if (representation !== "native") return delivery.inspectDelivery(entry, context, messageId);
+          await events.access(context, id, "inspectDelivery", entry);
+          return entry.provider.inspectAdmission({ messageId, threadId, context, representation });
+        });
+      },
+      async wait(input) {
+        await events.access(context, id, "read", entry);
+        if (entry.conversation?.commands) throw failure("This conversation uses its original read and subscription operations.", "conversation_original_read_only", 400, { messageCode: "assistant.conversation.originalReadOnly" });
+        if (entry.conversation?.native?.scoped) return entry.provider.waitNative({ input, context });
+        await entry.pending;
+        await entry.active?.done;
+        await events.access(context, id, "read", entry);
+        return reads.snapshot(entry, await entries.readState(entry));
+      },
+      // Cancel of one unsent or unconfirmed message always records it; an
+      // application conversation supplies its own operation for that.
+      async cancelDelivery({ messageId }) {
+        if (typeof messageId !== "string" || !messageId) throw new TypeError("A message id is required.");
+        await events.access(context, id, "cancel", entry);
+        if (entry.conversation?.commands) {
+          // readable-check: allow method-probe - optional operation: cancelling one message is optional in a logical conversation's commands
+          if (typeof entry.conversation.commands.cancelDelivery !== "function") {
+            throw failure("This conversation cannot cancel one message.", "conversation_message_cancel_unsupported", 400,
+              { messageCode: "assistant.conversation.messageCancelUnsupported" });
+          }
+          return entry.conversation.commands.cancelDelivery({ messageId }, context);
+        }
+        return stopping.cancelDelivery(entry, context, messageId, representation);
+      },
+      async cancel(input) {
+        await events.access(context, id, "cancel", entry);
+        if (entry.conversation?.commands) return entry.conversation.commands.cancel(input, context);
+        await entry.pending;
+        await events.access(context, id, "cancel", entry);
+        return stopping.stop(entry, context, input, representation);
+      },
+      async retrySave() {
+        await events.access(context, id, "retrySave", entry);
+        return serial(entry, async () => {
+          await events.access(context, id, "retrySave", entry);
+          return stopping.retrySave(entry);
+        });
+      },
+      async configure(patch) {
+        await events.access(context, id, "configure", entry);
+        if (entry.conversation?.commands) throw failure("Use the conversation's authorized selection operation.", "conversation_authorized_selection_required", 400, { messageCode: "assistant.conversation.authorizedSelectionRequired" });
+        return serial(entry, async () => {
+          await events.access(context, id, "configure", entry);
+          if (entry.active) throw failure("Stop the current turn before changing its settings.", "conversation_busy", 409, { messageCode: "assistant.conversation.stopBeforeSettings" });
+          if (entry.storageFailure) throw entry.storageFailure;
+          if (entry.executionFailure) throw entry.executionFailure;
+          if (entry.conversation) {
+            if (!entry.conversation.selection?.write) throw failure("This host requires its authorized assistant selection operation.", "conversation_host_selection_required", 409, { messageCode: "assistant.conversation.hostSelectionRequired" });
+            return entry.conversation.selection.write({ configuration: patch }, context);
+          }
+          return storage.write(id, async transaction => {
+            const metadata = await transaction.readMetadata();
+            if (metadata.runtime.replacement) throw failure("Finish the pending native replacement before changing settings.", "conversation_replacement_pending_before_settings", 409, { messageCode: "assistant.conversation.replacementPendingBeforeSettings" });
+            if (metadata.runtime.request && (entry.engine === "api" || metadata.runtime.request.attempted || metadata.runtime.request.inspectionOnly)) {
+              throw failure("Resolve uncertain delivery before changing settings.", "conversation_delivery_uncertain", 409, { messageCode: "assistant.conversation.deliveryUncertainBeforeSettings" });
+            }
+            const next = normalizeConversationConfiguration({ ...metadata.runtime.configuration, ...patch }, {
+              engine: metadata.runtime.engine, defaultIntegrationId
+            });
+            entry.driver.validateConfiguration(next);
+            metadata.runtime.configuration = next;
+            await transaction.writeMetadata(metadata);
+            return structuredClone(next);
+          });
+        });
+      },
+      async subscribe(listener) {
+        await events.access(context, id, "subscribe", entry);
+        if (entry.conversation?.native?.scoped) throw failure("This scoped conversation retains its original event delivery.", "conversation_event_delivery_retained", 409, { messageCode: "assistant.conversation.eventDeliveryRetained" });
+        if (typeof listener !== "function") throw new TypeError("A conversation listener is required.");
+        const subscription = { context, listener };
+        entry.listeners.add(subscription);
+        return () => entry.listeners.delete(subscription);
+      },
+      async dispose(options) {
+        await events.access(context, id, "dispose", entry);
+        return serial(entry, async () => {
+          await events.access(context, id, "dispose", entry);
+          const result = await stopping.disposeEntry(entry, context, options, representation);
+          if (result?.ok === false || representation === "native") return result;
+        });
+      }
+    });
+  }
+
+  return Object.freeze({
+    open
+  });
+}
+
+/** @typedef {ReturnType<typeof createConversationHandles>} ConversationHandles */
+
+export { createConversationHandles };

package/src/server/conversation/conversationReads.js

@@ -0,0 +1,206 @@
+import { codexAppServerTurnStateFromAgentRun } from "./codexTurn.js";
+import { failure, stateErrorFields } from "./conversationRefusals.js";
+
+/** @typedef {import("./conversationEntries.js").ConversationEntry} ConversationEntry */
+/** @typedef {import("./conversationEntries.js").ConversationState} ConversationState */
+
+/** The authored message of a saved turn: a user's message, or the application's. */
+const submittedMessage = turn => turn.user || turn.system;
+
+/** Every runtime segment a saved state retains: its predecessors and itself, once each. */
+const retainedSegments = state => [...new Map([...state.predecessors, state].map(segment => [segment.segmentId, segment])).values()];
+
+// readable-check: allow method-probe - optional operation: a host's conversation transcript may offer paged history
+const offersPages = entry => typeof entry.conversation.transcript.readConversationLogPage === "function";
+
+/** The predecessor whose replacement still waits for its successor's first accepted message. */
+const pendingSuccessor = state => state.engine !== "api" && state.predecessors.findLast(segment => segment.successorId === state.segmentId &&
+  segment.segmentId !== state.segmentId && segment.replacement?.operation === "replace" && !segment.acceptedAt);
+
+/**
+ * What an open conversation reads: its capabilities, its transcript, and the snapshot a reader
+ * sees. Nothing here changes the conversation.
+ * @param {object} dependencies
+ * @param {import("../types.js").ReentrantConversationStorage | null} dependencies.storage
+ * @param {import("../types.js").ConversationTranscript | null} dependencies.transcript
+ * @param {import("../types.js").ConversationStreams} dependencies.streams
+ * @param {boolean} dependencies.attachmentsOffered Whether the application resolves message attachments.
+ * @param {boolean} dependencies.completedEnvelope
+ */
+function createConversationReads({ storage, transcript, streams, attachmentsOffered, completedEnvelope }) {
+  /** @param {ConversationEntry} entry */
+  function capabilities(entry) {
+    const value = { ...entry.driver.capabilities, ...entry.provider?.capabilities,
+      attachments: Boolean((attachmentsOffered || entry.conversation?.prepareInput || entry.conversation?.commands) && entry.driver.capabilities.attachments) };
+    if (entry.conversation?.commands) {
+      delete value.goalCommands;
+      Object.assign(value, { goals: false, configuration: false, wake: false, replacement: false });
+    }
+    return value;
+  }
+
+  /**
+   * The saved turns; `afterTurnId` reads only the turns a stored summary doesn't cover.
+   * @param {ConversationEntry} entry
+   * @param {string} [afterTurnId]
+   */
+  const readTranscript = (entry, afterTurnId = "") => entry.conversation
+    ? entry.conversation.transcript.readConversationLog() : transcript.readConversationLog(entry.id, { afterTurnId });
+
+  /**
+   * The stored compaction summary, when it belongs to this history. A bound conversation's host
+   * owns its transcript, so it has none.
+   * @param {ConversationEntry} entry
+   * @param {(turn: object) => boolean} inHistory
+   */
+  async function readSummary(entry, inHistory) {
+    if (entry.conversation) return null;
+    return storage.read(entry.id, async transaction => {
+      const summary = await transaction.readSummary();
+      const covered = summary && await transaction.readTurn(summary.throughTurnId);
+      return covered && inHistory(covered) ? summary : null;
+    });
+  }
+
+  /**
+   * Identity lookups avoid reading the whole log when the transcript supports them. A bound host
+   * may supply findSubmittedTurn(messageId) and readTurn(turnId).
+   * @param {ConversationEntry} entry
+   * @param {string} messageId
+   */
+  async function findSubmittedTurn(entry, messageId) {
+    const find = entry.conversation ? entry.conversation.transcript.findSubmittedTurn : transcript.findSubmittedTurn &&
+      (id => transcript.findSubmittedTurn(entry.id, id));
+    if (typeof find === "function") return (await find(messageId)) || null;
+    return (await readTranscript(entry)).find(turn => submittedMessage(turn)?.messageId === messageId) || null;
+  }
+
+  /**
+   * @param {ConversationEntry} entry
+   * @param {string} turnId
+   */
+  async function readBoundTurn(entry, turnId) {
+    // readable-check: allow method-probe - optional operation: a host's conversation transcript may offer direct turn reads
+    if (typeof entry.conversation.transcript.readTurn === "function") return (await entry.conversation.transcript.readTurn(turnId)) || null;
+    return (await readTranscript(entry)).find(turn => turn.turnId === turnId) || null;
+  }
+
+  /** @param {ConversationEntry} entry */
+  async function lastTranscriptTurn(entry) {
+    const page = entry.conversation && !offersPages(entry) ? null
+      : entry.conversation ? await entry.conversation.transcript.readConversationLogPage({ limit: 1 })
+        : await transcript.readConversationLogPage(entry.id, { limit: 1 });
+    return page?.conversationLog.at(-1) || (await readTranscript(entry)).at(-1);
+  }
+
+  /**
+   * @param {ConversationEntry} entry
+   * @param {object} query
+   */
+  function readTranscriptPage(entry, query) {
+    if (!entry.conversation) return transcript.readConversationLogPage(entry.id, { ...query, presentation: completedEnvelope });
+    if (!offersPages(entry)) {
+      throw failure("This conversation does not supply paged history.", "conversation_paged_history_unsupported", 400, { messageCode: "assistant.conversation.pagedHistoryUnsupported" });
+    }
+    return entry.conversation.transcript.readConversationLogPage(query);
+  }
+
+  /**
+   * A bound conversation's own result, in its native representation.
+   * @param {ConversationEntry} entry
+   * @param {object} context
+   */
+  async function readNativeResult(entry, context) {
+    const value = entry.driver.readState
+      ? await entry.driver.readState({ conversation: entry.conversation, context, representation: "native" })
+      : await entry.conversation.read(context, "native");
+    return value.nativeResult;
+  }
+
+  /**
+   * What a reader sees of a logical conversation, from the result of its own read.
+   * @param {ConversationEntry} entry
+   * @param {object} logical
+   */
+  async function logicalSnapshot(entry, logical) {
+    const streaming = await entry.conversation.readStream();
+    const error = logical.error || "";
+    return {
+      id: entry.id, engine: entry.engine, capabilities: capabilities(entry), configuration: logical.configuration,
+      segmentId: logical.threadId ? `${logical.engine}:${logical.threadId}` : null,
+      replacement: null,
+      status: logical.status,
+      phase: logical.phase || "",
+      error,
+      ...stateErrorFields(error),
+      goal: entry.goal || null,
+      pendingRequest: logical.pendingRequest || null,
+      ...(logical.presentation ? { presentation: logical.presentation } : {}),
+      conversationLog: logical.conversationLog.filter(turn => !turn.metadata?.runtime?.supersededBy),
+      ...(logical.pagination ? { pagination: logical.pagination } : {}),
+      streaming
+    };
+  }
+
+  /**
+   * What a reader sees of a conversation from its saved state: a page of its transcript, or all
+   * of it, with the current turn's status, phase, error and live stream.
+   * @param {ConversationEntry} entry
+   * @param {ConversationState} state
+   * @param {object} [query]
+   */
+  async function snapshot(entry, state, query) {
+    const page = query ? await readTranscriptPage(entry, query) : null;
+    const conversationLog = page ? page.conversationLog
+      : completedEnvelope ? await transcript.readConversationLog(entry.id, { presentation: true }) : await readTranscript(entry);
+    // Browsing an older page does not change the current turn's control/error state.
+    const latest = completedEnvelope || query?.beforeTurnId
+      ? entry.conversation ? (await readTranscriptPage(entry, { limit: 1 })).conversationLog
+        : (await transcript.readConversationLogPage(entry.id, { limit: 1 })).conversationLog : conversationLog;
+    const last = latest.at(-1)?.metadata?.runtime;
+    const savedRequest = state.request;
+    const nativeTurn = state.nativeTurn || (entry.driver.canonicalTranscript && state.binding?.codexAppServerRun
+      ? codexAppServerTurnStateFromAgentRun(state.binding.codexAppServerRun) : null);
+    const request = savedRequest && (entry.engine === "api" || savedRequest.attempted || savedRequest.inspectionOnly ||
+      entry.active?.requests.has(savedRequest.messageId)) ? savedRequest : null;
+    const streaming = entry.conversation ? await entry.conversation.readStream() : streams.read(entry.id);
+    const error = entry.error || nativeTurn?.error || request?.error || last?.error || "";
+    const pendingRequest = request && !(completedEnvelope && request.origin === "application" && request.completedEnvelope === true) ? Object.fromEntries([
+      "messageId", "text", "origin", "data", "attachments", "at", "goal", "steering", "error"
+    ].filter(name => Object.hasOwn(request, name)).map(name => [name, request[name]])) : null;
+    if (pendingRequest?.error) Object.assign(pendingRequest, stateErrorFields(pendingRequest.error));
+    return {
+      id: entry.id, engine: entry.engine, capabilities: capabilities(entry), configuration: state.configuration,
+      segmentId: state.segmentId,
+      replacement: state.replacement ? { operationId: state.replacement.request?.operationId || state.replacement.operationId,
+        reason: state.replacement.reason, segmentId: state.replacement.segmentId } : null,
+      status: entry.storageFailure || entry.executionFailure ? "unavailable" : entry.active || nativeTurn?.active ? "working" : state.replacement ? "replacement-pending"
+        : state.request && (entry.engine === "api" || state.request.attempted || state.request.inspectionOnly) ? "unconfirmed" : "ready",
+      phase: entry.phase || (nativeTurn?.active && nativeTurn.status !== "observation_lost" ? ["compacting", "background"].includes(nativeTurn.phase) ? nativeTurn.phase : "working" : ""),
+      error,
+      ...stateErrorFields(error),
+      goal: entry.goal || null,
+      pendingRequest,
+      conversationLog: conversationLog.filter(turn => !turn.metadata?.runtime?.supersededBy),
+      ...(page ? { pagination: page.pagination } : {}),
+      streaming: completedEnvelope && !entry.conversation ? { ...streaming,
+        messages: streaming.messages.filter(message => !(message.origin === "application" && message.completedEnvelope === true)) } : streaming
+    };
+  }
+
+  return Object.freeze({
+    capabilities,
+    readTranscript,
+    readSummary,
+    findSubmittedTurn,
+    readBoundTurn,
+    lastTranscriptTurn,
+    readNativeResult,
+    logicalSnapshot,
+    snapshot
+  });
+}
+
+/** @typedef {ReturnType<typeof createConversationReads>} ConversationReads */
+
+export { createConversationReads, pendingSuccessor, retainedSegments, submittedMessage };