@bytespell/amux 0.0.18 → 0.0.22

package/CLAUDE.md

@@ -1,104 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code when working with this repository.
-
-## What is amux?
-
-**amux** (Agent Multiplexer) is a library for building agent-powered HTTP servers. Think of it like tmux, but for AI agents over HTTP. It provides:
-
-1. **Session management**: Spawn, manage, and multiplex multiple ACP agent sessions
-2. **WebSocket API**: Real-time streaming communication with agents
-3. **State persistence**: Session history, preferences, and replay
-4. **System context injection**: Customize agent behavior with injected knowledge
-
-## Project Structure
-
-```
-amux/
-├── src/
-│   ├── index.ts          # Public API exports
-│   ├── cli.ts            # CLI entry point
-│   ├── server.ts         # Express + WebSocket server factory
-│   ├── session.ts        # AgentSession - core session management
-│   ├── client.ts         # AmuxClient - ACP client implementation
-│   ├── terminal.ts       # TerminalManager - PTY management
-│   ├── state.ts          # StateManager - persistence
-│   ├── session-updates.ts # ACP update normalization
-│   └── types.ts          # TypeScript types
-├── package.json
-└── tsconfig.json
-```
-
-## Key Concepts
-
-### AgentSession
-
-The core class that manages an ACP agent lifecycle:
-- Spawns agent processes (claude-code-acp, codex-acp, pi-acp)
-- Handles ACP protocol communication
-- Manages session state and history
-- Supports system context injection
-
-### AmuxClient
-
-Implements the ACP Client interface:
-- Filesystem operations (read/write files)
-- Terminal management (spawn commands, get output)
-- Permission request handling
-- Session update broadcasting
-
-### Server Factory
-
-`createAmuxServer()` provides a batteries-included server:
-- Express app with API routes
-- WebSocket server on `/ws`
-- Automatic agent spawning
-- History replay on reconnect
-
-## Build Commands
-
-```bash
-npm run build      # Compile TypeScript
-npm run dev        # Watch mode
-npm run typecheck  # Type check only
-npm run test       # Run tests
-```
-
-## API Design
-
-The public API has three levels:
-
-1. **High-level**: `createAmuxServer(config)` - Full server in one call
-2. **Mid-level**: `attachAmux(app, server, config)` - Attach to existing Express app
-3. **Low-level**: `AgentSession` class - Full control over session management
-
-## State Storage
-
-By default, state is stored in `~/.local/state/amux/`:
-- `instance-{id}.json` - Per-instance state (cwd, sessionId, agentType)
-- `session-{id}-history.json` - Session event history for replay
-- `sessions.json` - Session registry with metadata
-
-## WebSocket Protocol
-
-The WebSocket API on `/ws` uses JSON messages. Key message types:
-
-**Client → Server:**
-- `prompt` - Send user message
-- `cancel` - Cancel current operation
-- `permission_response` - Respond to permission request
-- `change_cwd`, `new_session`, `change_agent`, etc.
-
-**Server → Client:**
-- `ready` - Connection established
-- `session_update` - Streaming updates from agent
-- `permission_request` - Agent needs permission
-- `history_replay` - Replay events on reconnect
-- `error` - Error occurred
-
-## Testing
-
-When adding features:
-1. Unit test individual components (StateManager, TerminalManager, etc.)
-2. Integration test the full server with a mock agent
-3. Test WebSocket message handling

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Ashley Hauck
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,234 +0,0 @@
-# amux
-
-**ACP Multiplexer** - the session layer for ACP agents.
-
-The [ACP TypeScript SDK](https://github.com/agentclientprotocol/typescript-sdk) does the hard work of getting the protocol right - json-rpc transport, type definitions, connection lifecycle. But there's a gap between "I can send messages to an agent" and "I can manage agent sessions in my app".
-
-amux fills that gap. Think tmux for agents - spawn sessions, detach, reattach later, pick up where you left off.
-
-Everything the SDK doesn't do:
-- Spawn and manage agent processes (the SDK gives you a connection, not a process)
-- Persist session state to disk (detach and reattach later)
-- Replay history on reconnect (your UI picks up where it left off)
-- Handle permission requests with pluggable strategies
-- Switch between agents (Claude Code, Codex, Pi) without changing your code
-
-Transport-agnostic core with an optional WebSocket adapter.
-
-## Installation
-
-```bash
-npm install @bytespell/amux
-```
-
-You'll also need at least one ACP agent installed and available on your PATH:
-
-```bash
-# Claude Code
-npm install -g @anthropics/claude-code
-
-# Codex
-npm install -g @openai/codex
-
-# Pi
-npm install -g @mariozechner/pi-coding-agent
-```
-
-amux automatically detects which agents are installed by checking your PATH.
-
-## Quick Start
-
-### With WebSocket Adapter
-
-```typescript
-import { AgentSession, createWsAdapter } from '@bytespell/amux';
-import { WebSocketServer } from 'ws';
-import { createServer } from 'http';
-
-const server = createServer();
-const wss = new WebSocketServer({ server, path: '/ws' });
-
-const session = new AgentSession({
-  instanceId: process.env.INSTANCE_ID ?? 'default',
-  systemContext: 'You are a helpful assistant...',
-});
-
-// Wire up WebSocket
-createWsAdapter(session, wss);
-
-// Start the agent
-await session.spawnAgent();
-
-server.listen(3000);
-```
-
-### Events Only (Bring Your Own Transport)
-
-```typescript
-import { AgentSession } from '@bytespell/amux';
-
-const session = new AgentSession({
-  instanceId: 'my-instance',
-});
-
-// Subscribe to events
-session.on('ready', (data) => {
-  console.log('Agent ready:', data.agent.name);
-});
-
-session.on('update', (update) => {
-  // Handle streaming updates
-  if (update.sessionUpdate === 'agent_message_chunk') {
-    process.stdout.write(update.content.text);
-  }
-});
-
-session.on('permission_request', (data) => {
-  // Auto-approve for demo
-  session.respondToPermission(data.requestId, data.options[0].optionId);
-});
-
-session.on('error', (data) => {
-  console.error('Error:', data.message);
-});
-
-// Start and prompt
-await session.spawnAgent();
-await session.prompt('Hello, what can you do?');
-```
-
-## API
-
-### `AgentSession`
-
-Core class for managing an ACP agent session. Extends `EventEmitter`.
-
-```typescript
-const session = new AgentSession({
-  instanceId: string;       // Unique ID for state isolation
-  systemContext?: string;   // Injected context for the agent
-  fixedCwd?: string;        // Lock working directory
-  agentType?: string;       // 'claude-code' | 'codex' | 'pi'
-  stateDir?: string;        // Custom state directory
-});
-```
-
-#### Methods
-
-```typescript
-await session.spawnAgent()              // Start the agent process
-await session.prompt(message)           // Send a prompt
-await session.cancel()                  // Cancel current operation
-session.respondToPermission(id, optId)  // Respond to permission request
-await session.newSession()              // Create new session
-await session.changeCwd(path)           // Change working directory
-await session.changeAgent(type)         // Switch agent type
-session.listSessions()                  // List available sessions
-session.loadHistory()                   // Get current session history
-session.getAvailableAgents()            // All agents with installed status
-session.getInstalledAgents()            // Only agents ready to use
-session.shutdown()                      // Cleanup and stop
-```
-
-#### Agent Discovery
-
-amux bundles ACP wrappers for supported agents. Use `getInstalledAgents()` to find which agents are ready to use (base CLI on PATH + ACP wrapper bundled):
-
-```typescript
-const agents = session.getInstalledAgents();
-// [{ id: 'claude-code', name: 'Claude Code' }, ...]
-
-const allAgents = session.getAvailableAgents();
-// [{ id: 'claude-code', name: 'Claude Code', installed: true }, ...]
-```
-
-The `ready` event also includes `availableAgents` (same as `getInstalledAgents()`).
-
-#### Events
-
-```typescript
-session.on('connecting', () => {})
-session.on('ready', (data) => {})           // Agent initialized
-session.on('update', (update) => {})        // Session update (streaming)
-session.on('turn_start', () => {})          // Prompt started
-session.on('turn_end', () => {})            // Prompt completed
-session.on('permission_request', (data) => {})
-session.on('prompt_complete', (data) => {})
-session.on('session_created', (data) => {})
-session.on('session_switched', (data) => {})
-session.on('history_replay', (data) => {})
-session.on('error', (data) => {})
-session.on('agent_exit', (data) => {})
-```
-
-### `createWsAdapter(session, wss, options?)`
-
-Wire up a WebSocket server to an AgentSession.
-
-```typescript
-import { createWsAdapter } from '@bytespell/amux';
-
-const adapter = createWsAdapter(session, wss, {
-  sendHistoryOnConnect: true,  // Default: true
-});
-
-adapter.clientCount()  // Get connected clients
-adapter.broadcast(msg) // Send custom message to all
-adapter.close()        // Close all connections
-```
-
-#### WebSocket Protocol
-
-**Client → Server:**
-```typescript
-{ type: 'prompt', message: 'Hello' }
-{ type: 'cancel' }
-{ type: 'permission_response', requestId: '...', optionId: '...' }
-{ type: 'change_cwd', path: '/new/path' }
-{ type: 'new_session' }
-{ type: 'change_agent', agentType: 'codex' }
-{ type: 'list_sessions' }
-{ type: 'switch_session', sessionId: '...' }
-```
-
-**Server → Client:**
-```typescript
-{ type: 'ready', cwd: '...', sessionId: '...', ... }
-{ type: 'session_update', update: { sessionUpdate: '...', ... } }
-{ type: 'permission_request', requestId: '...', toolCall: {...}, options: [...] }
-{ type: 'history_replay', events: [...], eventCount: 42 }
-{ type: 'error', message: '...' }
-```
-
-## System Context
-
-Inject context to customize agent behavior:
-
-```typescript
-const session = new AgentSession({
-  instanceId: 'docs-helper',
-  systemContext: `
-# Documentation Assistant
-
-You help users write documentation for this project.
-
-Key conventions:
-- Use markdown format
-- Include code examples
-- Keep explanations concise
-  `,
-});
-```
-
-## State Persistence
-
-Sessions are persisted to `~/.local/state/amux/` by default:
-- Instance state (cwd, sessionId, agentType)
-- Session history (for replay on reconnect)
-- Session registry (list all sessions)
-
-Override with `stateDir` option.
-
-## License
-
-MIT

package/dist/cli.d.ts

@@ -1,14 +0,0 @@
-#!/usr/bin/env node
-/**
- * amux CLI
- *
- * Quick way to start an amux server from the command line.
- *
- * Usage:
- *   amux                          # Start with defaults
- *   amux --context ./CONTEXT.md   # Start with system context from file
- *   amux --cwd /path/to/project   # Start with fixed working directory
- *   amux --port 3000              # Start on specific port
- */
-export {};
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}

