feat(cloud-agent-next): add manual compact command (#3627)

* feat(cloud-agent-next): add manual compact command

* fix(cloud-agent-next): harden compact completion delivery

Author: eshurakov

services/cloud-agent-next/src/kilo/wrapper-client.test.ts

@@ -569,6 +569,7 @@ describe('WrapperClient', () => {
         command: 'compact',
         args: '--aggressive',
         messageId: 'msg_018f1e2d3c4bCommandWireAAA',
+        agent: { model: { modelID: 'anthropic/claude-sonnet-4-20250514' } },
         autoCommit: true,
         condenseOnComplete: false,
         session: {
@@ -582,6 +583,7 @@ describe('WrapperClient', () => {
 
       const execCall = (session.exec as ReturnType<typeof vi.fn>).mock.calls[0][0] as string;
       expect(execCall).toContain('"messageId":"msg_018f1e2d3c4bCommandWireAAA"');
+      expect(execCall).toContain('"modelID":"anthropic/claude-sonnet-4-20250514"');
       expect(execCall).toContain('"autoCommit":true');
       expect(execCall).toContain('"condenseOnComplete":false');
       expect(execCall).toContain('"workerAuthToken":"tok_command"');

services/cloud-agent-next/src/persistence/CloudAgentSession.ts

@@ -636,12 +636,12 @@ export class CloudAgentSession extends DurableObject<WorkerEnv> {
         terminalizeSessionMessageOnce: async (messageId, params, wrapperRunId) => {
           await this.ensureAcceptedMessageBeforeTerminal(messageId, wrapperRunId);
           await this.recordCorrelatedAgentActivity(messageId);
-          await this.terminalizeSessionMessageOnce(messageId, {
-            ...params,
-            ...(params.kind === 'failed'
-              ? { failureStage: 'agent_activity', failureCode: 'assistant_error' }
-              : {}),
-          } as TerminalizeParams);
+          await this.terminalizeSessionMessageOnce(
+            messageId,
+            params.kind === 'failed'
+              ? { ...params, failureStage: 'agent_activity', failureCode: 'assistant_error' }
+              : params
+          );
         },
       };
 

services/cloud-agent-next/src/session-service.ts

@@ -1485,6 +1485,11 @@ export class SessionService {
         command: turn.command,
         ...(turn.arguments.length > 0 ? { args: turn.arguments } : {}),
         messageId: turn.messageId,
+        agent: {
+          mode: promptAgent,
+          model: { modelID: agent.model },
+          ...(agent.variant ? { variant: agent.variant } : {}),
+        },
         ...(finalization?.autoCommit !== undefined ? { autoCommit: finalization.autoCommit } : {}),
         ...(finalization?.condenseOnComplete !== undefined
           ? { condenseOnComplete: finalization.condenseOnComplete }

services/cloud-agent-next/src/session/ingest-handlers/commands-available.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { handleCommandsAvailable } from './commands-available.js';
-import { DEFAULT_SLASH_COMMANDS } from '../../shared/default-slash-commands.generated';
+import { commandsOrDefault } from '../../shared/slash-commands.js';
 
 const silentLogger = { info: () => {}, warn: () => {} };
 
@@ -18,10 +18,13 @@ describe('handleCommandsAvailable', () => {
     );
 
     expect(setAvailableCommands).toHaveBeenCalledTimes(1);
-    expect(setAvailableCommands).toHaveBeenCalledWith([
-      { name: 'review', description: 'Review', hints: [] },
-      { name: 'init', hints: ['$ARGUMENTS'], source: 'command' },
-    ]);
+    expect(setAvailableCommands).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'review', description: 'Review', hints: [] }),
+        expect.objectContaining({ name: 'init', hints: ['$ARGUMENTS'], source: 'command' }),
+        { name: 'compact', description: 'compact the current session context', hints: [] },
+      ])
+    );
   });
 
   it('drops items missing a name without rejecting the whole event', async () => {
@@ -31,7 +34,12 @@ describe('handleCommandsAvailable', () => {
       { setAvailableCommands, logger: silentLogger }
     );
 
-    expect(setAvailableCommands).toHaveBeenCalledWith([{ name: 'ok', hints: [] }]);
+    expect(setAvailableCommands).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({ name: 'ok', hints: [] }),
+        { name: 'compact', description: 'compact the current session context', hints: [] },
+      ])
+    );
   });
 
   it('warns and skips when commands array is missing', async () => {
@@ -60,7 +68,7 @@ describe('handleCommandsAvailable', () => {
     await handleCommandsAvailable({ commands: [] }, { setAvailableCommands, logger: silentLogger });
 
     expect(setAvailableCommands).toHaveBeenCalledTimes(1);
-    expect(setAvailableCommands).toHaveBeenCalledWith(DEFAULT_SLASH_COMMANDS);
+    expect(setAvailableCommands).toHaveBeenCalledWith(commandsOrDefault(undefined));
   });
 
   it('persists defaults when all items fail validation', async () => {
@@ -71,6 +79,6 @@ describe('handleCommandsAvailable', () => {
     );
 
     expect(setAvailableCommands).toHaveBeenCalledTimes(1);
-    expect(setAvailableCommands).toHaveBeenCalledWith(DEFAULT_SLASH_COMMANDS);
+    expect(setAvailableCommands).toHaveBeenCalledWith(commandsOrDefault(undefined));
   });
 });

services/cloud-agent-next/src/session/message-settlement-outbox.test.ts

@@ -198,6 +198,28 @@ describe('MessageSettlementOutbox', () => {
     });
   });
 
