@jskit-ai/assistant-core 0.1.199 → 0.1.201

package/test/conversationAttachments.test.js

@@ -0,0 +1,238 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createConversationRuntime, createMemoryConversationStorage } from "../src/server/conversation/index.js";
+import { codexLocalImageInput, codexTurnInput } from "../src/server/conversation/codexProvider.js";
+import { createConversationAttachmentReader } from "../src/server/conversation/attachments.js";
+import { conversationAttachmentManifest, prepareConversationAttachmentMessage } from "../src/shared/conversation/attachments.js";
+
+const image = Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aN7sAAAAASUVORK5CYII=", "base64");
+const receipt = { attachmentId: "picture", fileName: "picture.png", size: image.length };
+const input = { messageId: "first", text: "Describe this", attachmentIds: [receipt.attachmentId] };
+const context = { subject: "owner" };
+const configuration = { integrationId: "model", systemPrompt: "Be concise." };
+const resolution = () => ({ attachments: [{ ...receipt, privatePath: "/private/upload" }], content: [{ type: "image", image, mediaType: "image/png" }] });
+
+const localFiles = [
+  { attachmentId: "picture", fileName: "a b.png", size: 10 * 1024 * 1024, reference: "[Image #1]",
+    contentType: "image/png", path: "/session/artifacts/a b.png" },
+  { attachmentId: "data", fileName: "data.csv", size: 12, reference: "[File #1]",
+    contentType: "application/octet-stream", path: "/session/artifacts/data.csv" }
+];
+const localReceipts = localFiles.map(({ attachmentId, fileName, size, reference }) => ({ attachmentId, fileName, size, reference }));
+const localResolution = () => ({ attachments: structuredClone(localReceipts), localFiles: structuredClone(localFiles) });
+
+function localReader({ resolve = localResolution, types = ["text", "image", "localFile"], authorize = async () => {}, maximumBytes = 1024 } = {}) {
+  return createConversationAttachmentReader({ attachments: { resolve }, context, conversationId: "one",
+    signal: new AbortController().signal, authorize, types, maximumBytes });
+}
+
+test("prepared local files keep the original manifest, authored message and visible receipts", () => {
+  const prepared = prepareConversationAttachmentMessage({ message: "Inspect [Image #1] and [File #1]",
+    displayMessage: "My authored request", messageId: "prepared" }, localFiles, localReceipts);
+  assert.equal(prepared.message, 'Inspect [Image #1] and [File #1]\n\nAttached files:\n[Image #1] "a b.png": "/session/artifacts/a b.png"\n[File #1] "data.csv": "/session/artifacts/data.csv"');
+  assert.equal(prepared.displayMessage, "My authored request");
+  assert.equal(prepared.messageId, "prepared");
+  assert.equal(prepared.attachments, localFiles);
+  assert.equal(prepared.displayAttachments, localReceipts);
+  assert.equal(prepareConversationAttachmentMessage({ prompt: "Fallback" }, localFiles, localReceipts).displayMessage, "Fallback");
+  assert.equal(prepareConversationAttachmentMessage({ message: "", displayMessage: "" }, localFiles, localReceipts).displayMessage, "");
+  assert.deepEqual(prepareConversationAttachmentMessage({ prompt: "Unchanged" }, [], []), {
+    prompt: "Unchanged", attachments: [], displayAttachments: []
+  });
+  assert.equal(conversationAttachmentManifest([{ reference: "[File #1]", fileName: 'a"b\n.csv', path: '/session/a"b\n.csv' }]),
+    '\n\nAttached files:\n[File #1] "a\\"b\\n.csv": "/session/a\\"b\\n.csv"');
+});
+
+test("authorized local files retain native paths only in transient dispatch input", async () => {
+  const calls = [];
+  const read = localReader({ resolve: async request => { calls.push(request); return localResolution(); } });
+  const files = await read(localReceipts);
+  assert.deepEqual(calls[0].attachmentIds, ["picture", "data"]);
+  assert.equal(calls[0].context, context);
+  assert.equal(calls[0].conversationId, "one");
+  assert.deepEqual(files.attachments, localReceipts);
+  assert.deepEqual(files.localFiles, localFiles);
+  assert.deepEqual(files.content, []);
+  assert.equal(files.attachmentManifest, '\n\nAttached files:\n[Image #1] "a b.png": "/session/artifacts/a b.png"\n[File #1] "data.csv": "/session/artifacts/data.csv"');
+  assert.doesNotMatch(JSON.stringify(files.attachments), /session\/artifacts|contentType|path/);
+  assert.equal(files.localFiles[0].size, 10 * 1024 * 1024, "Native files keep the host upload limit rather than the byte-image memory limit");
+  assert.deepEqual(await read([]), { attachments: [], content: [], localFiles: [], attachmentManifest: "" });
+});
+
+test("local file resolution requires the exact requested receipts and native path", async () => {
+  for (const change of [
+    result => { result.localFiles.reverse(); },
+    result => { result.localFiles[0].attachmentId = "foreign"; },
+    result => { result.localFiles[0].fileName = "foreign.png"; },
+    result => { result.localFiles[0].size++; },
+    result => { result.localFiles[0].reference = "[Image #2]"; },
+    result => { result.localFiles[0].path = "../foreign.png"; },
+    result => { result.localFiles[0].path = "https://untrusted.invalid/image.png"; },
+    result => { result.localFiles[0].path += "\0"; },
+    result => { result.localFiles[0].contentType = "invalid"; },
+    result => { result.localFiles.pop(); },
+    result => { result.content = [{ type: "image", image, mediaType: "image/png" }]; }
+  ]) {
+    const result = localResolution();
+    change(result);
+    await assert.rejects(localReader({ resolve: async () => result })(localReceipts), { code: "conversation_invalid_attachments" });
+  }
+  await assert.rejects(localReader({ types: ["text", "image"] })(localReceipts), /cannot accept local attachment files/);
+  await assert.rejects(localReader({ maximumBytes: 1 })(localReceipts), /byte limit/);
+});
+
+test("local file authorization is checked again after resolution", async () => {
+  let allowed = true;
+  const read = localReader({
+    authorize: async () => { if (!allowed) throw new Error("Attachment access denied"); },
+    resolve: async () => { allowed = false; return localResolution(); }
+  });
+  await assert.rejects(read(localReceipts), /Attachment access denied/);
+});
+
+test("API rejects resolver-only native files before admission or dispatch", async t => {
+  const f = await fixture(t, { resolve: localResolution });
+  await assert.rejects(f.conversation.send({ messageId: "native-only", text: "Inspect", attachmentIds: ["picture", "data"] }),
+    /cannot accept local attachment files/);
+  assert.equal(f.requests.length, 0);
+  assert.equal((await f.conversation.read()).conversationLog.length, 0);
+});
+
+test("Codex translates resolved images into native input and leaves other files as path references", () => {
+  const attachments = [
+    { attachmentId: "image", fileName: "a b.png", path: "/session/artifacts/a b.png", contentType: "image/png" },
+    { attachmentId: "file", fileName: "data.csv", path: "/session/artifacts/data.csv", contentType: "application/octet-stream" }
+  ];
+  const codexInput = codexTurnInput([
+    "Inspect [Image #1] and [File #1]",
+    ...codexLocalImageInput(attachments)
+  ]);
+  assert.deepEqual(codexInput, [
+    { type: "text", text: "Inspect [Image #1] and [File #1]", text_elements: [] },
+    { type: "localImage", path: attachments[0].path }
+  ]);
+});
+
+async function fixture(t, { storage = createMemoryConversationStorage(), resolve = resolution, limits, authorize = () => true } = {}) {
+  const requests = [];
+  const reads = [];
+  const runtime = createConversationRuntime({ storage, authorize, limits,
+    connections: { resolve: async () => ({ providerId: "test", model: "test", sdkPackage: "@ai-sdk/openai-compatible",
+      apiKey: "test", baseURL: "https://provider.invalid/v1" }) },
+    attachments: { resolve: async request => { reads.push(request); return resolve(request); } },
+    fetch: async (url, request) => {
+      requests.push(JSON.parse(request.body));
+      return new Response('data: {"choices":[{"delta":{"content":"A picture."}}]}\n\ndata: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\n',
+        { headers: { "content-type": "text/event-stream" } });
+    }
+  });
+  t.after(() => runtime.close());
+  const conversation = await runtime.open({ id: "one", context, configuration });
+  return { runtime, conversation, storage, requests, reads };
+}
+
+test("authorized image bytes reach the API once and only safe receipts enter stored messages", async t => {
+  const f = await fixture(t);
+  assert.equal(f.conversation.capabilities.attachments, true);
+  const [first, duplicate] = await Promise.all([f.conversation.send(input), f.conversation.send(input)]);
+  assert.equal(first.turnId, duplicate.turnId);
+  const state = await f.conversation.wait();
+  assert.equal(state.conversationLog[0].metadata.runtime.status, "complete", state.error);
+  assert.equal(f.requests.length, 1);
+  assert.equal(f.reads.length, 1);
+  assert.equal(f.reads[0].context, context);
+  assert.equal(f.reads[0].conversationId, "one");
+  assert.deepEqual(f.reads[0].attachmentIds, [receipt.attachmentId]);
+  assert.deepEqual(f.requests[0].messages.at(-1).content, [
+    { type: "text", text: input.text }, { type: "image_url", image_url: { url: `data:image/png;base64,${image.toString("base64")}` } }
+  ]);
+  assert.deepEqual(state.conversationLog[0].user.attachments, [receipt]);
+  assert.doesNotMatch(JSON.stringify(state), /privatePath|private\/upload|iVBOR/);
+  assert.equal((await f.conversation.send(input)).duplicate, true);
+  assert.equal(f.reads.length, 1, "An accepted retry returns its receipt without rereading files or resending");
+  await assert.rejects(f.conversation.send({ ...input, attachmentIds: ["different"] }), { code: "conversation_message_conflict" });
+});
+
+test("API history and continuity reauthorize files after reopen and renewal", async t => {
+  let allowed = true;
+  const resolve = () => {
+    if (!allowed) throw new Error("This identity no longer has attachment access");
+    return resolution();
+  };
+  const f = await fixture(t, { resolve });
+  await f.conversation.send(input);
+  const first = await f.conversation.wait();
+  await f.runtime.close();
+  const resumed = await fixture(t, { storage: f.storage, resolve });
+  await resumed.conversation.send({ messageId: "second", text: "What was in it?" });
+  await resumed.conversation.wait();
+  assert.equal(resumed.requests[0].messages[1].content[1].type, "image_url");
+  await resumed.conversation.replace({ operationId: "renew", reason: "renewal", expectedSegmentId: first.segmentId });
+  await resumed.conversation.send({ messageId: "third", text: "Look again" });
+  await resumed.conversation.wait();
+  assert.equal(resumed.requests[1].messages.at(-1).content[1].type, "image_url");
+  allowed = false;
+  await assert.rejects(resumed.conversation.send({ messageId: "denied", text: "Look again" }), /attachment access/);
+  assert.equal(resumed.requests.length, 2);
+  assert.equal((await resumed.conversation.read()).conversationLog.length, 3);
+});
+
+test("an image-only request is accepted without invented user text", async t => {
+  const f = await fixture(t);
+  await f.conversation.send({ ...input, text: "" });
+  const state = await f.conversation.wait();
+  assert.equal(f.requests[0].messages.at(-1).content.length, 1);
+  assert.equal(f.requests[0].messages.at(-1).content[0].type, "image_url");
+  assert.equal(state.conversationLog[0].user.text, "");
+});
+
+test("denied files and malformed resolver content never admit a message or dispatch a model request", async t => {
+  const cases = [
+    () => { throw new Error("Attachment access denied"); },
+    () => ({ ...resolution(), attachments: [{ ...receipt, attachmentId: "someone-elses-file" }] }),
+    () => ({ ...resolution(), content: [] }),
+    () => ({ ...resolution(), content: [{ type: "image", image: "https://untrusted.invalid/image.png", mediaType: "image/png" }] }),
+    () => ({ ...resolution(), content: [{ type: "image", image, mediaType: "image/unknown" }] }),
+    () => ({ ...resolution(), content: [{ type: "file", data: "/private/upload", mediaType: "application/pdf" }] })
+  ];
+  for (const resolve of cases) {
+    const f = await fixture(t, { resolve });
+    await assert.rejects(f.conversation.send(input));
+    assert.equal(f.requests.length, 0);
+    const state = await f.conversation.read();
+    assert.equal(state.pendingRequest, null);
+    assert.equal(state.conversationLog.length, 0);
+  }
+});
+
+test("invalid IDs and caller-supplied attachment content do not reach the resolver", async t => {
+  const f = await fixture(t);
+  for (const attachmentIds of [null, "picture", [""], ["picture", "picture"], [{}], Array.from({ length: 11 }, (_, i) => String(i))]) {
+    await assert.rejects(f.conversation.send({ ...input, attachmentIds }), { code: "conversation_invalid_attachments" });
+  }
+  await assert.rejects(f.conversation.send({ ...input, attachments: [resolution()] }), { code: "conversation_unsupported" });
+  assert.equal(f.reads.length, 0);
+  assert.equal(f.requests.length, 0);
+});
+
+test("attachment bytes are bounded across current input and restored history", async t => {
+  const f = await fixture(t, { limits: { maxAttachmentBytes: image.length } });
+  await f.conversation.send(input);
+  await f.conversation.wait();
+  await assert.rejects(f.conversation.send({ ...input, messageId: "second" }), /byte limit/);
+  assert.equal(f.requests.length, 1);
+  const text = await fixture(t, { limits: { maxAttachmentBytes: 3 }, resolve: () => ({
+    attachments: [receipt], content: [{ type: "text", text: "Too long" }]
+  }) });
+  await assert.rejects(text.conversation.send(input), /byte limit/);
+  assert.equal(text.requests.length, 0);
+});
+
+test("authorization revoked during file resolution prevents dispatch", async t => {
+  let allowed = true;
+  const f = await fixture(t, { authorize: () => allowed, resolve: () => { allowed = false; return resolution(); } });
+  await assert.rejects(f.conversation.send(input), { code: "conversation_forbidden" });
+  assert.equal(f.requests.length, 0);
+  allowed = true;
+  assert.equal((await f.conversation.read()).conversationLog.length, 0);
+});

