@jskit-ai/assistant-core 0.1.240 → 0.1.242

package/src/server/conversation/openCodeTurn.js

@@ -1,7 +1,9 @@
 import { setTimeout as delay } from "node:timers/promises";
 import { openCodeAssistantMessageText as assistantMessageText } from "./openCodeClient.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeNullableText } from "./normalize.js";
 
-const text = value => String(value ?? "").trim();
+const text = normalizeNullableText;
 export const OPENCODE_INTERRUPT_TIMEOUT_MS = 5_000;
 const OPENCODE_EVENT_READY_TIMEOUT_MS = 120_000;
 
@@ -24,10 +26,7 @@ export function openCodeStructuredOutput(value = "") {
   return match ? match[1].trim() : original;
 }
 
-
-function record(value = null) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
+const record = value => isRecord(value) ? value : {};
 
 function openCodeEventSummary(event = {}) {
   const payload = record(event.data);
@@ -140,12 +139,11 @@ export async function inspectOpenCodeMessageAdmission(client, conversationId, in
   do {
     if (wait) signal.throwIfAborted();
     try {
-      // Do not create a missing native session or submit another prompt. Absence
-      // from bounded history is uncertainty, not proof of non-admission.
+      // Do not create a missing native session or submit another prompt.
       const readSignal = wait
         ? AbortSignal.any([signal, AbortSignal.timeout(OPENCODE_INTERRUPT_TIMEOUT_MS)])
         : signal;
-      const messages = await client.messages(conversationId, { limit: 100, order: "desc" }, { signal: readSignal });
+      const messages = await readOpenCodeMessagesUntil(client, conversationId, hasMessage(inputMessageId), { signal: readSignal });
       if (wait) signal.throwIfAborted();
       const accepted = openCodeMessageRows(messages).some((message) =>
         message.type === "user" && text(message.id) === inputMessageId);
@@ -178,7 +176,9 @@ export async function steerOpenCodeTurn(client, conversationId, turn, input, { s
   }
 }
 
-export async function dispatchOpenCodeTurn(client, conversationId, turn, input, options = {}) {
+// options.client and options.conversationId are read at each use, so callers can
+// pass getters that follow a replaced server.
+export async function dispatchOpenCodeTurn(turn, input, options = {}) {
   const { events, beforeDispatch, readiness, promptTimeoutMs } = options;
   turn.promptAttempted = false;
   if (events) await events.waitUntilReady(readiness);
@@ -188,20 +188,43 @@ export async function dispatchOpenCodeTurn(client, conversationId, turn, input,
   if (options.authorizeAttachments) {
     signal.throwIfAborted();
     if (input.attachments?.length) {
-      await (options.client ?? client).allowConversationAttachments(options.conversationId ?? conversationId, input.attachments);
+      await options.client.allowConversationAttachments(options.conversationId, input.attachments);
     }
     signal.throwIfAborted();
   }
   turn.promptAttempted = true;
   turn.mayBeRunning = true;
-  return (options.client ?? client).prompt(options.conversationId ?? conversationId, {
+  return options.client.prompt(options.conversationId, {
     ...input,
     delivery: input.delivery === "steer" ? "steer" : "queue",
     resume: true
   }, { signal: promptTimeoutMs ? AbortSignal.any([signal, AbortSignal.timeout(promptTimeoutMs)]) : signal });
 }
 
-// Native automatic compaction and its continuation belong to the admitted turn.
+const OPENCODE_MESSAGE_PAGE_SIZE = 100;
+
+// Native history pages run newest first. A long tool-using turn can outgrow one
+// page, so continue with older pages until `found` sees the rows it needs (or
+// history ends). The result keeps the client's `{ data }` message shape.
+export async function readOpenCodeMessagesUntil(client, conversationId, found, { signal } = {}) {
+  let rows = [];
+  let before = "";
+  const cursors = new Set();
+  for (;;) {
+    const page = await client.messages(conversationId, {
+      limit: OPENCODE_MESSAGE_PAGE_SIZE, ...(before ? { before } : {})
+    }, { signal });
+    signal?.throwIfAborted();
+    rows = openCodeMessageRows([...openCodeMessageRows(page), ...rows]);
+    if (found(rows) || !page?.nextCursor) return { data: rows };
+    if (cursors.has(page.nextCursor)) throw new Error("OpenCode repeated a native history cursor.");
+    cursors.add(page.nextCursor);
+    before = page.nextCursor;
+  }
+}
+
+const hasMessage = id => rows => rows.some(message => text(message?.id) === text(id));
+
 export function openCodeMessageRows(value = null) {
   const rows = Array.isArray(value) ? value : Array.isArray(value?.data) ? value.data : [];
   return rows
@@ -258,6 +281,7 @@ export async function projectOpenCodeConversationMessages(messages, expectedId,
   return { failure: result.error, providerApiFailure: text(result.message?.error?.name) === "APIError" };
 }
 
+// Native automatic compaction and its continuation belong to the admitted turn.
 export function openCodeRowsForInput(value = null, inputMessageId = "") {
   const rows = openCodeMessageRows(value);
   const index = rows.findIndex((message) => text(message?.id) === text(inputMessageId));
@@ -342,11 +366,8 @@ export async function waitForOpenCodeMessages(client, conversationId = "", input
   while (true) {
     signal?.throwIfAborted();
     const expectedInputMessageId = text(resolveInputMessageId());
-    const messages = await client.messages(conversationId, {
-      limit: 100,
-      order: "desc"
-    }, { signal });
-    signal?.throwIfAborted();
+    const messages = await readOpenCodeMessagesUntil(client, conversationId,
+      expectedInputMessageId ? hasMessage(expectedInputMessageId) : () => true, { signal });
     if (expectedInputMessageId !== text(resolveInputMessageId())) continue;
     if (typeof onMessages === "function") {
       await onMessages(messages, expectedInputMessageId);
@@ -516,10 +537,9 @@ export async function runOpenCodeConversationTurn(client, conversationId, input
   }
   let existingMessages;
   if (requireFreshHistory) {
-    existingMessages = openCodeMessageRows(await client.messages(
-      conversationId,
-      { limit: 100, order: "desc" }
-    ));
+    existingMessages = openCodeMessageRows(await readOpenCodeMessagesUntil(client, conversationId, rows => rows.some(
+      message => message?.type === "user" && text(message.id) !== inputMessageId
+    )));
     const unrelatedUserMessage = existingMessages.find((message) => (
       message?.type === "user" && text(message.id) !== inputMessageId
     ));
@@ -534,10 +554,7 @@ export async function runOpenCodeConversationTurn(client, conversationId, input
   // Hosts may build the approved prompt lazily, after the original identity and
   // freshness checks. The bounded turn keeps its separate receipt-history read.
   const { prompt, agent, model, timeoutMs = 180_000 } = input;
-  let messages = await client.messages(conversationId, {
-    limit: 100,
-    order: "desc"
-  });
+  let messages = await readOpenCodeMessagesUntil(client, conversationId, hasMessage(inputMessageId));
   let result = openCodeMessageResultForInput(messages, inputMessageId, { readError });
   let admitted = null;
   if (!result) {
@@ -567,10 +584,7 @@ export async function runOpenCodeConversationTurn(client, conversationId, input
       if (!inputAccepted && admitted) {
         try {
           inputAccepted = Boolean(openCodeMessageResultForInput(
-            await client.messages(conversationId, {
-              limit: 100,
-              order: "desc"
-            }),
+            await readOpenCodeMessagesUntil(client, conversationId, hasMessage(inputMessageId)),
             inputMessageId, { readError }
           ));
         } catch {

package/src/server/conversation/providers/claudeDriver.js

@@ -1,4 +1,5 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { jsonHash as hash } from "../normalize.js";
 import { homedir } from "node:os";
 import path from "node:path";
 import { realpath } from "node:fs/promises";
@@ -10,8 +11,8 @@ import { createClaudeConversationOwner, claudeNativeMessageId } from "../claudeT
 import { CLAUDE_APPLICATION_TOOL_SERVER } from "../claudeTools.js";
 import { createLocalConversationExecution } from "../localExecution.js";
 import { validateConversationConfiguration, validateConnectionModel } from "../configuration.js";
+import { SCOPED_CONVERSATION_CAPABILITIES, scopedConversationInput, unsupportedScopedConversation } from "./scoped.js";
 
-const hash = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const nativeInput = input => input.content?.length ? [...(input.text ? [{ type: "text", text: input.text }] : []),
   ...input.content.map(part => part.type === "text" ? part : { type: "image",
     source: { type: "base64", media_type: part.mediaType, data: part.image.toString("base64") } })] : input.text;
@@ -364,18 +365,9 @@ export function createClaudeConversationDriver({ connections, host = {}, limits
       const control = { current: null, disposed: false, cleanupFailure: null };
       const commandOptions = { acquire, reportFailure, entry,
         maximumOutput, maximumToolCalls: limits.maxToolCalls ?? 32, timeoutMs: limits.admissionTimeoutMs };
-      const scopedInput = (input = {}) => {
-        if (input.conversationId && String(input.conversationId).trim() !== scoped.conversationId) {
-          throw new TypeError("This operation belongs to a different scoped conversation.");
-        }
-        return { ...input, conversationId: scoped.conversationId };
-      };
-      const unsupported = () => { throw Object.assign(new Error("This original scoped conversation has no canonical message or goal receipt."), {
-        code: "conversation_unsupported"
-      }); };
+      const scopedInput = scopedConversationInput(scoped?.conversationId);
       return Object.freeze({
-        ...(scoped ? { capabilities: Object.freeze({ streaming: false, instructions: false, configuration: false,
-          goals: false, goalBudgets: false, goalCommands: Object.freeze({}), attachments: false, tools: false, nativeTools: false }),
+        ...(scoped ? { capabilities: SCOPED_CONVERSATION_CAPABILITIES,
           async sendNative({ input, context }) {
             input = scopedInput(input);
             return owner.startTurn(await acquire(context, input.conversationId, { operation: "start", input }), input);
@@ -393,7 +385,7 @@ export function createClaudeConversationDriver({ connections, host = {}, limits
           publishNative: event => conversation.publish({ ...event, goalChanged: event.reason === "claude-goal" })
         } : {}),
         async readGoal({ configuration, context }) {
-          if (scoped) return unsupported();
+          if (scoped) return unsupportedScopedConversation();
           if (supplied) {
             await acquire(context);
             const completeResult = supplied.completeResult?.(context);
@@ -407,7 +399,7 @@ export function createClaudeConversationDriver({ connections, host = {}, limits
           return claudeGoalValue(await entry.goals.read(), entry.id);
         },
         async updateGoal({ configuration, context, input, representation, interrupt, send }) {
-          if (scoped) return unsupported();
+          if (scoped) return unsupportedScopedConversation();
           if (supplied) {
             await acquire(context);
             const completeResult = supplied.completeResult?.(context);
@@ -436,7 +428,7 @@ export function createClaudeConversationDriver({ connections, host = {}, limits
           return claudeGoalValue(await entry.goals.read(), entry.id);
         },
         async inspectAdmission({ context, representation, verifyAccount = false, ...input }) {
-          if (scoped) return unsupported();
+          if (scoped) return unsupportedScopedConversation();
           if (supplied) {
             await acquire(context);
             const result = await owner.inspectAdmission(await acquire(context), input);

package/src/server/conversation/providers/codexDriver.js

@@ -1,8 +1,8 @@
-import { createHash } from "node:crypto";
+import { jsonHash as hash } from "../normalize.js";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { open, realpath } from "node:fs/promises";
-import { createCodexAppServerRuntime } from "../codexProcess.js";
+import { CODEX_APP_SERVER_DESKTOP_BUS_ENV_NAMES, codexCommandHookDefinition, createCodexAppServerRuntime } from "../codexProcess.js";
 import { CodexAppServerAgentProvider, codexLocalImageInput, ensureCodexAppServerThread, codexApplicationToolConfiguration,
   assertCodexApplicationToolSchemaIdentity, inspectCodexAppServerMessageAdmission, retireCodexConversationHistory } from "../codexProvider.js";
 import { createCodexAppServerProviderOwner } from "../codexProviderOwner.js";
@@ -11,11 +11,11 @@ import { nativeAiProvider, nativeAiModel } from "../../../shared/nativeProviders
 import { createCodexAppServerRunOwner, codexAppServerTurnState, codexAppServerFrozenTurnInterruptResponse } from "../codexTurn.js";
 import { createLocalConversationExecution } from "../localExecution.js";
 import { validateConversationConfiguration, validateConnectionModel } from "../configuration.js";
+import { createScopedConversationHandle } from "./scoped.js";
 import { codexCommandHookCommand } from "../commandWrapper.js";
 import { isCompletedEnvelopeTurn } from "../transcript.js";
 import { createInertCodexConversationBinding } from "../runtimeStateUpgrade.js";
 
-const hash = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const goalValue = goal => goal ? {
   id: hash([goal.threadId, goal.createdAt, goal.objective]), objective: goal.objective, status: goal.status,
   tokenBudget: goal.tokenBudget ?? null, tokensUsed: goal.tokensUsed, timeUsedSeconds: goal.timeUsedSeconds,
@@ -237,34 +237,18 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
         const { conversationId, context: openingContext } = supplied.scoped;
         const { runOwner: owner } = supplied;
         const sessionId = conversation.sessionId;
-        const inputFor = (input = {}) => {
-          if (input.conversationId && String(input.conversationId).trim() !== conversationId) {
-            throw new TypeError("This operation belongs to a different scoped conversation.");
-          }
-          return { ...input, conversationId };
-        };
-        const unsupported = () => { throw Object.assign(new Error("This original scoped conversation has no canonical message or goal receipt."), {
-          code: "conversation_unsupported"
-        }); };
-        return Object.freeze({
-          capabilities: Object.freeze({ streaming: false, instructions: false, configuration: false,
-            goals: false, goalBudgets: false, goalCommands: Object.freeze({}), attachments: false, tools: false, nativeTools: false }),
-          // These are the original scoped commands, including their native
-          // start dedup, watcher/deadline and Stop/delete proof. No main journal
-          // or additional command queue is introduced for this representation.
-          sendNative: ({ input, context }) => owner.startConversationTurn(sessionId, inputFor(input), context),
-          readNative: ({ input, context }) => owner.readConversation(sessionId, inputFor(input), context),
-          waitNative: ({ input, context }) => owner.waitForConversationTurn(sessionId, inputFor(input), context),
-          cancel: ({ input, context }) => owner.stopConversation(sessionId, inputFor(input), context),
-          readGoal: unsupported, updateGoal: unsupported, inspectAdmission: unsupported,
-          async dispose(options) {
-            if (options) return owner.deleteConversation(sessionId, inputFor(options.input), options.context);
-            // Runtime shutdown retains the parent's cleanup receipt. Explicit
-            // scoped deletion above owns native deletion and its proof.
-            const result = await disposeNative({ sessionId, namespace: conversation.namespace, native: supplied, options: openingContext });
-            if (result?.ok === false) throw Object.assign(new Error(result.error || "Scoped cleanup could not be confirmed."), result);
-            return result;
-          }
+        // These are the original scoped commands, including their native
+        // start dedup, watcher/deadline and Stop/delete proof. No main journal
+        // or additional command queue is introduced for this representation.
+        return createScopedConversationHandle({ conversationId,
+          sendNative: (input, context) => owner.startConversationTurn(sessionId, input, context),
+          readNative: (input, context) => owner.readConversation(sessionId, input, context),
+          waitNative: (input, context) => owner.waitForConversationTurn(sessionId, input, context),
+          cancel: (input, context) => owner.stopConversation(sessionId, input, context),
+          deleteConversation: (input, context) => owner.deleteConversation(sessionId, input, context),
+          // Runtime shutdown retains the parent's cleanup receipt. Explicit
+          // scoped deletion above owns native deletion and its proof.
+          disposeOpening: () => disposeNative({ sessionId, namespace: conversation.namespace, native: supplied, options: openingContext })
         });
       }
       if (!supplied && (!binding || typeof binding.threadId !== "string" || binding.workdir !== await realpath(workdir) || binding.configRoot !== configRoot)) {
@@ -644,7 +628,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
             throw new Error("Codex did not install the host's required command wrapper.");
           }
           toolConfiguration.features.hooks = true;
-          toolConfiguration.hooks.PreToolUse = [{ matcher: "^Bash$", hooks: [{ type: "command", command: hookCommand, timeout: 30 }] }];
+          toolConfiguration.hooks.PreToolUse = codexCommandHookDefinition(hookCommand);
           toolConfiguration.hooks.state[owned[0].key] = { enabled: true, trusted_hash: owned[0].currentHash };
         }
         if (nativeTools) {
@@ -653,7 +637,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
           toolConfiguration.include_permissions_instructions = true;
           toolConfiguration.tools.update_plan.enabled = true;
           toolConfiguration.shell_environment_policy.set = Object.fromEntries(Object.entries(env).filter(([name, value]) =>
-            typeof value === "string" && !["DBUS_SESSION_BUS_ADDRESS", "DBUS_STARTER_ADDRESS", "DBUS_STARTER_BUS_TYPE"].includes(name)));
+            typeof value === "string" && !CODEX_APP_SERVER_DESKTOP_BUS_ENV_NAMES.has(name)));
           toolConfiguration.web_search = selected.config?.web_search || "disabled";
         }
         const params = { developerInstructions: configuration.systemPrompt,
@@ -1048,6 +1032,10 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
           let executingProvider;
           const toolCalls = new Set();
           const toolRegistrations = new Map();
+          // This run still owns the original native provider's current turn.
+          const ownsTurn = (provider, threadId, turnId) => current === active && !disposed && !signal.aborted &&
+            Boolean(provider) && provider === executingProvider && provider === native &&
+            threadId === binding.threadId && turnId === active.turnId;
           function toolHandler(provider, threadId, isRegistered = () => true) {
             return async ({ method, params }) => {
               if (method !== "item/tool/call" || !tools || params?.threadId !== (threadId || binding.threadId) || params.namespace ||
@@ -1080,9 +1068,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
                 try {
                   result = await tools.execute({ id: params.callId, name: params.tool, arguments: JSON.stringify(params.arguments) });
                 } catch (error) {
-                  if (!supplied && owned && current === active && !disposed && !signal.aborted &&
-                      provider === executingProvider && provider === native &&
-                      params.threadId === binding.threadId && params.turnId === active.turnId) active.toolFailure ||= error;
+                  if (!supplied && owned && ownsTurn(provider, params.threadId, params.turnId)) active.toolFailure ||= error;
                   throw error;
                 }
                 return { success: result.ok, contentItems: [{ type: "inputText", text: JSON.stringify(result) }] };
@@ -1187,9 +1173,8 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
             // A direct Stop checkpoint can throw before its native completion
             // reaches the queue. Keep the same admitted tool failure with the
             // original observation-stop owner until its pending recovery joins.
-            if (!supplied && error === active.toolFailure && current === active && !disposed && !signal.aborted &&
-                executingProvider && executingProvider === native && binding.threadId === failureThreadId &&
-                active.turnId === failureTurnId && error.code !== "codex_runtime_invalidated") {
+            if (!supplied && error === active.toolFailure && ownsTurn(executingProvider, failureThreadId, failureTurnId) &&
+                error.code !== "codex_runtime_invalidated") {
               toolFailureRecovery = executingProvider.failObservation(error);
             }
           }
@@ -1200,8 +1185,7 @@ export function createCodexConversationDriver({ connections, host = {}, limits =
             if (!supplied) await providerOwner.pendingRecovery(providerKey, executingProvider);
             if (toolFailureRecovery) {
               await toolFailureRecovery;
-              if (problem === active.toolFailureCleanup && current === active && !disposed && !signal.aborted &&
-                  executingProvider === native && binding.threadId === failureThreadId && active.turnId === failureTurnId &&
+              if (problem === active.toolFailureCleanup && ownsTurn(executingProvider, failureThreadId, failureTurnId) &&
                   !observationError && binding.observationLoss?.stopped === true) delete problem.cleanupFailed;
             }
           } catch (error) { problem = error; }

package/src/server/conversation/providers/opencodeDriver.js

@@ -1,4 +1,5 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { jsonHash as hash } from "../normalize.js";
 import { mkdir, realpath, rm } from "node:fs/promises";
 import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -7,11 +8,11 @@ import { createOpenCodeConversationServer, openCodeConversationAgent } from "../
 import { createOpenCodeSharedRuntime, ensureOpenCodeSession, openCodeServerForDirectory } from "../openCodeRuntime.js";
 import { openCodeAssistantMessageText, retireOpenCodeConversationHistory } from "../openCodeClient.js";
 import { inspectOpenCodeMessageAdmission, observeOpenCodeEvents, openCodeRowsForInput,
-  openCodeDetachedPrompt, openCodeStructuredOutput } from "../openCodeTurn.js";
+  openCodeDetachedPrompt, openCodeStructuredOutput, readOpenCodeMessagesUntil } from "../openCodeTurn.js";
 import { createOpenCodeToolBridge } from "../openCodeTools.js";
 import { validateConversationConfiguration, validateConnectionModel } from "../configuration.js";
+import { createScopedConversationHandle } from "./scoped.js";
 
-const hash = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
 const nativeMessageId = id => `msg_jskit_${hash(id).slice(0, 40)}`;
 
 // Original standalone native-use validation and authored admission, shared by
@@ -28,7 +29,11 @@ async function executeOpenCodeApplicationTool({ active, turn, target, sessionId,
   const observed = AbortSignal.any([signal, turn.abortController.signal]);
   await turn.admission?.promise;
   observed.throwIfAborted();
-  const messages = await target.server.client.messages(sessionId, { limit: 100 }, { signal: observed });
+  // Read back to an admitted input that precedes the native tool use.
+  const messages = await readOpenCodeMessagesUntil(target.server.client, sessionId, rows => {
+    const index = rows.findIndex(row => row.id === input.messageId);
+    return index >= 0 && rows.slice(0, index).some(row => active.messageIds.has(row.id));
+  }, { signal: observed });
   let message;
   let owner;
   for (const [nativeId, authored] of active.messageIds) {
@@ -159,44 +164,14 @@ export function createOpenCodeConversationDriver({ connections, host = {}, limit
         const supplied = conversation.native;
         const { owner, preparation } = supplied;
         const { conversationId, context: openingContext } = supplied.scoped;
-        const inputFor = (input = {}) => {
-          if (input.conversationId && String(input.conversationId).trim() !== conversationId) {
-            throw new TypeError("This operation belongs to a different scoped conversation.");
-          }
-          return { ...input, conversationId };
-        };
-        const unsupported = () => { throw Object.assign(new Error("This original scoped conversation has no canonical message or goal receipt."), {
-          code: "conversation_unsupported"
-        }); };
-        return Object.freeze({
-          capabilities: Object.freeze({ streaming: false, instructions: false, configuration: false,
-            goals: false, goalBudgets: false, goalCommands: Object.freeze({}), attachments: false, tools: false, nativeTools: false }),
-          async sendNative({ input, context }) {
-            return owner.runPreparedConversationTurn(await preparation.turn(inputFor(input), context));
-          },
-          async readNative({ input, context }) {
-            const request = inputFor(input);
-            return owner.readPreparedConversation(await preparation.existing(request, context), request);
-          },
-          async waitNative({ input, context }) {
-            const request = inputFor(input);
-            return owner.waitPreparedConversationTurn(await preparation.existing(request, context), request);
-          },
-          async cancel({ input, context }) {
-            const request = inputFor(input);
-            return owner.stopPreparedConversation(await preparation.existing(request, context), request);
-          },
-          readGoal: unsupported, updateGoal: unsupported, inspectAdmission: unsupported,
-          async dispose(options) {
-            if (options) {
-              const request = inputFor(options.input);
-              const prepared = await preparation.existing(request, options.context, { operation: "delete" });
-              return owner.deletePreparedConversation(prepared, request);
-            }
-            const result = await disposeNative({ native: supplied, options: openingContext });
-            if (result?.ok === false) throw Object.assign(new Error(result.error || "Scoped cleanup could not be confirmed."), result);
-            return result;
-          }
+        return createScopedConversationHandle({ conversationId,
+          sendNative: async (input, context) => owner.runPreparedConversationTurn(await preparation.turn(input, context)),
+          readNative: async (input, context) => owner.readPreparedConversation(await preparation.existing(input, context), input),
+          waitNative: async (input, context) => owner.waitPreparedConversationTurn(await preparation.existing(input, context), input),
+          cancel: async (input, context) => owner.stopPreparedConversation(await preparation.existing(input, context), input),
+          deleteConversation: async (input, context) => owner.deletePreparedConversation(
+            await preparation.existing(input, context, { operation: "delete" }), input),
+          disposeOpening: () => disposeNative({ native: supplied, options: openingContext })
         });
       }
       if (conversation?.native) {

package/src/server/conversation/providers/scoped.js

@@ -1,4 +1,4 @@
-import { normalizeText } from "../normalize.js";
+import { normalizeNullableText } from "../normalize.js";
 import { createConversationChangeover } from "../continuity.js";
 
 // The host retains profile authority and durable parent receipts. This original
@@ -7,11 +7,11 @@ export async function runScopedConversationTurn({ operations, scope = {}, input
   executionProfile: profileSnapshot } = {}) {
   const request = { ...input, ephemeral: true, message: input.prompt || input.message };
   options.signal?.throwIfAborted();
-  let conversationId = normalizeText(input.conversationId || input.threadId);
+  let conversationId = normalizeNullableText(input.conversationId || input.threadId);
   if (!conversationId) {
     const created = await operations.createEphemeralConversation(scope, request, options);
     if (created?.ok === false) return created;
-    conversationId = normalizeText(created.conversationId);
+    conversationId = normalizeNullableText(created.conversationId);
     if (!conversationId) throw new Error("The helper did not return its conversation identity.");
   }
   // Await ownership before starting: Stop or a failed parent write must not
@@ -20,7 +20,7 @@ export async function runScopedConversationTurn({ operations, scope = {}, input
   options.signal?.throwIfAborted();
   const started = await operations.startEphemeralConversationTurn(scope, { ...request, conversationId }, options);
   if (started?.ok === false) return { ...started, threadId: conversationId };
-  const runId = normalizeText(started.runId);
+  const runId = normalizeNullableText(started.runId);
   await options.onEvent?.({ type: "turn", threadId: conversationId, turnId: runId, status: started.status });
   if (options.signal?.aborted) {
     const stopped = await operations.stopEphemeralConversation(scope, { ...request, conversationId, runId }, options);
@@ -56,6 +56,50 @@ export async function runScopedConversationTurn({ operations, scope = {}, input
       error: result.error || "The helper stopped before completing its answer." } : {}) };
 }
 
+export const SCOPED_CONVERSATION_CAPABILITIES = Object.freeze({ streaming: false, instructions: false, configuration: false,
+  goals: false, goalBudgets: false, goalCommands: Object.freeze({}), attachments: false, tools: false, nativeTools: false });
+
+/** Bind an operation's input to this scoped conversation, refusing another one. */
+export function scopedConversationInput(conversationId) {
+  return (input = {}) => {
+    if (input.conversationId && String(input.conversationId).trim() !== conversationId) {
+      throw new TypeError("This operation belongs to a different scoped conversation.");
+    }
+    return { ...input, conversationId };
+  };
+}
+
+export function unsupportedScopedConversation() {
+  throw Object.assign(new Error("This original scoped conversation has no canonical message or goal receipt."), {
+    code: "conversation_unsupported"
+  });
+}
+
+/**
+ * Driver handle for an original scoped conversation. Each engine supplies its
+ * native owner calls; every call receives input bound to `conversationId`.
+ * `disposeOpening` releases the opening without deleting the native conversation.
+ */
+export function createScopedConversationHandle({ conversationId, sendNative, readNative, waitNative, cancel,
+  deleteConversation, disposeOpening }) {
+  const inputFor = scopedConversationInput(conversationId);
+  return Object.freeze({
+    capabilities: SCOPED_CONVERSATION_CAPABILITIES,
+    sendNative: async ({ input, context }) => sendNative(inputFor(input), context),
+    readNative: async ({ input, context }) => readNative(inputFor(input), context),
+    waitNative: async ({ input, context }) => waitNative(inputFor(input), context),
+    cancel: async ({ input, context }) => cancel(inputFor(input), context),
+    readGoal: unsupportedScopedConversation, updateGoal: unsupportedScopedConversation,
+    inspectAdmission: unsupportedScopedConversation,
+    async dispose(options) {
+      if (options) return deleteConversation(inputFor(options.input), options.context);
+      const result = await disposeOpening();
+      if (result?.ok === false) throw Object.assign(new Error(result.error || "Scoped cleanup could not be confirmed."), result);
+      return result;
+    }
+  });
+}
+
 const messageWriters = {
   assistant: "writeConversationAssistantMessage",
   commentary: "writeConversationCommentaryMessage",