feat: add agents session

packages/api/src/acp-session-info.ts

@@ -0,0 +1,233 @@
+/**********************************************************************
+ * Copyright (C) 2026 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ***********************************************************************/
+
+export type AcpSessionStatus = 'idle' | 'running' | 'waiting_input' | 'completed' | 'error' | 'cancelled';
+
+export interface AcpModeInfo {
+  modeId: string;
+  name: string;
+  description?: string;
+}
+
+export interface AcpModelInfo {
+  modelId: string;
+  name: string;
+  description?: string;
+}
+
+export interface AcpSessionConfigSelectOption {
+  value: string;
+  name: string;
+  description?: string;
+}
+
+export interface AcpSessionConfigSelectGroup {
+  group: string;
+  name: string;
+  options: AcpSessionConfigSelectOption[];
+}
+
+export interface AcpSessionConfigOption {
+  id: string;
+  name: string;
+  category?: string;
+  description?: string;
+  type: 'select' | 'boolean';
+  currentValue?: string | boolean;
+  options?: AcpSessionConfigSelectOption[] | AcpSessionConfigSelectGroup[];
+}
+
+export interface AcpSlashCommand {
+  name: string;
+  description: string;
+  inputHint?: string;
+}
+
+export interface AcpSessionInfo {
+  id: string;
+  sandboxName: string;
+  sandboxId: string;
+  prompt: string;
+  status: AcpSessionStatus;
+  createdAt: number;
+  updatedAt: number;
+  agentId?: string;
+  agentName?: string;
+  cost?: AcpCost;
+  currentMode?: string;
+  availableModes?: AcpModeInfo[];
+  currentModeId?: string;
+  availableModels?: AcpModelInfo[];
+  currentModelId?: string;
+  availableCommands?: AcpSlashCommand[];
+  configOptions?: AcpSessionConfigOption[];
+  contextUsed?: number;
+  contextSize?: number;
+  error?: string;
+}
+
+export interface AcpCost {
+  inputTokens: number;
+  outputTokens: number;
+  totalCost: number;
+  currency: string;
+}
+
+export interface AcpPlanStep {
+  title: string;
+  state: 'done' | 'running' | 'blocked' | 'queued';
+}
+
+export interface AcpPermissionOption {
+  name: string;
+  kind: string;
+  optionId: string;
+}
+
+export type AcpFlowEvent =
+  | AcpFlowPromptEvent
+  | AcpFlowAgentMessageEvent
+  | AcpFlowThinkingEvent
+  | AcpFlowToolCallEvent
+  | AcpFlowPlanEvent
+  | AcpFlowPermissionRequestEvent
+  | AcpFlowElicitationEvent
+  | AcpFlowStatusChangeEvent
+  | AcpFlowCostUpdateEvent;
+
+export interface AcpAttachment {
+  filePath: string;
+  fileName: string;
+  mimeType: string;
+}
+
+export interface AcpFlowPromptEvent {
+  kind: 'prompt';
+  text: string;
+  attachments?: { fileName: string; mimeType: string }[];
+  timestamp: number;
+}
+
+export interface AcpFlowAgentMessageEvent {
+  kind: 'agent_message';
+  text: string;
+  messageId?: string;
+  turn?: number;
+  timestamp: number;
+}
+
+export interface AcpFlowThinkingEvent {
+  kind: 'thinking';
+  text: string;
+  messageId?: string;
+  timestamp: number;
+}
+
+export interface AcpFlowToolCallEvent {
+  kind: 'tool_call';
+  toolCallId: string;
+  title: string;
+  toolName?: string;
+  command?: string;
+  description?: string;
+  status: 'running' | 'completed' | 'error';
+  content?: string;
+  timestamp: number;
+  permissionRequest?: {
+    requestId: string;
+    options: AcpPermissionOption[];
+    resolved: boolean;
+    selectedOptionId?: string;
+  };
+}
+
+export interface AcpFlowPlanEvent {
+  kind: 'plan';
+  steps: AcpPlanStep[];
+  progress: number;
+  timestamp: number;
+}
+
+/** @deprecated Permission data is now embedded in AcpFlowToolCallEvent.permissionRequest */
+export interface AcpFlowPermissionRequestEvent {
+  kind: 'permission_request';
+  requestId: string;
+  toolCallTitle: string;
+  options: AcpPermissionOption[];
+  resolved?: boolean;
+  selectedOptionId?: string;
+  timestamp: number;
+}
+
+export interface AcpFlowElicitationEvent {
+  kind: 'elicitation';
+  requestId: string;
+  message: string;
+  schema?: AcpElicitationSchema;
+  resolved?: boolean;
+  timestamp: number;
+}
+
+export interface AcpElicitationSchema {
+  title?: string;
+  description?: string;
+  properties?: Record<string, AcpElicitationProperty>;
+  required?: string[];
+}
+
+export interface AcpElicitationProperty {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+  description?: string;
+  default?: unknown;
+  enum?: string[];
+}
+
+export interface AcpFlowStatusChangeEvent {
+  kind: 'status_change';
+  from: AcpSessionStatus;
+  to: AcpSessionStatus;
+  timestamp: number;
+}
+
+export interface AcpFlowCostUpdateEvent {
+  kind: 'cost_update';
+  cost: AcpCost;
+  timestamp: number;
+}
+
+export interface AcpSessionCreateOptions {
+  sandboxName: string;
+  prompt: string;
+  agentId?: string;
+}
+
+export interface AcpUserResponse {
+  sessionId: string;
+  requestId: string;
+  type: 'permission' | 'elicitation';
+  data: AcpPermissionResponseData | AcpElicitationResponseData;
+}
+
+export interface AcpPermissionResponseData {
+  optionId: string;
+}
+
+export interface AcpElicitationResponseData {
+  outcome: 'accept' | 'decline' | 'cancel';
+  values?: Record<string, unknown>;
+}

