@bytespell/amux 0.0.10 → 0.0.12

package/dist/ws-adapter.js

@@ -0,0 +1,198 @@
+import { WebSocket } from 'ws';
+/**
+ * Create a WebSocket adapter for an AgentSession.
+ *
+ * Bridges session events to WebSocket clients and handles incoming messages.
+ *
+ * @example
+ * ```typescript
+ * import { AgentSession } from 'amux';
+ * import { createWsAdapter } from 'amux/ws';
+ * import { WebSocketServer } from 'ws';
+ *
+ * const session = new AgentSession({ ... });
+ * const wss = new WebSocketServer({ server, path: '/ws' });
+ *
+ * createWsAdapter(session, wss);
+ *
+ * await session.spawnAgent();
+ * ```
+ */
+export function createWsAdapter(session, wss, options = {}) {
+    const clients = new Set();
+    const sendHistoryOnConnect = options.sendHistoryOnConnect ?? true;
+    // Helper to broadcast to all clients
+    function broadcast(message) {
+        const data = JSON.stringify(message);
+        for (const client of clients) {
+            if (client.readyState === WebSocket.OPEN) {
+                client.send(data);
+            }
+        }
+    }
+    // Wire up session events to broadcast
+    const eventHandlers = {
+        ready: (data) => broadcast({ type: 'ready', ...data }),
+        connecting: () => broadcast({ type: 'connecting' }),
+        update: (data) => broadcast({ type: 'session_update', update: data }),
+        turn_start: () => broadcast({ type: 'turn_start' }),
+        turn_end: () => broadcast({ type: 'turn_end' }),
+        permission_request: (data) => broadcast({ type: 'permission_request', ...data }),
+        prompt_complete: (data) => broadcast({ type: 'prompt_complete', ...data }),
+        session_created: (data) => broadcast({ type: 'session_created', ...data }),
+        session_switched: (data) => broadcast({ type: 'session_switched', ...data }),
+        history_replay: (data) => broadcast({ type: 'history_replay', ...data }),
+        error: (data) => broadcast({ type: 'error', ...data }),
+        agent_exit: (data) => broadcast({ type: 'agent_exit', ...data }),
+    };
+    // Register all event handlers
+    for (const [event, handler] of Object.entries(eventHandlers)) {
+        session.on(event, handler);
+    }
+    // Handle WebSocket connections
+    wss.on('connection', (ws) => {
+        console.log('[amux-ws] Client connected');
+        clients.add(ws);
+        // Send current state to new client
+        if (session.isConnected) {
+            ws.send(JSON.stringify({
+                type: 'ready',
+                cwd: session.cwd,
+                sessionId: session.sessionId,
+                capabilities: session.agentCapabilities,
+                agent: session.getAgentInfo(),
+                availableAgents: session.getAvailableAgents(),
+            }));
+            // Send history to hydrate the chat UI
+            if (sendHistoryOnConnect) {
+                const history = session.loadHistory();
+                if (history.length > 0) {
+                    ws.send(JSON.stringify({
+                        type: 'history_replay',
+                        previousSessionId: session.sessionId,
+                        events: history,
+                        eventCount: history.length,
+                    }));
+                }
+            }
+        }
+        else {
+            ws.send(JSON.stringify({ type: 'connecting' }));
+        }
+        // Handle incoming messages
+        ws.on('message', async (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                await handleMessage(ws, msg, session);
+            }
+            catch (err) {
+                console.error('[amux-ws] Invalid message:', err);
+                ws.send(JSON.stringify({ type: 'error', message: 'Invalid message format' }));
+            }
+        });
+        ws.on('close', () => {
+            console.log('[amux-ws] Client disconnected');
+            clients.delete(ws);
+        });
+        ws.on('error', (err) => {
+            console.error('[amux-ws] WebSocket error:', err);
+            clients.delete(ws);
+        });
+    });
+    return {
+        clientCount: () => clients.size,
+        broadcast,
+        close: () => {
+            for (const client of clients) {
+                client.close();
+            }
+            clients.clear();
+        },
+    };
+}
+/**
+ * Handle incoming WebSocket message
+ */
+async function handleMessage(ws, msg, session) {
+    switch (msg.type) {
+        case 'prompt':
+            if (!session.isConnected || !session.sessionId) {
+                ws.send(JSON.stringify({ type: 'error', message: 'Agent not ready' }));
+                return;
+            }
+            try {
+                await session.prompt(msg.message);
+            }
+            catch {
+                // Error already emitted by session
+            }
+            break;
+        case 'cancel':
+            await session.cancel();
+            break;
+        case 'permission_response':
+            session.respondToPermission(msg.requestId, msg.optionId);
+            break;
+        case 'change_cwd':
+            try {
+                await session.changeCwd(msg.path);
+            }
+            catch (err) {
+                ws.send(JSON.stringify({ type: 'error', message: err.message }));
+            }
+            break;
+        case 'new_session':
+            try {
+                await session.newSession();
+            }
+            catch (err) {
+                ws.send(JSON.stringify({ type: 'error', message: err.message }));
+            }
+            break;
+        case 'set_mode':
+            try {
+                await session.setMode(msg.modeId);
+            }
+            catch (err) {
+                ws.send(JSON.stringify({ type: 'error', message: err.message }));
+            }
+            break;
+        case 'set_model':
+            try {
+                await session.setModel(msg.modelId);
+            }
+            catch (err) {
+                ws.send(JSON.stringify({ type: 'error', message: err.message }));
+            }
+            break;
+        case 'change_agent':
+            try {
+                await session.changeAgent(msg.agentType);
+            }
+            catch (err) {
+                ws.send(JSON.stringify({ type: 'error', message: err.message }));
+            }
+            break;
+        case 'get_history': {
+            const history = session.loadHistory();
+            ws.send(JSON.stringify({ type: 'history', events: history, sessionId: session.sessionId }));
+            break;
+        }
+        case 'list_sessions': {
+            const sessions = session.listSessions();
+            ws.send(JSON.stringify({ type: 'sessions', sessions }));
+            break;
+        }
+        case 'switch_session':
+            try {
+                await session.switchSession(msg.sessionId);
+            }
+            catch (err) {
+                ws.send(JSON.stringify({ type: 'error', message: err.message }));
+            }
+            break;
+        default:
+            ws.send(JSON.stringify({ type: 'error', message: `Unknown message type: ${msg.type}` }));
+    }
+}
+//# sourceMappingURL=ws-adapter.js.map

