@jskit-ai/assistant-core 0.2.6 → 0.2.8

package/src/server/conversation/claudePromptDelivery.js

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import { claudeNativeMessageId } from "./claudeHistory.js";
+import { normalizeNullableText } from "./normalize.js";
+import { ignorePromptSending, ignoreReceipt } from "./nativeCommandCallbacks.js";
+
+/**
+ * Delivers an authored input to an entry's Claude process: duplicate checks,
+ * preparation, steering, the new turn, and the native and persisted receipts.
+ * @param {{
+ *   store: import("./claudeTurn.js").ClaudeConversationStore,
+ *   preparation: import("./claudeTurn.js").ClaudeConversationPreparation,
+ *   createError: import("./claudeTurn.js").ClaudeConversationErrorFactory,
+ *   onEvent: import("./claudeTurn.js").ClaudeConversationEventHandler,
+ *   readHistory: (entry: import("./claudeTurn.js").ClaudeConversationEntry) => Promise<Record<string, any>>,
+ *   bindAccount: (entry: import("./claudeTurn.js").ClaudeConversationEntry) => Promise<void>,
+ *   ensureProcess: (entry: import("./claudeTurn.js").ClaudeConversationEntry, input?: Record<string, any>) => Promise<Record<string, any>>,
+ *   snapshot: (entry: import("./claudeTurn.js").ClaudeConversationEntry) => Record<string, any> | null
+ * }} options
+ */
+export function createClaudePromptDelivery({
+  store,
+  preparation,
+  createError,
+  onEvent,
+  readHistory,
+  bindAccount,
+  ensureProcess,
+  snapshot
+}) {
+  async function send(entry, ...args) {
+    entry.sending = (entry.sending || 0) + 1;
+    try { return await dispatchPrompt(entry, ...args); }
+    finally { entry.sending -= 1; }
+  }
+
+  async function dispatchPrompt(entry, input = {}, { renewal = false, command, applicationCommand } = {}) {
+    const message = command ? input.text : normalizeNullableText(input.message || input.prompt);
+    if (!command && !message) throw createError("Enter a message for Claude.", { code: "conversation_claude_message_required" });
+    const context = entry.context;
+    const messageId = command ? input.messageId : normalizeNullableText(input.messageId) || randomUUID();
+    const uuid = claudeNativeMessageId(messageId);
+    const deliveryTiming = (command || input).deliveryTiming;
+    const { onNativeReceipt = ignoreReceipt, onReceiptPersisted = ignoreReceipt } = command || input;
+    const { onPromptSending = ignorePromptSending } = input;
+    if (!command) {
+      if (entry.main && await store.hasMessage(context, messageId)) {
+        return { ok: true, delivered: true, duplicate: true, thread: { id: entry.id }, turn: snapshot(entry) };
+      }
+      deliveryTiming?.("duplicate-checked");
+      preparation.check(entry, context);
+      const history = await readHistory(entry);
+      deliveryTiming?.("native-history-read");
+      if (history.userIds.includes(uuid)) {
+        return { ok: true, delivered: true, duplicate: true, thread: { id: entry.id }, turn: snapshot(entry) };
+      }
+    }
+    let native;
+    try {
+      if (!command && entry.main && entry.turn?.active && entry.process) {
+        // Main steering keeps the active instruction installation, just like
+        // command steering. Refresh guidance on the next idle admission.
+        // Account replacement must still confirm cleanup before any new send.
+        if (preparation.account) await bindAccount(entry);
+        native = entry.process || await ensureProcess(entry, input);
+      } else {
+        native = command ? command.steering ? entry.process : await entry.nativeTurn.prepare(command.prepared) : await ensureProcess(entry, input);
+      }
+    } catch (error) {
+      // Preparation may start or resume the process, but has not written this
+      // authored input. Keep its failure distinct from a lost native receipt.
+      throw Object.assign(error, { delivery: "not-sent" });
+    }
+    deliveryTiming?.("process-ready");
+    if (command && !command.steering) command.signal.throwIfAborted();
+    const steering = command ? command.steering === true : Boolean(entry.turn?.active);
+    if (input.signal?.aborted) {
+      throw Object.assign(createError("The goal command was stopped before delivery.", { code: "conversation_claude_command_stopped" }), { delivery: "not-sent" });
+    }
+    if (steering) {
+      if (command) {
+        await command.beforeDispatch({ threadId: entry.id });
+        command.signal.throwIfAborted();
+      }
+      // A mid-turn message is never an interrupt: Claude Code queues it and
+      // reads it after the running tool call. Only explicit Stop interrupts.
+      try { await entry.nativeTurn.prepareSteering(); }
+      catch (error) {
+        if (!command) await entry.nativeTurn.stopProcess(error.message);
+        // This precedes the input's pipe write: a refused steer is definitely not sent.
+        throw Object.assign(error, { delivery: "not-sent" });
+      }
+    }
+    const prompt = command ? undefined : await preparation.message(entry, input, { context, message, steering, renewal, deliveryTiming });
+    if (!command) deliveryTiming?.("prompt-rendered");
+    if (command) {
+      await command.beforeDispatch({ threadId: entry.id });
+      command.signal.throwIfAborted();
+    }
+    if (!steering) {
+      entry.renewal = renewal;
+      entry.nativeTurn.begin({ id: uuid, maxOutputCharacters: command ? command.maximumOutput : entry.profile?.limits.maxOutputCharacters });
+      entry.observationError = "";
+      entry.turn = { id: uuid, active: true, state: "starting", startedAt: new Date().toISOString(), updatedAt: new Date().toISOString(), error: "" };
+      if (!command) entry.completion = Promise.withResolvers();
+      if (!command) await entry.nativeTurn.updateState("starting");
+    }
+    entry.onEvent = context.onEvent;
+    entry.lastMessageId = uuid;
+    const actorMetadata = command ? undefined : await onEvent(entry, { type: "message-metadata", input, context });
+    if (!command) deliveryTiming?.("metadata-ready");
+    const nativeOwner = applicationCommand ? { process: native, executionId: entry.executionId,
+      accountIdentity: entry.accountIdentity, threadId: entry.id, turnId: entry.turn.id } : null;
+    let conversationTurn;
+    function deliveryResult() {
+      return { ok: true, delivered: true, deliveryMode: steering ? "steer" : "new_turn",
+        thread: { id: entry.id }, turn: snapshot(entry), workdir: context.workdir, conversationTurn };
+    }
+    async function accept() {
+      onNativeReceipt();
+      // The new native ACK retires old effect custody while its canonical
+      // admission/commit is awaited; it cannot retag a delayed old failure.
+      if (applicationCommand) applicationCommand.active.nativeOwner = null;
+      if (command) {
+        if (!steering) await onEvent(entry, { type: "binding-admitted" });
+        await command.accept();
+        if (steering) {
+          command.active.messageId = input.messageId;
+          command.active.nativeToolCount = 0;
+        } else command.active.admitted = true;
+        command.admitted = true;
+      } else {
+        const admission = onEvent(entry, { type: "admit-message", input, context, renewal, message, messageId, uuid, actorMetadata });
+        if (admission) conversationTurn = await admission;
+        deliveryTiming?.("receipt-written");
+      }
+      if (!command) {
+        await entry.nativeTurn.updateState("active");
+        deliveryTiming?.("state-active");
+      }
+      onReceiptPersisted();
+      if (applicationCommand && conversationTurn) {
+        const value = deliveryResult();
+        const active = applicationCommand.active;
+        const previousCompletion = active.completion;
+        if (active.finishIfCurrent) {
+          active.completion = Promise.withResolvers();
+          active.completion.promise.catch(() => {});
+        }
+        active.delivery = { value, completion: active.finishIfCurrent ? active.completion.promise : entry.completion?.promise };
+        if (active.finishIfCurrent) previousCompletion.resolve();
+        // The original canonical admission and publication precede Core's same
+        // accepted-request gate; native tools cannot race an unaccepted user.
+        await applicationCommand.accept({ nativeResult: { value }, conversationTurn, nativeTurnId: entry.turn?.id });
+        if (entry.process !== nativeOwner.process || entry.executionId !== nativeOwner.executionId ||
+            entry.accountIdentity !== nativeOwner.accountIdentity || entry.id !== nativeOwner.threadId ||
+            entry.turn?.id !== nativeOwner.turnId || entry.disposed || entry.stopping || entry.stopPending) {
+          throw new Error("Claude's admitted tools no longer belong to this native process.");
+        }
+        applicationCommand.active.nativeOwner = nativeOwner;
+        applicationCommand.active.messageId = messageId;
+        if (steering) applicationCommand.active.nativeToolCount = 0;
+        applicationCommand.active.admitted = true;
+      }
+    }
+    try {
+      if (command) command.attempted = true;
+      else await onPromptSending({ threadId: entry.id, displayAttachments: input.displayAttachments, turnMetadata: actorMetadata });
+      if (input.signal?.aborted) {
+        throw Object.assign(createError("The goal command was stopped before delivery.", { code: "conversation_claude_command_stopped" }), { delivery: "not-sent" });
+      }
+      await entry.nativeTurn.send(command ? entry.process.client : native.client, command ? preparation.message(entry, input) : prompt,
+        { messageId: uuid, accept, steer: steering, ...(command ? { timeoutMs: command.timeoutMs } : {}) });
+    } catch (error) {
+      if (!command) await entry.nativeTurn.stopProcess(error.message);
+      throw error;
+    }
+    return deliveryResult();
+  }
+
+  return Object.freeze({
+    send
+  });
+}