packages/api/src/navigation-page.ts

@@ -74,4 +74,7 @@ export enum NavigationPage {
   PROJECTS = 'projects',
   PROJECT_DETAILS = 'project-details',
   PROJECT_CREATE = 'project-create',
+  ACP_SESSIONS = 'acp-sessions',
+  ACP_SESSION_CREATE = 'acp-session-create',
+  ACP_SESSION_DETAILS = 'acp-session-details',
 }

packages/api/src/navigation-request.ts

@@ -98,6 +98,11 @@ export interface NavigationParameters {
     id: string;
   };
   [NavigationPage.PROJECT_CREATE]: never;
+  [NavigationPage.ACP_SESSIONS]: never;
+  [NavigationPage.ACP_SESSION_CREATE]: never;
+  [NavigationPage.ACP_SESSION_DETAILS]: {
+    id: string;
+  };
 }
 
 // the parameters property is optional when the NavigationParameters say it is

packages/main/src/plugin/acp/acp-debug.spec.ts

@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { createAcpDebug } from './acp-debug.js';
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  delete process.env['DEBUG'];
+});
+
+describe('createAcpDebug', () => {
+  test('suppresses output when DEBUG is unset', () => {
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debug = createAcpDebug('pty');
+    debug('hello');
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  test('suppresses output when DEBUG is empty', () => {
+    process.env['DEBUG'] = '';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debug = createAcpDebug('pty');
+    debug('hello');
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  test('enables all namespaces with DEBUG=acp', () => {
+    process.env['DEBUG'] = 'acp';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debugPty = createAcpDebug('pty');
+    const debugProtocol = createAcpDebug('protocol');
+    debugPty('pty msg');
+    debugProtocol('protocol msg');
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  test('enables all namespaces with DEBUG=acp:*', () => {
+    process.env['DEBUG'] = 'acp:*';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debugPty = createAcpDebug('pty');
+    const debugLifecycle = createAcpDebug('lifecycle');
+    debugPty('msg1');
+    debugLifecycle('msg2');
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  test('enables only matching namespace with DEBUG=acp:pty', () => {
+    process.env['DEBUG'] = 'acp:pty';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debugPty = createAcpDebug('pty');
+    const debugProtocol = createAcpDebug('protocol');
+    debugPty('should print');
+    debugProtocol('should not print');
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('[ACP:pty'), 'should print');
+  });
+
+  test('supports comma-separated patterns', () => {
+    process.env['DEBUG'] = 'acp:pty,acp:lifecycle';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debugPty = createAcpDebug('pty');
+    const debugProtocol = createAcpDebug('protocol');
+    const debugLifecycle = createAcpDebug('lifecycle');
+    debugPty('a');
+    debugProtocol('b');
+    debugLifecycle('c');
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  test('prefixes output with namespace and timestamp', () => {
+    process.env['DEBUG'] = 'acp';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debug = createAcpDebug('pty');
+    debug('test message');
+    expect(spy).toHaveBeenCalledTimes(1);
+    const prefix = spy.mock.calls[0]![0] as string;
+    expect(prefix).toMatch(/^\[ACP:pty \+\d+\.\d+s\]$/);
+  });
+
+  test('passes through multiple arguments', () => {
+    process.env['DEBUG'] = 'acp';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debug = createAcpDebug('protocol');
+    debug('init', { version: 1 }, 42);
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('[ACP:protocol'), 'init', { version: 1 }, 42);
+  });
+
+  test('responds to DEBUG changes at call time', () => {
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debug = createAcpDebug('pty');
+
+    debug('before');
+    expect(spy).not.toHaveBeenCalled();
+
+    process.env['DEBUG'] = 'acp';
+    debug('after');
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  test('ignores unrelated DEBUG values', () => {
+    process.env['DEBUG'] = 'express:*,http';
+    const spy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+    const debug = createAcpDebug('pty');
+    debug('hello');
+    expect(spy).not.toHaveBeenCalled();
+  });
+});

packages/main/src/plugin/acp/acp-debug.ts

@@ -0,0 +1,22 @@
+const startTime = performance.now();
+
+function isEnabled(namespace: string): boolean {
+  const debug = process.env['DEBUG'] ?? '';
+  if (!debug) return false;
+
+  const patterns = debug.split(',').map(p => p.trim());
+  const full = `acp:${namespace}`;
+
+  return patterns.some(pattern => {
+    if (pattern === 'acp' || pattern === 'acp:*') return true;
+    return pattern === full;
+  });
+}
+
+export function createAcpDebug(namespace: string): (...args: unknown[]) => void {
+  return (...args: unknown[]): void => {
+    if (!isEnabled(namespace)) return;
+    const elapsed = ((performance.now() - startTime) / 1000).toFixed(3);
+    console.debug(`[ACP:${namespace} +${elapsed}s]`, ...args);
+  };
+}