@jskit-ai/assistant-core 0.1.213 → 0.1.214

package/src/server/conversation/runtimeStateUpgrade.js

@@ -1,3 +1,5 @@
+import { isAbsolute } from "node:path";
+
 const engines = new Set(["api", "claude", "codex", "opencode"]);
 const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
 
@@ -74,12 +76,81 @@ function inspectRequest(request, segment, version, warnings) {
   warnings.push(`The retained ${segment.engine} request requires native receipt inspection. Its missing prompt was not reconstructed and will not be replayed.`);
 }
 
+/** Literal replacement state assembly shared by live and explicit offline callers. */
+export function createConversationRuntimeReplacement({ request, engine, configuration, reason, segmentId, continuity, seen, destination }) {
+  return { request, engine, configuration, reason, segmentId,
+    continuity: continuity.text, continuityAttachments: continuity.attachments, seen,
+    ...(destination ? { binding: destination.binding || null, submission: destination.request } : {}) };
+}
+
+export function releaseConversationRuntimeBinding(state, pending, request, engine) {
+  state.predecessors.push({ segmentId: state.segmentId, engine: state.engine,
+    configuration: state.configuration, binding: state.binding, seen: state.seen,
+    continuity: state.continuity, continuityAttachments: state.continuityAttachments, request: state.request,
+    successorId: pending.segmentId, replacement: request,
+    ...(pending.preparedAt ? { preparedAt: pending.preparedAt } : {}) });
+  Object.assign(state, { engine, configuration: pending.configuration, binding: pending.binding,
+    segmentId: pending.segmentId, continuity: pending.continuity, continuityAttachments: pending.continuityAttachments, seen: pending.seen });
+  if (pending.submission) state.request = pending.submission;
+  else delete state.request;
+}
+
+export function finishConversationRuntimeReplacement(state, { engine, selection, retireNative, pending, value }) {
+  if (value) {
+    if (engine !== "api") state.seen = value.engines[engine].seen;
+    state.lastEngine = value.lastEngine;
+  } else if (engine !== "api" &&
+      (!selection || retireNative === true || engine === "opencode" && !pending.binding.sessionId)) {
+    state.lastEngine = "";
+  }
+  delete state.replacement;
+}
+
+/** Paths are resolved and authorized by the caller; this constructor performs no I/O. */
+export function createInertCodexConversationBinding({ workdir, configRoot }) {
+  return { threadId: "", workdir, configRoot, executionId: "" };
+}
+
+function retireCodexBinding(runtime, retirement) {
+  const keys = ["operationId", "successorSegmentId", "expectedSegmentId", "expectedThreadId", "expectedToolSchemaIdentity", "workdir", "configRoot"];
+  if (!object(retirement) || Object.keys(retirement).some(key => !keys.includes(key)) ||
+      typeof retirement.operationId !== "string" || typeof retirement.successorSegmentId !== "string" ||
+      !/^[\w-]{1,128}$/u.test(retirement.operationId || "") ||
+      !/^[\w-]{1,128}$/u.test(retirement.successorSegmentId || "") ||
+      typeof retirement.expectedSegmentId !== "string" || !retirement.expectedSegmentId ||
+      typeof retirement.expectedThreadId !== "string" || !retirement.expectedThreadId ||
+      typeof retirement.expectedToolSchemaIdentity !== "string" || !/^[a-f0-9]{64}$/u.test(retirement.expectedToolSchemaIdentity) ||
+      typeof retirement.workdir !== "string" || !isAbsolute(retirement.workdir) ||
+      typeof retirement.configRoot !== "string" || !isAbsolute(retirement.configRoot)) {
+    invalid("Offline Codex retirement requires immutable operation/successor IDs, the exact old native tuple, and verified physical paths.");
+  }
+  if (runtime.version !== 3 || runtime.engine !== "codex" || runtime.request !== undefined || runtime.replacement !== undefined ||
+      runtime.segmentId !== retirement.expectedSegmentId || runtime.binding.threadId !== retirement.expectedThreadId ||
+      runtime.binding.toolSchemaIdentity !== retirement.expectedToolSchemaIdentity ||
+      runtime.binding.workdir !== retirement.workdir || runtime.binding.configRoot !== retirement.configRoot ||
+      retirement.successorSegmentId === runtime.segmentId ||
+      runtime.predecessors.some(segment => segment.segmentId === retirement.successorSegmentId ||
+        segment.successorId === retirement.successorSegmentId || segment.replacement?.operationId === retirement.operationId)) {
+    invalid("Offline Codex retirement conflicts with its saved native identity, pending delivery, paths or retained replacement IDs.");
+  }
+  const request = { operationId: retirement.operationId, expectedSegmentId: runtime.segmentId,
+    engine: "codex", configuration: structuredClone(runtime.configuration), retireNative: true, operation: "select" };
+  const pending = createConversationRuntimeReplacement({ request, engine: "codex", configuration: structuredClone(runtime.configuration),
+    reason: "model-change", segmentId: retirement.successorSegmentId, continuity: { text: undefined, attachments: [] }, seen: {} });
+  pending.binding = createInertCodexConversationBinding(retirement);
+  releaseConversationRuntimeBinding(runtime, pending, request, "codex");
+  finishConversationRuntimeReplacement(runtime, { engine: "codex", selection: true, retireNative: true, pending });
+}
+
 /** Pure offline transform. The application owns enumeration, backups and publication. */