package/dist/cli.js

@@ -1,118 +0,0 @@
-#!/usr/bin/env node
-/**
- * amux CLI
- *
- * Quick way to start an amux server from the command line.
- *
- * Usage:
- *   amux                          # Start with defaults
- *   amux --context ./CONTEXT.md   # Start with system context from file
- *   amux --cwd /path/to/project   # Start with fixed working directory
- *   amux --port 3000              # Start on specific port
- */
-import fs from 'fs';
-import path from 'path';
-import { createAmuxServer } from './server.js';
-function parseArgs() {
-    const args = {};
-    const argv = process.argv.slice(2);
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === '--help' || arg === '-h') {
-            args.help = true;
-        }
-        else if (arg === '--port' || arg === '-p') {
-            args.port = parseInt(argv[++i] ?? '', 10);
-        }
-        else if (arg === '--context' || arg === '-c') {
-            args.context = argv[++i];
-        }
-        else if (arg === '--cwd' || arg === '-d') {
-            args.cwd = argv[++i];
-        }
-        else if (arg === '--agent' || arg === '-a') {
-            args.agent = argv[++i];
-        }
-    }
-    return args;
-}
-function printHelp() {
-    console.log(`
-amux - ACP Multiplexer
-
-Start an agent-powered HTTP server with multiplexed sessions.
-
-USAGE:
-  amux [OPTIONS]
-
-OPTIONS:
-  -p, --port <port>       Port to listen on (default: 3000 or PORT env)
-  -c, --context <file>    Load system context from a markdown file
-  -d, --cwd <path>        Fixed working directory for all sessions
-  -a, --agent <type>      Agent type: claude-code, codex, pi (default: claude-code)
-  -h, --help              Show this help message
-
-EXAMPLES:
-  # Start with defaults
-  amux
-
-  # Start with system context
-  amux --context ./PLUGIN_GUIDE.md
-
-  # Start for a specific project
-  amux --cwd /path/to/project --context ./CONTEXT.md
-
-  # Use a different agent
-  amux --agent codex
-
-ENVIRONMENT:
-  PORT          Server port (overridden by --port)
-  INSTANCE_ID   Unique instance identifier for state isolation
-`);
-}
-async function main() {
-    const args = parseArgs();
-    if (args.help) {
-        printHelp();
-        process.exit(0);
-    }
-    // Load system context if specified
-    let systemContext;
-    if (args.context) {
-        const contextPath = path.resolve(args.context);
-        if (!fs.existsSync(contextPath)) {
-            console.error(`Error: Context file not found: ${contextPath}`);
-            process.exit(1);
-        }
-        systemContext = fs.readFileSync(contextPath, 'utf-8');
-        console.log(`[amux] Loaded system context from ${contextPath} (${systemContext.length} bytes)`);
-    }
-    // Resolve fixed cwd if specified
-    let fixedCwd;
-    if (args.cwd) {
-        fixedCwd = path.resolve(args.cwd);
-        if (!fs.existsSync(fixedCwd)) {
-            console.error(`Error: Working directory not found: ${fixedCwd}`);
-            process.exit(1);
-        }
-        console.log(`[amux] Using fixed working directory: ${fixedCwd}`);
-    }
-    const { start, shutdown } = createAmuxServer({
-        port: args.port,
-        systemContext,
-        fixedCwd,
-        agentType: args.agent,
-    });
-    // Handle shutdown gracefully
-    process.on('SIGINT', () => {
-        console.log('\n[amux] Received SIGINT, shutting down...');
-        shutdown();
-        process.exit(0);
-    });
-    await start();
-}
-main().catch((err) => {
-    console.error('[amux] Fatal error:', err);
-    process.exit(1);
-});
-//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/message-parser.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=message-parser.test.d.ts.map

package/dist/message-parser.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"message-parser.test.d.ts","sourceRoot":"","sources":["../src/message-parser.test.ts"],"names":[],"mappings":""}