package/dist/ws-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-adapter.js","sourceRoot":"","sources":["../src/ws-adapter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,36 +1,59 @@
 {
   "name": "@bytespell/amux",
-  "version": "0.0.10",
-  "description": "Agent Multiplexer - library for managing agent/terminal processes",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/bytespell-oss/shella"
-  },
+  "version": "0.0.12",
+  "description": "Agent Multiplexer - EventEmitter-based agent session management",
   "type": "module",
-  "files": [
-    "dist/",
-    "scripts/"
-  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./dist/types.js",
-    "./types": "./dist/types.js",
-    "./streams/manager": "./dist/streams/manager.js",
-    "./streams/backends": "./dist/streams/backends/index.js",
-    "./lib/logger": "./dist/lib/logger.js",
-    "./lib/mentions": "./dist/lib/mentions.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
-    "postinstall": "node scripts/fix-pty.cjs 2>/dev/null || true",
-    "build": "tsup",
-    "dev": "tsup --watch"
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build"
   },
+  "keywords": [
+    "acp",
+    "agent",
+    "claude",
+    "multiplexer",
+    "ai",
+    "websocket"
+  ],
+  "author": "",
+  "license": "MIT",
   "dependencies": {
-    "@agentclientprotocol/sdk": "^0.12.0",
-    "execa": "^9.6.1",
-    "node-pty": "^1.2.0-beta.2",
-    "tree-kill": "^1.2.2"
+    "@agentclientprotocol/sdk": "^0.13.0",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@types/node": "^24.10.1"
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.7.0",
+    "vitest": "^3.1.3"
+  },
+  "peerDependencies": {
+    "@zed-industries/claude-code-acp": ">=0.13.0",
+    "@zed-industries/codex-acp": ">=0.9.0",
+    "pi-acp": ">=0.0.14"
+  },
+  "peerDependenciesMeta": {
+    "@zed-industries/claude-code-acp": {
+      "optional": true
+    },
+    "@zed-industries/codex-acp": {
+      "optional": true
+    },
+    "pi-acp": {
+      "optional": true
+    }
   }
 }

