@jskit-ai/assistant-core 0.1.200 → 0.1.202

package/src/server/conversation/attachments.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+import { conversationAttachmentManifest } from "../../shared/conversation/attachments.js";
+
+function invalid(message) {
+  return Object.assign(new Error(message), { code: "conversation_invalid_attachments", statusCode: 400 });
+}
+
+export function conversationAttachmentIds(value = []) {
+  if (!Array.isArray(value) || value.length > 10 || value.some(id => typeof id !== "string" || !id.trim() || id.length > 256) ||
+      new Set(value).size !== value.length) {
+    throw invalid("Attachments require at most ten distinct, nonempty attachment IDs.");
+  }
+  return [...value];
+}
+
+/** Resolve app-owned files for one dispatch. Only receipts enter the transcript. */
+export function createConversationAttachmentReader({ attachments, context, conversationId, signal, authorize, types, maximumBytes }) {
+  let bytes = 0;
+  return async references => {
+    if (!references?.length) return { attachments: [], content: [], localFiles: [], attachmentManifest: "" };
+    if (typeof attachments?.resolve !== "function") {
+      throw Object.assign(new Error("File attachments are not configured for this conversation."), { code: "conversation_unsupported", statusCode: 400 });
+    }
+    const receipts = [];
+    const content = [];
+    const localFiles = [];
+    // Continuity may retain files from several earlier messages. Each resolver
+    // call uses the same bounded batch as a new user message.
+    for (let offset = 0; offset < references.length; offset += 10) {
+      const attachmentIds = conversationAttachmentIds(references.slice(offset, offset + 10).map(file => file.attachmentId));
+      signal.throwIfAborted();
+      await authorize();
+      const resolved = await attachments.resolve({ attachmentIds, context, conversationId, signal });
+      signal.throwIfAborted();
+      const local = resolved?.localFiles !== undefined;
+      if (!Array.isArray(resolved?.attachments) || resolved.attachments.length !== attachmentIds.length ||
+          (local ? !Array.isArray(resolved.localFiles) || resolved.localFiles.length !== attachmentIds.length ||
+            resolved.content !== undefined && (!Array.isArray(resolved.content) || resolved.content.length)
+            : !Array.isArray(resolved.content) || !resolved.content.length || resolved.content.length > 100)) {
+        throw invalid("The attachment resolver must return a receipt for every requested file and bounded model content.");
+      }
+      if (local && !types.includes("localFile")) {
+        throw invalid("This engine cannot accept local attachment files. Supply extracted text or supported image bytes.");
+      }
+      for (const [index, receipt] of resolved.attachments.entries()) {
+        if (receipt?.attachmentId !== attachmentIds[index] || typeof receipt.fileName !== "string" || !receipt.fileName.trim() ||
+            receipt.fileName.length > 256 || !Number.isSafeInteger(receipt.size) || receipt.size < 0 ||
+            receipt.reference !== undefined && (typeof receipt.reference !== "string" || receipt.reference.length > 256)) {
+          throw invalid("Attachment receipts require the requested ID, a bounded fileName and a nonnegative size.");
+        }
+        receipts.push({ attachmentId: receipt.attachmentId, fileName: receipt.fileName, size: receipt.size,
+          ...(receipt.reference ? { reference: receipt.reference } : {}) });
+        if (local) {
+          const file = resolved.localFiles[index];
+          if (file?.attachmentId !== receipt.attachmentId || file.fileName !== receipt.fileName || file.size !== receipt.size ||
+              typeof receipt.reference !== "string" || !receipt.reference.trim() || file.reference !== receipt.reference ||
+              typeof file.path !== "string" || !path.isAbsolute(file.path) || file.path.includes("\0") ||
+              typeof file.contentType !== "string" || !/^[\w.+-]+\/[\w.+-]+$/u.test(file.contentType)) {
+            throw invalid("Local attachment files require their exact requested receipt and an authorized absolute native path.");
+          }
+          localFiles.push({ attachmentId: file.attachmentId, fileName: file.fileName, size: file.size,
+            reference: file.reference, contentType: file.contentType, path: file.path });
+        }
+      }
+      for (const part of resolved.content || []) {
+        if (!types.includes(part?.type)) throw invalid("This engine cannot accept that attachment format. Supply extracted text or a supported image.");
+        if (part.type === "text") {
+          if (typeof part.text !== "string" || !part.text.trim()) throw invalid("Attachment text must be nonempty.");
+          bytes += Buffer.byteLength(part.text);
+          content.push({ type: "text", text: part.text });
+        } else {
+          const data = part.type === "image" ? part.image : part.data;
+          if (!(data instanceof Uint8Array) || !data.byteLength || typeof part.mediaType !== "string" ||
+              !/^[\w.+-]+\/[\w.+-]+$/u.test(part.mediaType) ||
+              part.type === "image" && !["image/png", "image/jpeg", "image/webp", "image/gif"].includes(part.mediaType) ||
+              part.filename !== undefined && (typeof part.filename !== "string" || part.filename.length > 256)) {
+            throw invalid("Attachments require authorized bytes and a supported media type; remote URLs and paths are not accepted.");
+          }
+          bytes += data.byteLength;
+          if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.");
+          content.push(part.type === "image" ? { type: "image", image: Buffer.from(data), mediaType: part.mediaType }
+            : { type: "file", data: Buffer.from(data), mediaType: part.mediaType, ...(part.filename ? { filename: part.filename } : {}) });
+        }
+        if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.");
+      }
+    }
+    const attachmentManifest = conversationAttachmentManifest(localFiles);
+    bytes += Buffer.byteLength(attachmentManifest);
+    if (bytes > maximumBytes) throw invalid("Attachment content exceeds the configured byte limit for this request.");
+    await authorize();
+    return { attachments: receipts, content, localFiles, attachmentManifest };
+  };
+}

