@zengxingyuan/aamp-cli-bridge 0.1.7-dev.2 → 0.1.7-dev.4

package/README.md

@@ -76,6 +76,33 @@ npx aamp-cli-bridge start --config ./production.cli-bridge.json
 npx aamp-cli-bridge list --config ./production.cli-bridge.json
 ```
 
+Desktop and other non-interactive clients can use JSON output:
+
+```bash
+npx aamp-cli-bridge init --json --input -
+npx aamp-cli-bridge discover --json
+npx aamp-cli-bridge list --json
+npx aamp-cli-bridge start --json
+npx aamp-cli-bridge pair --agent codex --json --no-start
+```
+
+`init --json` is an upsert operation for desktop clients: it writes the bridge config, reuses existing credentials when available, registers missing mailboxes, and does not auto-start the bridge. `discover --json` scans built-in profiles, user profiles, and already configured agents, then reports which commands are available on PATH. `start --json` emits JSONL runtime events on stdout and sends human-readable logs to stderr. `pair --json --no-start` creates a pairing URL without rendering a terminal QR code.
+
+Example JSON init input:
+
+```json
+{
+  "aampHost": "https://meshmail.ai",
+  "agents": [
+    {
+      "name": "codex",
+      "cliProfile": "codex",
+      "createPairing": true
+    }
+  ]
+}
+```
+
 ## Profile Model
 
 A CLI profile describes how to invoke an agent and how to interpret its output.
@@ -211,10 +238,10 @@ NDJSON stream:
 The parser accepts common event shapes used by CLI agents:
 
 - `text`, `delta`, `text.delta`: forwarded to AAMP as `text.delta`
-- `tool_start`, `tool_result`, `tool`: forwarded as stream progress or status events
-- `usage`: forwarded as a progress event
+- `tool_start`, `tool_result`, `tool`: forwarded to AAMP as `tool_call`
+- `usage`: forwarded as a `todo` update
 - `result`: used as final text when present
-- `done`: closes the stream state for the current task
+- `done`: ends parser consumption; terminal state is sent through `task.result`
 
 Text deltas are streamed to AAMP and concatenated into the final `task.result`. This lets a mailbox UI show live output while still preserving a complete final answer in the thread.
 
@@ -314,9 +341,11 @@ The CLI agent can use these plain-output conventions:
 
 ```bash
 npx aamp-cli-bridge init [--no-start]
-npx aamp-cli-bridge start [--config X]
+npx aamp-cli-bridge init --json --input -
+npx aamp-cli-bridge start [--config X] [--json]
 npx aamp-cli-bridge pair --agent NAME [--config X] [--no-start]
 npx aamp-cli-bridge list [--config X]
+npx aamp-cli-bridge discover [--config X] [--json]
 npx aamp-cli-bridge status
 npx aamp-cli-bridge profile-list
 npx aamp-cli-bridge profile-maker

package/dist/agent-bridge.d.ts

@@ -1,4 +1,5 @@
 import type { AgentConfig, BridgeConfig } from './config.js';