package/src/client.ts

@@ -0,0 +1,162 @@
+import fs from 'fs';
+import crypto from 'crypto';
+import type * as acp from '@agentclientprotocol/sdk';
+
+import { isToolCallUpdate, normalizeSessionUpdate } from './session-updates.js';
+import type { TerminalManager } from './terminal.js';
+import type { StoredEvent } from './types.js';
+
+/**
+ * Callback for routing events
+ */
+type EventCallback = (event: StoredEvent) => void;
+
+/**
+ * Pending permission request tracking
+ */
+interface PendingPermission {
+  resolve: (value: acp.RequestPermissionResponse) => void;
+  reject: (reason: Error) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * ACP Client implementation.
+ * Bridges agent notifications to WebSocket clients and handles
+ * file operations and terminal management.
+ */
+export class AmuxClient implements acp.Client {
+  pendingPermissions = new Map<string, PendingPermission>();
+
+  constructor(
+    private terminalManager: TerminalManager,
+    private onEvent: EventCallback
+  ) {}
+
+  /**
+   * Handle permission request from agent
+   */
+  async requestPermission(params: acp.RequestPermissionRequest): Promise<acp.RequestPermissionResponse> {
+    console.log('[amux] Permission request:', params.toolCall?.title);
+
+    // Send permission request
+    const requestId = crypto.randomUUID();
+    this.onEvent({
+      type: 'permission_request',
+      requestId,
+      toolCall: params.toolCall,
+      options: params.options,
+    });
+
+    // Wait for response from client (with timeout)
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingPermissions.delete(requestId);
+        resolve({ outcome: { outcome: 'cancelled' } });
+      }, 300000); // 5 minute timeout
+
+      this.pendingPermissions.set(requestId, { resolve, reject, timeout });
+    });
+  }
+
+  /**
+   * Handle permission response from UI
+   */
+  handlePermissionResponse(requestId: string, optionId: string): void {
+    const pending = this.pendingPermissions.get(requestId);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pendingPermissions.delete(requestId);
+      pending.resolve({
+        outcome: { outcome: 'selected', optionId },
+      });
+    }
+  }
+
+  /**
+   * Handle session update from agent
+   */
+  async sessionUpdate(params: acp.SessionNotification): Promise<void> {
+    const update = params.update;
+
+    // Normalize the update (convert Claude-style diffs to unified format)
+    const normalized = normalizeSessionUpdate(update);
+
+    // Route to session
+    this.onEvent({ type: 'session_update', update: normalized });
+
+    // Log updates for debugging
+    if (update.sessionUpdate === 'agent_message_chunk') {
+      // Don't log every chunk
+    } else if (isToolCallUpdate(update)) {
+      console.log(`[amux] Tool call: ${update.title} (${update.status}) id=${(update as { toolCallId?: string }).toolCallId}`);
+    } else if (update.sessionUpdate === 'tool_call_update') {
+      // Don't log every update
+    } else if (update.sessionUpdate === 'current_mode_update') {
+      console.log(`[amux] Mode update: ${update.currentModeId}`);
+    } else {
+      console.log(`[amux] Session update: ${update.sessionUpdate}`);
+    }
+  }
+
+  /**
+   * Write text file (ACP fs capability)
+   */
+  async writeTextFile(params: acp.WriteTextFileRequest): Promise<acp.WriteTextFileResponse> {
+    console.log('[amux] Write text file:', params.path);
+    try {
+      fs.writeFileSync(params.path, params.content);
+      return {};
+    } catch (err) {
+      throw new Error(`Failed to write file: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Read text file (ACP fs capability)
+   */
+  async readTextFile(params: acp.ReadTextFileRequest): Promise<acp.ReadTextFileResponse> {
+    console.log('[amux] Read text file:', params.path);
+    try {
+      const content = fs.readFileSync(params.path, 'utf-8');
+      return { content };
+    } catch (err) {
+      throw new Error(`Failed to read file: ${(err as Error).message}`);
+    }
+  }
+
+  /**
+   * Create terminal (ACP terminal capability)
+   */
+  async createTerminal(params: acp.CreateTerminalRequest): Promise<acp.CreateTerminalResponse> {
+    return this.terminalManager.create(params);
+  }
+
+  /**
+   * Get terminal output (ACP terminal capability)
+   */
+  async terminalOutput(params: acp.TerminalOutputRequest): Promise<acp.TerminalOutputResponse> {
+    return this.terminalManager.getOutput(params.terminalId);
+  }
+
+  /**
+   * Wait for terminal exit (ACP terminal capability)
+   */
+  async waitForTerminalExit(params: acp.WaitForTerminalExitRequest): Promise<acp.WaitForTerminalExitResponse> {
+    return this.terminalManager.waitForExit(params.terminalId);
+  }
+
+  /**
+   * Kill terminal (ACP terminal capability)
+   */
+  async killTerminal(params: acp.KillTerminalCommandRequest): Promise<acp.KillTerminalCommandResponse> {
+    return this.terminalManager.kill(params.terminalId);
+  }
+
+  /**
+   * Release terminal (ACP terminal capability)
+   */
+  async releaseTerminal(params: acp.ReleaseTerminalRequest): Promise<acp.ReleaseTerminalResponse> {
+    return this.terminalManager.release(params.terminalId);
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * amux - Agent Multiplexer
+ *
+ * A library for managing ACP agent sessions with an EventEmitter interface.
+ * Transport-agnostic - wire up to WebSocket, HTTP, IPC, or anything else.
+ *
+ * @example
+ * ```typescript
+ * import { AgentSession, createWsAdapter } from '@bytespell/amux';
+ * import { WebSocketServer } from 'ws';
+ *
+ * const session = new AgentSession({
+ *   instanceId: 'my-instance',
+ *   basePath: __dirname,
+ *   systemContext: 'You are a helpful assistant...',
+ * });
+ *
+ * // Option 1: Use the WebSocket adapter
+ * const wss = new WebSocketServer({ port: 3000 });
+ * createWsAdapter(session, wss);
+ *
+ * // Option 2: Handle events yourself
+ * session.on('ready', (data) => console.log('Ready:', data));
+ * session.on('update', (data) => myTransport.send(data));
+ *
+ * await session.spawnAgent();
+ * await session.prompt('Hello!');
+ * ```
+ */
+
+// Core session management
+export { AgentSession } from './session.js';
+export type { AgentSessionEvents } from './session.js';
+
+// WebSocket adapter
+export { createWsAdapter } from './ws-adapter.js';
+export type { WsAdapterOptions } from './ws-adapter.js';
+
+// Supporting components (for advanced usage)
+export { AmuxClient } from './client.js';
+export { TerminalManager } from './terminal.js';
+export { StateManager } from './state.js';
+
+// Session update utilities
+export {
+  isToolCallUpdate,
+  isToolCallUpdateMessage,
+  isDiffContent,
+  normalizeSessionUpdate,
+} from './session-updates.js';
+
+// Message parsing utilities
+export { parseMessageToContentBlocks } from './message-parser.js';
+
+// Types
+export type {
+  AgentSessionConfig,
+  AgentConfig,
+  SessionMetadata,
+  SessionState,
+  SessionRestoreInfo,
+  StoredEvent,
+} from './types.js';
+
+// Built-in agents registry
+export { AGENTS } from './types.js';

package/src/message-parser.ts

@@ -0,0 +1,54 @@
+import path from 'path';
+import type * as acp from '@agentclientprotocol/sdk';
+
+/**
+ * Parse message text with @mentions into ContentBlock array.
+ * @mentions become resource_link blocks, other text becomes text blocks.
+ *
+ * Examples:
+ * - "hello world" → [{ type: 'text', text: 'hello world' }]
+ * - "@src/foo.ts" → [{ type: 'resource_link', uri: 'file://...', name: 'src/foo.ts' }]
+ * - "check @src/foo.ts for bugs" → text + resource_link + text
+ */
+export function parseMessageToContentBlocks(
+  message: string,
+  workingDir: string
+): acp.ContentBlock[] {
+  const blocks: acp.ContentBlock[] = [];
+  // Match @path/to/file.ts, @./local.ts, @../parent/file.ts
+  // Allows leading ./ or ../ followed by path characters
+  const mentionRegex = /@(\.{0,2}[\w\/\.\-]+)/g;
+
+  let lastIndex = 0;
+  for (const match of message.matchAll(mentionRegex)) {
+    // Add text before mention
+    if (match.index! > lastIndex) {
+      const text = message.slice(lastIndex, match.index);
+      if (text.trim()) {
+        blocks.push({ type: 'text', text });
+      }
+    }
+
+    // Add resource_link for mention
+    const relativePath = match[1]!;
+    const absolutePath = path.resolve(workingDir, relativePath);
+    blocks.push({
+      type: 'resource_link',
+      uri: `file://${absolutePath}`,
+      name: relativePath,
+    });
+
+    lastIndex = match.index! + match[0].length;
+  }
+
+  // Add remaining text
+  if (lastIndex < message.length) {
+    const text = message.slice(lastIndex);
+    if (text.trim()) {
+      blocks.push({ type: 'text', text });
+    }
+  }
+
+  // If no mentions found, return single text block
+  return blocks.length > 0 ? blocks : [{ type: 'text', text: message }];
+}