package/src/server/conversation/claudeClient.js

@@ -0,0 +1,221 @@
+import { randomUUID } from "node:crypto";
+import { TextDecoder } from "node:util";
+
+const CLAUDE_JSON_MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+function claudeProtocolError(message, code = "assistant_claude_protocol_error") {
+  return Object.assign(new Error(message), { code });
+}
+
+// Geometric growth keeps fragmented frames linear with bounded memory. Decode complete
+// frames, so a UTF-8 character split across pipe reads is never corrupted.
+async function* readClaudeJsonFrames(stream, { maxFrameBytes = CLAUDE_JSON_MAX_FRAME_BYTES, allowIncompleteTail = false } = {}) {
+  if (!Number.isSafeInteger(maxFrameBytes) || maxFrameBytes < 1) {
+    throw new TypeError("Claude JSON frame limits must be positive integers.");
+  }
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let buffer = Buffer.alloc(0);
+  let length = 0;
+  function append(part) {
+    const required = length + part.length;
+    if (required > maxFrameBytes) throw claudeProtocolError("Claude JSON frame exceeded its size limit.");
+    if (required > buffer.length) {
+      const next = Buffer.allocUnsafe(Math.min(maxFrameBytes, Math.max(required, buffer.length * 2, 4096)));
+      buffer.copy(next, 0, 0, length);
+      buffer = next;
+    }
+    part.copy(buffer, length);
+    length = required;
+  }
+  function parse(bytes) {
+    let frame;
+    try {
+      const line = decoder.decode(bytes).trim();
+      if (!line) return null;
+      frame = JSON.parse(line);
+    } catch {
+      // Never include the frame: it can contain prompts, tool results, or secrets.
+      throw claudeProtocolError("Claude returned invalid UTF-8 or JSON.");
+    }
+    if (!frame || typeof frame !== "object" || Array.isArray(frame) || typeof frame.type !== "string") {
+      throw claudeProtocolError("Claude returned a JSON frame without an event type.");
+    }
+    return frame;
+  }
+  for await (const input of stream) {
+    const chunk = Buffer.isBuffer(input) ? input : Buffer.from(input);
+    let offset = 0;
+    for (let end = chunk.indexOf(10, offset); end !== -1; end = chunk.indexOf(10, offset)) {
+      const part = chunk.subarray(offset, end);
+      if (length + part.length > maxFrameBytes) throw claudeProtocolError("Claude JSON frame exceeded its size limit.");
+      if (length) append(part);
+      const bytes = length ? buffer.subarray(0, length) : part;
+      length = 0;
+      const frame = parse(bytes);
+      if (frame) yield frame;
+      offset = end + 1;
+    }
+    append(chunk.subarray(offset));
+  }
+  // A truncated write is not a complete protocol frame, even if it parses.
+  if (length && !allowIncompleteTail) throw claudeProtocolError("Claude JSON stream ended in an incomplete frame.");
+}
+
+function createClaudeJsonClient({ stream, onEvent = async () => {}, onControlRequest, onFailure = async () => {}, timeoutMs = 30_000 } = {}) {
+  const requests = new Map();
+  const incoming = new Map();
+  let failure = null;
+  let closed = false;
+  let writes = Promise.resolve();
+  let events = Promise.resolve();
+  let queuedEventBytes = 0;
+  let queuedControlBytes = 0;
+
+  function fail(error) {
+    failure ||= error;
+    for (const pending of requests.values()) pending.reject(failure);
+    requests.clear();
+    for (const pending of incoming.values()) pending.controller.abort(failure);
+    stream.destroy();
+  }
+
+  // Duplex teardown can emit an error after the readable iterator has ended.
+  // Keep its owner attached until both sides have actually closed.
+  stream.on("error", fail);
+  stream.once("close", () => stream.off("error", fail));
+
+  function write(frame) {
+    const payload = `${JSON.stringify(frame)}\n`;
+    if (Buffer.byteLength(payload) > CLAUDE_JSON_MAX_FRAME_BYTES) {
+      return Promise.reject(claudeProtocolError("Claude input exceeded its size limit."));
+    }
+    const next = writes.then(() => new Promise((resolve, reject) => {
+      if (failure || closed || stream.destroyed) {
+        reject(failure || claudeProtocolError("Claude connection is closed."));
+        return;
+      }
+      // A write callback, unlike write()'s boolean return, respects backpressure
+      // and reports EPIPE. A completed write is NOT an admission acknowledgement.
+      stream.write(payload, (error) => error ? reject(error) : resolve());
+    }));
+    writes = next.catch((error) => { fail(error); });
+    return next;
+  }
+
+  async function request(request, options = {}) {
+    if (failure || closed) throw failure || claudeProtocolError("Claude connection is closed.");
+    const requestId = randomUUID();
+    let timer;
+    const response = new Promise((resolve, reject) => {
+      timer = setTimeout(() => {
+        requests.delete(requestId);
+        reject(claudeProtocolError(`Claude ${request.subtype} timed out.`, "assistant_claude_control_timeout"));
+      }, options.timeoutMs ?? timeoutMs);
+      requests.set(requestId, { resolve, reject });
+    });
+    // Install both observers before a write can fail or an immediate reply arrives.
+    try {
+      const [, result] = await Promise.all([
+        write({ type: "control_request", request_id: requestId, request }), response
+      ]);
+      return result;
+    } finally {
+      clearTimeout(timer);
+      requests.delete(requestId);
+    }
+  }
+
+  function receiveControl(frame) {
+    const id = frame.request_id;
+    const bytes = Buffer.byteLength(JSON.stringify(frame));
+    if (typeof id !== "string" || !id || id.length > 256 || incoming.has(id) || incoming.size >= 32 ||
+        queuedControlBytes + bytes > 2 * CLAUDE_JSON_MAX_FRAME_BYTES) {
+      throw claudeProtocolError("Claude control processing exceeded its limits or reused an active request id.");
+    }
+    const controller = new AbortController();
+    const precedingEvents = events;
+    queuedControlBytes += bytes;
+    const pending = { controller };
+    incoming.set(id, pending);
+    pending.done = (async () => {
+      let response;
+      try {
+        // Admission and preceding native tool-use events must be persisted first.
+        // Waiting here does not block the reader from answering interrupt controls.
+        await precedingEvents;
+        controller.signal.throwIfAborted();
+        if (!onControlRequest) throw claudeProtocolError("This control request requires the native Claude Code terminal.");
+        const value = await onControlRequest(frame.request, { signal: controller.signal });
+        response = { subtype: "success", request_id: id, response: value || {} };
+      } catch (error) {
+        response = { subtype: "error", request_id: id, error: error.message || "Claude control request failed." };
+      }
+      if (!controller.signal.aborted && !closed && !failure) await write({ type: "control_response", response });
+    })().catch(fail).finally(() => { incoming.delete(id); queuedControlBytes -= bytes; });
+  }
+
+  const completion = (async () => {
+    try {
+      for await (const frame of readClaudeJsonFrames(stream)) {
+        if (frame.type === "control_response") {
+          const response = frame.response;
+          const pending = requests.get(response?.request_id);
+          if (!pending) continue; // A timed-out request may still get a reply.
+          requests.delete(response.request_id);
+          if (response.subtype === "success") pending.resolve(response.response || {});
+          else pending.reject(claudeProtocolError(String(response.error || "Claude control request failed.")));
+        } else if (frame.type === "control_request") {
+          receiveControl(frame);
+        } else if (frame.type === "control_cancel_request") {
+          incoming.get(frame.request_id)?.controller.abort(claudeProtocolError("Claude cancelled this control request."));
+        } else {
+          const bytes = Buffer.byteLength(JSON.stringify(frame));
+          queuedEventBytes += bytes;
+          if (queuedEventBytes > 2 * CLAUDE_JSON_MAX_FRAME_BYTES) {
+            throw claudeProtocolError("Claude event processing exceeded its queue limit.");
+          }
+          // Persist events in order without blocking control replies behind
+          // disk writes or realtime subscribers. Bound the queued payload too.
+          events = events.then(async () => {
+            try {
+              if (!closed && !failure) await onEvent(frame);
+            } finally {
+              queuedEventBytes -= bytes;
+            }
+          });
+          void events.catch(fail);
+        }
+      }
+      await events;
+      if (!closed) throw claudeProtocolError("Claude event connection ended unexpectedly.", "assistant_claude_observation_lost");
+    } catch (error) {
+      if (!closed) {
+        fail(error);
+        await onFailure(failure);
+      }
+    } finally {
+      fail(failure || claudeProtocolError("Claude connection is closed."));
+    }
+  })();
+  // Callers can await completion; the background observer must never leak an
+  // unhandled rejection if their failure callback itself fails.
+  void completion.catch(() => {});
+
+  return Object.freeze({
+    completion,
+    initialize: ({ hooks } = {}) => request({ subtype: "initialize", ...(hooks ? { hooks } : {}) }),
+    interrupt: () => request({ subtype: "interrupt" }),
+    request,
+    whenRequestsIdle: () => Promise.all([...incoming.values()].map(pending => pending.done)),
+    send(message, { messageId = randomUUID(), sessionId = "" } = {}) {
+      return write({ type: "user", uuid: messageId, session_id: sessionId,
+        parent_tool_use_id: null, message: { role: "user", content: message } });
+    },
+    close() {
+      closed = true;
+      fail(claudeProtocolError("Claude connection was closed."));
+    }
+  });
+}
+
+export { CLAUDE_JSON_MAX_FRAME_BYTES, createClaudeJsonClient, readClaudeJsonFrames };

