@jskit-ai/assistant-core 0.2.13 → 0.2.15

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

@@ -99,7 +99,9 @@ export async function openStandaloneOpenCodeConversation({
 
   if (!binding || typeof binding.sessionId !== "string" || binding.workdir !== await realpath(workdir) ||
       path.dirname(binding.directory || "") !== stateDirectory) {
-    throw new Error("This OpenCode conversation belongs to another working directory or native state directory. Restore its original host configuration.");
+    throw Object.assign(new Error("This OpenCode conversation belongs to another working directory or native state directory. Restore its original host configuration."), {
+      messageCode: "assistant.opencode.otherWorkingDirectory", messageParams: {}
+    });
   }
   let native;
   let toolBridge;
@@ -151,7 +153,8 @@ export async function openStandaloneOpenCodeConversation({
     })().catch(error => {
       error.cleanupFailed = true;
       if (error.code === "assistant_opencode_stop_unverified") {
-        error.message = "OpenCode process cleanup could not be confirmed. Restore its execution host before continuing.";
+        Object.assign(error, { message: "OpenCode process cleanup could not be confirmed. Restore its execution host before continuing.",
+          messageCode: "assistant.opencode.cleanupUnconfirmed", messageParams: {} });
       }
       throw error;
     }).finally(() => { stopping = null; });
@@ -175,11 +178,15 @@ export async function openStandaloneOpenCodeConversation({
       binding.runtimeDirectory && binding.runtimeDirectory !== preparedFacilities.runtimeDirectory ||
       facilities && facilities.runtime !== preparedFacilities.runtime
     )) {
-      throw new Error("This OpenCode conversation belongs to another native history store or runtime. Restore its original host configuration.");
+      throw Object.assign(new Error("This OpenCode conversation belongs to another native history store or runtime. Restore its original host configuration."), {
+        messageCode: "assistant.opencode.otherHistoryStoreOrRuntime", messageParams: {}
+      });
     }
     const allowCredentialRefresh = authoredPreparation && host.opencode && preparedFacilities.allowCredentialRefresh === true;
     if (binding.accountIdentity && identity !== binding.accountIdentity && !allowCredentialRefresh) {
-      throw new Error("This conversation belongs to another OpenCode account. Restore that connection or start a new conversation.");
+      throw Object.assign(new Error("This conversation belongs to another OpenCode account. Restore that connection or start a new conversation."), {
+        messageCode: "assistant.opencode.otherAccount", messageParams: {}
+      });
     }
     if (binding.accountIdentity !== identity) await updateBinding({ accountIdentity: identity });
     const model = { providerID: connection.providerId, id: connection.model };
@@ -223,7 +230,9 @@ export async function openStandaloneOpenCodeConversation({
         };
       }
       if (binding.databasePath && binding.databasePath !== facilities.databasePath) {
-        throw new Error("This OpenCode conversation belongs to another native history store. Restore its original host configuration.");
+        throw Object.assign(new Error("This OpenCode conversation belongs to another native history store. Restore its original host configuration."), {
+          messageCode: "assistant.opencode.otherHistoryStore", messageParams: {}
+        });
       }
       await updateBinding({ databasePath: facilities.databasePath, runtimeDirectory: facilities.runtimeDirectory });
     }
@@ -257,19 +266,25 @@ export async function openStandaloneOpenCodeConversation({
       await updateBinding({ executionId: native.server.executionId, processDirectory: native.server.privateRoot || "" });
       const catalogue = await native.server.client.providers({ signal });
       const selected = catalogue.all.find(provider => provider.id === connection.providerId)?.models?.[connection.model];
-      if (selected?.id !== connection.model) throw new Error("OpenCode could not load the configured model definition. Check the selected integration before sending.");
+      if (selected?.id !== connection.model) throw Object.assign(new Error("OpenCode could not load the configured model definition. Check the selected integration before sending."), {
+        messageCode: "assistant.opencode.modelDefinitionUnavailable", messageParams: {}
+      });
       processVariants = selected.variants || {};
     } catch (error) {
       if (error.stopProof?.scopeEmpty) await updateBinding({ executionId: "", processDirectory: "" });
       throw error;
     }
     if (configuration.effort) {
-      if (!Object.hasOwn(processVariants, configuration.effort)) throw new Error("The selected OpenCode model does not support this reasoning effort.");
+      if (!Object.hasOwn(processVariants, configuration.effort)) throw Object.assign(new Error("The selected OpenCode model does not support this reasoning effort."), {
+        messageCode: "assistant.opencode.reasoningEffortUnsupported", messageParams: {}
+      });
       model.variant = configuration.effort;
     }
     const retainedId = binding.sessionId;
     if (retainedId && (await native.server.client.sessionStatus(retainedId, { signal })).type !== "idle") {
-      throw new Error("The native OpenCode conversation is still working. Stop or inspect it before sending another message.");
+      throw Object.assign(new Error("The native OpenCode conversation is still working. Stop or inspect it before sending another message."), {
+        messageCode: "assistant.opencode.nativeStillWorking", messageParams: {}
+      });
     }
     const session = {
       selection: { agentId: agent, modelId: model.id, modelProviderId: model.providerID, variantId: model.variant || "" },
@@ -277,7 +292,9 @@ export async function openStandaloneOpenCodeConversation({
       invalidIdentity: () => new Error("OpenCode did not acknowledge a native conversation."),
       identity: {
         async write(nativeId) {
-          if (retainedId && nativeId !== retainedId) throw new Error("The saved OpenCode conversation is unavailable. Restore its native history before continuing.");
+          if (retainedId && nativeId !== retainedId) throw Object.assign(new Error("The saved OpenCode conversation is unavailable. Restore its native history before continuing."), {
+            messageCode: "assistant.opencode.savedConversationUnavailable", messageParams: {}
+          });
           if (binding.sessionId !== nativeId) await updateBinding({ sessionId: nativeId });
         },
         publish(nativeId) {
@@ -390,7 +407,9 @@ export async function openStandaloneOpenCodeConversation({
         monitor: messageMonitor(active, command)
       });
       if (value.failure) throw value.failure.error;
-      if (!value.delivered) throw new Error("OpenCode did not acknowledge the message.");
+      if (!value.delivered) throw Object.assign(new Error("OpenCode did not acknowledge the message."), {
+        messageCode: "assistant.opencode.messageNotAcknowledged", messageParams: {}
+      });
     } catch (error) {
       const turn = facilities.runtime.turns.get(binding.directory);
       const attempted = value?.failure ? value.failure.attempted : turn?.promptAttempted === true;
@@ -427,11 +446,15 @@ export async function openStandaloneOpenCodeConversation({
             text: configuration.outputSchema ? openCodeStructuredOutput(openCodeAssistantMessageText(message)) : openCodeAssistantMessageText(message) })) };
     },
     steer(command) {
-      if (!current || current.finished) throw new Error("OpenCode has no active turn to steer.");
+      if (!current || current.finished) throw Object.assign(new Error("OpenCode has no active turn to steer."), {
+        messageCode: "assistant.opencode.noTurnToSteer", messageParams: {}
+      });
       return send(command);
     },
     async run(command) {
-      if (disposed || current) throw new Error("This OpenCode conversation is closed or already working.");
+      if (disposed || current) throw Object.assign(new Error("This OpenCode conversation is closed or already working."), {
+        messageCode: "assistant.opencode.closedOrWorking", messageParams: {}
+      });
       const active = current = { tools: command.tools, configuration: command.configuration,
         onMessage: command.onMessage, onEvent: command.onEvent, messageIds: new Map(), previous: new Map() };
       let problem;
@@ -461,7 +484,8 @@ export async function openStandaloneOpenCodeConversation({
         }
       } catch (error) {
         problem = error.cleanupFailed ? error : command.signal.aborted ? command.signal.reason : error;
-        if (problem.cleanupFailed) problem.message = "OpenCode process cleanup could not be confirmed. Restore its execution host before continuing.";
+        if (problem.cleanupFailed) Object.assign(problem, { message: "OpenCode process cleanup could not be confirmed. Restore its execution host before continuing.",
+          messageCode: "assistant.opencode.cleanupUnconfirmed", messageParams: {} });
       }
       active.finished = true;
       try { if (!problem?.cleanupFailed && (problem || command.signal.aborted)) await stop(); }

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

@@ -376,7 +376,9 @@ export async function preparePersistentConversationChangeover(options) {
   const current = await records.read(context, record.conversationId);
   const native = current.providerConversationId ? requireSuccess(await operations.readConversation(sessionId,
     records.input(current), context)) : { status: "ready" };
-  if (["starting", "inProgress"].includes(native.status)) throw new Error("Stop this temporary conversation before changing its AI.");
+  if (["starting", "inProgress"].includes(native.status)) throw Object.assign(new Error("Stop this temporary conversation before changing its AI."), {
+    messageCode: "assistant.conversation.stopTemporaryBeforeChange", messageParams: {}
+  });
   record = await records.read(context, record.conversationId);
   if (record.providerConversationId) {
     requireSuccess(await operations.stopConversation(sessionId, records.input(record, { runId: record.runId }), context));

package/src/server/conversation/systemPrompt.js

@@ -41,7 +41,9 @@ export function createConversationSystemPrompt() {
       }
       // Do not let a caller start inference against an obsolete installation.
       if (generation !== startedGeneration) {
-        throw new Error("Conversation context changed while installing its system prompt. Retry before sending.");
+        throw Object.assign(new Error("Conversation context changed while installing its system prompt. Retry before sending."), {
+          messageCode: "assistant.conversation.contextChangedInstallingPrompt", messageParams: {}
+        });
       }
       installed = { systemPrompt, contextIdentity, value };
       return value;

package/src/server/conversation/tools.js

@@ -61,9 +61,13 @@ export function createConversationTools({ catalog, toolSet: retainedToolSet, con
     signal.throwIfAborted();
     if (typeof id !== "string" || !id || id.length > 256 || typeof name !== "string" || !name || name.length > 256 ||
         typeof argumentsText !== "string") throw new TypeError("An application tool requires its call id, name and JSON arguments.");
-    if (Buffer.byteLength(argumentsText) > catalog.limits.maxToolArgumentBytes) throw new Error("The application tool arguments exceed their size limit.");
+    if (Buffer.byteLength(argumentsText) > catalog.limits.maxToolArgumentBytes) throw Object.assign(new Error("The application tool arguments exceed their size limit."), {
+      messageCode: "assistant.conversation.toolArgumentsTooLarge", messageParams: {}
+    });
     const input = { id, name, arguments: argumentsText };
-    if (++requested > maximumCalls) throw new Error("The assistant reached the application tool-call limit for this turn.");
+    if (++requested > maximumCalls) throw Object.assign(new Error("The assistant reached the application tool-call limit for this turn."), {
+      messageCode: "assistant.conversation.toolCallLimit", messageParams: {}
+    });
     const recorded = calls.get(id);
     if (recorded) {
       if (!isDeepStrictEqual(input, { id: recorded.id, name: recorded.name, arguments: recorded.arguments })) {

package/src/shared/assistantSettingsResource.js

@@ -1,9 +1,21 @@
 import { createSchema } from "json-rest-schema";
 import { RECORD_ID_PATTERN } from "@jskit-ai/kernel/shared/validators";
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
 import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
 
 const MAX_SYSTEM_PROMPT_CHARS = 12_000;
 
+// Each field message: its English and the code a client renders it from in the
+// user's language, the { code, message, params } form of resource field messages.
+const ASSISTANT_SETTINGS_FIELD_MESSAGES = deepFreeze({
+  systemPromptTooLong: {
+    code: "assistant.settings.systemPromptTooLong",
+    message: `Assistant system prompt must be at most ${MAX_SYSTEM_PROMPT_CHARS} characters.`,
+    params: { max: MAX_SYSTEM_PROMPT_CHARS }
+  },
+  systemPromptInvalid: { code: "assistant.settings.systemPromptInvalid", message: "Assistant system prompt must be valid text." }
+});
+
 const assistantConfigRecordSchema = createSchema({
   targetSurfaceId: {
     type: "string",
@@ -43,8 +55,8 @@ const assistantConfigPatchSchema = createSchema({
     required: false,
     maxLength: MAX_SYSTEM_PROMPT_CHARS,
     messages: {
-      maxLength: `Assistant system prompt must be at most ${MAX_SYSTEM_PROMPT_CHARS} characters.`,
-      default: "Assistant system prompt must be valid text."
+      maxLength: ASSISTANT_SETTINGS_FIELD_MESSAGES.systemPromptTooLong,
+      default: ASSISTANT_SETTINGS_FIELD_MESSAGES.systemPromptInvalid
     }
   }
 });

package/test/claudeLifecycle.test.js

@@ -18,10 +18,11 @@ const IDLE_ID = "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee";
 // A host with Vibe64's storage rules: every save writes the session record, an
 // archived session refuses writes, saved conversations are re-read from storage
 // and a session whose workspace is gone cannot prepare a conversation context.
-async function lifecycleFixture(t) {
+// A running turn's end first runs the host's checkpoint, a Git snapshot there.
+async function lifecycleFixture(t, { turnEndCheckpoint = async () => {} } = {}) {
   const root = await mkdtemp(path.join(os.tmpdir(), "claude-lifecycle-"));
   const sessions = new Map();
-  const calls = { saves: [], reads: 0, stops: [] };
+  const calls = { saves: [], reads: 0, stops: [], checkpoints: [] };
   const processes = [];
   const session = sessionId => {
     if (!sessions.has(sessionId)) {
@@ -83,7 +84,13 @@ async function lifecycleFixture(t) {
       }
     },
     // As in Vibe64, the native turn's own checkpoints write the session record.
-    async onEvent(entry, event) { if (event.type === "save") await store.save(entry); }
+    async onEvent(entry, event) {
+      if (event.type === "before-state" && !event.active && entry.turn?.active) {
+        calls.checkpoints.push(`${entry.context.sessionId}:${event.state}`);
+        await turnEndCheckpoint();
+      }
+      if (event.type === "save") await store.save(entry);
+    }
   });
   owner = create();
   const terminals = [];
@@ -199,9 +206,40 @@ test("Claude shutdown stops sessions together and never rewrites an idle chat",
   assert.equal(result.ok, true);
   assert.deepEqual(running.map(entry => entry.process), [null, null, null]);
   const before = f.calls.saves.length;
-  // Shutdown invalidates more than once; the chats are idle now.
+  // Shutdown invalidates more than once; nothing is left to stop or write.
   assert.equal((await f.owner.invalidateRuntimes({ reason: "server-shutdown" }, f.application, f.account)).ok, true);
-  assert.equal(f.calls.saves.length, before, "idle chats were not written again");
+  assert.equal(f.calls.saves.length, before, "the chats were not written again");
+});
+
+test("Claude shutdown leaves a running turn's end and its checkpoint to the next server", { timeout: 5_000 }, async t => {
+  // The host's checkpoint can take longer than the server has to stop.
+  const checkpoint = Promise.withResolvers();
+  let checkpointWaits = true;
+  const f = await lifecycleFixture(t, { turnEndCheckpoint: () => checkpointWaits ? checkpoint.promise : undefined });
+  const a = await f.running("a");
+  const saved = f.session("a").records.get(MAIN_IDS.a);
+  let timer;
+  const result = await Promise.race([
+    f.owner.invalidateRuntimes({ reason: "server-shutdown" }, f.application, f.account),
+    new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Shutdown waited for the turn's checkpoint")), 1_000); })
+  ]).finally(() => {
+    clearTimeout(timer);
+    checkpoint.resolve();
+  });
+  assert.equal(result.ok, true, JSON.stringify(result));
+  assert.equal(a.process, null, "the process stopped");
+  assert.deepEqual(f.calls.checkpoints, [], "shutdown ran no checkpoint");
+  assert.equal(f.session("a").records.get(MAIN_IDS.a), saved, "the saved record was not rewritten");
+  const custody = ({ executionId, state }) => ({ executionId, state });
+  assert.deepEqual(custody(JSON.parse(saved)), { executionId: "execution-0", state: "active" });
+  // The next server's close proves that exit, then interrupts the turn through its checkpoint.
+  checkpointWaits = false;
+  f.restart();
+  const stops = f.calls.stops.length;
+  assert.equal((await f.owner.closeSession({ sessionId: "a" }, f.application)).ok, true);
+  assert.deepEqual(f.calls.stops.slice(stops), ["execution-0"]);
+  assert.deepEqual(f.calls.checkpoints, ["a:interrupted"]);
+  assert.deepEqual(custody(JSON.parse(f.session("a").records.get(MAIN_IDS.a))), { executionId: "", state: "interrupted" });
 });
 
 test("Claude project close releases its sessions from memory without reopening saved conversations", async t => {
@@ -280,6 +318,23 @@ test("closing a Claude session reopens only the saved custody an earlier server
     new RegExp(`saved Claude conversation ${IDLE_ID} is unreadable`));
 });
 
+test("reconciling a Claude session reopens only the saved custody an earlier server left", async t => {
+  const f = await lifecycleFixture(t);
+  const records = f.session("a").records;
+  const idle = JSON.stringify({ state: "completed", main: false });
+  records.set(MAIN_IDS.a, JSON.stringify({ state: "completed", turnId: "done", main: true }));
+  records.set(IDLE_ID, idle);
+  records.set(TEMPORARY_ID, JSON.stringify({ executionId: "execution-before-restart", state: "active", turnId: "turn", main: false }));
+  const result = await f.owner.reconcileSessions([{ sessionId: "a" }], {}, f.application);
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.results.map(({ ok, sessionId }) => [sessionId, ok]), [["a", true]]);
+  assert.deepEqual(f.calls.stops, ["execution-before-restart"], "the saved execution's exit was proven");
+  assert.equal(JSON.parse(records.get(TEMPORARY_ID)).executionId, "");
+  assert.equal(JSON.parse(records.get(TEMPORARY_ID)).state, "interrupted");
+  assert.deepEqual([...f.owner.entries.values()].map(entry => entry.id), [TEMPORARY_ID], "idle saved chats stayed closed");
+  assert.equal(records.get(IDLE_ID), idle, "an idle saved chat was not rewritten");
+});
+
 test("after shutdown invalidation a Claude session close reopens nothing", async t => {
   const f = await lifecycleFixture(t);
   await f.idle("a");