+import type { BridgeRuntimeEvent } from './bridge.js';
 export interface AgentIdentity {
     email: string;
     mailboxToken: string;
@@ -6,6 +7,7 @@ export interface AgentIdentity {
 }
 export interface AgentBridgeStartOptions {
     quiet?: boolean;
+    onEvent?: (event: BridgeRuntimeEvent) => void;
 }
 export declare class AgentBridge {
     private readonly agentConfig;
@@ -17,16 +19,19 @@ export declare class AgentBridge {
     private activeTaskCount;
     private pollingFallback;
     private cancelledTaskIds;
+    private activeTaskIds;
     private profileLabel;
     private streamEnabled;
     private senderPolicies;
     private isHistoricalReconcile;
+    private onEvent;
     constructor(agentConfig: AgentConfig, aampHost: string, rejectUnauthorized: boolean, customProfiles?: BridgeConfig['profiles']);
     get name(): string;
     get email(): string;
     get isConnected(): boolean;
     get isUsingPollingFallback(): boolean;
     get isBusy(): boolean;
+    private emit;
     private getConfiguredCardText;
     private syncDirectoryProfile;
     start(options?: AgentBridgeStartOptions): Promise<void>;

package/dist/agent-bridge.js

@@ -1,10 +1,10 @@
 import { AampClient, } from 'aamp-sdk';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { CliAgentClient } from './cli-agent-client.js';
 import { resolveCliProfile } from './cli-profiles.js';
 import { buildPrompt, parseResponse } from './prompt-builder.js';
-import { resolveCredentialsFile } from './storage.js';
+import { getBridgeHomeDir, resolveCredentialsFile } from './storage.js';
 import { addSenderPolicy, consumePairingCode, loadSenderPolicies, resolvePairingFile, resolveSenderPoliciesFile, rulesMatch, validatePairingCode, } from './pairing.js';
 const IDENTITY_AUTH_RETRY_COUNT = 5;
 const IDENTITY_AUTH_RETRY_DELAY_MS = 1_000;
@@ -12,7 +12,7 @@ function matchSenderPolicy(task, senderPolicies) {
     if (!senderPolicies?.length)
         return { allowed: false, reason: 'no configured senderPolicies' };
     const sender = task.from.toLowerCase();
-    const policy = senderPolicies.find((item) => item.sender.trim().toLowerCase() === sender);
+    const policy = senderPolicies.find((item) => matchesSenderPattern(sender, item.sender));
     if (!policy) {
         return { allowed: false, reason: `sender ${task.from} is not allowed by senderPolicies` };
     }
@@ -32,6 +32,17 @@ function matchSenderPolicy(task, senderPolicies) {
     }
     return { allowed: true };
 }
+function matchesSenderPattern(senderEmail, pattern) {
+    const normalizedSender = senderEmail.trim().toLowerCase();
+    const normalizedPattern = pattern.trim().toLowerCase();
+    if (!normalizedSender || !normalizedPattern)
+        return false;
+    const canonicalPattern = normalizedPattern.startsWith('@')
+        ? `*${normalizedPattern}`
+        : normalizedPattern;
+    const escaped = canonicalPattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`, 'i').test(normalizedSender);
+}
 function matchPairedSenderPolicy(task, senderPolicies) {
     if (senderPolicies.length === 0)
         return { allowed: false, reason: 'no paired sender policies configured' };
@@ -132,6 +143,39 @@ function stringifyStreamPayload(payload) {
         return payload.chunk;
     return JSON.stringify(payload, null, 2);
 }
+function taskLockName(taskId) {
+    return taskId
+        .trim()
+        .replace(/[^a-zA-Z0-9_.-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 128) || 'task';
+}
+function acquireTaskExecutionLock(taskId) {
+    const locksDir = join(getBridgeHomeDir(), 'task-locks');
+    const lockDir = join(locksDir, `${taskLockName(taskId)}.lock`);
+    mkdirSync(locksDir, { recursive: true });
+    try {
+        mkdirSync(lockDir);
+        writeFileSync(join(lockDir, 'owner.json'), `${JSON.stringify({
+            pid: process.pid,
+            taskId,
+            acquiredAt: new Date().toISOString(),
+        }, null, 2)}\n`);
+        return lockDir;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'EEXIST')
+            return null;
+        throw error;
+    }
+}
+function releaseTaskExecutionLock(lockDir) {
+    if (!lockDir)
+        return;
+    rmSync(lockDir, { recursive: true, force: true });
+}
 export class AgentBridge {
     agentConfig;
     aampHost;
@@ -142,10 +186,12 @@ export class AgentBridge {
     activeTaskCount = 0;
     pollingFallback = false;
     cancelledTaskIds = new Set();
+    activeTaskIds = new Set();
     profileLabel;
     streamEnabled;
     senderPolicies = [];
     isHistoricalReconcile = false;
+    onEvent;
     constructor(agentConfig, aampHost, rejectUnauthorized, customProfiles) {
         this.agentConfig = agentConfig;
         this.aampHost = aampHost;
@@ -160,6 +206,9 @@ export class AgentBridge {
     get isConnected() { return this.client?.isConnected() ?? false; }
     get isUsingPollingFallback() { return this.pollingFallback || (this.client?.isUsingPollingFallback() ?? false); }
     get isBusy() { return this.activeTaskCount > 0; }
+    emit(event) {
+        this.onEvent?.(event);
+    }
     getConfiguredCardText() {
         const inline = this.agentConfig.cardText?.trim();
         if (inline)
@@ -186,6 +235,7 @@ export class AgentBridge {
         }
     }
     async start(options = {}) {
+        this.onEvent = options.onEvent;
         let quietStartup = options.quiet === true;
         this.identity = await this.resolveIdentity();
         this.senderPolicies = loadSenderPolicies(resolveSenderPoliciesFile(this.agentConfig.senderPoliciesFile, this.agentConfig.name));
@@ -193,6 +243,13 @@ export class AgentBridge {
             console.log(`[${this.name}] AAMP identity: ${this.identity.email}`);
             console.log(`[${this.name}] CLI profile: ${this.profileLabel}`);
         }
+        this.emit({
+            type: 'agent.identity',
+            bridge: 'cli-bridge',
+            agent: this.name,
+            email: this.identity.email,
+            profile: this.profileLabel,
+        });
         this.client = AampClient.fromMailboxIdentity({
             email: this.identity.email,
             smtpPassword: this.identity.smtpPassword,
@@ -218,12 +275,27 @@ export class AgentBridge {
         });
         client.on('connected', () => {
             this.pollingFallback = client.isUsingPollingFallback();
+            this.emit({
+                type: 'agent.connected',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                pollingFallback: this.pollingFallback,
+            });
             if (!quietStartup) {
                 console.log(`[${this.name}] AAMP connected${this.pollingFallback ? ' (polling fallback)' : ''}`);
             }
         });
         client.on('disconnected', (reason) => {
             this.pollingFallback = client.isUsingPollingFallback();
+            this.emit({
+                type: 'agent.disconnected',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                reason,
+                pollingFallback: this.pollingFallback,
+            });
             if (!quietStartup) {
                 console.warn(`[${this.name}] AAMP disconnected: ${reason}`);
             }
@@ -231,11 +303,25 @@ export class AgentBridge {
         client.on('error', (err) => {
             if (err.message.includes('falling back to polling')) {
                 this.pollingFallback = true;
+                this.emit({
+                    type: 'agent.error',
+                    bridge: 'cli-bridge',
+                    agent: this.name,
+                    email: this.email,
+                    message: err.message,
+                });
                 if (!quietStartup) {
                     console.warn(`[${this.name}] ${err.message}`);
                 }
                 return;
             }
+            this.emit({
+                type: 'agent.error',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                message: err.message,
+            });
             console.error(`[${this.name}] AAMP error: ${err.message}`);
         });
         await client.connect();
@@ -253,6 +339,13 @@ export class AgentBridge {
         if (!quietStartup) {
             console.log(`[${this.name}] Reconciled ${reconciled} recent email(s)`);
         }
+        this.emit({
+            type: 'agent.reconciled',
+            bridge: 'cli-bridge',
+            agent: this.name,
+            email: this.email,
+            count: reconciled,
+        });
         await this.syncDirectoryProfile({ quiet: quietStartup }).catch((err) => {
             if (!quietStartup) {
                 console.warn(`[${this.name}] Directory profile sync failed: ${err.message}`);
@@ -270,6 +363,15 @@ export class AgentBridge {
         const shouldLogTask = !options.historical;
         if (shouldLogTask) {
             console.log(`[${this.name}] <- task.dispatch  ${task.taskId}  "${task.title}"  from=${task.from}`);
+            this.emit({
+                type: 'task.received',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: task.taskId,
+                title: task.title,
+                from: task.from,
+            });
         }
         if (task.expiresAt && new Date(task.expiresAt).getTime() <= Date.now()) {
             console.warn(`[${this.name}] Skipping expired task ${task.taskId}`);
@@ -279,6 +381,10 @@ export class AgentBridge {
             console.warn(`[${this.name}] Ignoring cancelled task ${task.taskId}`);
             return;
         }
+        if (this.activeTaskIds.has(task.taskId)) {
+            console.warn(`[${this.name}] Ignoring duplicate active task ${task.taskId}`);
+            return;
+        }
         const hydratedTask = await this.client.hydrateTaskDispatch(task).catch((err) => {
             if (!options.historical) {
                 console.warn(`[${this.name}] Failed to load thread history for ${task.taskId}: ${err.message}`);
@@ -305,6 +411,14 @@ export class AgentBridge {
             if (options.historical)
                 return;
             console.warn(`[${this.name}] Rejecting task ${task.taskId}: ${senderDecision.reason ?? 'sender policy rejected the task'}`);
+            this.emit({
+                type: 'task.rejected',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: task.taskId,
+                reason: senderDecision.reason ?? 'sender policy rejected the task',
+            });
             await this.client.sendResult({
                 to: task.from,
                 taskId: task.taskId,
@@ -315,6 +429,12 @@ export class AgentBridge {
             });
             return;
         }
+        const taskLockDir = acquireTaskExecutionLock(task.taskId);
+        if (!taskLockDir) {
+            console.warn(`[${this.name}] Ignoring duplicate locked task ${task.taskId}`);
+            return;
+        }
+        this.activeTaskIds.add(task.taskId);
         this.activeTaskCount += 1;
         let activeStream = null;
         let streamOpenedAt = null;
@@ -328,7 +448,7 @@ export class AgentBridge {
             let write;
             write = this.client.appendStreamEvent({
                 streamId,
-                type,
+                type: type,
                 payload,
             })
                 .then(() => undefined)
@@ -351,7 +471,6 @@ export class AgentBridge {
             if (update.textDelta) {
                 queueStreamAppend('text.delta', {
                     text: update.textDelta,
-                    channel: 'assistant',
                     sourceEvent: eventType,
                 });
                 return;
@@ -359,16 +478,14 @@ export class AgentBridge {
             if (update.finalText) {
                 queueStreamAppend('text.delta', {
                     text: update.finalText,
-                    channel: 'assistant',
                     sourceEvent: eventType,
                 });
                 return;
             }
             if (eventType === 'session') {
-                queueStreamAppend('status', {
-                    state: 'running',
-                    label: 'CLI session started',
-                    data,
+                queueStreamAppend('todo', {
+                    items: [{ id: 'cli-session', content: 'CLI session started', status: 'in_progress' }],
+                    summary: 'CLI session started',
                 });
                 return;
             }
@@ -376,10 +493,13 @@ export class AgentBridge {
                 const record = data && typeof data === 'object' && !Array.isArray(data)
                     ? data
                     : {};
-                queueStreamAppend('progress', {
+                const name = typeof record.name === 'string' ? record.name : 'tool';
+                const toolCallId = String(record.toolCallId ?? record.tool_call_id ?? record.call_id ?? record.id ?? name);
+                queueStreamAppend('tool_call', {
+                    toolCallId,
                     label: `Tool running: ${typeof record.name === 'string' ? record.name : 'tool'}`,
-                    status: 'in_progress',
-                    ...record,
+                    status: 'running',
+                    input: stringifyStreamPayload(record),
                 });
                 return;
             }
@@ -388,10 +508,13 @@ export class AgentBridge {
                     ? data
                     : {};
                 const failed = record.is_error === true || record.status === 'failed';
-                queueStreamAppend('progress', {
+                const name = typeof record.name === 'string' ? record.name : 'tool';
+                const toolCallId = String(record.toolCallId ?? record.tool_call_id ?? record.call_id ?? record.id ?? name);
+                queueStreamAppend('tool_call', {
+                    toolCallId,
                     label: `Tool ${failed ? 'failed' : 'completed'}: ${typeof record.name === 'string' ? record.name : 'tool'}`,
                     status: failed ? 'failed' : 'completed',
-                    ...record,
+                    output: stringifyStreamPayload(record),
                 });
                 return;
             }
@@ -400,28 +523,27 @@ export class AgentBridge {
                     ? data
                     : {};
                 const chunk = typeof record.chunk === 'string' ? record.chunk : undefined;
-                queueStreamAppend('progress', {
+                const name = typeof record.name === 'string' ? record.name : 'tool';
+                const toolCallId = String(record.toolCallId ?? record.tool_call_id ?? record.call_id ?? record.id ?? name);
+                queueStreamAppend('tool_call', {
+                    toolCallId,
                     label: 'Tool output',
-                    status: 'in_progress',
-                    ...record,
-                    ...(chunk ? { chunk } : {}),
+                    status: 'running',
+                    output: chunk ? chunk : stringifyStreamPayload(record),
                 });
                 return;
             }
             if (eventType === 'usage') {
-                queueStreamAppend('progress', {
-                    label: 'Token usage updated',
-                    ...(data && typeof data === 'object' && !Array.isArray(data)
-                        ? data
-                        : { data }),
+                queueStreamAppend('todo', {
+                    items: [{ id: 'token-usage', content: 'Token usage updated', status: 'in_progress' }],
+                    summary: 'Token usage updated',
                 });
                 return;
             }
             if (eventType === 'done') {
-                queueStreamAppend('status', {
-                    state: 'running',
-                    label: 'CLI stream completed',
-                    data,
+                queueStreamAppend('todo', {
+                    items: [{ id: 'cli-stream', content: 'CLI stream completed', status: 'completed' }],
+                    summary: 'CLI stream completed',
                 });
             }
         };
@@ -440,7 +562,10 @@ export class AgentBridge {
                         streamId: activeStream.streamId,
                         inReplyTo: task.messageId,
                     });
-                    queueStreamAppend('status', { state: 'running', label: 'CLI task started' });
+                    queueStreamAppend('todo', {
+                        items: [{ id: 'cli-task', content: 'CLI task started', status: 'in_progress' }],
+                        summary: 'CLI task started',
+                    });
                 }
                 catch (err) {
                     activeStream = null;
@@ -482,6 +607,14 @@ export class AgentBridge {
                     inReplyTo: task.messageId,
                 });
                 console.log(`[${this.name}] -> task.help_needed  ${task.taskId}`);
+                this.emit({
+                    type: 'task.completed',
+                    bridge: 'cli-bridge',
+                    agent: this.name,
+                    email: this.email,
+                    taskId: task.taskId,
+                    status: 'help_needed',
+                });
                 return;
             }
             const attachments = [];
@@ -522,6 +655,14 @@ export class AgentBridge {
                 attachments: attachments.length > 0 ? attachments : undefined,
             });
             console.log(`[${this.name}] -> task.result  ${task.taskId}  completed${structuredResult?.length ? ` (${structuredResult.length} structured field(s))` : ''}${attachments.length ? ` (${attachments.length} attachment(s))` : ''}`);
+            this.emit({
+                type: 'task.completed',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: task.taskId,
+                status: 'completed',
+            });
         }
         catch (err) {
             const errorMsg = err.message;
@@ -546,9 +687,19 @@ export class AgentBridge {
                 errorMsg: `CLI agent error: ${errorMsg}`,
                 inReplyTo: task.messageId,
             }).catch(() => { });
+            this.emit({
+                type: 'task.completed',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: task.taskId,
+                status: 'rejected',
+            });
         }
         finally {
             this.activeTaskCount = Math.max(0, this.activeTaskCount - 1);
+            this.activeTaskIds.delete(task.taskId);
+            releaseTaskExecutionLock(taskLockDir);
         }
     }
     normalizeEmail(email) {
@@ -585,6 +736,14 @@ export class AgentBridge {
         const shouldLogRequest = !options.historical;
         if (shouldLogRequest) {
             console.log(`[${this.name}] <- pair.request  ${request.taskId}  from=${request.from}`);
+            this.emit({
+                type: 'pair.request',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: request.taskId,
+                from: request.from,
+            });
         }
         const requestTo = this.normalizeEmail(request.to);
         if (requestTo && requestTo !== this.normalizeEmail(this.identity.email)) {
@@ -624,6 +783,16 @@ export class AgentBridge {
             }
             console.warn(`[${this.name}] Rejected pair.request from ${request.from}: ${reason}`);
             await this.sendPairResponse(request, false, reason);
+            this.emit({
+                type: 'pair.completed',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: request.taskId,
+                sender: request.from,
+                success: false,
+                reason,
+            });
             return;
         }
         this.senderPolicies = addSenderPolicy(senderPoliciesFile, {
@@ -633,6 +802,15 @@ export class AgentBridge {
         });
         console.log(`[${this.name}] Paired sender ${request.from}; sender policy saved to ${senderPoliciesFile}`);
         if (await this.sendPairResponse(request, true)) {
+            this.emit({
+                type: 'pair.completed',
+                bridge: 'cli-bridge',
+                agent: this.name,
+                email: this.email,
+                taskId: request.taskId,
+                sender: request.from,
+                success: true,
+            });
             consumePairingCode(pairParams);
         }
         else {