@jskit-ai/assistant-core 0.1.199 → 0.1.201

package/src/shared/conversation/patches.js

@@ -0,0 +1,150 @@
+import { normalizeThinkingMessageText } from "./thinkingText.js";
+import { normalizeConversationLogPagination } from "./pagination.js";
+
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeConversationMessage(message = {}, { normalizeAttachments = value => Array.isArray(value) ? value : [] } = {}) {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    return null;
+  }
+  const role = String(message.role || "").trim();
+  const text = role === "thinking"
+    ? normalizeThinkingMessageText(message.text)
+    : String(message.text || "").trim();
+  if (!role || !text) {
+    return null;
+  }
+  const attachments = normalizeAttachments(message.attachments);
+  return {
+    at: String(message.at || "").trim(),
+    ...(attachments.length ? { attachments } : {}),
+    ...(String(message.messageId || "").trim()
+      ? { messageId: String(message.messageId).trim() }
+      : {}),
+    role,
+    text,
+    ...(message.receipt === false ? { receipt: false } : {})
+  };
+}
+
+function chronologicalConversationActivity(messages = []) {
+  return [...messages].sort((left, right) => (
+    String(left?.at || "").localeCompare(String(right?.at || ""))
+  ));
+}
+
+function normalizeConversationTurn(turn = {}, index = 0, options = {}) {
+  if (!turn || typeof turn !== "object" || Array.isArray(turn)) {
+    return null;
+  }
+  const user = normalizeConversationMessage(turn.user, options);
+  const assistant = normalizeConversationMessage(turn.assistant, options);
+  const normalizedCommentary = Array.isArray(turn.commentary)
+    ? turn.commentary.map(message => normalizeConversationMessage(message, options)).filter(Boolean)
+    : [];
+  const system = normalizeConversationMessage(turn.system, options);
+  const normalizedThinking = Array.isArray(turn.thinking)
+    ? turn.thinking.map(message => normalizeConversationMessage(message, options)).filter(Boolean)
+    : [];
+  const activityFromMessages = Array.isArray(turn.messages)
+    ? turn.messages
+      .map(message => normalizeConversationMessage(message, options))
+      .filter((message) => ["commentary", "thinking"].includes(message?.role))
+    : [];
+  const activity = activityFromMessages.length
+    ? activityFromMessages
+    : chronologicalConversationActivity([...normalizedThinking, ...normalizedCommentary]);
+  const commentary = activity.filter((message) => message.role === "commentary");
+  const thinking = activity.filter((message) => message.role === "thinking");
+  if (!system && !user && !assistant && !activity.length) {
+    return null;
+  }
+  return {
+    assistant,
+    commentary,
+    messages: [system, user, ...activity, assistant].filter(Boolean),
+    ...(isRecord(turn.metadata) ? { metadata: turn.metadata } : {}),
+    ...(system ? { system } : {}),
+    thinking,
+    turnId: String(turn.turnId || index + 1).trim(),
+    user
+  };
+}
+
+function applyConversationLogPatch(payload = {}, patch = null, options = {}) {
+  if (patch?.type !== "upsert-turn" || !isRecord(patch.turn)) {
+    return null;
+  }
+  const source = isRecord(payload) ? payload : {};
+  const turns = Array.isArray(source.conversationLog) ? source.conversationLog : [];
+  const turnId = String(patch.turn.turnId || "").trim();
+  if (!turnId) {
+    return null;
+  }
+  const existingIndex = turns.findIndex((turn) => String(turn?.turnId || "").trim() === turnId);
+  const existing = turns[existingIndex];
+  const updated = { ...existing, ...patch.turn };
+  if (existing) {
+    // An upsert adds delivered messages. An older partial turn must not remove
+    // a saved answer or progress; authoritative history arrives through a fresh read.
+    for (const role of ["system", "user", "assistant"]) {
+      if (existing[role] && !updated[role]) {
+        updated[role] = existing[role];
+      }
+    }
+    const existingTurn = normalizeConversationTurn(existing, 0, options);
+    const patchedTurn = normalizeConversationTurn(patch.turn, 0, options);
+    for (const role of ["thinking", "commentary"]) {
+      const messages = new Map();
+      for (const message of [...(existingTurn?.[role] || []), ...(patchedTurn?.[role] || [])]) {
+        // Timestamped progress without a message ID updates one saved file as
+        // its text grows. Match that identity instead of retaining each version.
+        const key = message.messageId || JSON.stringify(message.at
+          ? [message.role, message.at]
+          : [message.role, "", message.text]);
+        messages.set(key, message);
+      }
+      updated[role] = chronologicalConversationActivity([...messages.values()]);
+    }
+    updated.messages = [
+      updated.system,
+      updated.user,
+      ...chronologicalConversationActivity([...updated.thinking, ...updated.commentary]),
+      updated.assistant
+    ].filter(Boolean);
+  }
+  const nextTurns = (existingIndex >= 0
+    ? turns.map((turn, index) => index === existingIndex ? updated : turn)
+    : [...turns, patch.turn]
+  ).sort((left, right) => String(left?.turnId || "").localeCompare(
+    String(right?.turnId || ""),
+    undefined,
+    {
+      numeric: true
+    }
+  ));
+  const limit = Number.parseInt(String(options.limit || ""), 10);
+  const limitedTurns = Number.isFinite(limit) && limit > 0
+    ? nextTurns.slice(-limit)
+    : nextTurns;
+  const wasTrimmed = limitedTurns.length < nextTurns.length;
+  const pagination = normalizeConversationLogPagination(source.pagination);
+  const hasMoreBefore = pagination.hasMoreBefore || wasTrimmed;
+  const oldestTurnId = String(limitedTurns[0]?.turnId || "").trim();
+  return {
+    ...source,
+    conversationLog: limitedTurns,
+    pagination: {
+      ...pagination,
+      count: limitedTurns.length,
+      hasMoreBefore,
+      newestTurnId: String(limitedTurns.at(-1)?.turnId || "").trim(),
+      nextBeforeTurnId: hasMoreBefore ? oldestTurnId : "",
+      oldestTurnId
+    }
+  };
+}
+
+export { normalizeConversationMessage, normalizeConversationTurn, applyConversationLogPatch };