+  it('persists manual compact terminalization and emits one completion event', async () => {
+    const harness = createHarness();
+    await putSessionMessageState(harness.storage, acceptedMessageState(firstMessageId));
+
+    const result = await harness.outbox.terminalizeSessionMessageOnce(firstMessageId, {
+      kind: 'completed',
+      completionSource: 'manual_compact_summarize',
+    });
+
+    expect(result.changed).toBe(true);
+    expect(await getSessionMessageState(harness.storage, firstMessageId)).toMatchObject({
+      status: 'completed',
+      completionSource: 'manual_compact_summarize',
+    });
+    expect(harness.events).toHaveLength(1);
+    expect(JSON.parse(harness.events[0].payload)).toMatchObject({
+      messageId: firstMessageId,
+      status: 'completed',
+      completionSource: 'manual_compact_summarize',
+    });
+  });
+
   it('dispatches one web-session push using message identity and assistant text', async () => {
     const harness = createHarness({
       metadata: pushMetadata,

services/cloud-agent-next/src/session/session-message-state.ts

@@ -12,6 +12,7 @@ export type SessionMessageStatus = 'queued' | 'accepted' | 'completed' | 'failed
 
 export type SessionMessageCompletionSource =
   | 'assistant_message_event'
+  | 'manual_compact_summarize'
   | 'idle_reconciliation'
   | 'wrapper_failure'
   | 'interrupt'
@@ -167,6 +168,7 @@ export const SessionMessageStateSchema = z
     completionSource: z
       .enum([
         'assistant_message_event',
+        'manual_compact_summarize',
         'idle_reconciliation',
         'wrapper_failure',
         'interrupt',

services/cloud-agent-next/src/shared/protocol.ts

@@ -5,7 +5,7 @@ import type { SlashCommandInfo } from './slash-commands.js';
  *
  * From wrapper -> DO:
  *   started, kilocode, output, status, heartbeat, pong, error, interrupted, complete, wrapper_resumed,
- *   autocommit_started, autocommit_completed
+ *   autocommit_started, autocommit_completed, cloud.message.completed
  *
  * From DO -> /stream clients:
  *   All of the above, plus wrapper_disconnected, wrapper_reconnected, preparing,

services/cloud-agent-next/src/shared/slash-commands.test.ts

@@ -94,21 +94,34 @@ describe('toSlashCommandInfo', () => {
 });
 
 describe('commandsOrDefault', () => {
-  it('returns the provided list when non-empty', () => {
+  it('returns live commands with session actions when non-empty', () => {
     const live = [{ name: 'live', hints: [] }];
+    expect(commandsOrDefault(live)).toEqual([
+      { name: 'live', hints: [] },
+      { name: 'compact', description: 'compact the current session context', hints: [] },
+    ]);
+  });
+
+  it('does not duplicate live session actions', () => {
+    const live = [{ name: 'compact', description: 'live compact', hints: [] }];
     expect(commandsOrDefault(live)).toBe(live);
   });
 
   it('returns defaults for undefined', () => {
-    expect(commandsOrDefault(undefined)).toEqual(DEFAULT_SLASH_COMMANDS);
+    expect(commandsOrDefault(undefined)).toEqual(
+      expect.arrayContaining([
+        ...DEFAULT_SLASH_COMMANDS,
+        { name: 'compact', description: 'compact the current session context', hints: [] },
+      ])
+    );
   });
 
   it('returns defaults for null', () => {
-    expect(commandsOrDefault(null)).toEqual(DEFAULT_SLASH_COMMANDS);
+    expect(commandsOrDefault(null)).toEqual(commandsOrDefault(undefined));
   });
 
   it('returns defaults for empty array', () => {
-    expect(commandsOrDefault([])).toEqual(DEFAULT_SLASH_COMMANDS);
+    expect(commandsOrDefault([])).toEqual(commandsOrDefault(undefined));
   });
 
   it('default commands are non-empty and validate', () => {

services/cloud-agent-next/src/shared/slash-commands.ts

@@ -6,6 +6,14 @@ import {
 
 export { DEFAULT_SLASH_COMMANDS, DEFAULT_SLASH_COMMANDS_SOURCE, type SlashCommandInfo };
 
+const SESSION_SLASH_COMMANDS = [
+  {
+    name: 'compact',
+    description: 'compact the current session context',
+    hints: [],
+  },
+] satisfies SlashCommandInfo[];
+
 /** Parsed result of "/name rest of the line" from the chat composer. */
 export type SlashCommandInvocation = {
   command: string;
@@ -55,10 +63,19 @@ export function toSlashCommandInfo(raw: unknown): SlashCommandInfo | null {
  * Return the provided command list when it is non-empty, otherwise fall back
  * to the hardcoded default catalog. Used both server-side (DO storage) and
  * client-side (hook) so empty always means "defaults" rather than "none yet".
+ * Session actions such as compaction are local Kilo actions rather than
+ * registered prompt commands, so append them when the live catalog omits them.
  */
 export function commandsOrDefault(
   commands: SlashCommandInfo[] | null | undefined
 ): SlashCommandInfo[] {
-  if (commands && commands.length > 0) return commands;
-  return DEFAULT_SLASH_COMMANDS;
+  return withSessionSlashCommands(
+    commands && commands.length > 0 ? commands : DEFAULT_SLASH_COMMANDS
+  );
+}
+
+function withSessionSlashCommands(commands: SlashCommandInfo[]): SlashCommandInfo[] {
+  const names = new Set(commands.map(command => command.name));
+  const missing = SESSION_SLASH_COMMANDS.filter(command => !names.has(command.name));
+  return missing.length > 0 ? [...commands, ...missing] : commands;
 }

services/cloud-agent-next/src/shared/wrapper-bootstrap.ts

@@ -100,6 +100,7 @@ export type WrapperCommandRequest = {
   command: string;
   args?: string;
   messageId: string;
+  agent?: WrapperPromptAgent;
   autoCommit?: boolean;
   condenseOnComplete?: boolean;
   session: WrapperSessionBinding;