@hmharness/agent 0.14.16 → 0.14.17

package/dist/acp.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @hmharness/agent - ACP Server/Client (P2-01 + P2-02)
+ *
+ * The audit called for ACP (Agent Communication Protocol) making hmharness
+ * "可被 IDE/Agent 调用的标准工程 Runtime" and A2A for "外部 Agent 以
+ * task/plan/artifact/evidence 方式协作".
+ *
+ * This module provides:
+ * 1. AcpServer: exposes hmharness capabilities to external agents/IDEs
+ * 2. AcpClient: calls external agents from hmharness
+ * 3. Task/Plan/Artifact/Evidence message types for A2A collaboration
+ */
+export type AcpMessageType = 'task' | 'plan' | 'artifact' | 'evidence' | 'query' | 'response' | 'error';
+export interface AcpMessage {
+    id: string;
+    type: AcpMessageType;
+    from: string;
+    to: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+}
+export interface AcpTask {
+    description: string;
+    priority: 'low' | 'medium' | 'high' | 'critical';
+    deadline?: string;
+    constraints?: string[];
+}
+export interface AcpPlan {
+    steps: Array<{
+        id: string;
+        description: string;
+        status: 'pending' | 'running' | 'done' | 'failed';
+    }>;
+    estimatedDuration?: number;
+}
+export interface AcpArtifact {
+    kind: 'code' | 'document' | 'config' | 'test' | 'report';
+    path: string;
+    content: string;
+    hash?: string;
+}
+export interface AcpServerConfig {
+    /** server identity */
+    agentId: string;
+    /** capabilities this server exposes */
+    capabilities: string[];
+    /** how to reach this server */
+    endpoint: string;
+}
+export interface AcpClientConfig {
+    /** client identity */
+    agentId: string;
+    /** known servers */
+    servers: Map<string, AcpServerConfig>;
+}
+/**
+ * Create an ACP message.
+ * Pure - testable.
+ */
+export declare function createMessage(type: AcpMessageType, from: string, to: string, payload: Record<string, unknown>): AcpMessage;
+/**
+ * Validate an ACP message.
+ * Pure - testable.
+ */
+export declare function validateMessage(msg: unknown): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * ACP server handler registry - routes incoming messages to handlers.
+ */
+export declare class AcpServer {
+    readonly config: AcpServerConfig;
+    private handlers;
+    constructor(config: AcpServerConfig);
+    on(type: AcpMessageType, handler: (msg: AcpMessage) => Promise<AcpMessage>): void;
+    handle(msg: AcpMessage): Promise<AcpMessage>;
+    /** Advertise capabilities as a capability document */
+    capabilities(): Record<string, unknown>;
+}
+/**
+ * ACP client - sends messages to servers and awaits responses.
+ */
+export declare class AcpClient {
+    readonly config: AcpClientConfig;
+    constructor(config: AcpClientConfig);
+    send(to: string, type: AcpMessageType, payload: Record<string, unknown>): Promise<AcpMessage>;
+    /** Discover servers by capability */
+    discoverByCapability(capability: string): AcpServerConfig[];
+}

package/dist/acp.js

