@jskit-ai/assistant-core 0.1.200 → 0.1.201

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

@@ -0,0 +1,136 @@
+import { conversationRequestText } from "../continuity.js";
+import { validateConversationConfiguration, validateConnectionModel } from "../configuration.js";
+import { consumeCompletionStream, sanitizeAssistantMessageText } from "../../lib/assistantCompletion.js";
+import { runAssistantToolLoop } from "../../lib/assistantToolLoop.js";
+import { isAssistantProgressOnlyText } from "../../../shared/assistantResponseText.js";
+
+// Preserve the original assistant service's model-facing action result. The
+// durable receipt keeps its full ok/result/error envelope in common storage.
+const toolResultContent = result => JSON.stringify(result.ok ? result.result ?? null : { error: result.error });
+
+/** Direct API inference uses the same authorized connection catalogue as other JSKIT services. */
+export function createApiConversationDriver({ connections, apiClientFactory, fetch, limits = {} }) {
+  if (apiClientFactory !== undefined && typeof apiClientFactory?.resolveClient !== "function") {
+    throw new TypeError("An API client factory requires resolveClient({ context, configuration }).");
+  }
+  if (!apiClientFactory && typeof connections?.resolve !== "function") throw new TypeError("API conversations require an authorized AI connection resolver.");
+  const maximumOutput = limits.maxOutputCharacters ?? 64_000;
+  const maximumHistory = limits.maxHistoryCharacters ?? 256_000;
+  const preserveWhitespace = apiClientFactory?.preserveWhitespace !== false;
+  for (const limit of [maximumOutput, maximumHistory]) {
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError("Invalid API conversation limit.");
+  }
+  const driver = Object.freeze({
+    admissionBeforeDispatch: true,
+    attachmentTypes: ["text", "image", "file"],
+    capabilities: Object.freeze({ streaming: true, cancellation: true, instructions: true,
+      configuration: true, history: true, steering: false, goals: false, attachments: true, tools: true, nativeTools: false, structuredOutput: false }),
+    open() { return { run: driver.run, dispose: async () => {} }; },
+    validateConfiguration(configuration) {
+      validateConversationConfiguration(configuration, { engine: "API", connections, apiClientFactory, connectionRequired: true,
+        efforts: ["none", "minimal", "low", "medium", "high", "xhigh"] });
+    },
+    async run({ configuration, context, input, history, requestHistory, continuity, tools, signal, accept, beforeDispatch, onMessage }) {
+      const { createAiConnectionClient } = await import("../../lib/aiConnectionClient.js");
+      const content = message => message.content?.length
+        ? [...(message.text ? [{ type: "text", text: message.text }] : []), ...message.content] : message.text;
+      const messages = [
+        { role: "system", content: configuration.systemPrompt },
+        ...(continuity ? [{ role: "user", content: continuity }] : []),
+        ...(requestHistory ?? history.flatMap(turn => [
+          ...(turn.user ? [{ role: "user", content: content({ ...turn.user, text: conversationRequestText(turn.user) }) }] : []),
+          ...(turn.system ? [{ role: "user", content: content({ ...turn.system, text: conversationRequestText({ ...turn.system, origin: "application" }) }) }] : []),
+          ...(turn.metadata?.applicationTools || []).filter(call => call.result).flatMap(call => [
+            { role: "assistant", content: "", tool_calls: [{ id: call.id, type: "function", function: { name: call.name, arguments: call.arguments } }] },
+            { role: "tool", tool_call_id: call.id, content: toolResultContent(call.result) }
+          ]),
+          ...(turn.assistant ? [{ role: "assistant", content: turn.assistant.text }] : [])
+        ])),
+        { role: "user", content: content(input) }
+      ];
+      let accepted = false;
+      let round = 0;
+      let responseId;
+      let responseIsCommentary = false;
+      async function prepareClient(inferenceMessages = messages) {
+        if (inferenceMessages.reduce((size, message) => size + (typeof message.content === "string" ? message.content.length
+          : message.content.reduce((count, part) => count + (part.type === "text" ? part.text.length : 0), 0)) +
+          (message.tool_calls ? JSON.stringify(message.tool_calls).length : 0), 0) > maximumHistory) {
+          throw new Error("This conversation exceeds the configured API history limit. Start another conversation or increase the limit.");
+        }
+        let client;
+        if (apiClientFactory) {
+          client = await apiClientFactory.resolveClient({ context, configuration });
+          if (!client?.enabled || typeof client.createChatCompletionStream !== "function") {
+            throw new Error("Assistant provider is not configured.");
+          }
+          validateConnectionModel(configuration, { model: client.defaultModel });
+        } else {
+          const connection = await connections.resolve({ context, integrationId: configuration.integrationId });
+          validateConnectionModel(configuration, connection);
+          client = createAiConnectionClient(connection, { fetch, effort: configuration.effort,
+            maxOutputTokens: limits.maxOutputTokens, timeoutMs: limits.timeoutMs });
+        }
+        signal.throwIfAborted();
+        await beforeDispatch();
+        if (!accepted) { await accept(); accepted = true; }
+        return client;
+      }
+      return runAssistantToolLoop({
+        messages, input: input.text, toolSet: { tools: tools?.descriptors || [] }, preserveWhitespace,
+        toToolSchema: tool => tools.schemas.find(schema => schema.function.name === tool.name),
+        async complete(messages, schemas) {
+          const id = responseId = `reply-${++round}`;
+          responseIsCommentary = false;
+          const client = await prepareClient(messages);
+          const completion = await consumeCompletionStream(
+            await client.createChatCompletionStream({ signal, messages, tools: schemas }),
+            async text => { if (text.trim()) await onMessage({ id, outputId: id, role: "assistant", text, complete: false }); },
+            { signal, preserveWhitespace, requireCallIds: true, callIdPrefix: `${id}:`,
+              limits: { maxOutputCharacters: maximumOutput, maxToolCalls: tools ? limits.maxToolCalls ?? 32 : 0,
+                maxToolArgumentBytes: tools?.maximumArgumentBytes ?? 0 } }
+          );
+          const { toolCalls: calls, toolCallSource } = completion;
+          // Environment clients expose the provider's original OpenAI spelling;
+          // SDK connection clients use the normalized equivalent.
+          const finishReason = completion.finishReason === "tool_calls" ? "tool-calls" : completion.finishReason;
+          const text = sanitizeAssistantMessageText(completion.assistantText, { preserveWhitespace });
+          if (finishReason === "length") throw new Error("The model reached its output token limit before completing the answer. Increase maxOutputTokens in the conversation limits.");
+          if (calls.length) {
+            if (finishReason !== (toolCallSource === "text" ? "stop" : "tool-calls")) throw new Error("The model stream ended without confirming its application tool calls.");
+          } else if (finishReason !== "stop") {
+            throw new Error("The model stream ended without confirming a completed answer.");
+          }
+          if (text.trim() && (calls.length || isAssistantProgressOnlyText(text))) {
+            responseIsCommentary = true;
+            await onMessage({ id, outputId: id, role: "commentary", text, complete: true });
+          }
+          return completion;
+        },
+        async executeToolCalls(calls, { toolFailures, toolSuccesses }) {
+          // The original preflight runs before inference, but never before the
+          // same authorized connection and durable admission as ordinary sends.
+          if (!accepted) await prepareClient();
+          const failures = [];
+          for (const call of calls) {
+            const result = await tools.execute(call);
+            messages.push({ role: "tool", tool_call_id: call.id, content: toolResultContent(result) });
+            if (result.ok) toolSuccesses.push({ name: call.name, result: result.result });
+            else {
+              const failure = { name: call.name, error: result.error };
+              failures.push(failure);
+              toolFailures.push(failure);
+            }
+          }
+          return failures;
+        },
+        async finish(text, { metadata = {} } = {}) {
+          const id = responseIsCommentary ? `reply-${++round}` : responseId;
+          await onMessage({ id, outputId: id, role: "assistant", text, complete: true });
+          return { metadata };
+        }
+      });
+    }
+  });
+  return driver;
+}

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