package/src/server/conversation/claudeHistory.js

@@ -0,0 +1,256 @@
+import { createReadStream } from "node:fs";
+import { lstat, readdir, realpath, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { readClaudeJsonFrames } from "./claudeClient.js";
+import { createNativeHistoryExport, retireNativeConversation } from "./nativeHistoryExport.js";
+
+const UUID_PATTERN = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/iu;
+
+function requireClaudeSessionId(id) {
+  if (!UUID_PATTERN.test(id)) throw new TypeError("Invalid Claude conversation id.");
+  return id;
+}
+
+async function archivedClaudeProjectDirectory(workdir) {
+  const canonical = await realpath(workdir).catch((error) => {
+    if (error.code === "ENOENT") return workdir;
+    throw error;
+  });
+  return canonical.normalize("NFC").replace(/[^a-zA-Z0-9]/gu, "-");
+}
+
+function matchingClaudeProjectDirectories(names, directory) {
+  return names.filter((name) => directory.length <= 200
+    ? name === directory
+    : name.startsWith(`${directory.slice(0, 200)}-`));
+}
+
+export async function listClaudeConversationStorage({ configRoot, binding }) {
+  if (!path.isAbsolute(configRoot) || !path.isAbsolute(binding.workdir || "")) throw new TypeError("Claude inventory requires absolute directories.");
+  const directory = await archivedClaudeProjectDirectory(binding.workdir);
+  const projects = path.join(configRoot, "projects");
+  const names = await readdir(projects).catch((error) => { if (error.code === "ENOENT") return []; throw error; });
+  const candidates = matchingClaudeProjectDirectories(names, directory);
+  if (names.length > 10000 || candidates.length > 1) throw new Error("Claude project inventory is ambiguous or exceeds its limit.");
+  const ids = new Set();
+  for (const name of candidates) {
+    const entries = await readdir(path.join(projects, name), { withFileTypes: true });
+    if (entries.length > 10000) throw new Error("Claude conversation inventory exceeds its limit.");
+    for (const entry of entries) {
+      const id = entry.name.replace(/\.jsonl(?:\.(?:superseded|orphaned)-.*)?$/u, "");
+      if (UUID_PATTERN.test(id) && entry.isFile()) ids.add(id);
+    }
+  }
+  return [...ids].sort().map((conversationId) => ({ ...binding, conversationId }));
+}
+
+// Claude's SDK documents this layout. Only the requested native conversation is
+// read; authentication files are never opened. Long paths use the CLI's prefix
+// lookup because its native and Node builds use different hash suffixes.
+async function claudeHistoryPath({ configRoot, workdir, conversationId }) {
+  requireClaudeSessionId(conversationId);
+  const canonical = (await realpath(workdir)).normalize("NFC");
+  const directory = canonical.replace(/[^a-zA-Z0-9]/gu, "-");
+  const projects = path.join(configRoot, "projects");
+  const candidates = directory.length <= 200 ? [directory] :
+    (await readdir(projects).catch((error) => {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    })).filter((name) => name.startsWith(`${directory.slice(0, 200)}-`));
+  for (const name of candidates) {
+    const candidate = path.join(projects, name, `${conversationId}.jsonl`);
+    const info = await stat(candidate).catch((error) => {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    });
+    if (info?.isFile()) return { path: candidate, size: info.size };
+  }
+  return null;
+}
+
+function claudeMessageBlocks(frame, { includeNested = false } = {}) {
+  if (frame.type !== "assistant" || frame.parent_tool_use_id && !includeNested) return [];
+  const content = frame.message?.content;
+  if (!Array.isArray(content)) return [];
+  // Native frames split one API message into blocks with distinct UUIDs.
+  const messageId = frame.uuid || frame.message.id;
+  if (!messageId) return [];
+  const commentary = content.some((block) => block.type === "tool_use");
+  return content.flatMap((block, index) => {
+    const text = block.type === "thinking" ? block.thinking : block.type === "text" ? block.text : "";
+    return typeof text === "string" && text.trim() ? [{
+      id: `claude_${messageId}_${index}`, text, complete: true,
+      role: block.type === "thinking" ? "thinking" : commentary ? "commentary" : "assistant"
+    }] : [];
+  });
+}
+
+async function readClaudeHistory(options) {
+  const file = await claudeHistoryPath(options);
+  if (!file || file.size === 0) return { exists: false, messages: [], userIds: [], text: "" };
+  if (file.size > 256 * 1024 * 1024) throw new Error("Claude history exceeds the supported read limit.");
+  const messages = new Map();
+  const userIds = [];
+  let lastUserId = "";
+  let goal = null;
+  const frames = [];
+  const byId = new Map();
+  let leafUuid = "";
+  let rewound = false;
+  // Snapshot the file length. A writer can be in the middle of its last frame;
+  // only this native-history read allows that unfinished tail.
+  for await (const frame of readClaudeJsonFrames(createReadStream(file.path, { end: file.size - 1 }), {
+    allowIncompleteTail: true
+  })) {
+    if (frame.isSidechain) continue;
+    frames.push(frame);
+    if (frame.uuid) byId.set(frame.uuid, frame);
+    if (["user", "assistant"].includes(frame.type) && frame.uuid) leafUuid = frame.uuid;
+    if (frame.type === "last-prompt" && frame.leafUuid) {
+      leafUuid = frame.leafUuid;
+      rewound ||= frame.rewound === true;
+    }
+  }
+  // Native rewind appends a resume anchor; it retains the discarded branch.
+  // Follow the selected branch so restart/admission reads cannot revive it.
+  const retained = new Set();
+  if (rewound) {
+    while (leafUuid && !retained.has(leafUuid)) {
+      retained.add(leafUuid);
+      leafUuid = byId.get(leafUuid)?.parentUuid;
+    }
+  }
+  for (const frame of frames) {
+    if (rewound && frame.uuid && !retained.has(frame.uuid)) continue;
+    const status = frame.attachment;
+    if (status?.type === "goal_status" && typeof status.condition === "string") {
+      if (status.met === true && status.sentinel === true) goal = null;
+      else if (status.met === false || status.met === true) {
+        const timestamp = Date.parse(frame.timestamp) / 1000;
+        goal = {
+          threadId: options.conversationId, objective: status.condition,
+          createdAt: goal?.objective === status.condition && !status.sentinel ? goal.createdAt : timestamp,
+          status: status.met ? "complete" : "active", updatedAt: timestamp,
+          reason: typeof status.reason === "string" ? status.reason : ""
+        };
+      }
+    }
+    if (frame.type === "user" && !frame.isMeta && frame.uuid &&
+        (typeof frame.message?.content === "string" || frame.message?.content?.some((block) => block.type === "text"))) {
+      userIds.push(frame.uuid);
+      lastUserId = frame.uuid;
+    }
+    for (const message of claudeMessageBlocks(frame)) {
+      messages.set(message.id, { ...message, userId: lastUserId });
+    }
+  }
+  return { exists: true, messages: [...messages.values()], userIds, goal,
+    text: [...messages.values()].filter((message) => message.role === "assistant" && message.userId === lastUserId)
+      .map((message) => message.text).join("\n") };
+}
+
+/** Remove the stopped temporary conversation's active native transcript. */
+export async function deleteClaudeConversationHistory({ configRoot, workdir, conversationId }) {
+  const file = await claudeHistoryPath({ configRoot, workdir, conversationId });
+  if (file) await rm(file.path, { force: true });
+}
+
+export { claudeMessageBlocks, readClaudeHistory, requireClaudeSessionId, archivedClaudeProjectDirectory, matchingClaudeProjectDirectories };
+
+const TRANSCRIPT_PATH_PATTERN = /\.jsonl(?:\.(?:superseded|orphaned)-.*)?$/u;
+
+export async function retireClaudeConversationHistory({ configRoot, binding, beforeDelete, requireIdle, signal }) {
+  const id = requireClaudeSessionId(binding.conversationId);
+  if (!path.isAbsolute(configRoot)) throw new TypeError("Claude retirement requires an absolute configuration root.");
+  const root = path.resolve(configRoot);
+  const projects = path.join(root, "projects");
+  const isTranscript = (file) => !file.directory &&
+    file.path.startsWith(`${projects}${path.sep}`) && TRANSCRIPT_PATH_PATTERN.test(file.path);
+  const missing = (error) => { if (error.code === "ENOENT") return null; throw error; };
+  const inspect = async () => {
+    await requireIdle();
+    const rootInfo = await lstat(root).catch(missing);
+    if (!rootInfo) return [];
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || await realpath(root) !== root) {
+      throw new Error("Claude storage root must be a canonical directory without symlink parents.");
+    }
+    const directory = await archivedClaudeProjectDirectory(binding.workdir);
+    const directories = async (parent) => {
+      const info = await lstat(parent).catch(missing);
+      if (!info) return [];
+      if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Claude storage contains an unsafe directory.");
+      const names = await readdir(parent);
+      if (names.length > 10000) throw new Error("Claude storage directory exceeds its inspection limit.");
+      return names;
+    };
+    const projectNames = await directories(projects);
+    const candidates = matchingClaudeProjectDirectories(projectNames, directory);
+    const targets = [];
+    let matches = 0;
+    for (const name of candidates) {
+      const parent = path.join(projects, name);
+      const names = await directories(parent);
+      const owned = names.filter((name) => name === id || name === `${id}.jsonl` ||
+        name.startsWith(`${id}.jsonl.superseded-`) || name.startsWith(`${id}.jsonl.orphaned-`));
+      if (owned.length) matches += 1;
+      targets.push(...owned.map((name) => path.join(parent, name)));
+    }
+    if (matches > 1) throw new Error("Claude conversation occurs in more than one native project directory.");
+    for (const kind of ["file-history", "image-cache", "uploads"]) {
+      const parent = path.join(root, kind);
+      if ((await directories(parent)).includes(id)) targets.push(path.join(parent, id));
+    }
+    const files = [];
+    const visit = async (file) => {
+      const info = await lstat(file);
+      if ((!info.isFile() && !info.isDirectory()) || info.isSymbolicLink() || files.length >= 10000) {
+        throw new Error("Claude conversation contains unsafe paths or exceeds its inspection limit.");
+      }
+      files.push({ path: file, directory: info.isDirectory(), inode: info.ino, size: info.size, modified: info.mtimeMs });
+      if (info.isDirectory()) for (const name of (await directories(file)).sort()) await visit(path.join(file, name));
+    };
+    for (const target of targets.sort()) await visit(target);
+    const transcripts = files.filter(isTranscript);
+    return targets.length ? [{ conversationId: id, workdir: binding.workdir, paths: targets, files,
+      ...(transcripts.length ? { updatedAt: new Date(Math.max(...transcripts.map((file) => file.modified))).toISOString() } : {}) }] : [];
+  };
+  return retireNativeConversation({ binding, inspect, beforeDelete,
+    exportConversation: async (_id, onRecord) => {
+      const deadline = AbortSignal.timeout(300_000);
+      const boundedSignal = signal ? AbortSignal.any([signal, deadline]) : deadline;
+      const output = createNativeHistoryExport(onRecord, { signal: boundedSignal });
+      const [conversation] = await inspect();
+      if (!conversation) throw new Error("Claude conversation disappeared before export.");
+      for (const file of conversation.files.filter(isTranscript)) {
+        const branchId = path.relative(projects, file.path).split(path.sep).join("/");
+        if (!file.size) continue;
+        const stream = createReadStream(file.path, { end: file.size - 1, signal: boundedSignal });
+        for await (const frame of readClaudeJsonFrames(stream)) {
+          const provenance = { branchId,
+            ...(frame.uuid || frame.message?.id ? { messageId: frame.uuid || frame.message.id } : {}),
+            ...(frame.parentUuid ? { parentMessageId: frame.parentUuid } : {}),
+            ...(frame.timestamp ? { createdAt: frame.timestamp } : {}),
+            ...(frame.message?.model ? { modelId: frame.message.model } : {}) };
+          const text = claudeMessageBlocks(frame, { includeNested: true })
+            .filter((message) => message.role !== "thinking")
+            .map((message) => ({ ...provenance, role: "assistant", text: message.text }));
+          if (frame.type === "user") {
+            const content = frame.message?.content;
+            const user = typeof content === "string" ? content : (Array.isArray(content) ? content : [])
+              .filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("\n\n");
+            if (user) text.push({ ...provenance, role: "user", text: user });
+          }
+          if (frame.attachment?.type === "goal_status" && typeof frame.attachment.condition === "string") {
+            text.push({ ...provenance, role: "goal", text: frame.attachment.condition });
+          }
+          await output.emit({ type: "frame", branchId, frame, text });
+        }
+      }
+      return output.complete();
+    },
+    remove: async (records) => {
+      await requireIdle();
+      for (const target of records[0].paths) await rm(target, { recursive: true, force: true });
+    }
+  });
+}