package/src/shared/conversation/questions.js

@@ -0,0 +1,48 @@
+function messageText(value = "") {
+  return String(value || "").trim();
+}
+
+function conversationTurns(conversationLog = {}) {
+  if (Array.isArray(conversationLog?.turns)) {
+    return conversationLog.turns;
+  }
+  return Array.isArray(conversationLog) ? conversationLog : [];
+}
+
+function latestAssistantMessageAwaitingUserReply(conversationLog = {}) {
+  const turns = conversationTurns(conversationLog);
+  for (let turnIndex = turns.length - 1; turnIndex >= 0; turnIndex -= 1) {
+    const turn = turns[turnIndex];
+    const messages = Array.isArray(turn?.messages) ? turn.messages : [];
+    if (messages.length) {
+      for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        const text = messageText(message?.text);
+        if (!text) {
+          continue;
+        }
+        if (message?.role === "user") {
+          return "";
+        }
+        if (message?.role === "assistant") {
+          if (message.status === "inProgress") return "";
+          return text;
+        }
+      }
+      continue;
+    }
+    if (messageText(turn?.user?.text)) {
+      return "";
+    }
+    const assistantText = messageText(turn?.assistant?.text);
+    if (assistantText) {
+      if (turn.assistant.status === "inProgress") return "";
+      return assistantText;
+    }
+  }
+  return "";
+}
+
+export {
+  latestAssistantMessageAwaitingUserReply
+};

package/src/shared/conversation/streaming.js

