@zhijiewang/openharness 1.0.0 → 1.3.0

package/dist/remote/server.js

@@ -1,18 +1,24 @@
 /**
  * Remote server — HTTP + WebSocket server for remote agent dispatch,
- * bidirectional channels, and structured event streaming.
+ * bidirectional channels, A2A protocol, and structured event streaming.
  *
  * Endpoints:
- * - POST /dispatch  — send a prompt, get a streaming response
+ * - POST /dispatch  — send a prompt, get a streaming response (SSE)
+ * - POST /a2a       — A2A protocol: task delegation, discovery, status
  * - GET  /status    — check server status
  * - WS   /channel   — bidirectional WebSocket channel
+ *
+ * Security: bearer token auth, per-IP rate limiting, tool allowlists.
  */
 import { createServer } from 'node:http';
 import { WebSocketServer, WebSocket } from 'ws';
+import { authenticateRequest, filterRemoteTools } from './auth.js';
+import { createSessionCard, publishCard, unpublishCard, discoverAgents, generateMessageId, } from '../services/a2a.js';
 export class RemoteServer {
     config;
     channels = new Map();
     server = null;
+    agentCardId = null;
     constructor(config) {
         this.config = config;
     }
@@ -33,12 +39,27 @@ export class RemoteServer {
             });
             this.server.listen(this.config.port, () => {
                 process.stderr.write(`[remote] Server listening on http://localhost:${this.config.port}\n`);
-                process.stderr.write(`[remote] Endpoints: POST /dispatch, GET /status, WS /channel\n`);
+                process.stderr.write(`[remote] Endpoints: POST /dispatch, POST /a2a, GET /status, WS /channel\n`);
+                // Publish A2A agent card with HTTP endpoint
+                const sessionId = this.config.sessionId ?? Date.now().toString(36);
+                const card = createSessionCard(sessionId, {
+                    provider: this.config.provider.name,
+                    model: this.config.model,
+                    port: this.config.port,
+                });
+                publishCard(card);
+                this.agentCardId = card.id;
+                process.stderr.write(`[remote] A2A agent card published: ${card.id}\n`);
                 resolve();
             });
         });
     }
     stop() {
+        // Unpublish A2A card
+        if (this.agentCardId) {
+            unpublishCard(this.agentCardId);
+            this.agentCardId = null;
+        }
         for (const ch of this.channels.values()) {
             ch.abortController.abort();
             ch.ws.close();
@@ -50,12 +71,23 @@ export class RemoteServer {
         // CORS headers
         res.setHeader('Access-Control-Allow-Origin', '*');
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
             res.end();
             return;
         }
+        // Auth check (skip for /status which is a health check)
+        if (req.url !== '/status') {
+            const auth = authenticateRequest(req, res);
+            if (!auth.allowed) {
+                const status = auth.reason?.includes('Rate limit') ? 429 : 401;
+                res.writeHead(status, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: auth.reason, requestId: auth.requestId }));
+                return;
+            }
+        }
+        // ── GET /status ──
         if (req.url === '/status' && req.method === 'GET') {
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
@@ -63,50 +95,146 @@ export class RemoteServer {
                 provider: this.config.provider.name,
                 model: this.config.model,
                 channels: this.channels.size,
+                agentId: this.agentCardId,
             }));
             return;
         }
