@jskit-ai/assistant-core 0.2.33 → 0.2.34

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- A Bash command that Claude steering moves to the background keeps its own time limit: its `timeout`, or Claude's two-minute default, counted from when it started. Moved by the `background_tasks` control (Ctrl+B) so a person's message reaches Claude, the command used to lose that limit, so a wait loop that never ended held the turn in its background phase (and the host's Save behind it) until it failed half an hour later. When its limit passes, the shared Claude turn stops its task with the `stop_task` control and publishes the `steered_command_limit` diagnostic (`steered_command_stop_failed` when Claude refuses it); Claude answers the task notification and the turn settles as after a foreground timeout. Commands Claude starts with `run_in_background`, and subagents, keep running as before.
 - Claude's model list is kept once per account in the server process instead of once per account-query owner, as plan usage already is: an owner the host creates again (a restarted service, a reopened project) answers `readCatalogue` from the list another owner read, without starting a tool-free Claude, while the account's credentials and Claude Code are unchanged. A credentials change (sign-in, sign-out, token refresh) or a Claude Code update still reads it again, and an owner's `invalidate()` drops the list of every account it used, for every owner.
 - Test fixture only: the responsive assistant fixture's avatar is drawn in the theme's `primary` and `on-primary` roles instead of a raw `#6750a4` and `white`, so it follows the dark scheme like the rest of the conversation. A package test runs `jskit check m3`'s raw-colour rule over the fixture, which the check itself skips with every `fixtures/` folder.
 - The assistant settings resource (`assistantConfigResource`) has a required boolean `canUpdate` attribute: whether the signed-in person may change the settings, as the server decides (`@jskit-ai/assistant-runtime`'s settings pane shows Save only when it is true).

package/examples/conversation/package.json

@@ -8,14 +8,14 @@
     "build": "vite build"
   },
   "dependencies": {
-    "@jskit-ai/assistant-core": "0.2.33",
-    "@jskit-ai/http-runtime": "0.2.15",
-    "@jskit-ai/kernel": "0.2.15",
+    "@jskit-ai/assistant-core": "0.2.34",
+    "@jskit-ai/http-runtime": "0.2.16",
+    "@jskit-ai/kernel": "0.2.16",
     "@jskit-ai/material-web": "0.1.4",
     "vue": "^3.5.13",
     "vuetify": "^4.0.0",
-    "@jskit-ai/connectors-core": "0.2.19",
-    "@jskit-ai/connectors-catalog": "0.2.19"
+    "@jskit-ai/connectors-core": "0.2.20",
+    "@jskit-ai/connectors-catalog": "0.2.20"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.7",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/assistant-core",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "type": "module",
   "scripts": {
     "test": "jskit test"
@@ -52,7 +52,7 @@
     "@ai-sdk/togetherai": "^3.0.49",
     "@ai-sdk/xai": "^4.0.58",
     "@jskit-ai/agent": "0.1.2",
-    "@jskit-ai/resource-core": "0.1.206",
+    "@jskit-ai/resource-core": "0.1.207",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.152",
     "json-rest-schema": "^1.0.17",
@@ -60,8 +60,8 @@
     "ws": "^8.20.1"
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.2.15",
-    "@jskit-ai/kernel": "0.2.15",
+    "@jskit-ai/http-runtime": "0.2.16",
+    "@jskit-ai/kernel": "0.2.16",
     "vue": "^3.5.13",
     "vuetify": "^4.3.0"
   },

package/src/server/conversation/claudeNativeTurn.js

@@ -2,6 +2,7 @@ import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { claudeMessageBlocks } from "./claudeHistory.js";
 import { stopClaudeCodeProcess } from "./claudeProcess.js";
 import { createClaudeConversationAdapter } from "./providers/claude.js";
+import { createClaudeSteeringBackground } from "./claudeSteeringBackground.js";
 
 // messageCode names the sentence, since one turn-failure code covers several.
 export function claudeTurnFailure(message, { code = "assistant_claude_turn_failed", messageCode } = {}) {
@@ -143,6 +144,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
   const waitingSteers = new Set();
   let steeringClient = null;
   const tasks = new Set();
+  const steeringBackground = createClaudeSteeringBackground({ publish, running: taskId => tasks.has(taskId) && !stopped && !cancelling,
+    counts: () => ({ pendingCommands: inFlight.size, backgroundTasks: tasks.size }) });
   let turnId = "";
   let messageId = "";
   let currentCommandId = "";
@@ -181,6 +184,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
     assistantRoles.clear();
     result = "";
     outcome = null;
+    steeringBackground.clear();
     invalidateFinalAssistantResult();
   }
 
@@ -189,13 +193,8 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
   // and subagents to the background: they keep running and report completion,
   // and the blocked tool call returns so Claude reads the steer now.
   function backgroundForegroundWork() {
-    const client = steeringClient;
-    if (!waitingSteers.size || !client?.request || stopped || cancelling) return;
-    void client.request({ subtype: "background_tasks" }).then(
-      () => publish({ type: "diagnostic", stage: "steering_backgrounded", pendingCommands: inFlight.size, backgroundTasks: tasks.size }),
-      // An older CLI still reads the steer when its tool call returns.
-      error => publish({ type: "diagnostic", stage: "steering_background_failed", error: error.message })
-    ).catch(() => {});
+    if (!waitingSteers.size || !steeringClient?.request || stopped || cancelling) return;
+    steeringBackground.background(steeringClient);
   }
 
   function currentReceiptOwner(owner) {
@@ -479,6 +478,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
       }
       const previousTaskCount = tasks.size;
       updateClaudeBackgroundTasks(tasks, frame);
+      steeringBackground.received(frame);
       // A command Claude started before reading a waiting steer would hold it too.
       if (frame.subtype === "task_started") backgroundForegroundWork();
       // Inventory removal can precede the task notification and the main model's
@@ -528,6 +528,7 @@ export function createClaudeConversationTurn({ conversationId, onEvent, process,
       if (apiMessageId && frame.message.content?.some(block => block.type === "tool_use")) {
         await flushAssistantMessages(apiMessageId, "commentary");
       }
+      for (const block of frame.message?.content || []) steeringBackground.called(block);
       for (const block of claudeMessageBlocks(frame)) {
         block.userId = currentCommandId;
         checkOutput(block.text, block.role);

package/src/server/conversation/claudeSteeringBackground.js

@@ -0,0 +1,97 @@
+// Claude Code's limit for a Bash call that names none (its BASH_DEFAULT_TIMEOUT_MS default).
+const CLAUDE_BASH_DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Steering's request that Claude move its foreground work to the background
+ * (Claude's Ctrl+B), and the time limit each Bash call it moves keeps.
+ *
+ * A moved call loses Claude's own limit, so a wait loop that never ends would
+ * hold the turn for good. Each foreground Bash call keeps its limit (its
+ * `timeout`, or Claude's default), counted from when it started: once steering
+ * has moved it, its task is stopped with Claude's `stop_task` control when that
+ * limit passes, as Claude would have stopped it in the foreground. Claude then
+ * answers the task notification and the turn settles. A call Claude ran with
+ * `run_in_background` has no limit and is never tracked.
+ * @param {{
+ *   publish: (event: Record<string, any>) => unknown,
+ *   running: (taskId: string) => boolean,
+ *   counts: () => { pendingCommands: number, backgroundTasks: number }
+ * }} dependencies
+ */
+export function createClaudeSteeringBackground({ publish, running, counts }) {
+  const calls = new Map();
+  const timers = new Map();
+  /** @type {{ request: (request: Record<string, any>) => Promise<unknown> } | null} */
+  let client = null;
+
+  // One control request; its diagnostic reports Claude's answer.
+  function control(request, stage, failedStage) {
+    void client.request(request).then(
+      () => publish({ type: "diagnostic", stage, ...counts() }),
+      error => publish({ type: "diagnostic", stage: failedStage, error: error.message })
+    ).catch(() => {});
+  }
+
+  function schedule(call) {
+    if (!call.steered || !call.taskId || timers.has(call.taskId) || !running(call.taskId)) return;
+    const timer = setTimeout(() => {
+      timers.delete(call.taskId);
+      if (running(call.taskId)) control({ subtype: "stop_task", task_id: call.taskId }, "steered_command_limit", "steered_command_stop_failed");
+    }, Math.max(0, call.startedAt + call.limitMs - Date.now()));
+    timer.unref();
+    timers.set(call.taskId, timer);
+  }
+
+  /**
+   * Asks Claude to move every running foreground call to the background. An
+   * older CLI refuses, and still reads the steer when its tool call returns.
+   * @param {{ request: (request: Record<string, any>) => Promise<unknown> }} steeringClient
+   */
+  function background(steeringClient) {
+    client = steeringClient;
+    for (const call of calls.values()) {
+      call.steered = true;
+      schedule(call);
+    }
+    control({ subtype: "background_tasks" }, "steering_backgrounded", "steering_background_failed");
+  }
+
+  // A content block of an assistant frame: a foreground Bash call starts now.
+  function called(block) {
+    if (block.type !== "tool_use" || block.name !== "Bash" || !block.id || calls.has(block.id) ||
+        block.input?.run_in_background === true) return;
+    const timeout = block.input?.timeout;
+    calls.set(block.id, { startedAt: Date.now(), taskId: "", steered: false,
+      limitMs: Number.isSafeInteger(timeout) && timeout > 0 ? timeout : CLAUDE_BASH_DEFAULT_TIMEOUT_MS });
+  }
+
+  // A system frame, after the turn has counted its tasks: task_started names the
+  // call its task runs, and a task that has finished needs no limit.
+  function received(frame) {
+    const call = frame.subtype === "task_started" ? calls.get(frame.tool_use_id) : null;
+    if (call) {
+      call.taskId = frame.task_id;
+      schedule(call);
+    }
+    for (const [taskId, timer] of timers) {
+      if (!running(taskId)) {
+        clearTimeout(timer);
+        timers.delete(taskId);
+      }
+    }
+  }
+
+  function clear() {
+    for (const timer of timers.values()) clearTimeout(timer);
+    timers.clear();
+    calls.clear();
+    client = null;
+  }
+
+  return Object.freeze({
+    background,
+    called,
+    received,
+    clear
+  });
+}

package/test/claudeTurn.test.js

@@ -2035,6 +2035,80 @@ test("a steer during Claude's follow-up to a finished background task moves that
   turn.stop();
 });
 
+// Frame shapes from Claude Code 2.1.308/2.1.319 stream-json: a person wrote while
+// a foreground wait loop with `timeout: 150000` ran. Steering backgrounded it, the
+// call lost its limit, and the wait held the turn in its background phase for
+// thirty minutes. The moved call stops at its own limit, as in the foreground.
+const flushControls = () => new Promise(setImmediate);
+for (const [timeout, limitMs] of [[150_000, 150_000], [undefined, 120_000]]) {
+  test(`a command steering moves to the background still stops at its own limit, timeout=${timeout}`, async t => {
+    t.mock.timers.enable({ apis: ["setTimeout", "Date"] });
+    const { turn, send, read, requests, events } = steeringFixture();
+    await send();
+    await read("first");
+    await turn.receive({ type: "assistant", uuid: "wait-call", message: { id: "wait-api", stop_reason: "tool_use",
+      content: [{ type: "tool_use", id: "toolu_wait", name: "Bash", input: {
+        command: "until grep -q ready status.txt; do sleep 5; done", description: "Wait for the status file",
+        ...(timeout ? { timeout } : {}) } }] } });
+    await turn.receive({ type: "system", subtype: "task_started", task_id: "b0wait", tool_use_id: "toolu_wait",
+      description: "Wait for the status file", task_type: "local_bash", is_backgrounded: false });
+    t.mock.timers.tick(60_000);
+    await turn.prepareSteering();
+    await send("question", { steer: true });
+    await flushControls();
+    assert.deepEqual(requests, [{ subtype: "background_tasks" }]);
+    await turn.receive({ type: "system", subtype: "task_updated", task_id: "b0wait", patch: { is_backgrounded: true } });
+    await turn.receive({ type: "user", uuid: "wait-result", message: { content: [{ type: "tool_result", tool_use_id: "toolu_wait",
+      content: "Command was manually backgrounded by user with ID: b0wait. Output is being written to: /tmp/b0wait.output" }] } });
+    await read("question");
+    await turn.receive({ type: "result", subtype: "success", result: "Here is the answer." });
+    await turn.receive({ type: "command_lifecycle", command_uuid: claudeNativeMessageId("first"), state: "completed" });
+    await turn.receive({ type: "command_lifecycle", command_uuid: claudeNativeMessageId("question"), state: "completed" });
+    assert.deepEqual([turn.read().active, turn.read().phase], [true, "background"]);
+
+    t.mock.timers.tick(limitMs - 60_001);
+    await flushControls();
+    assert.deepEqual(requests, [{ subtype: "background_tasks" }], "The call still has time left");
+    t.mock.timers.tick(1);
+    await flushControls();
+    assert.deepEqual(requests, [{ subtype: "background_tasks" }, { subtype: "stop_task", task_id: "b0wait" }],
+      "The moved call is stopped when its own limit passes");
+    assert.equal(events.filter(event => event.type === "diagnostic" && event.stage === "steered_command_limit").length, 1);
+    // Claude stops the task, reports it, and answers that notification.
+    await turn.receive({ type: "system", subtype: "task_notification", task_id: "b0wait", status: "stopped" });
+    await turn.receive({ type: "user", uuid: "stopped-notice", origin: { kind: "task-notification" } });
+    await turn.receive({ type: "result", subtype: "success", result: "The wait hit its time limit." });
+    assert.deepEqual([turn.read().active, turn.read().phase, turn.read().status], [false, "", "completed"]);
+    assert.equal(events.filter(event => event.type === "settled").length, 1);
+  });
+}
+
+test("steering leaves deliberate background commands and finished commands to run their course", async t => {
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"] });
+  const { turn, send, read, requests } = steeringFixture();
+  await send();
+  await read("first");
+  await turn.receive({ type: "assistant", uuid: "server-call", message: { id: "server-api", stop_reason: "tool_use",
+    content: [{ type: "tool_use", id: "toolu_server", name: "Bash", input: { command: "npm run dev", timeout: 60_000, run_in_background: true } }] } });
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "b0server", tool_use_id: "toolu_server",
+    description: "Start the dev server", task_type: "local_bash", is_backgrounded: true });
+  await turn.receive({ type: "assistant", uuid: "build-call", message: { id: "build-api", stop_reason: "tool_use",
+    content: [{ type: "tool_use", id: "toolu_build", name: "Bash", input: { command: "npm run build", timeout: 90_000 } }] } });
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "b0build", tool_use_id: "toolu_build",
+    description: "Build", task_type: "local_bash", is_backgrounded: false });
+  await turn.prepareSteering();
+  await send("question", { steer: true });
+  await flushControls();
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }]);
+  t.mock.timers.tick(30_000);
+  await turn.receive({ type: "system", subtype: "task_notification", task_id: "b0build", status: "completed" });
+  t.mock.timers.tick(30 * 60_000);
+  await flushControls();
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }], "Neither the dev server nor the finished build is stopped");
+  assert.equal(turn.read().backgroundTasks, 1);
+  turn.stop();
+});
+
 test("a refused background request leaves the steer delivered and reports it", async () => {
   const { turn, send, read, requests, client, events } = steeringFixture();
   await send();