package/src/session-updates.ts

@@ -0,0 +1,87 @@
+import type * as acp from '@agentclientprotocol/sdk';
+
+/**
+ * Type guard for tool_call session updates
+ */
+export function isToolCallUpdate(
+  update: acp.SessionUpdate
+): update is acp.ToolCall & { sessionUpdate: 'tool_call' } {
+  return update.sessionUpdate === 'tool_call';
+}
+
+/**
+ * Type guard for tool_call_update session updates
+ */
+export function isToolCallUpdateMessage(
+  update: acp.SessionUpdate
+): update is acp.ToolCallUpdate & { sessionUpdate: 'tool_call_update' } {
+  return update.sessionUpdate === 'tool_call_update';
+}
+
+/**
+ * Type guard for diff content items
+ */
+export function isDiffContent(
+  item: acp.ToolCallContent
+): item is acp.Diff & { type: 'diff' } {
+  return item.type === 'diff';
+}
+
+/**
+ * Normalize ACP session updates.
+ * Claude sends Edit/Write diffs as {newText, oldText, path} instead of unified diff.
+ * We convert these to standard unified diff format so the UI doesn't need agent-specific logic.
+ */
+export function normalizeSessionUpdate(
+  update: acp.SessionUpdate
+): acp.SessionUpdate {
+  // Only process tool_call and tool_call_update events with content arrays
+  if (!isToolCallUpdate(update) && !isToolCallUpdateMessage(update)) {
+    return update;
+  }
+
+  const content = update.content;
+  if (!content || !Array.isArray(content)) {
+    return update;
+  }
+
+  // Check for diff items that need normalization
+  const normalizedContent = content.map((item): acp.ToolCallContent => {
+    if (!isDiffContent(item)) return item;
+
+    const diffItem = item;
+    const newText = diffItem.newText;
+    const oldText = diffItem.oldText;
+    const filePath = diffItem.path ?? 'file';
+
+    // Generate unified diff
+    const oldLines = oldText ? oldText.split('\n') : [];
+    const newLines = newText.split('\n');
+
+    let unifiedDiff = `Index: ${filePath}\n`;
+    unifiedDiff += '===================================================================\n';
+    unifiedDiff += `--- ${filePath}\n`;
+    unifiedDiff += `+++ ${filePath}\n`;
+    unifiedDiff += `@@ -${oldLines.length > 0 ? 1 : 0},${oldLines.length} +1,${newLines.length} @@\n`;
+
+    for (const line of oldLines) {
+      unifiedDiff += `-${line}\n`;
+    }
+    for (const line of newLines) {
+      unifiedDiff += `+${line}\n`;
+    }
+
+    // Return normalized diff item
+    return {
+      type: 'diff',
+      newText: unifiedDiff,
+      oldText: '',
+      path: filePath,
+    };
+  });
+
+  return {
+    ...update,
+    content: normalizedContent,
+  };
+}