+        // ── POST /dispatch ──
         if (req.url === '/dispatch' && req.method === 'POST') {
-            const body = await readBody(req);
-            try {
-                const { prompt, maxTurns } = JSON.parse(body);
-                if (!prompt) {
-                    res.writeHead(400, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Missing "prompt" field' }));
+            await this.handleDispatch(req, res);
+            return;
+        }
+        // ── POST /a2a ──
+        if (req.url === '/a2a' && req.method === 'POST') {
+            await this.handleA2A(req, res);
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    }
+    async handleDispatch(req, res) {
+        const body = await readBody(req);
+        try {
+            const { prompt, maxTurns } = JSON.parse(body);
+            if (!prompt) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Missing "prompt" field' }));
+                return;
+            }
+            // Apply tool filtering for remote callers
+            const tools = filterRemoteTools(this.config.tools);
+            // Stream response as Server-Sent Events
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+            });
+            const { query } = await import('../query.js');
+            const config = {
+                provider: this.config.provider,
+                tools,
+                systemPrompt: this.config.systemPrompt,
+                permissionMode: this.config.permissionMode,
+                model: this.config.model,
+                maxTurns: maxTurns ?? 20,
+            };
+            for await (const event of query(prompt, config)) {
+                const data = JSON.stringify(event);
+                res.write(`data: ${data}\n\n`);
+            }
+            res.write('data: [DONE]\n\n');
+            res.end();
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+            }
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
+    }
+    /**
+     * A2A protocol handler — receives inter-agent messages.
+     *
+     * Supports:
+     * - task: delegate a task to this agent
+     * - discover: return this agent's capabilities
+     * - status: return current state
+     * - cancel: abort a running task
+     */
+    async handleA2A(req, res) {
+        const body = await readBody(req);
+        try {
+            const message = JSON.parse(body);
+            switch (message.payload.kind) {
+                case 'discover': {
+                    // Return our agent card
+                    const agents = discoverAgents();
+                    const self = agents.find(a => a.id === this.agentCardId);
+                    const response = {
+                        id: generateMessageId(),
+                        from: this.agentCardId ?? 'unknown',
+                        to: message.from,
+                        type: 'result',
+                        payload: { kind: 'result', taskId: message.id, output: self ?? { error: 'agent not found' } },
+                        timestamp: Date.now(),
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(response));
                     return;
                 }
-                // Stream response as Server-Sent Events
-                res.writeHead(200, {
-                    'Content-Type': 'text/event-stream',
-                    'Cache-Control': 'no-cache',
-                    'Connection': 'keep-alive',
-                });
-                const { query } = await import('../query.js');
-                const config = {
-                    provider: this.config.provider,
-                    tools: this.config.tools,
-                    systemPrompt: this.config.systemPrompt,
-                    permissionMode: this.config.permissionMode,
-                    model: this.config.model,
-                    maxTurns: maxTurns ?? 20,
-                };
-                for await (const event of query(prompt, config)) {
-                    const data = JSON.stringify(event);
-                    res.write(`data: ${data}\n\n`);
+                case 'task': {
+                    // Execute the task via query loop
+                    const tools = filterRemoteTools(this.config.tools);
+                    const { query } = await import('../query.js');
+                    const config = {
+                        provider: this.config.provider,
+                        tools,
+                        systemPrompt: `[A2A Task from agent ${message.from}]\n\n${this.config.systemPrompt}`,
+                        permissionMode: this.config.permissionMode,
+                        model: this.config.model,
+                        maxTurns: 10,
+                    };
+                    let output = '';
+                    for await (const event of query(String(message.payload.input), config)) {
+                        if (event.type === 'text_delta')
+                            output += event.content;
+                    }
+                    const response = {
+                        id: generateMessageId(),
+                        from: this.agentCardId ?? 'unknown',
+                        to: message.from,
+                        type: 'result',
+                        payload: { kind: 'result', taskId: message.id, output },
+                        timestamp: Date.now(),
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(response));
+                    return;
                 }
-                res.write('data: [DONE]\n\n');
-                res.end();
-            }
-            catch (err) {
-                if (!res.headersSent) {
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                case 'status': {
+                    const response = {
+                        id: generateMessageId(),
+                        from: this.agentCardId ?? 'unknown',
+                        to: message.from,
+                        type: 'status',
+                        payload: { kind: 'status', state: 'idle' },
+                        timestamp: Date.now(),
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(response));
+                    return;
+                }
+                default: {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: `Unknown A2A message kind: ${message.payload.kind}` }));
+                    return;
                 }
-                res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
             }
-            return;
         }
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'Not found' }));
+        catch (err) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
     }
     handleChannel(ws) {
         const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
@@ -119,10 +247,11 @@ export class RemoteServer {
             try {
                 const msg = JSON.parse(data.toString());
                 if (msg.type === 'dispatch') {
+                    const tools = filterRemoteTools(this.config.tools);
                     const { query } = await import('../query.js');
                     const config = {
                         provider: this.config.provider,
-                        tools: this.config.tools,
+                        tools,
                         systemPrompt: this.config.systemPrompt,
                         permissionMode: this.config.permissionMode,
                         model: this.config.model,

package/dist/repl.js

@@ -62,6 +62,13 @@ export async function startREPL(config) {
     const { CronExecutor } = await import('./services/CronExecutor.js');
     const cronExecutor = new CronExecutor(config.provider, config.tools, config.systemPrompt, config.permissionMode, config.model);
     cronExecutor.start();
+    // A2A: publish agent card for cross-process discovery
+    const { createSessionCard, publishCard, unpublishCard } = await import('./services/a2a.js');
+    const agentCard = createSessionCard(session.id, {
+        provider: config.provider.name,
+        model: config.model,
+    });
+    publishCard(agentCard);
     const cost = new CostTracker();
     let cachedConfig = readOhConfig();
     // Centralized state store — all REPL state lives here
@@ -923,6 +930,7 @@ export async function startREPL(config) {
         if (cleanedUp)
             return;
         cleanedUp = true;
+        unpublishCard(agentCard.id);
         cronExecutor.stop();
         renderer.stop();
         session.messages = messages;

package/dist/services/PipelineExecutor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * PipelineExecutor — declarative multi-step tool workflows.
+ *
+ * Executes a sequence of tool calls with dependency resolution and
+ * variable substitution. Steps can reference prior step outputs via $stepId.
+ *
+ * Unlike the LLM-mediated agent loop, pipelines are deterministic —
+ * faster, cheaper, and repeatable for known workflows.
+ *
+ * Reuses the dependency resolution pattern from AgentDispatcher.
+ */
+import type { Tools, ToolContext } from '../Tool.js';
+export type PipelineStep = {
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    dependsOn?: string[];
+};
+export type PipelineStepResult = {
+    stepId: string;
+    output: string;
+    isError: boolean;
+    durationMs: number;
+};
+export declare class PipelineExecutor {
+    private tools;
+    private context;
+    constructor(tools: Tools, context: ToolContext);
+    /**
+     * Execute a pipeline. Returns results for all steps.
+     * Steps with unmet dependencies (failed/skipped blockers) are skipped.
+     */
+    execute(steps: PipelineStep[]): Promise<PipelineStepResult[]>;
+    private isReady;
+    private hasFailedBlocker;
+    private executeStep;
+    /**
+     * Resolve $stepId references in args.
+     * If a string value starts with $, replace it with the output of that step.
+     * Supports nested objects and arrays.
+     */
+    private resolveArgs;
+}
+/**
+ * Format pipeline results as a readable summary.
+ */
+export declare function formatPipelineResults(results: PipelineStepResult[]): string;
+//# sourceMappingURL=PipelineExecutor.d.ts.map

package/dist/services/PipelineExecutor.js

@@ -0,0 +1,179 @@
+/**
+ * PipelineExecutor — declarative multi-step tool workflows.
+ *
+ * Executes a sequence of tool calls with dependency resolution and
+ * variable substitution. Steps can reference prior step outputs via $stepId.
+ *
+ * Unlike the LLM-mediated agent loop, pipelines are deterministic —
+ * faster, cheaper, and repeatable for known workflows.
+ *
+ * Reuses the dependency resolution pattern from AgentDispatcher.
+ */
+import { findToolByName } from '../Tool.js';
+// ── Executor ──
+export class PipelineExecutor {
+    tools;
+    context;
+    constructor(tools, context) {
+        this.tools = tools;
+        this.context = context;
+    }
+    /**
+     * Execute a pipeline. Returns results for all steps.
+     * Steps with unmet dependencies (failed/skipped blockers) are skipped.
+     */
+    async execute(steps) {
+        // Validate step IDs are unique
+        const ids = new Set(steps.map(s => s.id));
+        if (ids.size !== steps.length) {
+            return [{ stepId: 'pipeline', output: 'Error: duplicate step IDs', isError: true, durationMs: 0 }];
+        }
+        const internal = new Map();
+        for (const step of steps) {
+            internal.set(step.id, { ...step, status: 'pending' });
+        }
+        const results = [];
+        // Process steps in dependency order
+        while (true) {
+            const ready = [...internal.values()].filter(s => s.status === 'pending' && this.isReady(s, internal));
+            const running = [...internal.values()].filter(s => s.status === 'running');
+            if (ready.length === 0 && running.length === 0)
+                break;
+            // Execute ready steps (sequentially for safety — tools may have side effects)
+            for (const step of ready) {
+                step.status = 'running';
+                // Check if any blocker failed — skip this step
+                if (this.hasFailedBlocker(step, internal)) {
+                    step.status = 'skipped';
+                    const result = {
+                        stepId: step.id,
+                        output: 'Skipped: dependency failed',
+                        isError: true,
+                        durationMs: 0,
+                    };
+                    step.result = result;
+                    results.push(result);
+                    continue;
+                }
+                const result = await this.executeStep(step, internal);
+                step.result = result;
+                step.status = result.isError ? 'failed' : 'completed';
+                results.push(result);
+            }
+        }
+        return results;
+    }
+    isReady(step, all) {
+        if (!step.dependsOn || step.dependsOn.length === 0)
+            return true;
+        return step.dependsOn.every(id => {
+            const dep = all.get(id);
+            return dep && (dep.status === 'completed' || dep.status === 'failed' || dep.status === 'skipped');
+        });
+    }
+    hasFailedBlocker(step, all) {
+        if (!step.dependsOn)
+            return false;
+        return step.dependsOn.some(id => {
+            const dep = all.get(id);
+            return dep && (dep.status === 'failed' || dep.status === 'skipped');
+        });
+    }
+    async executeStep(step, all) {
+        const start = Date.now();
+        // Find the tool
+        const tool = findToolByName(this.tools, step.tool);
+        if (!tool) {
+            return {
+                stepId: step.id,
+                output: `Error: unknown tool '${step.tool}'`,
+                isError: true,
+                durationMs: Date.now() - start,
+            };
+        }
+        // Substitute $refs in args
+        const resolvedArgs = this.resolveArgs(step.args, all);
+        // Validate and execute
+        const parsed = tool.inputSchema.safeParse(resolvedArgs);
+        if (!parsed.success) {
+            return {
+                stepId: step.id,
+                output: `Validation error: ${parsed.error.message}`,
+                isError: true,
+                durationMs: Date.now() - start,
+            };
+        }
+        try {
+            const result = await tool.call(parsed.data, this.context);
+            return {
+                stepId: step.id,
+                output: result.output,
+                isError: result.isError,
+                durationMs: Date.now() - start,
+            };
+        }
+        catch (err) {
+            return {
+                stepId: step.id,
+                output: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                isError: true,
+                durationMs: Date.now() - start,
+            };
+        }
+    }
+    /**
+     * Resolve $stepId references in args.
+     * If a string value starts with $, replace it with the output of that step.
+     * Supports nested objects and arrays.
+     */
+    resolveArgs(args, all) {
+        const resolve = (value) => {
+            if (typeof value === 'string' && value.startsWith('$')) {
+                const refId = value.slice(1);
+                const refStep = all.get(refId);
+                if (refStep?.result && !refStep.result.isError) {
+                    return refStep.result.output;
+                }
+                return value; // Keep as-is if ref not found
+            }
+            if (Array.isArray(value))
+                return value.map(resolve);
+            if (value && typeof value === 'object') {
+                const resolved = {};
+                for (const [k, v] of Object.entries(value)) {
+                    resolved[k] = resolve(v);
+                }
+                return resolved;
+            }
+            return value;
+        };
+        return resolve(args);
+    }
+}
+/**
+ * Format pipeline results as a readable summary.
+ */
+export function formatPipelineResults(results) {
+    const lines = [];
+    let totalMs = 0;
+    for (const r of results) {
+        const status = r.isError ? '✗' : '✓';
+        const duration = r.durationMs > 0 ? ` (${r.durationMs}ms)` : '';
+        lines.push(`${status} Step "${r.stepId}"${duration}`);
+        // Show truncated output
+        const output = r.output.length > 200
+            ? r.output.slice(0, 200) + '...'
+            : r.output;
+        if (output) {
+            for (const line of output.split('\n').slice(0, 5)) {
+                lines.push(`  ${line}`);
+            }
+        }
+        lines.push('');
+        totalMs += r.durationMs;
+    }
+    const passed = results.filter(r => !r.isError).length;
+    lines.push(`Pipeline: ${passed}/${results.length} steps passed (${totalMs}ms total)`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=PipelineExecutor.js.map

package/dist/services/a2a.d.ts

@@ -0,0 +1,119 @@
+/**
+ * A2A Protocol — Agent-to-Agent discovery and routing.
+ *
+ * Enables agents running in separate processes (or machines) to:
+ * - Advertise their capabilities via Agent Cards
+ * - Discover other agents via a shared registry
+ * - Route messages to agents by name or capability
+ * - Delegate tasks with typed request/response
+ *
+ * Registry is file-based (~/.oh/agents/) for same-machine agents.
+ * Each running agent writes a card file on startup and removes it on exit.
+ *
+ * Based on the emerging A2A (Agent-to-Agent) protocol standard.
+ */
+export type AgentCard = {
+    /** Unique agent instance ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Agent version */
+    version: string;
+    /** What this agent can do */
+    capabilities: AgentCapability[];
+    /** How to reach this agent */
+    endpoint: AgentEndpoint;
+    /** When this card was published */
+    registeredAt: number;
+    /** PID of the agent process */
+    pid: number;
+    /** Provider and model info */
+    provider?: string;
+    model?: string;
+    /** Working directory */
+    workingDir?: string;
+};
+export type AgentCapability = {
+    /** Capability identifier (e.g., 'code-review', 'test-generation') */
+    name: string;
+    /** Human description */
+    description: string;
+    /** Input schema (JSON Schema format) */
+    inputSchema?: Record<string, unknown>;
+    /** Output schema */
+    outputSchema?: Record<string, unknown>;
+};
+export type AgentEndpoint = {
+    /** Transport type */
+    type: 'http' | 'ipc' | 'stdio';
+    /** Address (URL for http, socket path for ipc, pid for stdio) */
+    address: string;
+    /** Port for HTTP transport */
+    port?: number;
+};
+export type A2AMessage = {
+    /** Message ID */
+    id: string;
+    /** Source agent ID */
+    from: string;
+    /** Target agent ID or capability name */
+    to: string;
+    /** Message type */
+    type: 'task' | 'result' | 'status' | 'cancel' | 'discover';
+    /** Payload */
+    payload: A2APayload;
+    /** Timestamp */
+    timestamp: number;
+};
+export type A2APayload = {
+    kind: 'task';
+    capability: string;
+    input: unknown;
+    timeout?: number;
+} | {
+    kind: 'result';
+    taskId: string;
+    output: unknown;
+    error?: string;
+} | {
+    kind: 'status';
+    state: 'idle' | 'working' | 'done' | 'error';
+    progress?: string;
+} | {
+    kind: 'cancel';
+    taskId: string;
+    reason?: string;
+} | {
+    kind: 'discover';
+    filter?: {
+        capability?: string;
+        name?: string;
+    };
+};
+/** Publish an agent card to the shared registry */
+export declare function publishCard(card: AgentCard): void;
+/** Remove an agent card from the registry */
+export declare function unpublishCard(agentId: string): void;
+/** Discover all registered agents */
+export declare function discoverAgents(): AgentCard[];
+/** Find agents by capability name */
+export declare function findAgentsByCapability(capabilityName: string): AgentCard[];
+/** Find an agent by name */
+export declare function findAgentByName(name: string): AgentCard | null;
+/**
+ * Route a message to an agent.
+ * For HTTP endpoints: sends via fetch.
+ * For IPC/stdio: writes to the agent's inbox file.
+ */
+export declare function routeMessage(message: A2AMessage): Promise<A2AMessage | null>;
+/** Read pending messages from an agent's inbox */
+export declare function readInbox(agentId: string): A2AMessage[];
+/** Generate a unique message ID */
+export declare function generateMessageId(): string;
+/** Create a standard agent card for the current openHarness session */
+export declare function createSessionCard(sessionId: string, opts?: {
+    provider?: string;
+    model?: string;
+    port?: number;
+}): AgentCard;
+//# sourceMappingURL=a2a.d.ts.map