@@ -0,0 +1,97 @@
+/**
+ * @hmharness/agent - ACP Server/Client (P2-01 + P2-02)
+ *
+ * The audit called for ACP (Agent Communication Protocol) making hmharness
+ * "可被 IDE/Agent 调用的标准工程 Runtime" and A2A for "外部 Agent 以
+ * task/plan/artifact/evidence 方式协作".
+ *
+ * This module provides:
+ * 1. AcpServer: exposes hmharness capabilities to external agents/IDEs
+ * 2. AcpClient: calls external agents from hmharness
+ * 3. Task/Plan/Artifact/Evidence message types for A2A collaboration
+ */
+/**
+ * Create an ACP message.
+ * Pure - testable.
+ */
+export function createMessage(type, from, to, payload) {
+    return {
+        id: `msg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+        type, from, to,
+        timestamp: new Date().toISOString(),
+        payload,
+    };
+}
+/**
+ * Validate an ACP message.
+ * Pure - testable.
+ */
+export function validateMessage(msg) {
+    const errors = [];
+    const m = msg;
+    if (!m.id)
+        errors.push('missing id');
+    if (!m.type)
+        errors.push('missing type');
+    if (!m.from)
+        errors.push('missing from');
+    if (!m.to)
+        errors.push('missing to');
+    if (!m.timestamp)
+        errors.push('missing timestamp');
+    if (m.payload === undefined)
+        errors.push('missing payload');
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * ACP server handler registry - routes incoming messages to handlers.
+ */
+export class AcpServer {
+    config;
+    handlers = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    on(type, handler) {
+        this.handlers.set(type, handler);
+    }
+    async handle(msg) {
+        const handler = this.handlers.get(msg.type);
+        if (!handler) {
+            return createMessage('error', this.config.agentId, msg.from, { reason: `no handler for ${msg.type}` });
+        }
+        return handler(msg);
+    }
+    /** Advertise capabilities as a capability document */
+    capabilities() {
+        return {
+            agentId: this.config.agentId,
+            endpoint: this.config.endpoint,
+            capabilities: this.config.capabilities,
+            messageTypes: [...this.handlers.keys()],
+        };
+    }
+}
+/**
+ * ACP client - sends messages to servers and awaits responses.
+ */
+export class AcpClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async send(to, type, payload) {
+        const server = this.config.servers.get(to);
+        if (!server) {
+            throw new Error(`unknown server: ${to}`);
+        }
+        const msg = createMessage(type, this.config.agentId, to, payload);
+        // In a real implementation this would make an HTTP/WebSocket call
+        // For now, return the message as sent (for testing)
+        return msg;
+    }
+    /** Discover servers by capability */
+    discoverByCapability(capability) {
+        return [...this.config.servers.values()].filter(s => s.capabilities.includes(capability));
+    }
+}

package/dist/index.d.ts

@@ -7,3 +7,5 @@ export { strings, type Locale, type Strings } from './i18n.ts';
 export { makeSpawnTool, MAX_SPAWN_DEPTH, type SpawnBase } from './spawn.ts';
 export { buildRegistry, contextPack, makeApproval, nativeRegistry, runAgentTask, spawnBase, toServerConfig, type AgentTaskOptions, type RunnerEvents, } from './runner.ts';
 export * from './skills-conformance.ts';
+export * from './acp.ts';
+export * from './topology.ts';

package/dist/index.js

@@ -7,3 +7,5 @@ export { strings } from "./i18n.js";
 export { makeSpawnTool, MAX_SPAWN_DEPTH } from "./spawn.js";
 export { buildRegistry, contextPack, makeApproval, nativeRegistry, runAgentTask, spawnBase, toServerConfig, } from "./runner.js";
 export * from "./skills-conformance.js";
+export * from "./acp.js";
+export * from "./topology.js";

package/dist/topology.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @hmharness/agent - Dynamic Agent Topology (P2-03)
+ *
+ * The audit called for: "根据任务复杂度自动决定单 Agent、双 Agent 或完整 Team"
+ *
+ * Analyzes task characteristics and decides the optimal agent configuration.
+ */
+export type TopologyMode = 'single' | 'dual' | 'team' | 'pipeline';
+export interface TopologyDecision {
+    mode: TopologyMode;
+    /** roles to activate */
+    roles: string[];
+    /** confidence in this decision [0,1] */
+    confidence: number;
+    /** reasoning for the decision */
+    reason: string;
+    /** estimated complexity score [0,100] */
+    complexity: number;
+}
+export interface TaskCharacteristics {
+    /** word count of the task description */
+    wordCount: number;
+    /** number of distinct file types mentioned */
+    fileTypes: number;
+    /** whether the task mentions building/testing/deploying */
+    requiresBuild: boolean;
+    requiresTest: boolean;
+    requiresDeploy: boolean;
+    /** whether the task mentions multiple modules/services */
+    multiModule: boolean;
+    /** estimated number of steps from the task description */
+    estimatedSteps: number;
+    /** whether the task involves external APIs/services */
+    externalDependencies: boolean;
+}
+/**
+ * Compute a complexity score [0,100] from task characteristics.
+ * Pure - testable.
+ */
+export declare function complexityScore(c: TaskCharacteristics): number;
+/**
+ * Decide the optimal topology based on complexity.
+ * Pure - testable.
+ */
+export declare function decideTopology(c: TaskCharacteristics): TopologyDecision;
+/**
+ * Extract task characteristics from a natural language task description.
+ * Pure - testable.
+ */
+export declare function extractCharacteristics(taskDescription: string): TaskCharacteristics;

package/dist/topology.js

@@ -0,0 +1,117 @@
+/**
+ * @hmharness/agent - Dynamic Agent Topology (P2-03)
+ *
+ * The audit called for: "根据任务复杂度自动决定单 Agent、双 Agent 或完整 Team"
+ *
+ * Analyzes task characteristics and decides the optimal agent configuration.
+ */
+/**
+ * Compute a complexity score [0,100] from task characteristics.
+ * Pure - testable.
+ */
+export function complexityScore(c) {
+    let score = 0;
+    // word count: longer tasks are generally more complex (up to +20)
+    score += Math.min(20, c.wordCount / 5);
+    // file types: more types = more complexity (up to +15)
+    score += Math.min(15, c.fileTypes * 3);
+    // build/test/deploy requirements (+5 each, max +15)
+    if (c.requiresBuild)
+        score += 5;
+    if (c.requiresTest)
+        score += 5;
+    if (c.requiresDeploy)
+        score += 5;
+    // multi-module (+10)
+    if (c.multiModule)
+        score += 10;
+    // estimated steps (up to +25)
+    score += Math.min(25, c.estimatedSteps * 3);
+    // external deps (+15)
+    if (c.externalDependencies)
+        score += 15;
+    return Math.min(100, Math.round(score));
+}
+/**
+ * Decide the optimal topology based on complexity.
+ * Pure - testable.
+ */
+export function decideTopology(c) {
+    const complexity = complexityScore(c);
+    if (complexity < 20) {
+        return {
+            mode: 'single', roles: ['coder'],
+            confidence: 0.9,
+            reason: `low complexity (${complexity}/100) - single agent sufficient`,
+            complexity,
+        };
+    }
+    if (complexity < 45) {
+        return {
+            mode: 'dual', roles: ['coder', 'reviewer'],
+            confidence: 0.8,
+            reason: `medium complexity (${complexity}/100) - coder + reviewer pair`,
+            complexity,
+        };
+    }
+    if (complexity < 70) {
+        return {
+            mode: 'pipeline', roles: ['planner', 'coder', 'tester', 'judge'],
+            confidence: 0.75,
+            reason: `high complexity (${complexity}/100) - pipeline with review gate`,
+            complexity,
+        };
+    }
+    return {
+        mode: 'team', roles: ['planner', 'architect', 'coder', 'tester', 'reviewer', 'judge'],
+        confidence: 0.85,
+        reason: `very high complexity (${complexity}/100) - full team with architecture`,
+        complexity,
+    };
+}
+/**
+ * Extract task characteristics from a natural language task description.
+ * Pure - testable.
+ */
+export function extractCharacteristics(taskDescription) {
+    const words = taskDescription.split(/\s+/).filter(Boolean);
+    const lower = taskDescription.toLowerCase();
+    return {
+        wordCount: words.length,
+        fileTypes: countFileTypes(taskDescription),
+        requiresBuild: /build|compile|make|npm run/i.test(taskDescription),
+        requiresTest: /test|spec|verify|assert/i.test(taskDescription),
+        requiresDeploy: /deploy|install|publish|release/i.test(taskDescription),
+        multiModule: /module|service|package|component/i.test(lower) && (lower.match(/module|service|package|component/g) ?? []).length > 1,
+        estimatedSteps: countSteps(taskDescription),
+        externalDependencies: /api|http|url|fetch|request|external/i.test(lower),
+    };
+}
+function countFileTypes(text) {
+    const types = new Set();
+    const exts = text.match(/\.\w{1,5}\b/g) ?? [];
+    for (const e of exts)
+        types.add(e);
+    // also count mentioned languages
+    if (/typescript|\.ts\b/i.test(text))
+        types.add('.ts');
+    if (/javascript|\.js\b/i.test(text))
+        types.add('.js');
+    if (/python|\.py\b/i.test(text))
+        types.add('.py');
+    if (/json/i.test(text))
+        types.add('.json');
+    return types.size;
+}
+function countSteps(text) {
+    const stepPatterns = [
+        /first.*then/i, /step \d/i, /\d+\./, /after that/i, /next/i, /finally/i,
+        /then/i, /create.*write.*test/i, /read.*modify.*verify/i,
+    ];
+    let count = 1; // at least one step
+    for (const p of stepPatterns) {
+        if (p.test(text))
+            count++;
+    }
+    return Math.min(count, 10);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/agent",
-  "version": "0.14.16",
+  "version": "0.14.17",
   "description": "hmharness agent execution layer: base tools, system prompt, sub-agent spawn, and the shared task runner that frontends (cli, web) drive.",
   "type": "module",
   "main": "dist/index.js",