package/src/server/conversation/claudeSessionCleanup.js

@@ -0,0 +1,248 @@
+import path from "node:path";
+import { deleteClaudeConversationHistory } from "./claudeHistory.js";
+import { hasPendingClaudeStartup } from "./claudeProcessStart.js";
+import { normalizeNullableText } from "./normalize.js";
+
+const ACTIVE_TURN_STATES = ["starting", "active", "finalizing"];
+
+/**
+ * Closes what an owner runs: sessions, projects, a connection change's work
+ * and the whole owner at shutdown. It knows which sessions are closing and
+ * whether the owner itself is.
+ * @param {{
+ *   entries: Map<string, import("./claudeTurn.js").ClaudeConversationEntry>,
+ *   store: import("./claudeTurn.js").ClaudeConversationStore,
+ *   configRoot: string,
+ *   acquire: (context: Record<string, any>, conversationId?: string, options?: Record<string, any>) => Promise<import("./claudeTurn.js").ClaudeConversationEntry>,
+ *   savedState: (saved: string | null, conversationId: string) => Record<string, any>,
+ *   holdsNativeWork: (entry: import("./claudeTurn.js").ClaudeConversationEntry) => boolean,
+ *   disconnectedMessage: string
+ * }} options
+ */
+export function createClaudeSessionCleanup({
+  entries,
+  store,
+  configRoot,
+  acquire,
+  savedState,
+  holdsNativeWork,
+  disconnectedMessage
+}) {
+  const closingSessions = new Set();
+  let closing = false;
+
+  // The owner is closing for shutdown, or the session this context key names is.
+  function isClosing(contextKey) {
+    return closing || closingSessions.has(contextKey);
+  }
+
+  async function reconcileSessions(sessions, options = {}, application) {
+    const results = [];
+    for (const session of sessions) {
+      const ctx = await application.readContext({ ...options, session, sessionId: session.sessionId });
+      await recover(await restoreSessionEntries(ctx, { acquire }));
+      results.push({ ok: true, sessionId: session.sessionId, resumed: false });
+    }
+    return { ok: true, results, failed: [], sessionCount: results.length };
+  }
+
+  async function restoreSessionEntries(context, { acquire }) {
+    let saved = store.readSessionConversations(context);
+    // readable-check: allow method-probe - data: a store lists a session's conversations synchronously or with a promise
+    if (saved && typeof saved.then === "function") saved = await saved;
+    for (const conversationId of saved.ids) await acquire(saved.context, conversationId);
+    return [...entries.values()].filter((entry) => entry.context.key === context.key);
+  }
+
+  // A session's close stops what this server runs for it, then reopens only
+  // saved custody an earlier server left. Once the owner is closing for an
+  // account change or shutdown it reopens nothing.
+  async function closeSession(context, application) {
+    return closeRetained(await application.readContext(context), application,
+      { recover: !closing, forget: context.forgetConversationBinding === true });
+  }
+
+  // Renewal proof release ends a session this server no longer uses. Its own
+  // close already recovered saved custody while its record could be written.
+  async function releaseSession(context, application) {
+    return closeRetained(await application.readContext(context), application, { recover: false, forget: true });
+  }
+
+  async function closeRetained(ctx, application, { recover: recoverCustody, forget: forgetEntries }) {
+    closingSessions.add(ctx.key);
+    try {
+      if (recoverCustody) await recoverSavedCustody(ctx);
+      const proofs = await drain(ctx.key);
+      const terminal = await application.terminals.close(ctx.sessionId);
+      // A forgotten entry is drained: everything it held is in its saved record.
+      if (terminal?.ok !== false && forgetEntries) forget(ctx.key);
+      return { ok: terminal?.ok !== false, closed: proofs.length + Number(terminal?.closed || 0),
+        processExitProof: proofs.at(-1) || { exited: true, scopeEmpty: true }, processExitProofs: proofs };
+    } finally {
+      closingSessions.delete(ctx.key);
+    }
+  }
+
+  // Saved custody an earlier server left: an execution whose exit is still
+  // unproven, or a turn saved as active. Only those conversations are reopened,
+  // so a verified stop can retire them; idle saved conversations stay closed.
+  async function recoverSavedCustody(ctx) {
+    let saved = store.readSessionConversations(ctx);
+    // readable-check: allow method-probe - data: a store lists a session's conversations synchronously or with a promise
+    if (saved && typeof saved.then === "function") saved = await saved;
+    for (const conversationId of saved.ids) {
+      if (entries.has(`${ctx.key}\0${conversationId}`)) continue;
+      let record = store.read(saved.context, conversationId);
+      // readable-check: allow method-probe - data: a store reads a saved record synchronously or with a promise
+      if (record && typeof record.then === "function") record = await record;
+      const state = savedState(record, conversationId);
+      if (state.executionId || ACTIVE_TURN_STATES.includes(state.state)) await acquire(saved.context, conversationId);
+    }
+  }
+
+  // Project close releases what this server runs for the project's sessions,
+  // from their retained entries alone, and forgets them: nothing uses them.
+  function closeProject(input = {}, application) {
+    const root = normalizeNullableText(input.projectContextRoot);
+    return eachSession(entry => !root || path.resolve(store.projectContextRoot(entry)) === path.resolve(root),
+      ctx => closeRetained(ctx, application, { recover: false, forget: true }));
+  }
+
+  async function invalidateRuntimes(input = {}, application, account) {
+    if (input.provider && input.provider !== "claude") return { ok: true, closed: 0 };
+    if (input.modelProviderId) {
+      return stopSelected(entry => store.modelProviderId(entry) === input.modelProviderId,
+        "The provider connection changed.");
+    }
+    if (input.reason !== "server-shutdown") {
+      // An account change stops and waits on nothing. Claude Code reads its
+      // credentials for every request, so running work continues on the newly
+      // connected account or ends at once as signed out; each conversation
+      // rebinds its account at its next idle admission. Only the account's
+      // cached reads are dropped. A cancelled query's process stop that fails
+      // stays owned and is retried before the next query.
+      account.queries.invalidate().catch(() => {});
+      return { ok: true, closed: 0 };
+    }
+    closing = true;
+    // Neither waits for the other: a failed account query cleanup must not
+    // leave the sessions' processes running.
+    const [queries, retained] = await Promise.allSettled([account.queries.invalidate(), stopRetained(application)]);
+    if (queries.status === "rejected") await account.failure(queries.reason);
+    if (retained.status === "rejected") throw retained.reason;
+    return retained.value;
+  }
+
+  // Shutdown stops only what this server runs: a Claude process cannot outlive
+  // the server that started it, so retained entries hold every one. Saved
+  // conversations are not reopened just to be stopped.
+  function stopRetained(application) {
+    return eachSession(() => true, ctx => closeRetained(ctx, application, { recover: false, forget: false }));
+  }
+
+  // Sessions close independently and together: one that fails is reported by
+  // its ID while every other session still stops.
+  async function eachSession(select, close) {
+    const contexts = new Map([...entries.values()].filter(select).map(entry => [entry.context.key, entry.context]));
+    const settled = await Promise.allSettled([...contexts.values()].map(ctx => close(ctx)));
+    let closed = 0;
+    const failed = [];
+    [...contexts.values()].forEach((ctx, index) => {
+      const result = settled[index];
+      if (result.status === "fulfilled") closed += result.value.closed;
+      const error = result.status === "rejected" ? result.reason?.message || String(result.reason)
+        : result.value.ok === false ? "Its Claude Code terminal could not be closed." : "";
+      if (error) failed.push({ sessionId: ctx.sessionId, error });
+    });
+    return { ok: failed.length === 0, closed, failed,
+      ...(failed.length ? { error: failed.map(({ sessionId, error }) => `Claude session ${sessionId}: ${error}`).join(" ") } : {}) };
+  }
+
+  async function drain(key) {
+    const selected = [...entries.values()].filter(entry => entry.context.key === key);
+    // Fence configuration still in progress: it must not start a process later.
+    for (const entry of selected) entry.preparationRevision++;
+    const proofs = [];
+    let failure;
+    async function stop() {
+      for (const entry of selected) if (holdsNativeWork(entry)) {
+        try { proofs.push(await entry.nativeTurn.stopProcess()); }
+        catch (error) { failure ||= error; }
+      }
+    }
+    // Startup already lends cleanup before initialization completes. Stop it
+    // first; waiting for the preparation queue first can exhaust host shutdown.
+    await stop();
+    await Promise.allSettled(selected.map(entry => entry.nativeTurn.whenIdle()));
+    await stop();
+    // Every other entry still stopped; the first failure keeps the close retryable.
+    if (failure) throw failure;
+    return proofs;
+  }
+
+  function forget(contextKey) {
+    for (const [key, entry] of entries) if (entry.context.key === contextKey) {
+      // Nothing would ever stop a process a forgotten entry started.
+      entry.disposed = true;
+      entries.delete(key);
+    }
+  }
+
+  async function close(entry) {
+    await entry.nativeTurn.stopProcess("Conversation closed.");
+    entry.disposed = true;
+    await entry.nativeTurn.whenIdle().catch(() => {});
+    await entry.nativeTurn.stopProcess("Conversation closed.");
+    if (entries.get(entry.key) === entry) entries.delete(entry.key);
+  }
+
+  async function deleteConversation(entry) {
+    await entry.nativeTurn.stopProcess();
+    await deleteClaudeConversationHistory({ configRoot, workdir: entry.nativeWorkdir, conversationId: entry.id });
+    await store.remove(entry);
+    entries.delete(entry.key);
+    return { ok: true, deleted: true, conversationId: entry.id };
+  }
+
+  async function recover(restoredEntries) {
+    for (const entry of restoredEntries) {
+      if (!entry.process && !hasPendingClaudeStartup(entry) && (entry.executionId || entry.turn?.active)) await entry.nativeTurn.stopProcess(disconnectedMessage);
+    }
+  }
+
+  // A provider connection change stops the matching work this server runs.
+  // Each entry stops on its own, so one failure is reported by ID.
+  async function stopSelected(select, reason) {
+    let closed = 0;
+    const failed = [];
+    for (const entry of [...entries.values()].filter(select)) {
+      entry.preparationRevision++;
+      if (!holdsNativeWork(entry)) continue;
+      try {
+        await entry.nativeTurn.stopProcess(reason);
+        closed++;
+      } catch (error) {
+        failed.push({ sessionId: entry.context.sessionId, conversationId: entry.id, error: error.message });
+      }
+    }
+    return { ok: failed.length === 0, closed, failed };
+  }
+
+  return Object.freeze({
+    get closing() { return closing; },
+    closingSessions,
+    isClosing,
+    reconcileSessions,
+    restoreSessionEntries,
+    closeSession,
+    releaseSession,
+    closeProject,
+    invalidateRuntimes,
+    drain,
+    forget,
+    close,
+    deleteConversation,
+    recover,
+    stopSelected
+  });
+}

