@zhijiewang/openharness 1.0.0 → 1.2.0

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

package/dist/services/a2a.js

@@ -0,0 +1,176 @@
+/**
+ * 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.
+ */
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const AGENT_REGISTRY_DIR = join(homedir(), '.oh', 'agents');
+// ── Registry Operations ──
+/** Publish an agent card to the shared registry */
+export function publishCard(card) {
+    mkdirSync(AGENT_REGISTRY_DIR, { recursive: true });
+    const filePath = join(AGENT_REGISTRY_DIR, `${card.id}.json`);
+    writeFileSync(filePath, JSON.stringify(card, null, 2));
+}
+/** Remove an agent card from the registry */
+export function unpublishCard(agentId) {
+    const filePath = join(AGENT_REGISTRY_DIR, `${agentId}.json`);
+    try {
+        unlinkSync(filePath);
+    }
+    catch { /* ignore */ }
+}
+/** Discover all registered agents */
+export function discoverAgents() {
+    if (!existsSync(AGENT_REGISTRY_DIR))
+        return [];
+    const cards = [];
+    for (const file of readdirSync(AGENT_REGISTRY_DIR).filter(f => f.endsWith('.json'))) {
+        try {
+            const raw = readFileSync(join(AGENT_REGISTRY_DIR, file), 'utf-8');
+            const card = JSON.parse(raw);
+            // Check if the agent process is still alive
+            if (isProcessAlive(card.pid)) {
+                cards.push(card);
+            }
+            else {
+                // Stale card — clean up
+                try {
+                    unlinkSync(join(AGENT_REGISTRY_DIR, file));
+                }
+                catch { /* ignore */ }
+            }
+        }
+        catch { /* skip malformed cards */ }
+    }
+    return cards;
+}
+/** Find agents by capability name */
+export function findAgentsByCapability(capabilityName) {
+    return discoverAgents().filter(card => card.capabilities.some(c => c.name.toLowerCase() === capabilityName.toLowerCase()));
+}
+/** Find an agent by name */
+export function findAgentByName(name) {
+    return discoverAgents().find(c => c.name.toLowerCase() === name.toLowerCase()) ?? null;
+}
+// ── Message Routing ──
+/**
+ * Route a message to an agent.
+ * For HTTP endpoints: sends via fetch.
+ * For IPC/stdio: writes to the agent's inbox file.
+ */
+export async function routeMessage(message) {
+    // Find the target agent
+    let targetCard = null;
+    // Try by agent ID first
+    const agents = discoverAgents();
+    targetCard = agents.find(a => a.id === message.to) ?? null;
+    // Try by name
+    if (!targetCard) {
+        targetCard = agents.find(a => a.name.toLowerCase() === message.to.toLowerCase()) ?? null;
+    }
+    // Try by capability
+    if (!targetCard && message.type === 'task' && message.payload.kind === 'task') {
+        const capable = findAgentsByCapability(message.payload.capability);
+        if (capable.length > 0)
+            targetCard = capable[0];
+    }
+    if (!targetCard)
+        return null;
+    // Route based on endpoint type
+    switch (targetCard.endpoint.type) {
+        case 'http': {
+            try {
+                const url = `${targetCard.endpoint.address}${targetCard.endpoint.port ? ':' + targetCard.endpoint.port : ''}/a2a`;
+                const res = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(message),
+                    signal: AbortSignal.timeout(30_000),
+                });
+                if (res.ok) {
+                    return await res.json();
+                }
+            }
+            catch { /* delivery failed */ }
+            return null;
+        }
+        case 'ipc': {
+            // File-based inbox for local IPC
+            const inboxDir = join(AGENT_REGISTRY_DIR, 'inboxes', targetCard.id);
+            mkdirSync(inboxDir, { recursive: true });
+            const msgFile = join(inboxDir, `${message.id}.json`);
+            writeFileSync(msgFile, JSON.stringify(message, null, 2));
+            return null; // Async — no immediate response
+        }
+        default:
+            return null;
+    }
+}
+/** Read pending messages from an agent's inbox */
+export function readInbox(agentId) {
+    const inboxDir = join(AGENT_REGISTRY_DIR, 'inboxes', agentId);
+    if (!existsSync(inboxDir))
+        return [];
+    const messages = [];
+    for (const file of readdirSync(inboxDir).filter(f => f.endsWith('.json'))) {
+        try {
+            const raw = readFileSync(join(inboxDir, file), 'utf-8');
+            messages.push(JSON.parse(raw));
+            // Remove after reading
+            unlinkSync(join(inboxDir, file));
+        }
+        catch { /* skip */ }
+    }
+    return messages.sort((a, b) => a.timestamp - b.timestamp);
+}
+// ── Helpers ──
+/** Check if a process is still alive */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = check existence only
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Generate a unique message ID */
+export function generateMessageId() {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+/** Create a standard agent card for the current openHarness session */
+export function createSessionCard(sessionId, opts = {}) {
+    return {
+        id: `oh-${sessionId}`,
+        name: `openharness-${sessionId.slice(0, 6)}`,
+        version: '1.0.0',
+        capabilities: [
+            { name: 'code-generation', description: 'Generate, edit, and review code' },
+            { name: 'code-review', description: 'Review code for bugs and quality' },
+            { name: 'test-generation', description: 'Write tests for existing code' },
+            { name: 'file-operations', description: 'Read, write, search files' },
+            { name: 'bash-execution', description: 'Run shell commands' },
+        ],
+        endpoint: opts.port
+            ? { type: 'http', address: 'http://localhost', port: opts.port }
+            : { type: 'ipc', address: join(AGENT_REGISTRY_DIR, 'inboxes', `oh-${sessionId}`) },
+        registeredAt: Date.now(),
+        pid: process.pid,
+        provider: opts.provider,
+        model: opts.model,
+        workingDir: process.cwd(),
+    };
+}
+//# sourceMappingURL=a2a.js.map

package/dist/tools/PipelineTool/index.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { Tool } from "../../Tool.js";
+declare const inputSchema: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodString;
+        args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        args: Record<string, unknown>;
+        id: string;
+        dependsOn?: string[] | undefined;
+    }, {
+        tool: string;
+        args: Record<string, unknown>;
+        id: string;
+        dependsOn?: string[] | undefined;
+    }>, "many">;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    steps: {
+        tool: string;
+        args: Record<string, unknown>;
+        id: string;
+        dependsOn?: string[] | undefined;
+    }[];
+    description?: string | undefined;
+}, {
+    steps: {
+        tool: string;
+        args: Record<string, unknown>;
+        id: string;
+        dependsOn?: string[] | undefined;
+    }[];
+    description?: string | undefined;
+}>;
+export declare const PipelineTool: Tool<typeof inputSchema>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/PipelineTool/index.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { PipelineExecutor, formatPipelineResults } from "../../services/PipelineExecutor.js";
+const stepSchema = z.object({
+    id: z.string().describe("Unique step identifier"),
+    tool: z.string().describe("Tool name to execute (Glob, Grep, Read, Bash, etc.)"),
+    args: z.record(z.unknown()).describe("Tool arguments. Use $stepId to reference output of a prior step."),
+    dependsOn: z.array(z.string()).optional().describe("Step IDs that must complete before this step runs"),
+});
+const inputSchema = z.object({
+    steps: z.array(stepSchema).min(1).describe("Pipeline steps to execute in dependency order"),
+    description: z.string().optional().describe("What this pipeline does"),
+});
+export const PipelineTool = {
+    name: "Pipeline",
+    description: "Execute a declarative multi-step tool pipeline. Steps run in dependency order with variable substitution.",
+    inputSchema,
+    riskLevel: "medium",
+    isReadOnly(input) {
+        // Pipeline is read-only only if ALL steps use read-only tools
+        // Conservative: assume not read-only
+        return false;
+    },
+    isConcurrencySafe() {
+        return false;
+    },
+    async call(input, context) {
+        if (!context.tools) {
+            return { output: "Pipeline unavailable: no tools in context.", isError: true };
+        }
+        const executor = new PipelineExecutor(context.tools, context);
+        const results = await executor.execute(input.steps);
+        const summary = formatPipelineResults(results);
+        const hasErrors = results.some(r => r.isError);
+        return { output: summary, isError: hasErrors };
+    },
+    prompt() {
+        return `Execute a declarative multi-step tool pipeline. Each step specifies a tool and its arguments, with optional dependencies on prior steps. Use $stepId in args to reference the output of a completed step.
+
+Example:
+{
+  "steps": [
+    { "id": "find", "tool": "Glob", "args": { "pattern": "src/**/*.ts" } },
+    { "id": "search", "tool": "Grep", "args": { "pattern": "TODO", "path": "$find" }, "dependsOn": ["find"] }
+  ],
+  "description": "Find all TODO comments in TypeScript files"
+}
+
+Parameters:
+- steps (array, required): Pipeline steps with id, tool, args, and optional dependsOn
+- description (string, optional): What this pipeline does`;
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/tools/WebFetchTool/index.js

@@ -95,8 +95,8 @@ export const WebFetchTool = {
         }
     },
     prompt() {
-        return `Fetch a URL and return its text content. Parameters:
-- url (string, required): The URL to fetch (http/https only).
+        return `Fetch a URL and return its text content. Parameters:
+- url (string, required): The URL to fetch (http/https only).
 HTML tags are stripped. Output is truncated at 50K characters. Private/internal hosts are blocked for security.`;
     },
 };

package/dist/tools.js

@@ -41,6 +41,7 @@ import { ExitWorktreeTool } from "./tools/ExitWorktreeTool/index.js";
 import { KillProcessTool } from "./tools/KillProcessTool/index.js";
 import { RemoteTriggerTool } from "./tools/RemoteTriggerTool/index.js";
 import { MultiEditTool } from "./tools/MultiEditTool/index.js";
+import { PipelineTool } from "./tools/PipelineTool/index.js";
 /**
  * Returns all registered tools.
  *
@@ -71,6 +72,8 @@ export function getAllTools() {
         ExitPlanModeTool,
         // Tool Discovery
         ToolSearchTool,
+        // Pipelines
+        PipelineTool,
         // Memory management
         MemoryTool,
     ];

package/package.json

@@ -1,73 +1,73 @@
-{
-  "name": "@zhijiewang/openharness",
-  "version": "1.0.0",
-  "description": "Open-source terminal coding agent. Works with any LLM.",
-  "type": "module",
-  "bin": {
-    "openharness": "./dist/main.js",
-    "oh": "./dist/main.js"
-  },
-  "main": "./dist/main.js",
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "!dist/**/*.test.*",
-    "!dist/**/test-helpers.*",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "dev": "tsx src/main.tsx",
-    "build": "tsc",
-    "prepare": "tsc",
-    "prepublishOnly": "npm run build",
-    "test": "node scripts/test.mjs",
-    "test:coverage": "node scripts/coverage.mjs",
-    "typecheck": "tsc --noEmit",
-    "start": "node dist/main.js"
-  },
-  "dependencies": {
-    "@types/marked": "^5.0.2",
-    "chalk": "^5.4.1",
-    "commander": "^13.0.0",
-    "ink": "^5.2.0",
-    "ink-spinner": "^5.0.0",
-    "ink-text-input": "^6.0.0",
-    "marked": "^17.0.5",
-    "react": "^18.3.1",
-    "yaml": "^2.7.0",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/react": "^18.3.0",
-    "c8": "^11.0.0",
-    "sharp": "^0.34.5",
-    "tsx": "^4.19.0",
-    "typescript": "^5.8.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "llm",
-    "cli",
-    "coding-agent",
-    "terminal",
-    "coding-assistant",
-    "ollama",
-    "openai",
-    "anthropic"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/zhijiewong/openharness"
-  },
-  "bugs": {
-    "url": "https://github.com/zhijiewong/openharness/issues"
-  },
-  "homepage": "https://github.com/zhijiewong/openharness#readme"
-}
+{
+  "name": "@zhijiewang/openharness",
+  "version": "1.2.0",
+  "description": "Open-source terminal coding agent. Works with any LLM.",
+  "type": "module",
+  "bin": {
+    "openharness": "./dist/main.js",
+    "oh": "./dist/main.js"
+  },
+  "main": "./dist/main.js",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.*",
+    "!dist/**/test-helpers.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/main.tsx",
+    "build": "tsc",
+    "prepare": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node scripts/test.mjs",
+    "test:coverage": "node scripts/coverage.mjs",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@types/marked": "^5.0.2",
+    "chalk": "^5.4.1",
+    "commander": "^13.0.0",
+    "ink": "^5.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "marked": "^17.0.5",
+    "react": "^18.3.1",
+    "yaml": "^2.7.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "c8": "^11.0.0",
+    "sharp": "^0.34.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "cli",
+    "coding-agent",
+    "terminal",
+    "coding-assistant",
+    "ollama",
+    "openai",
+    "anthropic"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhijiewong/openharness"
+  },
+  "bugs": {
+    "url": "https://github.com/zhijiewong/openharness/issues"
+  },
+  "homepage": "https://github.com/zhijiewong/openharness#readme"
+}