@cloudcli-ai/cloudcli 1.37.3 → 1.37.4

package/server/modules/providers/tests/sessions.service.test.ts

@@ -1,11 +1,15 @@
 import assert from 'node:assert/strict';
-import { appendFile, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 
 import { closeConnection, initializeDatabase, projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
 import { sessionsService } from '@/modules/providers/services/sessions.service.js';
+import { chatRunRegistry } from '@/modules/websocket/index.js';
+import type { IProvider } from '@/shared/interfaces.js';
+import type { BackgroundTaskSummary } from '@/shared/types.js';
 
 async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
   const previousDatabasePath = process.env.DATABASE_PATH;
@@ -191,3 +195,235 @@ test('history pages are sliced from the cached full transcript and see appended
     await rm(transcriptDirectory, { recursive: true, force: true });
   }
 });
+
+/**
+ * Stands in for the provider registry with one provider per id, each with the
+ * runtime given — the seam through which a runtime's background work reaches
+ * the running-sessions list without an SDK run behind it.
+ */
+async function withProviders(
+  runtimes: Partial<Record<'claude' | 'codex', IProvider['runtime']>>,
+  runTest: () => void | Promise<void>,
+): Promise<void> {
+  const realListProviders = providerRegistry.listProviders;
+  providerRegistry.listProviders = () =>
+    Object.entries(runtimes).map(([id, runtime]) => ({ id, runtime }) as IProvider);
+  try {
+    await runTest();
+  } finally {
+    providerRegistry.listProviders = realListProviders;
+    chatRunRegistry.clearAll();
+  }
+}
+
+/**
+ * Runs `runTest` against a Claude CLI process registry containing exactly
+ * `records`, so the running-sessions tests never read the developer's real
+ * `~/.claude/sessions`.
+ */
+async function withClaudeCliRegistry(
+  records: Array<Record<string, unknown>>,
+  runTest: () => void | Promise<void>,
+): Promise<void> {
+  const homeDirectory = await mkdtemp(path.join(os.tmpdir(), 'claude-cli-registry-'));
+  await mkdir(path.join(homeDirectory, '.claude', 'sessions'), { recursive: true });
+  for (const record of records) {
+    await writeFile(
+      path.join(homeDirectory, '.claude', 'sessions', `${record.pid}.json`),
+      JSON.stringify(record),
+      'utf8',
+    );
+  }
+
+  const realHomedir = os.homedir;
+  (os as unknown as { homedir: () => string }).homedir = () => homeDirectory;
+  try {
+    await runTest();
+  } finally {
+    (os as unknown as { homedir: () => string }).homedir = realHomedir;
+    await rm(homeDirectory, { recursive: true, force: true });
+  }
+}
+
+const task = (taskId: string, startedAt: number): BackgroundTaskSummary => ({
+  taskId,
+  toolUseId: `toolu_${taskId}`,
+  taskType: 'local_agent',
+  description: `Task ${taskId}`,
+  startedAt,
+});
+
+test('running sessions list a session whose background work outlived its turn', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('held-session', 'claude', '/tmp/running-project');
+    // The turn ran and completed: the registry still holds the finished run.
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'held-session', provider: 'claude', providerSessionId: null, connection: null, userId: null,
+    });
+    assert.ok(run);
+    run.writer.send({ kind: 'text', content: 'launched', sessionId: 'held-session', provider: 'claude' });
+    run.writer.sendComplete({ exitCode: 0 });
+    assert.equal(run.status, 'completed');
+
+    const tasks = [task('late', 2_000), task('early', 1_000)];
+    await withClaudeCliRegistry([], async () => await withProviders(
+      { claude: { run: async () => undefined, abort: () => false, listBackgroundWork: () => [{ sessionId: 'held-session', tasks }] } },
+      async () => {
+        assert.deepEqual(await sessionsService.listRunningSessions(), [{
+          sessionId: 'held-session',
+          provider: 'claude',
+          startedAt: 1_000,
+          lastSeq: run.lastSeq,
+          background: true,
+          canInterrupt: false,
+          tasks,
+        }]);
+        assert.ok(run.lastSeq > 0, 'the finished run still reports its sequence for replay');
+      },
+    ));
+  });
+});
+
+test('running sessions carry their tasks on a chat run that is still going', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('busy-session', 'claude', '/tmp/running-project');
+    sessionsDb.createAppSession('idle-session', 'codex', '/tmp/running-project');
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'busy-session', provider: 'claude', providerSessionId: null, connection: null, userId: null,
+    });
+    assert.ok(run);
+
+    const tasks = [task('agent', 5_000)];
+    await withClaudeCliRegistry([], async () => await withProviders(
+      {
+        claude: { run: async () => undefined, abort: () => false, listBackgroundWork: () => [{ sessionId: 'busy-session', tasks }] },
+        // A runtime without background work contributes chat runs alone.
+        codex: { run: async () => undefined, abort: () => false },
+      },
+      async () => {
+        const sessions = await sessionsService.listRunningSessions();
+        assert.equal(sessions.length, 1, 'a session with a running chat run is listed once');
+        assert.deepEqual(sessions[0], {
+          sessionId: 'busy-session',
+          provider: 'claude',
+          startedAt: run.startedAt,
+          lastSeq: 0,
+          tasks,
+        });
+      },
+    ));
+  });
+});
+
+test('running sessions with no background work are the chat runs alone', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('plain-session', 'codex', '/tmp/running-project');
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'plain-session', provider: 'codex', providerSessionId: null, connection: null, userId: null,
+    });
+    assert.ok(run);
+
+    await withClaudeCliRegistry([], async () => await withProviders(
+      { codex: { run: async () => undefined, abort: () => false } },
+      async () => {
+        assert.deepEqual(await sessionsService.listRunningSessions(), [{
+          sessionId: 'plain-session', provider: 'codex', startedAt: run.startedAt, lastSeq: 0,
+        }]);
+      },
+    ));
+  });
+});
+
+test('running sessions report a turn driven by the Claude CLI', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('cli-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('cli-session', 'claude-native-1');
+
+    // `process.pid` is the one pid guaranteed to be alive; omitting procStart
+    // keeps the fixture portable, since the start-time cross-check is Linux-only.
+    await withClaudeCliRegistry(
+      [{ pid: process.pid, sessionId: 'claude-native-1', status: 'busy', entrypoint: 'cli', startedAt: 4_000 }],
+      async () => await withProviders(
+        { claude: { run: async () => undefined, abort: () => false } },
+        async () => {
+          assert.deepEqual(await sessionsService.listRunningSessions(), [{
+            sessionId: 'cli-session',
+            provider: 'claude',
+            startedAt: 4_000,
+            lastSeq: 0,
+            canInterrupt: false,
+            statusText: 'Running in the Claude CLI',
+          }]);
+        },
+      ),
+    );
+  });
+});
+
+test('running sessions ignore registry files a crash left behind', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('stale-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('stale-session', 'claude-native-stale');
+
+    await withClaudeCliRegistry(
+      [
+        // The process is gone: signal 0 cannot find this pid.
+        { pid: 4_194_302, sessionId: 'claude-native-stale', status: 'busy', startedAt: 1_000 },
+        // Alive, but waiting for input rather than producing a response.
+        { pid: process.pid, sessionId: 'claude-native-idle', status: 'idle', startedAt: 2_000 },
+      ],
+      async () => await withProviders(
+        { claude: { run: async () => undefined, abort: () => false } },
+        async () => {
+          assert.deepEqual(await sessionsService.listRunningSessions(), []);
+        },
+      ),
+    );
+  });
+});
+
+test('a CLI turn does not duplicate a session already running a chat run', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('both-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('both-session', 'claude-native-both');
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'both-session', provider: 'claude', providerSessionId: 'claude-native-both', connection: null, userId: null,
+    });
+    assert.ok(run);
+
+    await withClaudeCliRegistry(
+      [{ pid: process.pid, sessionId: 'claude-native-both', status: 'busy', startedAt: 3_000 }],
+      async () => await withProviders(
+        { claude: { run: async () => undefined, abort: () => false } },
+        async () => {
+          const sessions = await sessionsService.listRunningSessions();
+          assert.equal(sessions.length, 1, 'the chat run already covers this session');
+          assert.equal(sessions[0].canInterrupt, undefined, 'the interruptible chat run entry wins');
+        },
+      ),
+    );
+  });
+});
+
+test('an unreadable registry never fails the running-sessions poll', { concurrency: false }, async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('safe-session', 'claude', '/tmp/running-project');
+    sessionsDb.assignProviderSessionId('safe-session', 'claude-native-safe');
+
+    await withClaudeCliRegistry(
+      [{ pid: process.pid, sessionId: 'claude-native-safe', status: 'busy', startedAt: 5_000 }],
+      async () => {
+        // A half-written file sits alongside the good one; it must be skipped
+        // rather than abort the whole poll.
+        await writeFile(path.join(os.homedir(), '.claude', 'sessions', 'broken.json'), '{"pid":', 'utf8');
+        await withProviders(
+          { claude: { run: async () => undefined, abort: () => false } },
+          async () => {
+            const sessions = await sessionsService.listRunningSessions();
+            assert.deepEqual(sessions.map((session) => session.sessionId), ['safe-session']);
+          },
+        );
+      },
+    );
+  });
+});