package/src/server/conversation/claudeTools.js

@@ -2,9 +2,21 @@ import { isDeepStrictEqual } from "node:util";
 
 export const CLAUDE_APPLICATION_TOOL_SERVER = "application";
 
+/** A call from tools the conversation owns needs no supplied owner's check. */
+function acceptNativeCall() {}
+
+/** A call from tools the conversation owns fails only its own exchange. */
+function ignoreExecutionFailure() {}
+
 // The CLI carries this SDK MCP exchange over its existing control pipe. There
 // is no listening socket or separate tool process. The shared executor owns effects.
-export async function claudeApplicationToolResponse(request, { schemas, turn, signal, assertCurrent, onExecutionFailure }) {
+export async function claudeApplicationToolResponse(request, {
+  schemas,
+  turn,
+  signal,
+  assertCurrent = acceptNativeCall,
+  onExecutionFailure = ignoreExecutionFailure
+}) {
   if (request?.subtype !== "mcp_message" || request.server_name !== CLAUDE_APPLICATION_TOOL_SERVER ||
       request.message?.jsonrpc !== "2.0") throw new Error("This Claude control request is not an application tool exchange.");
   const message = request.message;
@@ -33,12 +45,12 @@ export async function claudeApplicationToolResponse(request, { schemas, turn, si
       }
       // Optional supplied-owner checks run after the unchanged native-use
       // validation. Protocol/stale refusals are not owned executor failures.
-      assertCurrent?.(native);
+      assertCurrent(native);
       let value;
       try {
         value = await turn.tools.execute({ id, name: params.name, arguments: JSON.stringify(params.arguments || {}) }, { signal, messageId: native.messageId });
       } catch (error) {
-        onExecutionFailure?.(error, native);
+        onExecutionFailure(error, native);
         throw error;
       }
       result = { content: [{ type: "text", text: JSON.stringify(value) }], isError: value.ok === false };