@@ -0,0 +1,63 @@
+import { createConversationSystemPrompt } from "../systemPrompt.js";
+
+/** One instance per native Claude conversation; process ownership stays with the host. */
+export function createClaudeConversationAdapter({ getProcess, isActive, startProcess, stopProcess } = {}) {
+  for (const callback of [getProcess, isActive, startProcess, stopProcess]) {
+    if (typeof callback !== "function") throw new TypeError("Claude requires process and activity callbacks.");
+  }
+  const instructions = createConversationSystemPrompt();
+  let pending = Promise.resolve();
+  let updateIdentity;
+  let installedMode;
+
+  function instructionArguments({ systemPrompt, instructionMode = "append" }) {
+    if (typeof systemPrompt !== "string" || !systemPrompt.trim()) throw new TypeError("Claude instructions must contain text.");
+    if (!["append", "replace"].includes(instructionMode)) throw new TypeError("Invalid instruction mode.");
+    // Claude otherwise restores its recorded system prompt on resume, ignoring
+    // changed prompt arguments until compaction. The host supplies current text.
+    return [instructionMode === "replace" ? "--system-prompt" : "--append-system-prompt", systemPrompt,
+      "--system-prompt-snapshot", "off"];
+  }
+
+  function prepare(input) {
+    // Check active work when this request reaches the front of the queue, so
+    // a queued change cannot stop a turn admitted during earlier preparation.
+    const operation = pending.catch(() => {}).then(async () => {
+      const { systemPrompt, settings, model, liveUpdateIdentity } = input;
+      const instructionMode = input.instructionMode || "append";
+      const contextIdentity = JSON.stringify([input.contextIdentity, instructionMode]);
+      if (!getProcess()) instructions.invalidate();
+      if (getProcess() && isActive() && !instructions.isCurrent({ systemPrompt, contextIdentity })) {
+        throw new Error("Stop the current Claude turn before changing its settings.");
+      }
+      return instructions.ensure({
+        systemPrompt,
+        contextIdentity,
+        install: async ({ promptChanged }) => {
+          let native = getProcess();
+          const canUpdate = native && !promptChanged && installedMode === instructionMode &&
+            liveUpdateIdentity !== undefined && updateIdentity === liveUpdateIdentity;
+          if (!canUpdate) {
+            // The host must prove owned cleanup before launching the successor.
+            await stopProcess("Claude's previous process was stopped before reconnecting.");
+            native = await startProcess({ ...input, instructionArguments: instructionArguments(input) });
+          }
+          try {
+            await native.client.request({ subtype: "apply_flag_settings", settings });
+            await native.client.request({ subtype: "set_model", model });
+          } catch (error) {
+            await stopProcess(error.message);
+            throw error;
+          }
+          updateIdentity = liveUpdateIdentity;
+          installedMode = instructionMode;
+          return native;
+        }
+      });
+    });
+    pending = operation;
+    return operation;
+  }
+
+  return Object.freeze({ prepare, instructionArguments, invalidate: instructions.invalidate, whenIdle: () => pending });
+}

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