@@ -16,10 +16,13 @@ export function mergeConversationStream(turns = [], snapshot = {}) {
   const result = [...turns];
   for (const message of messages) {
     const tail = result.at(-1);
-    const turn = tail && !tail.assistant && !tail.system
-      ? { ...tail, messages: [...messagesForTurn(tail)] }
-      : { turnId: `stream:${message.messageId}`, messages: [] };
-    if (turn.turnId === tail?.turnId) result[result.length - 1] = turn;
+    const authoredIndex = message.turnId ? result.findIndex(turn => turn.turnId === message.turnId) : -1;
+    const existing = authoredIndex >= 0 ? result[authoredIndex] : !message.turnId && tail && !tail.assistant && !tail.system ? tail : null;
+    const turn = existing
+      ? { ...existing, messages: [...messagesForTurn(existing)] }
+      : { turnId: message.turnId || `stream:${message.messageId}`, messages: [] };
+    if (authoredIndex >= 0) result[authoredIndex] = turn;
+    else if (existing) result[result.length - 1] = turn;
     else result.push(turn);
     turn.messages.push(message);
     turn.pending = true;

package/src/shared/index.js

@@ -54,3 +54,5 @@ export {
 
 export { parseJsonObject } from "./support/jsonObject.js";
 export { toPositiveInteger } from "./support/positiveInteger.js";
+
+export { isAssistantProgressOnlyText } from "./assistantResponseText.js";

package/src/shared/nativeProviders.js

@@ -0,0 +1,45 @@
+// Native integration facts, separate from an application's offered models,
+// recommended thinking levels, account permissions and billing presentation.
+const model = (id, contextWindow, variants, options = {}) => Object.freeze({
+  id, contextWindow, variants: Object.freeze(variants), ...options
+});
+
+const NATIVE_AI_PROVIDERS = Object.freeze([
+  Object.freeze({
+    id: "deepseek", baseUrl: "https://api.deepseek.com/", claudeBaseUrl: "https://api.deepseek.com/anthropic",
+    claudeAutoCompactWindow: 786432, webSearch: false,
+    models: Object.freeze([
+      model("deepseek-flash", 1048576, ["low", "high", "max"], { images: true, freeformPatch: true, codexHistoryRouting: true }),
+      model("deepseek-v4-pro", 1048576, ["low", "high", "max"], { freeformPatch: true })
+    ])
+  }),
+  Object.freeze({
+    id: "zai-coding-plan", baseUrl: "https://api.z.ai/api/v1", claudeBaseUrl: "https://api.z.ai/api/anthropic",
+    claudeAutoCompactWindow: 1000000, webSearch: false,
+    models: Object.freeze([
+      model("glm-5.3", 1048576, ["low", "high", "max"], { freeformPatch: true, codexHistoryRouting: true })
+    ])
+  }),
+  Object.freeze({
+    id: "zai", baseUrl: "https://api.z.ai/api/v1", claudeBaseUrl: "https://api.z.ai/api/anthropic",
+    claudeAutoCompactWindow: 1000000, webSearch: false,
+    models: Object.freeze([
+      model("glm-5.3", 1048576, ["low", "high", "max"], { freeformPatch: true, codexHistoryRouting: true })
+    ])
+  })
+]);
+
+function nativeAiProvider(id) {
+  return NATIVE_AI_PROVIDERS.find(provider => provider.id === id) || null;
+}
+
+function nativeAiModel(id, providerId = "") {
+  for (const provider of NATIVE_AI_PROVIDERS) {
+    if (providerId && provider.id !== providerId) continue;
+    const model = provider.models.find(candidate => candidate.id === id);
+    if (model) return { ...model, modelProviderId: provider.id };
+  }
+  return null;
+}
+
+export { NATIVE_AI_PROVIDERS, nativeAiProvider, nativeAiModel };

package/src/testing/conversationStorageContract.js

@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
 import { createConversationTranscript } from "../server/conversation/transcript.js";
 
 /** Run against an app's isolated adapter fixture; never point this at production data. */
-export async function verifyConversationStorageContract(storage) {
+export async function verifyConversationStorageContract(storage, { runtime = false } = {}) {
   const transcript = createConversationTranscript({ storage, clock: () => new Date("2026-01-01T00:00:00Z") });
   const scope = "actor-a:workspace-a:conversation-a";
   const other = "actor-b:workspace-a:conversation-a";
@@ -31,5 +31,35 @@ export async function verifyConversationStorageContract(storage) {
   assert.deepEqual(older.conversationLog[0].messages.map((message) => message.role), ["user", "thinking", "commentary", "assistant"]);
   older.conversationLog[0].user.text = "Client mutation";
   assert.equal((await transcript.readConversationLog(scope))[0].user.text, "First question", "Reads must be detached snapshots.");
+  if (runtime) {
+    const retainedMetadata = (await storage.read(scope, transaction => transaction.readTurn(first.turnId))).metadata || {};
+    await storage.write(scope, async transaction => {
+      for (const method of ["readMetadata", "writeMetadata", "updateTurnMetadata"]) {
+        assert.equal(typeof transaction[method], "function", `Runtime storage requires ${method}().`);
+      }
+      await transaction.writeMetadata({ runtime: { receipt: "accepted" } });
+      await transaction.updateTurnMetadata(first.turnId, { product: { retained: true } });
+      await transaction.updateTurnMetadata(first.turnId, { runtime: { status: "complete" } });
+    });
+    const before = await storage.read(scope, async transaction => ({
+      metadata: await transaction.readMetadata(), turn: await transaction.readTurn(first.turnId), ids: await transaction.listTurnIds()
+    }));
+    assert.deepEqual(before.metadata, { runtime: { receipt: "accepted" } });
+    assert.deepEqual(before.turn.metadata, { ...retainedMetadata, product: { retained: true }, runtime: { status: "complete" } });
+    assert.deepEqual(await storage.read(other, transaction => transaction.readMetadata()), {}, "Metadata must remain scoped.");
+    const detached = await storage.read(scope, transaction => transaction.readMetadata());
+    detached.runtime.receipt = "client edit";
+    assert.deepEqual(await storage.read(scope, transaction => transaction.readMetadata()), before.metadata);
+    await assert.rejects(storage.write(scope, async transaction => {
+      await transaction.writeMetadata({ runtime: { receipt: "uncommitted" } });
+      await transaction.updateTurnMetadata(first.turnId, { runtime: { status: "uncommitted" } });
+      await transaction.appendMessage(await transaction.nextTurnId(), { role: "user", messageId: "uncommitted", text: "Uncommitted", at: "2026-01-01T00:00:00Z" });
+      throw new Error("contract-rollback");
+    }), /contract-rollback/);
+    const after = await storage.read(scope, async transaction => ({
+      metadata: await transaction.readMetadata(), turn: await transaction.readTurn(first.turnId), ids: await transaction.listTurnIds()
+    }));
+    assert.deepEqual(after, before, "Failed runtime writes must preserve transcript and metadata together.");
+  }
   return { scope, other, transcript };
 }

package/src/testing/nativeCodex.js

@@ -0,0 +1,11 @@
+// Original native probes for host integration tests. The test supplies its
+// executable or endpoint, authorization and cleanup.
+export { CodexAppServerJsonRpcClient } from "../server/conversation/codexClient.js";
+export { startCodexHistoryAdapter } from "../server/conversation/codexHistoryAdapter.js";
+export {
+  classifyCodexAppServerEvent,
+  codexAppServerErrorText,
+  codexAppServerNotificationUsageLimitExceeded,
+  codexAppServerOutputOwnerTurnId
+} from "../server/conversation/codexEvents.js";
+export { prepareCodexModelCatalog } from "../server/conversation/codexConfiguration.js";

package/src/testing/nativeOpenCode.js

@@ -0,0 +1,3 @@
+// Original loopback client for host integration tests. The test supplies its
+// endpoint, authorization and cleanup.
+export { createOpenCodeServerClient } from "../server/conversation/openCodeClient.js";

package/test/aiConnectionClient.test.js

@@ -42,6 +42,7 @@ test("the configured public AI integration streams its first chunk before comple
   assert.equal((await second).value.choices[0].delta.content, " there");
   await writer.write(new TextEncoder().encode('data: {"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}\n\n'));
   await writer.close();
+  assert.equal((await iterator.next()).value.choices[0].finish_reason, "stop");
   assert.equal((await iterator.next()).done, true);
 });
 
@@ -120,6 +121,7 @@ test("legacy Anthropic configuration streams through the native Messages protoco
   await send({ type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 2 } });
   await send({ type: "message_stop" });
   await writer.close();
+  assert.equal((await iterator.next()).value.choices[0].finish_reason, "stop");
   assert.equal((await iterator.next()).done, true);
 });
 

package/test/apiConversationDriver.test.js

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createApiConversationDriver } from "../src/server/conversation/providers/api.js";
+
+const frame = (delta, finish_reason) => `data: ${JSON.stringify({ choices: [{ index: 0, delta, finish_reason }] })}\n\n`;
+const schema = tool => ({ type: "function", function: { name: tool.name, parameters: tool.parameters } });
+function fixture({ response, execute, descriptors = [{ name: "action_execute", parameters: { type: "object" } }],
+  authorize = () => {}, limits } = {}) {
+  const requests = [], executions = [], messages = [];
+  let accepted = false;
+  const driver = createApiConversationDriver({ limits, connections: { resolve: async () => {
+    await authorize();
+    return { providerId: "test", model: "exact-model", sdkPackage: "@ai-sdk/openai-compatible",
+      apiKey: "test", baseURL: "http://test.invalid/v1" };
+  } }, fetch: (_url, request) => {
+    requests.push(JSON.parse(request.body));
+    const value = response(requests.length);
+    return new Response(frame(value.call ? { tool_calls: [{ index: 0, id: `call_${requests.length}`,
+      function: { name: value.call, arguments: "{}" } }] } : { content: value.text }, value.call ? "tool_calls" : "stop"),
+    { headers: { "content-type": "text/event-stream" } });
+  } });
+  return { requests, executions, messages, run: (text = "Complete the task.") => driver.run({
+    configuration: { systemPrompt: "Use the supplied actions.", integrationId: "assistant" },
+    context: { subjectId: "owner" }, input: { messageId: "request", text }, history: [],
+    signal: new AbortController().signal, beforeDispatch: async () => {}, accept: async () => { accepted = true; },
+    onMessage: async message => { messages.push(message); },
+    tools: { descriptors, schemas: descriptors.map(schema), maximumArgumentBytes: 32768,
+      async execute(input) {
+        assert.equal(accepted, true, "Preflight and ordinary actions require prior admission");
+        executions.push(input);
+        return execute?.(input, executions.length) ?? { ok: true, result: { sequence: executions.length } };
+      }
+    }
+  }) };
+}
+
+// Original assistant-runtime exhaustion assertions, using the actual API driver
+// and confirmed provider framing instead of its former private loop harness.
+test("the API owner preserves sixteen tool rounds and three recovery passes", async () => {
+  const f = fixture({ response: round => round <= 16 ? { call: "action_execute" } : { text: "Let me prepare the answer." } });
+  await f.run();
+  assert.equal(f.executions.length, 16);
+  assert.equal(f.requests.length, 19);
+  assert.deepEqual(f.messages.filter(message => message.complete && message.role === "assistant").map(message => message.text),
+    ["Limit reached. Start a new conversation."]);
+  assert.equal(new Set(f.messages.filter(message => message.complete).map(message => message.id)).size, 4,
+    "Recovery commentary and the final answer retain independent identities");
+});
+
+test("clock preflight is admitted before execution and precedes model inference", async () => {
+  const descriptors = [{ name: "workspace_clock", parameters: { type: "object", properties: {} }, preflight: ["current-time"] }];
+  const f = fixture({ descriptors, response: () => ({ text: "It is Tuesday." }),
+    execute: () => ({ ok: true, result: { timeZone: "Australia/Perth" } }) });
+  await f.run("What day is it today?");
+  assert.deepEqual(f.executions.map(call => call.name), ["workspace_clock"]);
+  assert.equal(f.requests[0].messages.some(message => message.role === "tool" && /Australia\/Perth/.test(message.content)), true);
+  const denied = fixture({ descriptors, authorize: () => { throw new Error("Connection access revoked"); } });
+  await assert.rejects(denied.run("What time is it now?"), /Connection access revoked/);
+  assert.deepEqual(denied.executions, []);
+  assert.deepEqual(denied.requests, []);
+  const bounded = fixture({ descriptors, limits: { maxHistoryCharacters: 10 } });
+  await assert.rejects(bounded.run("What time is it now?"), /history limit/);
+  assert.deepEqual(bounded.executions, []);
+});
+
+test("unknown tool outcomes never enter ordinary failure recovery or request another action", async () => {
+  const f = fixture({ response: () => ({ call: "action_execute" }), execute: () => {
+    throw Object.assign(new Error("Inspect the interrupted action"), { code: "conversation_tool_outcome_unknown" });
+  } });
+  await assert.rejects(f.run(), { code: "conversation_tool_outcome_unknown" });
+  assert.equal(f.executions.length, 1);
+  assert.equal(f.requests.length, 1);
+});

package/test/assistantApiSurfaceHeader.test.js

@@ -100,3 +100,88 @@ test("assistant api omits surface header when surface id is empty", async () =>
   assert.equal(observed.length, 1);
   assert.equal(Object.hasOwn(observed[0].options || {}, "headers"), false);
 });