-export function upgradeConversationRuntimeState({ metadata, conversationLog }) {
+export function upgradeConversationRuntimeState({ metadata, conversationLog, retirement }) {
   if (!object(metadata) || !Array.isArray(conversationLog)) {
     invalid("Conversation runtime upgrade requires metadata and the complete stored transcript.");
   }
-  if (metadata.runtime === undefined) return { metadata, changed: false, warnings: [] };
+  if (metadata.runtime === undefined) {
+    if (retirement !== undefined) invalid("Offline native retirement requires the exact saved runtime; it cannot create a historical binding.");
+    return { metadata, changed: false, warnings: [] };
+  }
   const source = metadata.runtime;
   if (!object(source) || ![2, 3].includes(source.version) || !Array.isArray(source.predecessors)) {
     invalid("This conversation has an unsupported runtime version. Inspect its original format and provide an offline conversion before opening it.");
@@ -110,6 +181,10 @@ export function upgradeConversationRuntimeState({ metadata, conversationLog }) {
       invalid("An unfinished replacement has a request without its exact saved binding. Inspect it before upgrading.");
     }
   }
+  if (retirement !== undefined) {
+    retireCodexBinding(runtime, retirement);
+    return { metadata: { ...metadata, runtime }, changed: true, warnings };
+  }
   if (source.version === 3) return { metadata, changed: false, warnings: [] };
   let lastEngine = "";
   for (const turn of conversationLog) {

package/src/server/conversation/streams.js

@@ -11,15 +11,19 @@ export function createConversationStreams({ clock = () => new Date() } = {}) {
     };
   }
 
-  function update(scope, { turnId, messageId, role = "assistant", text, delta, at, origin, nativeIdentity, outputId } = {}) {
+  function update(scope, { turnId, messageId, role = "assistant", text, delta, at, origin, nativeIdentity, outputId, authorship } = {}) {
     if (!turnId || !messageId || !["assistant", "commentary"].includes(role)) return null;
     let stream = streams.get(scope);
     if (!stream || stream.turnId !== turnId) {
-      stream = { turnId, messages: new Map(), completed: new Set() };
+      stream = { turnId, messages: new Map(), completed: new Set(), authorship: new Map() };
       streams.set(scope, stream);
     }
     if (stream.completed.has(messageId)) return null;
     const previous = stream.messages.get(messageId);
+    const captured = stream.authorship.get(messageId);
+    if (authorship?.messageId && (!previous || captured?.messageId === authorship.messageId)) {
+      stream.authorship.set(messageId, captured?.turnId ? captured : { ...authorship });
+    }
     const next = {
       messageId,
       ...((previous?.outputId || outputId) ? { outputId: previous?.outputId || outputId } : {}),
@@ -27,24 +31,40 @@ export function createConversationStreams({ clock = () => new Date() } = {}) {
       // Ordinary runtime output already carries the exact authored row identity.
       ...(["user", "application"].includes(origin || previous?.origin)
         ? { ...(!nativeIdentity ? { turnId } : {}), origin: origin || previous.origin } : {}),
+      ...(stream.authorship.get(messageId)?.origin === "application" && stream.authorship.get(messageId)?.completedEnvelope === true
+        ? { completedEnvelope: true } : {}),
       role: previous?.role || role,
       at: previous?.at || at || clock().toISOString(),
       text: typeof delta === "string" ? (previous?.text || "") + delta : (text ?? previous?.text ?? ""),
       status: "inProgress"
     };
-    if (previous?.text === next.text && previous.role === next.role && previous.outputId === next.outputId) return null;
+    if (previous?.text === next.text && previous.role === next.role && previous.outputId === next.outputId &&
+        previous.completedEnvelope === next.completedEnvelope) return null;
     stream.messages.set(messageId, next);
     revision += 1;
     return read(scope);
   }
 
-  function complete(scope, messageId) {
+  function complete(scope, messageId, { text, role, authorship } = {}) {
     const stream = streams.get(scope);
     if (!stream) return read(scope);
+    const message = stream.messages.get(messageId);
+    const captured = stream.authorship.get(messageId);
+    const completedAuthorship = captured?.messageId === authorship?.messageId && captured?.origin === authorship?.origin && !captured?.turnId
+      ? { ...captured, ...(authorship?.turnId ? { turnId: authorship.turnId } : {}) } : captured;
     stream.completed.add(messageId);
     stream.messages.delete(messageId);
+    stream.authorship.delete(messageId);
     revision += 1;
-    return read(scope);
+    const snapshot = read(scope);
+    // Only the exact native completed-text path supplies a completion carrier.
+    // Cleanup, duplicate notifications and ordinary reads cannot replay it.
+    if (message && typeof text === "string" && completedAuthorship?.turnId && ["user", "application"].includes(completedAuthorship.origin)) {
+      snapshot.completedMessages = [{ ...message, turnId: completedAuthorship.turnId, origin: completedAuthorship.origin,
+        ...(completedAuthorship.origin === "application" && completedAuthorship.completedEnvelope === true ? { completedEnvelope: true } : {}),
+        ...(["assistant", "commentary", "thinking"].includes(role) ? { role } : {}), text, status: "complete" }];
+    }
+    return snapshot;
   }
 
   function clear(scope) {

package/src/server/conversation/tools.js

@@ -3,7 +3,7 @@ import { isDeepStrictEqual } from "node:util";
 const unknownOutcome = "The application operation did not return a verified result. Inspect its target before requesting another execution.";
 
 /** One turn's application calls. Native/API adapters only transport these calls. */
-export function createConversationTools({ catalog, context, prepareContext, signal: turnSignal, previousCalls = [], authorize, save, emit,
+export function createConversationTools({ catalog, toolSet: retainedToolSet, context, prepareContext, signal: turnSignal, previousCalls = [], authorize, save, emit,
   maximumCalls = 32, discoveryOnly = false, transient = false, propagateErrors = false }) {
   if (transient !== true && [authorize, save, emit].some(hook => typeof hook !== "function")) {
     throw new TypeError("Conversation tools require authorization, durable save and event facilities.");
@@ -12,7 +12,7 @@ export function createConversationTools({ catalog, context, prepareContext, sign
     throw new TypeError("Transient application tools cannot restore a previous execution.");
   }
   if (prepareContext !== undefined && typeof prepareContext !== "function") throw new TypeError("Application tool context requires a server-owned mapper.");
-  const toolSet = catalog.resolveToolSet(context, { discoveryOnly });
+  const toolSet = retainedToolSet ?? catalog.resolveToolSet(context, { discoveryOnly });
   const calls = new Map(structuredClone(previousCalls).map(call => [call.id, call]));
   let pending = Promise.resolve();
   let requested = 0;

package/src/server/conversation/transcript.js

@@ -6,23 +6,30 @@ export function createConversationTranscript({ storage, clock = () => new Date()
     throw new TypeError("Conversation storage requires read(scope, callback) and write(scope, callback).");
   }
 
-  async function readConversationLog(scope) {
+  async function readConversationLog(scope, { presentation = false } = {}) {
+    if (typeof presentation !== "boolean") throw new TypeError("Transcript presentation requires an explicit boolean.");
     return storage.read(scope, async (transaction) => {
       const ids = await transaction.listTurnIds();
-      return (await Promise.all(ids.map((id) => transaction.readTurn(id)))).filter(hasMessages);
+      const turns = (await Promise.all(ids.map((id) => transaction.readTurn(id)))).filter(hasMessages);
+      return presentation ? turns.filter(turn => !isCompletedEnvelopeTurn(turn)) : turns;
     });
   }
 
-  async function readConversationLogPage(scope, { beforeTurnId = "", limit = 0 } = {}) {
+  async function readConversationLogPage(scope, { beforeTurnId = "", limit = 0, presentation = false } = {}) {
+    if (typeof presentation !== "boolean") throw new TypeError("Transcript presentation requires an explicit boolean.");
     return storage.read(scope, async (transaction) => {
-      const ids = await transaction.listTurnIds();
+      const allIds = await transaction.listTurnIds();
+      const visible = presentation ? (await Promise.all(allIds.map(id => transaction.readTurn(id))))
+        .filter(turn => hasMessages(turn) && !isCompletedEnvelopeTurn(turn)) : null;
+      const ids = visible ? visible.map(turn => turn.turnId) : allIds;
       const before = normalizeText(beforeTurnId);
       const requestedLimit = Number.parseInt(String(limit || ""), 10);
       const pageLimit = Number.isFinite(requestedLimit) && requestedLimit > 0 ? Math.min(requestedLimit, 100) : 0;
       const end = before && ids.includes(before) ? ids.indexOf(before) : ids.length;
       const start = pageLimit ? Math.max(0, end - pageLimit) : 0;
       const selected = ids.slice(start, end);
-      const turns = (await Promise.all(selected.map((id) => transaction.readTurn(id)))).filter(hasMessages);
+      const turns = visible ? visible.slice(start, end)
+        : (await Promise.all(selected.map((id) => transaction.readTurn(id)))).filter(hasMessages);
       return {
         conversationLog: turns,
         pagination: {
@@ -44,20 +51,23 @@ export function createConversationTranscript({ storage, clock = () => new Date()
     return ids.length ? transaction.readTurn(ids.at(-1)) : null;
   }
 
-  async function append(scope, role, { text = "", messageId = "", at = "", attachments = [], data, turnMetadata = null, requireOpenTurn = false, outputId = "" } = {}) {
+  async function append(scope, role, { text = "", messageId = "", at = "", attachments = [], data, turnMetadata = null, requireOpenTurn = false, outputId = "", turnId: requestedTurnId = "" } = {}) {
     const messageText = normalizeText(text);
     const id = normalizeText(messageId);
     if (!messageText && !(role === "user" && Array.isArray(attachments) && attachments.length)) return null;
     return storage.write(scope, async (transaction) => {
       if (id && await transaction.hasMessage(id)) return null;
       const createdAt = new Date(at || clock());
-      const tail = ["assistant", "commentary", "thinking"].includes(role) ? await tailTurn(transaction) : null;
+      const targetId = ["assistant", "commentary", "thinking"].includes(role) ? normalizeText(requestedTurnId) : "";
+      const target = targetId ? await transaction.readTurn(targetId) : null;
+      if (targetId && !target) throw new Error("The native output's original turn no longer exists.");
+      const tail = target || (["assistant", "commentary", "thinking"].includes(role) ? await tailTurn(transaction) : null);
       const open = (tail?.user || applicationTurns && tail?.system?.origin === "application") && !tail.assistant ? tail : null;
       if (requireOpenTurn && !open) return null;
       const thinkingOnly = role === "thinking" && !open && at && tail &&
         !tail.system && !tail.user && !tail.assistant && !tail.commentary?.length &&
         tail.thinking?.some((message) => message.at === createdAt.toISOString());
-      const turnId = open?.turnId || (thinkingOnly ? tail.turnId : await transaction.nextTurnId());
+      const turnId = target?.turnId || open?.turnId || (thinkingOnly ? tail.turnId : await transaction.nextTurnId());
       await transaction.appendMessage(turnId, {
         role, text: messageText, messageId: id, at: createdAt.toISOString(),
         ...(["assistant", "commentary", "thinking"].includes(role) && normalizeText(outputId) ? { outputId: normalizeText(outputId) } : {}),
@@ -91,3 +101,8 @@ export function createConversationTranscript({ storage, clock = () => new Date()
 function hasMessages(turn) {
   return Boolean(turn && (turn.system || turn.user || turn.assistant || turn.commentary?.length || turn.thinking?.length));
 }
+
+// Only the future server-owned application response marker identifies a private carrier.
+export function isCompletedEnvelopeTurn(turn) {
+  return turn?.metadata?.runtime?.origin === "application" && turn.metadata.runtime.completedEnvelope === true;
+}

package/src/server/hosts/claudeHistory.js

@@ -1,4 +1,5 @@
 export {
+  claudeHistoryPath,
   listClaudeConversationStorage,
   readClaudeHistory,
   retireClaudeConversationHistory

package/src/server/hosts/claudeProcess.js

@@ -1,6 +1,7 @@
 export {
   bindClaudeConversationAccount,
   claudeCodeArguments,
+  claudeConnectionIdentity,
   claudeCatalogueModels,
   claudeFlagSettings,
   claudeModelConfiguration,

package/src/server/hosts/codexProvider.js

@@ -16,8 +16,11 @@ export {
   ensureCodexAppServerThread,
   inspectCodexAppServerMessageAdmission,
   retireCodexConversationHistory,
+  readCodexNativeGoal,
   resumeExactCodexAppServerThread,
   sendCodexAppServerPrompt,
   shellQuote,
   startFreshCodexAppServerThread
 } from "../conversation/codexProvider.js";
+
+export { readCodexHistoryRows } from "../conversation/codexHistoryAdapter.js";

package/src/server/hosts/nativeHistory.js

@@ -1,3 +1,4 @@
 export {
+  readStoppedNativeDatabase,
   retireNativeConversation
 } from "../conversation/nativeHistoryExport.js";

package/src/server/hosts/openCodeClient.js

@@ -3,5 +3,6 @@ export {
   createOpenCodeServerClient,
   openCodeAssistantMessageText,
   readBoundedResponse,
+  readOpenCodeConversationDatabase,
   retireOpenCodeConversationHistory
 } from "../conversation/openCodeClient.js";

package/src/server/hosts/openCodeTurn.js

@@ -2,6 +2,7 @@ export {
   openCodeDetachedPrompt,
   openCodeMessageError,
   openCodeRowsForInput,
+  openCodeLastAssistantResult,
   openCodeStructuredOutput,
   runOpenCodeConversationTurn
 } from "../conversation/openCodeTurn.js";

package/src/server/index.js

@@ -15,4 +15,4 @@ export {
 export { resolveWorkspaceSlug } from "./lib/resolveWorkspaceSlug.js";
 export { createServiceToolCatalog } from "./lib/serviceToolCatalog.js";
 export { consumeCompletionStream, sanitizeAssistantMessageText } from "./lib/assistantCompletion.js";
-export { runAssistantToolLoop, runBoundedAssistantToolLoop } from "./lib/assistantToolLoop.js";
+export { runAssistantToolLoop, runBoundedAssistantToolLoop, readAssistantResponseEnvelope, readPartialAssistantReply } from "./lib/assistantToolLoop.js";

package/src/server/lib/assistantToolLoop.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { createSchema } from "@jskit-ai/kernel/shared/validators";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { isAssistantProgressOnlyText } from "../../shared/assistantResponseText.js";
 import { sanitizeAssistantMessageText } from "./assistantCompletion.js";
@@ -259,6 +260,43 @@ async function runAssistantToolLoop({ messages, input, toolSet, toToolSchema, co
   });
 }
 
+const ASSISTANT_TOOL_PAYLOAD_LIMIT = 256 * 1024;
+
+const assistantEnvelopeSchema = createSchema({
+  kind: { type: "string", enum: ["reply", "tool"], required: true },
+  text: { type: "string", maxLength: 16000, required: false },
+  toolName: { type: "string", maxLength: 256, required: false },
+  arguments: { type: "string", maxLength: ASSISTANT_TOOL_PAYLOAD_LIMIT, required: false }
+});
+
+const assistantEnvelopeOutputSchema = {
+  type: "object", additionalProperties: false,
+  required: ["kind", "text", "toolName", "arguments"],
+  properties: {
+    kind: { type: "string", enum: ["reply", "tool"] },
+    text: { type: "string", maxLength: 16000, description: "The final reply, or a brief progress sentence for the first tool request; empty for subsequent tool requests." }, toolName: { type: "string", maxLength: 256 }, arguments: { type: "string", maxLength: ASSISTANT_TOOL_PAYLOAD_LIMIT }
+  }
+};
+
+function readAssistantResponseEnvelope(text) {
+  const parsed = JSON.parse(text);
+  const result = assistantEnvelopeSchema.create(parsed);
+  if (Object.keys(result.errors).length || !parsed || Array.isArray(parsed)) throw new Error("Invalid assistant response envelope.");
+  const value = result.validatedObject;
+  if (value.kind === "reply" && (!value.text || value.toolName || value.arguments)) throw new Error("A reply needs text and no tool call.");
+  if (value.kind === "tool" && (!value.toolName || !value.arguments || (value.text || "").length > 280)) throw new Error("A tool call needs its name and JSON arguments, with at most 280 characters of progress text.");
+  return value;
+}
+
+function readPartialAssistantReply(text) {
+  // Only the reply prefix from our envelope is visible. An unfinished escape
+  // waits for its remaining bytes; tool envelopes never become chat text.
+  // eslint-disable-next-line no-control-regex -- JSON strings forbid literal control characters.
+  const match = /^\s*\{\s*"kind"\s*:\s*"reply"\s*,\s*"text"\s*:\s*("(?:[^"\\\u0000-\u001f]|\\(?:["\\/bfnrt]|u[\da-fA-F]{4}))*)/.exec(text);
+  if (!match) return "";
+  return JSON.parse(`${match[1]}"`).slice(0, 16000).replace(/[\uD800-\uDBFF]$/, "");
+}
+
 function boundedResponseSchema(outputSchema, descriptors) {
   const object = properties => ({ type: "object", additionalProperties: false,
     properties, required: Object.keys(properties) });
@@ -273,9 +311,68 @@ function boundedResponseSchema(outputSchema, descriptors) {
 /** Original bounded response/operation order, with one shared reply/tool protocol. */
 async function runBoundedAssistantToolLoop({ prompt, signal, policy, complete, outputSchema, limitError,
   invalidResponseError = new Error("The assistant returned an invalid response."),
-  failureError = new Error("The assistant could not complete this request."), toolCatalog, toolContext }) {
+  failureError = new Error("The assistant could not complete this request."), toolCatalog, toolContext,
+  completedEnvelope = false, settle }) {
+  if (typeof completedEnvelope !== "boolean") throw new TypeError("Completed envelope mode must be a boolean.");
+  if (completedEnvelope && (policy.maximumResponses !== 24 || typeof settle !== "function")) {
+    throw new TypeError("Completed envelope mode requires 24 responses and application settlement.");
+  }
+  let invalidResponses = 0;
+  let previousResponse;
   for (let round = 0; round < policy.maximumResponses; round += 1) {
     signal?.throwIfAborted();
+    if (completedEnvelope) {
+      // complete returns inside the original worker's current authority lifetime.
+      // Its durable response tools must not reuse a sealed native request's tools.
+      const result = await complete(prompt, { timeoutMs: policy.timeoutMs,
+        outputSchema: assistantEnvelopeOutputSchema, previousResponse });
+      signal?.throwIfAborted();
+      if (result?.ok === false) {
+        throw Object.assign(new Error(normalizeText(result.error) || failureError.message), {
+          code: normalizeText(result.code) || failureError.code
+        });
+      }
+      const decision = await settle({ phase: "before-parse", result });
+      signal?.throwIfAborted();
+      if (decision === "continue") continue;
+      if (decision === "end") return;
+      if (decision !== "use") throw new TypeError("Invalid completed-response settlement decision.");
+      let response;
+      try {
+        response = readAssistantResponseEnvelope(result?.text);
+        if (result.nativeToolAttempt && response.kind === "reply") {
+          throw new Error("Application tools must use the response envelope.");
+        }
+      } catch {
+        previousResponse = { kind: "invalid", nativeToolAttempt: Boolean(result?.nativeToolAttempt) };
+        if (++invalidResponses > 2) {
+          const error = typeof invalidResponseError === "function"
+            ? invalidResponseError({ nativeToolAttempt: previousResponse.nativeToolAttempt }) : invalidResponseError;
+          if (!(error instanceof Error)) throw new TypeError("Invalid response error must be an Error.");
+          throw error;
+        }
+        continue;
+      }
+      if (response.kind === "reply") {
+        const decision = await settle({ phase: "after-final", response });
+        signal?.throwIfAborted();
+        if (decision === "continue") continue;
+        if (decision !== "end") throw new TypeError("Invalid completed-response settlement decision.");
+        return response.text;
+      }
+      if (typeof result?.tools?.execute !== "function") {
+        throw new TypeError("Completed application operations require the current durable tools.");
+      }
+      if (typeof result.toolCallId !== "string" || !result.toolCallId || result.toolCallId.length > 256) {
+        throw new TypeError("Completed application operations require their verified response call id.");
+      }
+      // Recovery reuses the verified response identity, never a new reservation.
+      // The existing tool owner alone reserves, authorizes, executes and saves.
+      const toolResult = await result.tools.execute({ id: result.toolCallId, name: response.toolName,
+        arguments: response.arguments }, { signal });
+      previousResponse = { ...response, result: toolResult };
+      continue;
+    }
     const tools = createConversationTools({ catalog: toolCatalog, context: toolContext,
       signal: signal || new AbortController().signal, maximumCalls: 1, discoveryOnly: false,
       transient: true, propagateErrors: true });
@@ -311,4 +408,4 @@ async function runBoundedAssistantToolLoop({ prompt, signal, policy, complete, o
   throw limitError;
 }
 
-export { runAssistantToolLoop, runBoundedAssistantToolLoop };
+export { runAssistantToolLoop, runBoundedAssistantToolLoop, readAssistantResponseEnvelope, readPartialAssistantReply };

package/test/aiConnectionClient.test.js

@@ -368,3 +368,60 @@ test("only explicit application-catalogue mode reports well-formed unavailable t
   assert.equal(chunks.at(-1).choices[0].finish_reason, "tool-calls");
   assert.equal(requests, 1, "reporting the attempted call neither executes an action nor starts another request");
 });
+
+// Saved app-model aliases are direct API choices, not new native Codex/Claude
+// offerings. Retain the original resolver and image-SDK assertions together.
+for (const modelId of ["deepseek-flash", "deepseek-v4-flash", "deepseek-v4-flash-vision-exp"]) {
+  test(`saved DeepSeek ${modelId} reaches the authorized SDK unchanged with exact limits and image bytes`, async () => {
+    const selected = `deepseek/${modelId}`;
+    const configuration = { schemaVersion: 1, registrations: {}, integrations: {
+      assistant: { provider: "ai", accountMode: "per-user", scopes: [],
+        authentication: { method: "api-key", secretRef: "account:deepseek" }, settings: { model: selected } }
+    } };
+    const actor = { applicationId: "example", subjectId: "person-one" };
+    let credentialReads = 0, requests = 0;
+    const connection = await createAiConnectionResolver({ configuration,
+      authorize(context, operation) {
+        assert.deepEqual(context, actor);
+        assert.deepEqual(operation, { integrationId: "assistant", operation: "ai.resolve", accountMode: "per-user" });
+        return actor;
+      },
+      resolveReference(reference, owner, slot) {
+        credentialReads++;
+        assert.equal(reference, "account:deepseek");
+        assert.deepEqual(owner, actor);
+        assert.deepEqual(slot, { integrationId: "assistant", accountMode: "per-user", providerId: "deepseek" });
+        return "selected-person-key";
+      }
+    }).resolve({ context: actor, integrationId: "assistant" });
+    assert.equal(connection.providerId, "deepseek");
+    assert.equal(connection.model, modelId);
+    assert.deepEqual(connection.modelLimits, { context: 1048576, output: 393216 });
+    assert.equal(connection.sdkPackage, "@ai-sdk/openai-compatible");
+    assert.equal(configuration.integrations.assistant.settings.model, selected, "Resolving preserves the saved selection");
+    const client = createAiConnectionClient(connection, {
+      async fetch(url, options) {
+        requests++;
+        assert.equal(String(url), "https://api.deepseek.com/chat/completions");
+        assert.equal(new Headers(options.headers).get("authorization"), "Bearer selected-person-key");
+        const body = JSON.parse(options.body);
+        assert.equal(body.model, modelId, "The actual SDK never substitutes the current Flash ID for a saved alias");
+        assert.equal(body.stream, true);
+        const content = body.messages[0].content;
+        assert.equal(content[0].text, "Describe this");
+        assert.equal(content[1].type, "image_url");
+        assert.equal(content[1].image_url.url, "data:image/png;base64,AQID");
+        return eventsResponse([{ choices: [{ index: 0, delta: { content: "An image" }, finish_reason: "stop" }] }]);
+      }
+    });
+    assert.equal(client.defaultModel, modelId);
+    const chunks = await Array.fromAsync(client.createChatCompletionStream({ messages: [{ role: "user", content: [
+      { type: "text", text: "Describe this" }, { type: "image", image: new Uint8Array([1, 2, 3]), mediaType: "image/png" }
+    ] }] }));
+    assert.equal(chunks[0].choices[0].delta.content, "An image");
+    assert.equal(chunks.at(-1).choices[0].finish_reason, "stop");
+    assert.equal(credentialReads, 1);
+    assert.equal(requests, 1, "One selected connection produces one inference without fallback or retry");
+    assert.deepEqual(connection.modelLimits, { context: 1048576, output: 393216 });
+  });
+}