package/test/conversationCommandWrapper.test.js

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { execFileSync } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { nativeCommandHook, wrapNativeCommand } from "../src/server/conversation/commandWrapper.js";
+import { createConversationRuntime, createMemoryConversationStorage } from "../src/server/conversation/index.js";
+
+test("a command wrapper receives exactly one original argument, including shell syntax", async t => {
+  const directory = await mkdtemp(path.join(tmpdir(), "jskit-command-wrapper-"));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  const wrapper = path.join(directory, "wrapper's executable");
+  await writeFile(wrapper, `#!${process.execPath}\nimport { writeFileSync } from 'node:fs';\nwriteFileSync(process.env.RECEIPT, JSON.stringify(process.argv.slice(2)));\n`, { mode: 0o700 });
+  const command = "printf '%s' \"$SECRET\"\n$(touch escaped) `touch escaped` '🌏'";
+  execFileSync("sh", ["-c", wrapNativeCommand(wrapper, command)], { cwd: directory, env: { ...process.env, RECEIPT: path.join(directory, "receipt") } });
+  assert.deepEqual(JSON.parse(await readFile(path.join(directory, "receipt"), "utf8")), [command]);
+  await assert.rejects(readFile(path.join(directory, "escaped")), { code: "ENOENT" });
+});
+
+test("native command hooks preserve tool options and deny malformed commands", () => {
+  const input = { hook_event_name: "PreToolUse", tool_name: "Bash", tool_input: { command: "pwd", timeout: 500, description: "Current directory" } };
+  const output = nativeCommandHook("/host/wrapper", input).hookSpecificOutput;
+  assert.equal(output.updatedInput.command, "'/host/wrapper' 'pwd'");
+  assert.equal(output.updatedInput.timeout, 500);
+  assert.equal(output.updatedInput.description, "Current directory");
+  for (const command of [null, "", "  ", "pwd\0bad"]) {
+    assert.equal(nativeCommandHook("/host/wrapper", { ...input, tool_input: { command } }).hookSpecificOutput.permissionDecision, "deny");
+  }
+  assert.throws(() => nativeCommandHook("/host/wrapper", { ...input, tool_name: "Read" }), /unexpected native tool/);
+});
+
+test("the native hook executable fails closed on malformed or oversized input", () => {
+  const executable = fileURLToPath(new URL("../src/server/conversation/commandHook.js", import.meta.url));
+  for (const input of ["invalid JSON", "x".repeat(2 * 1024 * 1024 + 1)]) {
+    const output = JSON.parse(execFileSync(process.execPath, [executable, "/host/wrapper"], { input, encoding: "utf8" }));
+    assert.equal(output.hookSpecificOutput.permissionDecision, "deny");
+  }
+});
+
+test("a required command wrapper cannot be silently ignored by an incompatible host", async () => {
+  for (const host of [{ commandWrapper: "relative", nativeTools: true }, { commandWrapper: "/host/wrapper" }, { commandWrapper: "/host/wrapper", nativeTools: true }]) {
+    const runtime = createConversationRuntime({ storage: createMemoryConversationStorage(), authorize: () => true, host });
+    await assert.rejects(runtime.open({ id: "wrapper", configuration: { integrationId: "unused" } }), /commandWrapper|requires native/);
+    await runtime.close();
+  }
+});

