@zengxingyuan/aamp-acp-bridge 0.1.28-dev.10

package/README.md

@@ -0,0 +1,136 @@
+# aamp-acp-bridge
+
+Config-driven bridge that connects ACP-compatible agents to the AAMP email network.
+
+## Install
+
+```bash
+npm install aamp-acp-bridge
+```
+
+## Usage
+
+Initialize the bridge:
+
+```bash
+npx aamp-acp-bridge init
+```
+
+The init wizard scans installed ACP-capable agents, including Hermes, then lets you select multiple entries with arrow keys, Space, and Enter. For each selected agent, choose one authorization setup method:
+
+- Pair with a five-minute terminal QR code plus the matching `aamp://connect?...` URL.
+- Manually enter `senderPolicies`.
+- Reuse existing `senderPolicies`, when any are available.
+- Configure sender authorization later; `task.dispatch` is rejected until pairing or policy setup is complete.
+
+If you choose QR pairing, `init` starts the bridge immediately after writing config, so scanning the QR code with AAMP App works right away. The bridge answers each `pair.request` with `pair.respond`; rejected responses include the failure reason.
+
+Use `--no-start` only when you need to generate config in a script without
+keeping the bridge process running:
+
+```bash
+npx aamp-acp-bridge init --agent claude --no-start
+```
+
+After an agent has been initialized, generate a fresh pairing QR code without
+re-running setup:
+
+```bash
+npx aamp-acp-bridge pair --agent claude
+```
+
+Start the bridge:
+
+```bash
+npx aamp-acp-bridge start
+```
+
+When debugging task routing, add `--debug` to print the exact prompt sent to
+the ACP agent for each `task.dispatch`:
+
+```bash
+npx aamp-acp-bridge start --debug
+```
+
+By default, the bridge stores its config under `~/.aamp/acp-bridge/config.json` and agent credentials under `~/.aamp/acp-bridge/credentials/`.
+Legacy `./bridge.json` and `~/.acp-bridge/` data are migrated automatically on first use without deleting the original files.
+
+The bridge understands these task lifecycle intents:
+
+- `task.dispatch`
+- `task.stream.opened`
+- `task.help_needed`
+- `task.result`
+- `task.cancel`
+
+Dispatch tasks can also carry:
+
+- `priority`: `urgent | high | normal`
+- `expiresAt`: an ISO-8601 timestamp after which the task should no longer run
+- `promptRules`: an optional complete text block that replaces the default task
+  prompt rules
+
+If a `task.cancel` arrives before the ACP agent returns a final answer, the bridge suppresses any later result send for that task.
+
+When `promptRules` is present on `task.dispatch`, the ACP prompt keeps its
+standard task identity, metadata, dispatch context, description, and thread
+context, then replaces the default task rule block with the provided text.
+
+While ACP execution is in progress, the bridge can:
+
+- create an AAMP task stream for the task
+- send `task.stream.opened`
+- append `status`, `progress`, and `text.delta` events
+- forward ACP `agent_thought_chunk` / `agent_message_chunk` updates into the AAMP stream in realtime
+- expose tool progress as stream progress labels while the agent is working
+- close the stream before the authoritative `task.result` or `task.help_needed`
+
+When `acpx` supports `--format json --json-strict`, the bridge consumes the structured ACP NDJSON stream so reasoning / reply chunks can be forwarded live. Older `acpx` builds automatically fall back to plain-text mode, which preserves compatibility but cannot expose thought chunks incrementally.
+
+## Config
+
+Minimal example:
+
+```json
+{
+  "aampHost": "https://meshmail.ai",
+  "rejectUnauthorized": false,
+  "agents": [
+    {
+      "name": "claude",
+      "acpCommand": "claude",
+      "slug": "claude-bridge",
+      "taskDispatchConcurrency": 10,
+      "credentialsFile": "~/.aamp/acp-bridge/credentials/claude.json",
+      "senderPolicies": [
+        {
+          "sender": "system@aamp.local",
+          "dispatchContextRules": {
+            "project_key": ["proj_123"]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+`senderPolicies` is optional, but omitted policies do not authorize anyone by default. Use QR pairing or configure at least one policy before sending `task.dispatch`; matching policies can also enforce exact-match `X-AAMP-Dispatch-Context` rules.
+Legacy `senderWhitelist` configs still load and are normalized into `senderPolicies`.
+When editing the `senderPoliciesFile` directly, `pairedAt` is optional; the bridge accepts manually added records with just `sender` and optional `dispatchContextRules`.
+`credentialsFile` is optional. If omitted, the bridge uses `~/.aamp/acp-bridge/credentials/<agent>.json`.
+`taskDispatchConcurrency` is optional and defaults to `10`.
+
+### Hermes
+
+Hermes exposes ACP through `hermes acp`, so its bridge config uses a raw ACP command:
+
+```json
+{
+  "name": "hermes",
+  "acpCommand": "hermes acp",
+  "slug": "hermes-bridge"
+}
+```
+
+`init --agent hermes` writes this command automatically when Hermes is installed.

package/dist/acpx-client.d.ts

@@ -0,0 +1,81 @@
+export interface AcpEvent {
+    eventVersion?: number;
+    sessionId?: string;
+    requestId?: string;
+    seq?: number;
+    type?: string;
+    messageId?: string;
+    content?: unknown;
+    [key: string]: unknown;
+}
+export type AcpTextChunkChannel = 'assistant' | 'thought';
+export interface AcpTextChunk {
+    channel: AcpTextChunkChannel;
+    text: string;
+    messageId?: string;
+}
+export interface AcpToolUpdate {
+    toolCallId?: string;
+    title?: string;
+    status?: string;
+    kind?: string;
+    text?: string;
+    locations?: Array<{
+        path: string;
+        line?: number;
+    }>;
+}
+export interface AcpPlanEntry {
+    content: string;
+    status?: string;
+    priority?: string;
+}
+export interface AcpPromptHandlers {
+    onEvent?: (event: AcpEvent) => void;
+    onTextChunk?: (chunk: AcpTextChunk) => void;
+    onToolUpdate?: (update: AcpToolUpdate) => void;
+    onPlanUpdate?: (entries: AcpPlanEntry[]) => void;
+}
+export interface AcpResult {
+    output: string;
+    events: AcpEvent[];
+    stopReason?: string;
+    streamedAssistantText: boolean;
+}
+/**
+ * Wrapper around acpx CLI.
+ * Invokes acpx as a subprocess and parses NDJSON output.
+ */
+export declare class AcpxClient {
+    private cwd;
+    constructor(cwd?: string);
+    private isRawAgentCommand;
+    private buildAcpxArgs;
+    private formatArgForLog;
+    private formatFailedCommand;
+    private buildSubprocessEnv;
+    private formatProcessFailure;
+    /**
+     * Ensure a named ACP session exists for the given agent.
+     */
+    ensureSession(agent: string, sessionName: string): Promise<string>;
+    /**
+     * Send a prompt to an ACP agent and wait for completion.
+     * Collects all stdout + stderr output and extracts the agent's response.
+     */
+    prompt(agent: string, sessionName: string, text: string, handlers?: AcpPromptHandlers): Promise<AcpResult>;
+    private promptJsonMode;
+    private promptTextMode;
+    /**
+     * Cancel the current operation in a session.
+     */
+    cancel(agent: string, sessionName: string): Promise<void>;
+    /**
+     * Close a session.
+     */
+    close(agent: string, sessionName: string): Promise<void>;
+    /**
+     * Execute an acpx command and return stdout.
+     */
+    private exec;
+}

package/dist/acpx-client.js

@@ -0,0 +1,485 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function extractContentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content.map((item) => extractContentText(item)).join('');
+    }
+    const record = asRecord(content);
+    if (!record)
+        return '';
+    if (typeof record.text === 'string')
+        return record.text;
+    if (typeof record.thinking === 'string')
+        return record.thinking;
+    const resource = asRecord(record.resource);
+    if (resource && typeof resource.text === 'string')
+        return resource.text;
+    return '';
+}
+function extractToolLocations(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const locations = value.flatMap((item) => {
+        const record = asRecord(item);
+        if (!record)
+            return [];
+        const path = asString(record.path);
+        if (!path)
+            return [];
+        const line = typeof record.line === 'number' && Number.isFinite(record.line)
+            ? record.line
+            : undefined;
+        return [{ path, ...(line != null ? { line } : {}) }];
+    });
+    return locations.length > 0 ? locations : undefined;
+}
+function extractPlanEntries(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        const record = asRecord(item);
+        const content = asString(record?.content);
+        if (!content)
+            return [];
+        return [{
+                content,
+                ...(asString(record?.status) ? { status: asString(record?.status) } : {}),
+                ...(asString(record?.priority) ? { priority: asString(record?.priority) } : {}),
+            }];
+    });
+}
+function normalizeLegacyEvent(record) {
+    const rawType = asString(record.type);
+    if (!rawType)
+        return null;
+    const mappedType = rawType === 'thinking' ? 'agent_thought_chunk' : rawType;
+    return {
+        ...record,
+        type: mappedType,
+        ...(asString(record.sessionId) ? { sessionId: asString(record.sessionId) } : {}),
+        ...(asString(record.requestId) ? { requestId: asString(record.requestId) } : {}),
+        ...(typeof record.seq === 'number' ? { seq: record.seq } : {}),
+    };
+}
+function normalizeJsonRpcEvent(record) {
+    if (record.method === 'session/update') {
+        const params = asRecord(record.params);
+        if (!params)
+            return null;
+        const explicitUpdate = asRecord(params.update);
+        const fallbackUpdate = asString(params.sessionUpdate)
+            ? {
+                ...params,
+                sessionUpdate: params.sessionUpdate,
+            }
+            : null;
+        const update = explicitUpdate ?? fallbackUpdate;
+        if (!update)
+            return null;
+        const type = asString(update.sessionUpdate);
+        if (!type)
+            return null;
+        const normalized = {
+            type,
+            ...(asString(params.sessionId) ? { sessionId: asString(params.sessionId) } : {}),
+        };
+        for (const [key, value] of Object.entries(update)) {
+            if (key === 'sessionUpdate')
+                continue;
+            normalized[key] = value;
+        }
+        return normalized;
+    }
+    if (record.result) {
+        const result = asRecord(record.result);
+        if (!result)
+            return null;
+        return {
+            type: 'result',
+            ...(asString(record.id) ? { requestId: asString(record.id) } : {}),
+            ...result,
+        };
+    }
+    if (record.error) {
+        return {
+            type: 'error',
+            ...(asString(record.id) ? { requestId: asString(record.id) } : {}),
+            error: record.error,
+        };
+    }
+    return null;
+}
+function parseAcpLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { event: null, isJson: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { event: null, isJson: false };
+    }
+    const record = asRecord(parsed);
+    if (!record)
+        return { event: null, isJson: true };
+    if (record.jsonrpc === '2.0') {
+        return { event: normalizeJsonRpcEvent(record), isJson: true };
+    }
+    return { event: normalizeLegacyEvent(record), isJson: true };
+}
+function supportsJsonStreamingFallback(stderr) {
+    return /unknown option|unknown argument|unexpected argument|invalid value|--format|--json-strict/i.test(stderr);
+}
+function isCliTranscriptHeader(line) {
+    return /^\[(acpx|client|tool|done|error|warning)\](?:\s|$)/i.test(line);
+}
+function extractFinalReplyFromTranscript(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return '';
+    const lines = trimmed.replace(/\r\n/g, '\n').split('\n');
+    const textBlocks = [];
+    let currentBlock = [];
+    let skippingTranscriptDetails = false;
+    const flushBlock = () => {
+        const block = currentBlock.join('\n').trim();
+        if (block)
+            textBlocks.push(block);
+        currentBlock = [];
+    };
+    for (const line of lines) {
+        if (isCliTranscriptHeader(line)) {
+            flushBlock();
+            skippingTranscriptDetails = true;
+            continue;
+        }
+        if (skippingTranscriptDetails) {
+            if (!line || /^[ \t]+/.test(line)) {
+                continue;
+            }
+            skippingTranscriptDetails = false;
+        }
+        currentBlock.push(line);
+    }
+    flushBlock();
+    return textBlocks.at(-1) ?? '';
+}
+function sanitizePromptOutput(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return '';
+    if (!trimmed.split(/\r?\n/).some((line) => isCliTranscriptHeader(line))) {
+        return trimmed;
+    }
+    return extractFinalReplyFromTranscript(trimmed);
+}
+/**
+ * Wrapper around acpx CLI.
+ * Invokes acpx as a subprocess and parses NDJSON output.
+ */
+export class AcpxClient {
+    cwd;
+    constructor(cwd) {
+        this.cwd = cwd ?? process.cwd();
+    }
+    isRawAgentCommand(agent) {
+        return /\s/.test(agent.trim());
+    }
+    buildAcpxArgs(agent, args, globalArgs = []) {
+        if (this.isRawAgentCommand(agent)) {
+            return ['--approve-all', '--cwd', this.cwd, ...globalArgs, '--agent', agent, ...args];
+        }
+        return ['--approve-all', '--cwd', this.cwd, ...globalArgs, agent, ...args];
+    }
+    formatArgForLog(arg) {
+        const normalized = arg.replace(/\s+/g, ' ').trim();
+        if (normalized.length <= 160)
+            return normalized;
+        return `${normalized.slice(0, 157)}...`;
+    }
+    formatFailedCommand(agent, args, globalArgs = []) {
+        return ['acpx', ...this.buildAcpxArgs(agent, args, globalArgs)]
+            .map((arg) => this.formatArgForLog(arg))
+            .join(' ');
+    }
+    buildSubprocessEnv() {
+        const env = { ...process.env };
+        const registry = env.npm_config_registry || env.NPM_CONFIG_REGISTRY || 'https://registry.npmjs.org/';
+        const cache = env.npm_config_cache || env.NPM_CONFIG_CACHE || `${tmpdir()}/aamp-acpx-npm-cache`;
+        for (const key of Object.keys(env)) {
+            const lower = key.toLowerCase();
+            if (lower.startsWith('npm_config_')
+                || lower.startsWith('npm_package_')
+                || lower.startsWith('npm_lifecycle_')
+                || lower === 'npm_command'
+                || lower === 'npm_execpath'
+                || lower === 'npm_node_execpath'
+                || lower === 'init_cwd') {
+                delete env[key];
+            }
+        }
+        mkdirSync(cache, { recursive: true });
+        env.npm_config_registry = registry;
+        env.NPM_CONFIG_REGISTRY = registry;
+        env.npm_config_cache = cache;
+        env.NPM_CONFIG_CACHE = cache;
+        return env;
+    }
+    formatProcessFailure(agent, args, code, stdout, stderr, globalArgs = []) {
+        const details = [
+            stderr.trim() ? `stderr: ${stderr.trim()}` : '',
+            stdout.trim() ? `stdout: ${stdout.trim()}` : '',
+        ].filter(Boolean);
+        return `${this.formatFailedCommand(agent, args, globalArgs)} failed (${code ?? 'unknown'}): ${details.join('\n') || 'no output from acpx'}`;
+    }
+    /**
+     * Ensure a named ACP session exists for the given agent.
+     */
+    async ensureSession(agent, sessionName) {
+        const result = await this.exec(agent, ['sessions', 'ensure', '--name', sessionName]);
+        // Try to extract sessionId from the JSON output
+        try {
+            const data = JSON.parse(result.trim().split('\n').pop() ?? '{}');
+            return data.sessionId ?? sessionName;
+        }
+        catch {
+            return sessionName;
+        }
+    }
+    /**
+     * Send a prompt to an ACP agent and wait for completion.
+     * Collects all stdout + stderr output and extracts the agent's response.
+     */
+    async prompt(agent, sessionName, text, handlers) {
+        try {
+            return await this.promptJsonMode(agent, sessionName, text, handlers);
+        }
+        catch (err) {
+            if (supportsJsonStreamingFallback(err.message)) {
+                return await this.promptTextMode(agent, sessionName, text);
+            }
+            throw err;
+        }
+    }
+    async promptJsonMode(agent, sessionName, text, handlers) {
+        const events = [];
+        let stopReason;
+        let streamedAssistantText = false;
+        const assistantMessages = new Map();
+        const assistantMessageOrder = [];
+        let lastAssistantMessageKey;
+        let lastThoughtMessageKey;
+        let thoughtMessageCount = 0;
+        let previousEventType;
+        return new Promise((resolve, reject) => {
+            const proc = spawn('acpx', this.buildAcpxArgs(agent, [
+                'prompt',
+                '-s', sessionName,
+                text,
+            ], ['--format', 'json', '--json-strict']), {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                cwd: this.cwd,
+                env: this.buildSubprocessEnv(),
+            });
+            let stdoutBuffer = '';
+            let rawStdout = '';
+            let stderr = '';
+            const processLine = (line) => {
+                const parsed = parseAcpLine(line);
+                const event = parsed.event;
+                if (!event) {
+                    if (!parsed.isJson) {
+                        rawStdout += `${line}\n`;
+                    }
+                    return;
+                }
+                events.push(event);
+                handlers?.onEvent?.(event);
+                if (event.type === 'agent_message_chunk') {
+                    const textChunk = extractContentText(event.content);
+                    if (textChunk) {
+                        const explicitMessageId = asString(event.messageId);
+                        const messageKey = explicitMessageId
+                            ?? (previousEventType === 'agent_message_chunk' && lastAssistantMessageKey
+                                ? lastAssistantMessageKey
+                                : `anonymous:${assistantMessageOrder.length}`);
+                        if (!assistantMessages.has(messageKey)) {
+                            assistantMessages.set(messageKey, '');
+                            assistantMessageOrder.push(messageKey);
+                        }
+                        assistantMessages.set(messageKey, `${assistantMessages.get(messageKey) ?? ''}${textChunk}`);
+                        lastAssistantMessageKey = messageKey;
+                        streamedAssistantText = true;
+                        handlers?.onTextChunk?.({
+                            channel: 'assistant',
+                            text: textChunk,
+                            messageId: messageKey,
+                        });
+                    }
+                    previousEventType = event.type;
+                    return;
+                }
+                if (event.type === 'agent_thought_chunk') {
+                    const textChunk = extractContentText(event.content);
+                    if (textChunk) {
+                        const messageId = asString(event.messageId)
+                            ?? (previousEventType === 'agent_thought_chunk' && lastThoughtMessageKey
+                                ? lastThoughtMessageKey
+                                : `anonymous-thought:${thoughtMessageCount++}`);
+                        lastThoughtMessageKey = messageId;
+                        handlers?.onTextChunk?.({
+                            channel: 'thought',
+                            text: textChunk,
+                            messageId,
+                        });
+                    }
+                    previousEventType = event.type;
+                    return;
+                }
+                if (event.type === 'tool_call' || event.type === 'tool_call_update') {
+                    handlers?.onToolUpdate?.({
+                        toolCallId: asString(event.toolCallId),
+                        title: asString(event.title),
+                        status: asString(event.status),
+                        kind: asString(event.kind),
+                        text: extractContentText(event.content),
+                        locations: extractToolLocations(event.locations),
+                    });
+                    previousEventType = event.type;
+                    return;
+                }
+                if (event.type === 'plan') {
+                    const entries = extractPlanEntries(event.entries);
+                    if (entries.length > 0) {
+                        handlers?.onPlanUpdate?.(entries);
+                    }
+                    previousEventType = event.type;
+                    return;
+                }
+                if (event.type === 'result') {
+                    stopReason = asString(event.stopReason);
+                }
+                previousEventType = event.type;
+            };
+            const processStdoutChunk = (chunk) => {
+                stdoutBuffer += chunk.toString();
+                let newlineIndex = stdoutBuffer.indexOf('\n');
+                while (newlineIndex >= 0) {
+                    const line = stdoutBuffer.slice(0, newlineIndex).replace(/\r$/, '');
+                    stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+                    processLine(line);
+                    newlineIndex = stdoutBuffer.indexOf('\n');
+                }
+            };
+            proc.stdout.on('data', processStdoutChunk);
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            proc.on('close', (code) => {
+                if (stdoutBuffer.trim()) {
+                    processLine(stdoutBuffer.replace(/\r$/, ''));
+                }
+                const finalAssistantOutput = [...assistantMessageOrder]
+                    .reverse()
+                    .map((messageKey) => assistantMessages.get(messageKey)?.trim() ?? '')
+                    .find((message) => message.length > 0) ?? '';
+                const output = finalAssistantOutput
+                    || sanitizePromptOutput(rawStdout)
+                    || sanitizePromptOutput(stderr);
+                if (code !== 0 && !output) {
+                    reject(new Error(this.formatProcessFailure(agent, ['prompt', '-s', sessionName, text], code, rawStdout, stderr, ['--format', 'json', '--json-strict'])));
+                }
+                else {
+                    resolve({
+                        output,
+                        events,
+                        ...(stopReason ? { stopReason } : {}),
+                        streamedAssistantText,
+                    });
+                }
+            });
+            proc.on('error', (err) => {
+                reject(new Error(`Failed to spawn acpx: ${err.message}. Is acpx installed?`));
+            });
+        });
+    }
+    async promptTextMode(agent, sessionName, text) {
+        const events = [];
+        return await new Promise((resolve, reject) => {
+            // Old acpx builds may not support JSON output yet.
+            const proc = spawn('acpx', this.buildAcpxArgs(agent, ['prompt', '-s', sessionName, text]), {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                cwd: this.cwd,
+                env: this.buildSubprocessEnv(),
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            proc.on('close', (code) => {
+                const output = sanitizePromptOutput(stdout) || sanitizePromptOutput(stderr);
+                if (code !== 0 && !output) {
+                    reject(new Error(this.formatProcessFailure(agent, ['prompt', '-s', sessionName, text], code, stdout, stderr)));
+                }
+                else {
+                    resolve({
+                        output,
+                        events,
+                        streamedAssistantText: false,
+                    });
+                }
+            });
+            proc.on('error', (err) => {
+                reject(new Error(`Failed to spawn acpx: ${err.message}. Is acpx installed?`));
+            });
+        });
+    }
+    /**
+     * Cancel the current operation in a session.
+     */
+    async cancel(agent, sessionName) {
+        await this.exec(agent, ['cancel', '-s', sessionName]);
+    }
+    /**
+     * Close a session.
+     */
+    async close(agent, sessionName) {
+        await this.exec(agent, ['sessions', 'close', sessionName]);
+    }
+    /**
+     * Execute an acpx command and return stdout.
+     */
+    exec(agent, args) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn('acpx', this.buildAcpxArgs(agent, args), {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                cwd: this.cwd,
+                env: this.buildSubprocessEnv(),
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            proc.on('close', (code) => {
+                if (code !== 0)
+                    reject(new Error(this.formatProcessFailure(agent, args, code, stdout, stderr)));
+                else
+                    resolve(stdout);
+            });
+            proc.on('error', (err) => {
+                reject(new Error(`Failed to spawn acpx: ${err.message}`));
+            });
+        });
+    }
+}
+//# sourceMappingURL=acpx-client.js.map