@@ -0,0 +1,425 @@
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { bindClaudeConversationAccount, claudeFlagSettings, claudeModelConfiguration, readClaudeCodeAuthStatus } from "../claudeProcess.js";
+import { nativeAiModel, nativeAiProvider } from "../../../shared/nativeProviders.js";
+import { requireClaudeSessionId, listClaudeConversationStorage } from "../claudeHistory.js";
+import { createClaudeConversationOwner, claudeNativeMessageId } from "../claudeTurn.js";
+import { createLocalConversationExecution } from "../localExecution.js";
+import { validateConversationConfiguration, validateConnectionModel } from "../configuration.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;
+const claudeGoalValue = (goal, conversationId) => goal ? { ...goal,
+  id: hash([conversationId, goal.createdAt, goal.objective]),
+  ...(Number.isFinite(goal.createdAt) ? { createdAt: new Date(goal.createdAt * 1000).toISOString() } : {}),
+  ...(Number.isFinite(goal.updatedAt) ? { updatedAt: new Date(goal.updatedAt * 1000).toISOString() } : {})
+} : null;
+const goalCapabilities = Object.freeze({ goals: true, goalBudgets: false,
+  goalCommands: Object.freeze({
+    set: Object.freeze({ delivery: "message", interruptsTurn: false }),
+    resume: Object.freeze({ delivery: "message", interruptsTurn: false }),
+    pause: Object.freeze({ delivery: "control", interruptsTurn: true }),
+    cancel: Object.freeze({ delivery: "message", interruptsTurn: true })
+  }) });
+
+/** The ordinary native host uses the CLI's own login; no application launch callbacks. */
+export function createClaudeConversationDriver({ connections, host = {}, limits = {} } = {}) {
+  const env = { ...(host.env || process.env) };
+  const workdir = path.resolve(host.workdir || process.cwd());
+  const configRoot = path.resolve(workdir, env.CLAUDE_CONFIG_DIR || path.join(env.HOME || homedir(), ".claude"));
+  if (env.CLAUDE_CONFIG_DIR) env.CLAUDE_CONFIG_DIR = configRoot;
+  const command = host.commands?.claude || "claude";
+  const execution = host.execution || createLocalConversationExecution();
+  const nativeTools = host.nativeTools === true;
+  const pendingAccountStops = new Set();
+  const maximumOutput = limits.maxOutputCharacters ?? 64_000;
+  if (!Number.isSafeInteger(maximumOutput) || maximumOutput < 1) throw new TypeError("Invalid Claude output limit.");
+
+  async function stopAccount(id) {
+    pendingAccountStops.add(id);
+    try {
+      const proof = await execution.stop(id);
+      if (!proof?.scopeEmpty) throw new Error("Claude account process cleanup could not be confirmed.");
+      pendingAccountStops.delete(id);
+    } catch (error) { error.cleanupFailed = true; throw error; }
+  }
+
+  async function captureAccountStatus({ command, args, cwd, baseEnv, signal, timeout, maxBuffer }) {
+    signal.throwIfAborted();
+    const native = await execution.start({ command, args, cwd, env: baseEnv, stream: true, limits: host.limits });
+    const cancelled = Promise.withResolvers();
+    const abort = () => cancelled.reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    const result = (async () => {
+      native.stdin.end();
+      const chunks = [];
+      let bytes = 0;
+      for await (const chunk of native.stdout) {
+        bytes += chunk.length;
+        if (bytes > maxBuffer) throw new Error("Claude account status exceeded its size limit.");
+        chunks.push(chunk);
+      }
+      const exit = await native.exited;
+      return { ok: !exit.signal && exit.code === 0, exitCode: exit.code,
+        signal: exit.signal, stdout: Buffer.concat(chunks).toString("utf8") };
+    })();
+    let timer;
+    try {
+      return await Promise.race([result, cancelled.promise, new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Claude account status timed out.")), timeout);
+      })]);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      await stopAccount(native.id);
+    }
+  }
+
+  async function accountIdentity(signal) {
+    signal.throwIfAborted();
+    for (const id of pendingAccountStops) await stopAccount(id);
+    // Native API credentials already have an explicit identity. Never persist
+    // credentials or include them in configuration returned to the browser.
+    const key = env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY;
+    if (key) return hash([configRoot, env.ANTHROPIC_BASE_URL || "https://api.anthropic.com", key]);
+    const account = await readClaudeCodeAuthStatus({ command, env,
+      credentialHome: { home: env.HOME || homedir() }, commandRunner: captureAccountStatus, signal });
+    signal.throwIfAborted();
+    if (!account.loggedIn || !account.email) {
+      throw new Error(account.error || "Sign in with claude auth login before using this conversation.");
+    }
+    return hash([configRoot, account.authMethod, account.email.toLowerCase()]);
+  }
+
+  let standalone;
+  function standaloneOwner() {
+    if (standalone) return standalone;
+    const store = {
+      read(context) { return JSON.stringify({ executionId: context.binding.executionId, sent: context.binding.sent }); },
+      async save(entry, { execution = false } = {}) {
+        if (execution) await entry.context.updateBinding({ executionId: entry.executionId });
+      },
+      async releaseExecution(entry) {
+        await entry.context.updateBinding({ executionId: "" });
+        entry.executionId = "";
+      }
+    };
+    standalone = createClaudeConversationOwner({ configRoot, store,
+      preparation: {
+        async configuration(entry, { configuration, context, signal, tools }) {
+          const { selected, identity } = await bindAccount(entry, configuration, context, signal);
+          const settings = claudeFlagSettings({ effort: configuration.effort, providerEnv: selected.env });
+          return { systemPrompt: configuration.systemPrompt, instructionMode: "replace",
+            model: selected.model, settings, external: Boolean(configuration.integrationId),
+            contextIdentity: JSON.stringify([configuration, identity, Boolean(tools)]),
+            liveUpdateIdentity: JSON.stringify([Boolean(tools), configuration.outputSchema ?? null]),
+            outputSchema: configuration.outputSchema };
+        },
+        message: (_entry, input) => nativeInput(input)
+      },
+      process: {
+        stopExecution: (id, options) => execution.stop(id, options),
+        configure(entry, { instructionArguments, model, settings, external, outputSchema }) {
+          return { execution, command, env, model: external ? "" : model,
+            settings: claudeFlagSettings(), effort: settings.effortLevel || "", instructionArguments,
+            toolFree: !nativeTools, isolated: true, permissionMode: nativeTools ? "bypassPermissions" : undefined, outputSchema,
+            commandWrapper: host.commandWrapper, applicationTools: Boolean(entry.command.tools),
+            executionLimits: host.limits, signal: entry.command.signal };
+        }
+      },
+      async onEvent(entry, event) {
+        if (event.type === "save") return store.save(entry);
+        if (event.type === "binding-admitted") {
+          await entry.context.updateBinding({ sent: true });
+          entry.sent = true;
+          return;
+        }
+        const current = entry.command;
+        if (!current) return;
+        if (event.type === "message") await current.onMessage({ ...event.message, transient: !event.message.complete });
+        else if (event.type === "message-complete") await current.onEvent(event);
+        else if ((event.type === "admitted" && current.goal) || event.type === "settled") {
+          await current.onEvent({ type: "goal", goal: claudeGoalValue(await entry.goals.read(), entry.id) });
+        } else if (event.type === "phase") await current.onEvent({ type: "phase", phase: event.phase === "compacting" ? "compacting" : "working" });
+      }
+    });
+    return standalone;
+  }
+
+  async function bindAccount(entry, configuration, context, signal = AbortSignal.timeout(30_000)) {
+    let selected;
+    let providerId;
+    let identity;
+    if (configuration.integrationId) {
+      const connection = await connections.resolve({ context, integrationId: configuration.integrationId });
+      signal.throwIfAborted();
+      providerId = connection.providerId;
+      const provider = nativeAiProvider(providerId);
+      const model = nativeAiModel(connection.model, providerId);
+      if (providerId !== "anthropic" && (!provider || !model)) throw new Error("This exact provider/model is not supported by the Claude integration. Choose a supported model without renaming it.");
+      validateConnectionModel(configuration, connection);
+      if (model && configuration.effort && !model.variants.includes(configuration.effort)) throw new Error("The selected Claude model does not support this reasoning effort.");
+      selected = claudeModelConfiguration({ providerId, model: connection.model }, {
+        apiKey: connection.apiKey, baseUrl: provider?.claudeBaseUrl || connection.baseURL || "https://api.anthropic.com"
+      });
+      identity = hash([configRoot, providerId, selected.env.ANTHROPIC_BASE_URL, connection.apiKey]);
+    } else {
+      identity = await accountIdentity(signal);
+      selected = claudeModelConfiguration({ providerId: "anthropic", model: configuration.model || "default" });
+      // Returning to the native host clears connection overrides, while
+      // retaining explicitly supplied standalone host credentials/routing.
+      for (const name of Object.keys(selected.env)) if (Object.hasOwn(env, name)) selected.env[name] = env[name];
+    }
+    signal.throwIfAborted();
+    const previous = providerId ? entry.context.binding.connectionIdentities?.[providerId] : entry.context.binding.accountIdentity;
+    await bindClaudeConversationAccount({ accountIdentity: previous,
+      accountIdentities: { [providerId || "anthropic"]: previous }
+    }, { identity, providerId: providerId || "anthropic",
+      stop: (_entry, reason) => entry.nativeTurn.stopProcess(reason),
+      save: account => entry.context.updateBinding(providerId
+        ? { connectionIdentities: { ...entry.context.binding.connectionIdentities, [providerId]: account.accountIdentity } }
+        : { accountIdentity: account.accountIdentity })
+    });
+    return { selected, identity };
+  }
+
+  async function disposeNative({ native, options }) {
+    const prepared = native.preparation.cleanup(options);
+    return native.owner.closeSession(prepared.context, prepared.application);
+  }
+
+  return Object.freeze({
+    admissionBeforeDispatch: false,
+    toolDiscovery: true,
+    attachmentTypes: ["text", "image"],
+    capabilities: Object.freeze({ streaming: true, cancellation: true, instructions: true,
+      configuration: true, history: true, steering: true, ...goalCapabilities,
+      attachments: true, tools: true, nativeTools, structuredOutput: true }),
+    validateConfiguration(configuration) {
+      validateConversationConfiguration(configuration, { engine: "Claude", connections, efforts: ["low", "medium", "high", "xhigh", "max"],
+        structuredOutput: true, maxOutputCharacters: maximumOutput });
+    },
+    async readState({ conversation, context, representation }) {
+      let nativeResult = null;
+      if (representation === "native" || context) {
+        const { owner } = conversation.native;
+        const entry = await owner.acquire(context);
+        nativeResult = { ok: true, thread: { id: entry.id }, turn: owner.snapshot(entry), workdir: entry.context.workdir };
+      }
+      return conversation.read(context, representation, nativeResult);
+    },
+    inspectTemporaryActivity({ native, context }) {
+      return native.owner.hasActiveTemporaryConversation(context, { acquire: native.owner.acquire });
+    },
+    releaseRenewalPredecessorProcessExitProof({ native, context }) {
+      return native.owner.closeSession(context, native.application);
+    },
+    releaseRenewalSuccessorProcessExitProof({ native, context }) {
+      return native.owner.closeSession(context, native.application);
+    },
+    async generateRenewalHandover({ native, input, context }) {
+      const prepared = native.preparation.handover(input, context);
+      const entry = await native.owner.acquire(context);
+      const result = await native.owner.renewal(entry, prepared.input, prepared.options, { context, acquire: native.owner.acquire });
+      return prepared.completeResult(result);
+    },
+    async seedRenewalHandover({ native, input, context }) {
+      const prepared = native.preparation.seed(input, context);
+      const entry = await native.owner.acquire(context);
+      const result = await native.owner.renewal(entry, prepared.input, prepared.options, { context, acquire: native.owner.acquire });
+      return prepared.completeResult(result);
+    },
+    async ensureConversation({ native, context }) {
+      const entry = await native.owner.acquire(context);
+      return native.owner.ensureReady(entry);
+    },
+    disposeNative,
+    async interruptDetachedConversation({ native, input, context }) {
+      const entry = await native.owner.acquire(context, input.conversationId || input.threadId,
+        { cleanupExecutionId: input.cleanupExecutionId });
+      return native.owner.stopConversation(entry);
+    },
+    async deleteDetachedConversation({ native, input, context }) {
+      const entry = await native.owner.acquire(context, input.conversationId || input.threadId,
+        { operation: "delete", input, cleanupExecutionId: input.cleanupExecutionId });
+      return native.owner.deleteConversation(entry);
+    },
+    listConversationStorage({ native, binding }) {
+      return listClaudeConversationStorage({ configRoot: native.configRoot, binding });
+    },
+    retireConversationHistory({ native, binding, context }) {
+      return native.owner.retireConversationHistory(native.preparation.retirement(binding, context));
+    },
+    closeProject({ native, input }) {
+      return native.owner.closeProject(input, native.application);
+    },
+    invalidateRuntimes({ native, input }) {
+      return native.owner.invalidateRuntimes(input, native.application, native.account);
+    },
+    reconcileSessions({ native, sessions, options }) {
+      return native.owner.reconcileSessions(sessions, options, native.application);
+    },
+    async createConversation({ native, input, context }) {
+      return native.owner.createConversation(input, { context, acquire: native.owner.acquire });
+    },
+    async createBinding() {
+      return { conversationId: randomUUID(), workdir: await realpath(workdir), configRoot, executionId: "", sent: false };
+    },
+    async open({ binding, writeBinding, onFailure: reportFailure, conversation }) {
+      const supplied = conversation?.native;
+      const scoped = supplied?.scoped;
+      let owner = supplied?.owner;
+      let entry;
+      if (!supplied) {
+        requireClaudeSessionId(binding?.conversationId);
+        if (binding.workdir !== await realpath(workdir) || binding.configRoot !== configRoot) {
+          throw new Error("This Claude conversation belongs to another working directory or credential home. Restore its original host configuration.");
+        }
+        owner = standaloneOwner();
+        const context = { key: binding.workdir, workdir: binding.workdir, binding, reportFailure,
+          async updateBinding(patch) {
+            const next = { ...context.binding, ...patch };
+            await writeBinding(next);
+            context.binding = next;
+          }
+        };
+        entry = await owner.open(context, { conversationId: binding.conversationId, mainId: binding.conversationId, create: true });
+        // An unknown execution is never reclaimed by PID or silently abandoned.
+        // Managed hosts can prove cleanup using their durable execution identity.
+        if (binding.executionId) await entry.nativeTurn.stopProcess("The application reconnected to this conversation.");
+      }
+      const acquire = supplied ? owner.acquire : (() => entry);
+      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"
+      }); };
+      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 }),
+          async sendNative({ input, context }) {
+            input = scopedInput(input);
+            return owner.startTurn(await acquire(context, input.conversationId, { operation: "start", input }), input);
+          },
+          async readNative({ input, context }) {
+            input = scopedInput(input);
+            return owner.read(await acquire(context, input.conversationId), input);
+          },
+          async waitNative({ input, context }) {
+            input = scopedInput(input);
+            return owner.wait(await acquire(context, input.conversationId), input, { context, acquire });
+          }
+        } : {}),
+        ...(supplied && !scoped ? {
+          publishNative: event => conversation.publish({ ...event, goalChanged: event.reason === "claude-goal" })
+        } : {}),
+        async readGoal({ configuration, context }) {
+          if (scoped) return unsupported();
+          if (supplied) {
+            await acquire(context);
+            const completeResult = supplied.completeResult?.(context);
+            const nativeResult = await owner.readGoal(await acquire(context));
+            await completeResult?.(nativeResult, {
+              segmentId: nativeResult.threadId ? `claude:${nativeResult.threadId}` : null, capabilities: goalCapabilities
+            });
+            return { nativeResult, goal: claudeGoalValue(nativeResult.goal, nativeResult.threadId) };
+          }
+          await bindAccount(entry, configuration, context);
+          return claudeGoalValue(await entry.goals.read(), entry.id);
+        },
+        async updateGoal({ configuration, context, input, representation, interrupt, send }) {
+          if (scoped) return unsupported();
+          if (supplied) {
+            await acquire(context);
+            const completeResult = supplied.completeResult?.(context);
+            let command = input;
+            let facilities;
+            if (representation !== "native") {
+              const current = await owner.readGoal(await acquire(context));
+              if (input.action !== "set" && claudeGoalValue(current.goal, current.threadId)?.id !== input.expectedGoalId) {
+                throw new Error("The Claude goal changed. Refresh before trying again.");
+              }
+              command = { ...input, threadId: current.threadId,
+                ...(input.action !== "set" ? { createdAt: current.goal.createdAt, objective: current.goal.objective } : {}) };
+              facilities = { interrupt, send: command => send(command, { threadId: current.threadId }) };
+            }
+            const nativeResult = await owner.updateGoal(await acquire(context), command, facilities);
+            await completeResult?.(nativeResult);
+            return { nativeResult, goal: claudeGoalValue(nativeResult.goal, nativeResult.threadId) };
+          }
+          await bindAccount(entry, configuration, context);
+          const goal = await entry.goals.read();
+          if (input.action !== "set" && claudeGoalValue(goal, entry.id)?.id !== input.expectedGoalId) {
+            throw new Error("The Claude goal changed. Refresh before trying again.");
+          }
+          await entry.goals.update({ ...input, threadId: entry.id,
+            ...(input.action !== "set" ? { createdAt: goal?.createdAt, objective: goal?.objective } : {}) }, { interrupt, send });
+          return claudeGoalValue(await entry.goals.read(), entry.id);
+        },
+        async inspectAdmission({ context, representation, ...input }) {
+          if (scoped) return unsupported();
+          if (supplied) {
+            await acquire(context);
+            const result = await owner.inspectAdmission(await acquire(context), input);
+            return representation === "native" ? result : { accepted: result.admission === "accepted" };
+          }
+          const history = await owner.readHistory(entry);
+          const nativeId = claudeNativeMessageId(input.messageId);
+          return { accepted: history.userIds.includes(nativeId),
+            messages: history.messages.filter(message => message.userId === nativeId) };
+        },
+        steer: command => owner.steer(control, command, commandOptions),
+        async run(command) {
+          if (entry && (entry.disposed || entry.command)) throw new Error("This Claude conversation is closed or already working.");
+          return owner.run(control, command, commandOptions);
+        },
+        async cancel({ input, context, representation } = {}) {
+          if (scoped) {
+            input = scopedInput(input);
+            return owner.stopConversation(await acquire(context, input.conversationId, { cleanupExecutionId: input.cleanupExecutionId }));
+          }
+          if (!supplied) for (const id of pendingAccountStops) await stopAccount(id);
+          const value = await owner.cancel(control, { context, acquire, reportFailure, entry });
+          return supplied && representation === "native" ? { value } : value;
+        },
+        async dispose(options) {
+          try {
+            let result;
+            if (scoped && options) {
+              const input = scopedInput(options.input);
+              result = await owner.deleteConversation(await acquire(options.context, input.conversationId, {
+                operation: "delete", input, cleanupExecutionId: input.cleanupExecutionId }));
+            } else if (supplied) {
+              result = await disposeNative({ native: supplied, options: scoped ? scoped.context : options });
+              if (result?.ok === false) throw Object.assign(new Error(result.error || (scoped ? "Scoped cleanup could not be confirmed." : "Claude cleanup could not be confirmed.")), result);
+            } else {
+              await entry.nativeTurn.whenIdle().catch(() => {});
+              for (const id of pendingAccountStops) await stopAccount(id);
+              await owner.close(entry);
+            }
+            control.disposed = true;
+            return result;
+          } catch (error) {
+            if (supplied && !scoped) {
+              error.cleanupFailed = true;
+              control.current?.failure.reject(error);
+            }
+            throw error;
+          }
+        }
+      });
+    }
+  });
+}