package/test/conversationConfiguration.test.js

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createConversationRuntime, createMemoryConversationStorage, createFileConversationStorage, normalizeConversationConfiguration } from "../src/server/conversation/index.js";
+import { validateConversationConfiguration } from "../src/server/conversation/configuration.js";
+
+test("configuration shorthand retains native login, explicit connection defaults and JSON-stable optional fields", () => {
+  const input = Object.freeze({ systemPrompt: "Answer briefly.", integrationId: undefined,
+    model: undefined, effort: undefined, outputSchema: undefined });
+  for (const engine of ["api", "opencode", "claude", "codex"]) {
+    const configuration = normalizeConversationConfiguration(input, { engine, defaultIntegrationId: "assistant" });
+    assert.deepEqual(configuration, engine === "api" || engine === "opencode"
+      ? { systemPrompt: input.systemPrompt, integrationId: "assistant" } : { systemPrompt: input.systemPrompt });
+    assert.deepEqual(JSON.parse(JSON.stringify(configuration)), configuration);
+    const explicit = { ...input, integrationId: "authorized-choice", model: "exact-model-id", effort: "high" };
+    assert.deepEqual(normalizeConversationConfiguration(explicit, { engine, defaultIntegrationId: "assistant" }), {
+      systemPrompt: input.systemPrompt, integrationId: "authorized-choice", model: "exact-model-id", effort: "high"
+    });
+  }
+  assert.equal(Object.hasOwn(input, "integrationId"), true);
+  assert.equal(input.integrationId, undefined);
+  const withoutDefault = normalizeConversationConfiguration(input, { engine: "api" });
+  assert.deepEqual(withoutDefault, { systemPrompt: input.systemPrompt });
+  assert.throws(() => validateConversationConfiguration(withoutDefault, {
+    engine: "API", connectionRequired: true, connections: { resolve() {} }
+  }), /requires an authorized integrationId/);
+  const invalid = normalizeConversationConfiguration({ systemPrompt: input.systemPrompt, integrationId: "" }, {
+    engine: "api", defaultIntegrationId: "assistant"
+  });
+  assert.equal(invalid.integrationId, "");
+  assert.throws(() => validateConversationConfiguration(invalid), /configuration requires/);
+  const unsupported = normalizeConversationConfiguration({ systemPrompt: input.systemPrompt, unexpected: undefined });
+  assert.equal(Object.hasOwn(unsupported, "unexpected"), true);
+  assert.throws(() => validateConversationConfiguration(unsupported), /configuration requires/);
+});
+
+async function fixture(t, { file = false } = {}) {
+  const directory = await mkdtemp(join(tmpdir(), "conversation-configuration-"));
+  const storage = file ? createFileConversationStorage({ directory: join(directory, "conversations") }) : createMemoryConversationStorage();
+  const runtimes = [];
+  t.after(async () => {
+    try { for (const runtime of runtimes) await runtime.close(); }
+    finally { await rm(directory, { recursive: true, force: true }); }
+  });
+  function runtime(options = {}) {
+    const value = createConversationRuntime({ storage, defaultIntegrationId: "assistant", authorize: () => true,
+      connections: { resolve() { assert.fail("Configuration must not resolve credentials or run inference."); } },
+      fetch() { assert.fail("Configuration must not issue a provider request."); },
+      host: { workdir: directory, env: { HOME: directory }, execution: {
+        start() { assert.fail("Configuration must not start a native process."); },
+        stop() { assert.fail("An unopened native conversation has no process to stop."); }
+      } }, ...options });
+    runtimes.push(value);
+    return value;
+  }
+  return { runtime, storage };
+}
+
+test("runtime normalizes open and configure inputs with only an explicit connection default", async t => {
+  const f = await fixture(t);
+  const runtime = f.runtime();
+  const input = Object.freeze({ systemPrompt: "Answer briefly.", integrationId: undefined,
+    model: undefined, effort: undefined, outputSchema: undefined });
+  const expected = { systemPrompt: input.systemPrompt, integrationId: "assistant" };
+  const conversation = await runtime.open({ id: "one", configuration: input });
+  assert.deepEqual((await conversation.read()).configuration, expected);
+  assert.deepEqual((await (await runtime.open({ id: "one", configuration: input })).read()).configuration, expected);
+  assert.deepEqual(await conversation.configure({ integrationId: "explicit", model: "exact-model-id", effort: "high" }), {
+    systemPrompt: input.systemPrompt, integrationId: "explicit", model: "exact-model-id", effort: "high"
+  });
+  assert.deepEqual(await conversation.configure({ integrationId: undefined, model: undefined, effort: undefined }), expected);
+  await assert.rejects(conversation.configure({ integrationId: "" }), /configuration requires/);
+  await assert.rejects(conversation.configure({ unexpected: undefined }), /configuration requires/);
+  assert.deepEqual((await conversation.read()).configuration, expected);
+  assert.equal(Object.hasOwn(input, "integrationId"), true);
+  assert.equal(input.integrationId, undefined);
+  await assert.rejects(f.runtime({ defaultIntegrationId: undefined }).open({ id: "without-default", configuration: input }),
+    /requires an authorized integrationId/);
+});
+
+test("runtime normalization uses the saved engine on reopen and never rewrites saved configuration", async t => {
+  const f = await fixture(t);
+  for (const engine of ["api", "claude"]) {
+    const options = { engine: engine === "api" ? "claude" : "api" };
+    const input = { systemPrompt: "Keep this configuration.", integrationId: undefined,
+      model: undefined, effort: undefined, outputSchema: undefined };
+    const expected = { systemPrompt: input.systemPrompt, ...(engine === "api" ? { integrationId: "assistant" } : {}) };
+    const first = f.runtime(options);
+    await first.open({ id: engine, engine, configuration: input });
+    await first.close();
+    const second = f.runtime(options);
+    const reopened = await second.open({ id: engine, configuration: input });
+    assert.equal((await reopened.read()).engine, engine);
+    assert.deepEqual((await reopened.read()).configuration, expected);
+    await reopened.configure({ integrationId: "explicit", model: "exact-model-id", effort: "high" });
+    assert.deepEqual(await reopened.configure({ integrationId: undefined, model: undefined, effort: undefined }), expected);
+    await second.close();
+    await f.storage.write(engine, async transaction => {
+      const metadata = await transaction.readMetadata();
+      metadata.runtime.configuration.model = undefined;
+      await transaction.writeMetadata(metadata);
+    });
+    const saved = await f.storage.read(engine, transaction => transaction.readMetadata());
+    const restored = await f.runtime(options).open({ id: engine });
+    assert.deepEqual((await restored.read()).configuration, saved.runtime.configuration);
+    assert.equal(Object.hasOwn((await restored.read()).configuration, "model"), true);
+    assert.deepEqual(await f.storage.read(engine, transaction => transaction.readMetadata()), saved);
+  }
+});
+
+test("runtime normalizes destination settings and retains file-backed selection and replacement retries", async t => {
+  const f = await fixture(t, { file: true });
+  const first = f.runtime();
+  let conversation = await first.open({ id: "one", configuration: { systemPrompt: "Initial instructions." } });
+  const selection = { operationId: "native", expectedSegmentId: (await conversation.read()).segmentId, engine: "claude",
+    configuration: { systemPrompt: "Native instructions.", integrationId: undefined, model: "exact-model-id", effort: "high" } };
+  const selected = await conversation.select(selection);
+  assert.equal((await conversation.read()).engine, "claude");
+  assert.deepEqual((await conversation.read()).configuration, {
+    systemPrompt: "Native instructions.", model: "exact-model-id", effort: "high"
+  });
+  assert.deepEqual((await f.storage.read("one", transaction => transaction.readMetadata())).runtime.predecessors.at(-1).replacement,
+    { ...selection, configuration: { systemPrompt: "Native instructions.", model: "exact-model-id", effort: "high" }, operation: "select" });
+  await first.close();
+  const second = f.runtime({ defaultIntegrationId: "next-default" });
+  conversation = await second.open({ id: "one" });
+  assert.equal((await conversation.select(selection)).duplicate, true);
+  await assert.rejects(conversation.select({ ...selection, configuration: { ...selection.configuration, model: "changed-model" } }),
+    { code: "conversation_replacement_conflict" });
+  const replacement = { operationId: "api", expectedSegmentId: selected.segmentId, reason: "engine-change", engine: "api",
+    configuration: { systemPrompt: "API instructions.", integrationId: undefined, model: undefined, effort: undefined } };
+  await conversation.replace(replacement);
+  assert.equal((await conversation.read()).engine, "api");
+  assert.deepEqual((await conversation.read()).configuration, { systemPrompt: "API instructions.", integrationId: "next-default" });
+  assert.deepEqual((await f.storage.read("one", transaction => transaction.readMetadata())).runtime.predecessors.at(-1).replacement,
+    { ...replacement, configuration: { systemPrompt: "API instructions." }, operation: "replace" });
+  await second.close();
+  conversation = await f.runtime({ defaultIntegrationId: "later-default" }).open({ id: "one" });
+  assert.equal((await conversation.replace(replacement)).duplicate, true);
+  await assert.rejects(conversation.replace({ ...replacement, configuration: { ...replacement.configuration, integrationId: "changed" } }),
+    { code: "conversation_replacement_conflict" });
+  assert.deepEqual((await conversation.read()).configuration, { systemPrompt: "API instructions.", integrationId: "next-default" });
+  assert.deepEqual((await conversation.read()).conversationLog, []);
+});
+
+test("file-backed pending replacement keeps its admitted configuration across a new runtime default", async t => {
+  const f = await fixture(t, { file: true });
+  const interruptedStorage = { ...f.storage, write: (id, callback) => f.storage.write(id, async transaction => {
+    const previous = await transaction.readMetadata();
+    const value = await callback(transaction);
+    const next = await transaction.readMetadata();
+    if (previous.runtime?.replacement && !next.runtime?.replacement) throw new Error("Storage unavailable during replacement commit.");
+    return value;
+  }) };
+  const first = f.runtime({ storage: interruptedStorage });
+  const conversation = await first.open({ id: "one", configuration: { systemPrompt: "Initial instructions." } });
+  const input = { operationId: "pending", expectedSegmentId: (await conversation.read()).segmentId, reason: "model-change",
+    engine: undefined, briefing: undefined,
+    configuration: { systemPrompt: "Replacement instructions.", integrationId: undefined, model: undefined, effort: undefined } };
+  await assert.rejects(conversation.replace(input), /Storage unavailable during replacement commit/);
+  const saved = await f.storage.read("one", transaction => transaction.readMetadata());
+  assert.deepEqual(saved.runtime.replacement.configuration, { systemPrompt: "Replacement instructions.", integrationId: "assistant" });
+  assert.deepEqual(saved.runtime.replacement.request.configuration, { systemPrompt: "Replacement instructions." });
+  await first.close();
+  const resumed = await f.runtime({ defaultIntegrationId: "later-default" }).open({ id: "one" });
+  await assert.rejects(resumed.replace({ ...input, configuration: { ...input.configuration, systemPrompt: "Different instructions." } }),
+    { code: "conversation_replacement_pending" });
+  assert.deepEqual(await f.storage.read("one", transaction => transaction.readMetadata()), saved);
+  await resumed.replace(input);
+  assert.deepEqual((await resumed.read()).configuration, { systemPrompt: "Replacement instructions.", integrationId: "assistant" });
+  assert.equal((await resumed.replace(input)).duplicate, true);
+});