package/server/modules/scheduled-messages/services/scheduled-message-dispatcher.service.ts

@@ -81,13 +81,26 @@ async function sendClaimedQueuedMessage(
   sessionDraftsDb.deleteEmptyDraft(candidate.userId, candidate.sessionId);
 }
 
+/**
+ * Whether a queued turn has to keep waiting for the session.
+ *
+ * A turn that ends with background work still going (a backgrounded command,
+ * agent or workflow) is marked completed, but its CLI process stays open so
+ * that work can report back. A new turn replaces that process and stops the
+ * work, which is why the composer asks before an interactive send. A queued
+ * turn was promised to go "when this finishes", so it waits for that work too.
+ */
+function isSessionBusy(sessionId: string, runtime: ProviderRuntimeGateway): boolean {
+  return chatRunRegistry.isProcessing(sessionId) || runtime.hasBackgroundWork(sessionId);
+}
+
 /** Sends every persisted queued turn whose session is currently idle. */
 export async function dispatchQueuedMessages(runtime: ProviderRuntimeGateway): Promise<number> {
   const candidates = sessionDraftsDb.listQueuedMessages();
   let claimed = 0;
 
   await Promise.all(candidates.map(async (candidate) => {
-    if (chatRunRegistry.isProcessing(candidate.sessionId)) {
+    if (isSessionBusy(candidate.sessionId, runtime)) {
       return;
     }
     if (!sessionDraftsDb.claimQueuedMessage(candidate)) {

package/server/modules/scheduled-messages/tests/scheduled-messages.test.ts

@@ -37,9 +37,15 @@ async function withIsolatedDatabase(runTest: (userId: number) => void | Promise<
 
 type RunCall = { provider: string; command: string; options: Record<string, unknown> };
 
-function createRuntime(runs: RunCall[], behaviour: 'ok' | 'throw' = 'ok', aborts: string[] = []) {
+function createRuntime(
+  runs: RunCall[],
+  behaviour: 'ok' | 'throw' = 'ok',
+  aborts: string[] = [],
+  hasBackgroundWork: (sessionId: string) => boolean = () => false,
+) {
   return {
     hasRuntime: () => true,
+    hasBackgroundWork,
     run: async (provider: string, command: string, options: Record<string, unknown>) => {
       if (behaviour === 'throw') {
         throw new Error('provider exploded');
@@ -117,6 +123,44 @@ test('a queued message stays pending while its session is busy', async () => {
   });
 });
 
+test('a queued message waits for background work its session\'s last turn left running', async () => {
+  await withIsolatedDatabase(async (userId) => {
+    sessionDraftsDb.saveDraft(userId, SESSION_ID, {
+      text: '',
+      queuedMessage: { content: 'send after the background job' },
+    });
+    // Turn A ended, so its run is completed, but it backgrounded a command
+    // that is still running under A's CLI process.
+    const runA = chatRunRegistry.startRun({
+      appSessionId: SESSION_ID,
+      provider: 'claude',
+      providerSessionId: null,
+      connection: null,
+      userId,
+    });
+    runA!.writer.sendComplete({ exitCode: 0 });
+    assert.equal(chatRunRegistry.isProcessing(SESSION_ID), false);
+
+    let backgroundWork = true;
+    const runs: RunCall[] = [];
+    const runtime = createRuntime(runs, 'ok', [], (sessionId) => sessionId === SESSION_ID && backgroundWork);
+
+    // Starting B now would replace that process and stop the command.
+    assert.equal(await dispatchQueuedMessages(runtime), 0);
+    assert.equal(runs.length, 0);
+    assert.deepEqual(sessionDraftsDb.getDrafts(userId)[0]?.queuedMessage, {
+      content: 'send after the background job',
+    });
+
+    // Once the work has reported back, B goes on the next pass.
+    backgroundWork = false;
+    assert.equal(await dispatchQueuedMessages(runtime), 1);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].command, 'send after the background job');
+    assert.equal(sessionDraftsDb.getDrafts(userId).length, 0);
+  });
+});
+
 test('a due message interrupts a run in progress instead of failing', async () => {
   await withIsolatedDatabase(async (userId) => {
     scheduledMessagesService.schedule({

package/server/modules/websocket/README.md

@@ -33,7 +33,7 @@ Benefits:
 |---|---|
 | `services/websocket-server.service.ts` | Creates `WebSocketServer`, binds `verifyClient`, routes connection by pathname |
 | `services/websocket-auth.service.ts` | Authenticates upgrade requests and attaches `request.user` |
-| `services/chat-websocket.service.ts` | Handles the `/ws` chat protocol (`chat.send` / `chat.abort` / `chat.subscribe` / `chat.permission-response`) |
+| `services/chat-websocket.service.ts` | Handles the `/ws` chat protocol (`chat.send` / `chat.abort` / `chat.stop-task` / `chat.subscribe` / `chat.permission-response`) |
 | `services/chat-run-registry.service.ts` | Tracks live provider runs per app session id: seq numbering, event replay buffer, provider-id mapping, completion state |
 | `services/chat-session-writer.service.ts` | Gateway writer handed to provider runtimes: remaps provider session ids to app ids, swallows `session_created`, assigns `seq` |
 | `services/shell-websocket.service.ts` | Handles `/shell` PTY lifecycle, reconnect buffering, auth URL detection |
@@ -108,7 +108,7 @@ When a chat socket connects:
 
 1. Add socket to `connectedClients`.
 2. Parse each incoming message with `parseIncomingJsonObject`.
-3. Dispatch by `data.type` (four message types, none provider-specific).
+3. Dispatch by `data.type` (six message types, none provider-specific).
 4. On close, remove socket from `connectedClients`.
 
 ### Session identity model
@@ -130,7 +130,9 @@ flowchart TD
   B -->|ok| D{data.type}
 
   D -->|chat.send| E[resolve session row -> startRun -> providerRuntimeService.run]
+  D -->|chat.edit-send| E2[history_truncated -> rewind or resume at the anchor -> same as chat.send]
   D -->|chat.abort| F[providerRuntimeService.abort + synthetic complete]
+  D -->|chat.stop-task| F2[providerRuntimeService.stopBackgroundTask]
   D -->|chat.subscribe| G[chat_subscribed ack + attach socket + replay events seq > lastSeq]
   D -->|chat.permission-response| H[providerRuntimeService.resolveToolApproval]
   D -->|other| I[send kind:protocol_error]

package/server/modules/websocket/services/chat-run-registry.service.ts

@@ -59,12 +59,31 @@ const MAX_BUFFERED_EVENTS_PER_RUN = 5000;
  */
 const runs = new Map<string, ChatRun>();
 
-function evictRunLater(appSessionId: string): void {
+/**
+ * Answers whether a completed run must stay registered a while longer. Set by
+ * the composition root to the provider runtimes' background-work check: a
+ * session whose turn ended but whose agents, workflows or commands are still
+ * running keeps sending live events through this run's writer, and a tab that
+ * subscribes meanwhile needs the run to attach to.
+ */
+let retainCompletedRun: (appSessionId: string) => boolean = () => false;
+
+/**
+ * Schedules one run's eviction. The timer is bound to the run it was armed
+ * for: a later run can take the session's slot while this one's retention —
+ * re-armed for as long as the guard holds — is still pending, and firing on
+ * the slot alone would evict that newer run early.
+ */
+function evictRunLater(run: ChatRun): void {
   const timer = setTimeout(() => {
-    const run = runs.get(appSessionId);
-    if (run && run.status === 'completed') {
-      runs.delete(appSessionId);
+    if (runs.get(run.appSessionId) !== run || run.status !== 'completed') {
+      return;
+    }
+    if (retainCompletedRun(run.appSessionId)) {
+      evictRunLater(run);
+      return;
     }
+    runs.delete(run.appSessionId);
   }, COMPLETED_RUN_RETENTION_MS);
 
   // Never keep the process alive just to evict a buffered run.
@@ -104,7 +123,7 @@ function decorateAndRecordEvent(run: ChatRun, message: NormalizedMessage): Norma
     outbound.actualSessionId = run.appSessionId;
     run.status = 'completed';
     run.completedAt = Date.now();
-    evictRunLater(run.appSessionId);
+    evictRunLater(run);
   }
 
   run.events.push(outbound);
@@ -160,6 +179,11 @@ function recordProviderSessionId(run: ChatRun, providerSessionId: string): void
  * regardless of which provider runtime produced them.
  */
 export const chatRunRegistry = {
+  /** Installs the check that keeps a completed run registered while its session still has background work. */
+  setRetentionGuard(guard: (appSessionId: string) => boolean): void {
+    retainCompletedRun = guard;
+  },
+
   /**
    * Starts tracking a run and returns it, or `null` when a run is already in
    * progress for the session (callers must reject the duplicate send).

package/server/modules/websocket/services/chat-websocket.service.ts

@@ -73,6 +73,9 @@ export type ProviderRuntimeGateway = {
     writer: ProviderRuntimeWriter,
   ): Promise<unknown>;
   abort(provider: LLMProvider, sessionId: string): Promise<boolean>;
+  stopBackgroundTask(provider: LLMProvider, sessionId: string, taskId: string): Promise<boolean>;
+  /** Whether a provider runtime still holds background work for the session after its turn ended. */
+  hasBackgroundWork(sessionId: string): boolean;
   resolveToolApproval(requestId: string, payload: ProviderPermissionDecision): void;
   getPendingApprovalsForSession(sessionId: string): unknown[];
 };
@@ -437,6 +440,52 @@ async function handleChatAbort(
   });
 }
 
+/**
+ * Handles `chat.stop-task`: stops one background task of a session — an
+ * agent, a workflow or a backgrounded command that is still going after its
+ * turn ended. Unlike `chat.abort` there is no run to consult: the task lives
+ * in the provider's held process, which is the only thing that can stop it.
+ * The provider then reports the task as stopped on the session's stream, so
+ * nothing is echoed back here on success.
+ */
+async function handleChatStopTask(
+  ws: WebSocket,
+  data: AnyRecord,
+  dependencies: ChatWebSocketDependencies
+): Promise<void> {
+  const sessionId = readRequiredSessionId(data);
+  if (!sessionId) {
+    sendProtocolError(ws, 'SESSION_ID_REQUIRED', 'chat.stop-task requires a sessionId.');
+    return;
+  }
+
+  const taskId = typeof data.taskId === 'string' ? data.taskId.trim() : '';
+  if (!taskId) {
+    sendProtocolError(ws, 'TASK_ID_REQUIRED', 'chat.stop-task requires a taskId.', sessionId);
+    return;
+  }
+
+  const session = sessionsDb.getSessionById(sessionId);
+  if (!session) {
+    sendProtocolError(ws, 'SESSION_NOT_FOUND', `Session "${sessionId}" was not found.`, sessionId);
+    return;
+  }
+
+  const stopped = await dependencies.runtime.stopBackgroundTask(
+    session.provider as LLMProvider,
+    sessionId,
+    taskId,
+  );
+  if (!stopped) {
+    sendProtocolError(
+      ws,
+      'NO_SUCH_TASK',
+      `Session "${sessionId}" has no running background task "${taskId}".`,
+      sessionId,
+    );
+  }
+}
+
 /**
  * Handles `chat.subscribe`: for each requested session, reports whether a run
  * is processing, re-attaches the live stream to this socket, replays missed
@@ -474,7 +523,11 @@ function handleChatSubscribe(
 
     // Future live events for this run should land on the socket that asked —
     // this is what makes mid-stream page refreshes work for all providers.
-    if (isProcessing) {
+    // A session whose turn ended but whose background work is still going
+    // keeps producing events through the same writer (task progress, the
+    // turn the CLI pushes when a task reports), so a tab opened during that
+    // work attaches too; the registry keeps the run while the work lasts.
+    if (isProcessing || dependencies.runtime.hasBackgroundWork(sessionId)) {
       chatRunRegistry.attachConnection(sessionId, ws);
     }
 
@@ -527,6 +580,7 @@ function handlePermissionResponse(data: AnyRecord, dependencies: ChatWebSocketDe
  * Inbound protocol (client to server):
  * - `chat.send`                { sessionId, content, options? }
  * - `chat.abort`               { sessionId }
+ * - `chat.stop-task`           { sessionId, taskId }
  * - `chat.subscribe`           { sessions: [{ sessionId, lastSeq? }] }
  * - `chat.permission-response` { requestId, allow, updatedInput?, message?, rememberEntry? }
  *
@@ -630,6 +684,9 @@ export function handleChatConnection(
         case 'chat.abort':
           await handleChatAbort(ws, data, dependencies);
           return;
+        case 'chat.stop-task':
+          await handleChatStopTask(ws, data, dependencies);
+          return;
         case 'chat.subscribe':
           handleChatSubscribe(ws, data, dependencies);
           return;