+
+test("canonical operations reuse the request owner, surface header and encoded conversation identity", async () => {
+  const calls = [];
+  const receipt = { status: "accepted", messageId: "question", turnId: "turn" };
+  const controller = new AbortController();
+  const api = createAssistantApi({
+    resolveBasePath: () => "/api/w/one/assistant/admin",
+    resolveSurfaceId: () => "AdMiN",
+    async request(url, options) { calls.push({ url, options }); return receipt; }
+  });
+  const id = "chat:one/two";
+  assert.equal(await api.readConversation(id, { signal: controller.signal }), receipt);
+  assert.equal(await api.sendConversationMessage(id, {
+    messageId: "question", text: "", attachmentIds: ["file-one"], steer: false,
+    actor: { id: "injected" }, context: { forged: true }, host: { nativeTools: true }, engine: "codex"
+  }), receipt);
+  assert.equal(await api.cancelConversation(id), receipt);
+  assert.equal(await api.inspectConversationDelivery(id, "question"), receipt);
+  const base = "/api/w/one/assistant/admin/conversations/chat%3Aone%2Ftwo";
+  assert.deepEqual(calls.map(call => call.url), [base, `${base}/messages`, `${base}/cancel`, `${base}/deliveries/question/inspect`]);
+  assert.deepEqual(calls.map(call => call.options.method), ["GET", "POST", "POST", "POST"]);
+  assert.ok(calls.every(call => call.options.headers["x-jskit-surface"] === "admin"));
+  assert.equal(calls[0].options.signal, controller.signal);
+  assert.deepEqual(calls[1].options.body, { messageId: "question", text: "", attachmentIds: ["file-one"], steer: false });
+  assert.equal(Object.hasOwn(calls[2].options, "body"), false);
+  assert.equal(Object.hasOwn(calls[3].options, "body"), false, "Inspection supplies only the stable path identity");
+
+  await api.sendConversationMessage(id, { messageId: "plain", text: "Exact\n  authored text" });
+  assert.deepEqual(calls[4].options.body, { messageId: "plain", text: "Exact\n  authored text" });
+  const goal = { action: "set", expectedSegmentId: "current", expectedGoalId: null,
+    messageId: "goal-one", objective: "Finish this", tokenBudget: 1000, attachmentIds: ["file-one"] };
+  await api.readConversationGoal(id);
+  await api.updateConversationGoal(id, { ...goal, actor: { id: "injected" }, engine: "codex",
+    attachments: [{ path: "/private/secret" }], host: { nativeTools: true } }, { signal: controller.signal });
+  assert.deepEqual(calls.slice(5).map(call => [call.url, call.options.method]), [[`${base}/goal`, "GET"], [`${base}/goal`, "POST"]]);
+  assert.deepEqual(calls[6].options.body, goal);
+  assert.equal(calls[6].options.signal, controller.signal);
+  await assert.rejects(api.streamChat({ input: "Legacy stream" }), /streamChat requires requestStream/);
+
+  const data = { clientId: "browser-one", focus: { sessionId: "authored-target" } };
+  await api.sendConversationMessage(id, { messageId: "with-data", text: "Use this capture", data,
+    actor: { id: "injected" }, context: { forged: true }, host: { nativeTools: true } });
+  assert.deepEqual(calls[7].options.body, { messageId: "with-data", text: "Use this capture", data });
+  assert.equal(calls[7].url, `${base}/messages`);
+  assert.equal(calls[7].options.headers["x-jskit-surface"], "admin");
+
+  const configuration = { effort: "high" };
+  const selection = { modelChoice: "catalogue-choice" };
+  await api.configureConversation(id, configuration, { signal: controller.signal });
+  await api.selectConversation(id, selection, { signal: controller.signal });
+  assert.deepEqual(calls.slice(8).map(call => [call.url, call.options.method, call.options.body]), [
+    [`${base}/configuration`, "PATCH", { configuration }],
+    [`${base}/selection`, "POST", { selection }]
+  ]);
+  assert.ok(calls.slice(8).every(call => call.options.signal === controller.signal &&
+    call.options.headers["x-jskit-surface"] === "admin"));
+
+  await api.readConversation(id, { beforeTurnId: "turn:one/two & three", limit: 20, signal: controller.signal,
+    actor: { id: "injected" }, context: { forged: true }, host: { nativeTools: true } });
+  assert.equal(calls[10].url, `${base}?beforeTurnId=turn%3Aone%2Ftwo+%26+three&limit=20`);
+  assert.equal(calls[10].options.method, "GET");
+  assert.equal(calls[10].options.signal, controller.signal);
+  assert.deepEqual(calls[10].options.headers, { "x-jskit-surface": "admin" });
+  assert.equal(Object.hasOwn(calls[10].options, "body"), false);
+  await api.readConversation(id, { beforeTurnId: "", limit: 0 });
+  assert.equal(calls[11].url, `${base}?limit=0`, "Explicit zero retains the original unbounded page query");
+});
+
+test("declared replacement client retains the surface, exact choice and abort signal", async () => {
+  const calls = [];
+  const api = createAssistantApi({
+    request: async (url, options) => { calls.push({ url, options }); return { ok: true }; },
+    resolveBasePath: () => "/api/assistant/app",
+    resolveSurfaceId: () => "app"
+  });
+  const controller = new AbortController();
+  const replacement = { operationId: "renew-one", expectedSegmentId: "observed-segment", choice: "renew" };
+  await api.replaceConversation("chat:one/two", replacement, { signal: controller.signal });
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].url, "/api/assistant/app/conversations/chat%3Aone%2Ftwo/replacement");
+  assert.equal(calls[0].options.method, "POST");
+  assert.deepEqual(calls[0].options.body, { replacement });
+  assert.deepEqual(calls[0].options.headers, { "x-jskit-surface": "app" });
+  assert.equal(calls[0].options.signal, controller.signal);
+});