package/test/conversationNativeStorage.test.js

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { nativeConversationStoragePolicy } from "../src/server/conversation/nativeStorage.js";
+
+test("native storage policy distinguishes locked deletion from host writer exclusion", () => {
+  assert.equal(nativeConversationStoragePolicy("codex").requiresWriterExclusion, false);
+  assert.equal(nativeConversationStoragePolicy("claude").requiresWriterExclusion, true);
+  assert.equal(nativeConversationStoragePolicy("claude").allowsManagedServer, false);
+  assert.equal(nativeConversationStoragePolicy("opencode").requiresWriterExclusion, true);
+  assert.equal(nativeConversationStoragePolicy("opencode").allowsManagedServer, true);
+  for (const engine of ["api", "unknown", "toString", "__proto__", undefined]) {
+    assert.throws(() => nativeConversationStoragePolicy(engine), /Unsupported/u);
+  }
+});
+
+test("native writer recognition handles executables and node entry points without matching similar names", () => {
+  const claude = nativeConversationStoragePolicy("claude");
+  assert.ok(claude.matchesProcess({ executable: "/tools/claude", commandLine: "native\0--resume\0" }));
+  assert.ok(claude.matchesProcess({ executable: "/usr/bin/node", commandLine: "node\0/tools/node_modules/@anthropic-ai/claude-code/cli.js\0" }));
+  assert.equal(claude.matchesProcess({ executable: "/tools/claude-helper", commandLine: "node\0/notes/claude.txt\0" }), false);
+  const opencode = nativeConversationStoragePolicy("opencode");
+  assert.ok(opencode.matchesProcess({ executable: "/tools/opencode", commandLine: "opencode\0serve\0" }));
+  assert.ok(opencode.matchesProcess({ executable: "/usr/bin/bun", commandLine: "bun\0/tools/opencode\0serve\0" }));
+  assert.equal(opencode.matchesProcess({ executable: "/tools/opencode-helper", commandLine: "node\0/notes/opencode.txt\0" }), false);
+});