va-agent-protocol 0.1.0

package/bin/va-orchestrate.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+/**
+ * va-orchestrate — CLI entry point for va-agent-protocol orchestrator.
+ *
+ * Usage:
+ *   va-orchestrate dispatch --task <task.json>   Dispatch a task from JSON file
+ *   va-orchestrate status                        Show active task status
+ *   va-orchestrate agents                        List registered agents
+ *
+ * This is a minimal CLI skeleton for v0.1.
+ * The primary interface is the TypeScript API.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const [, , command, ...rest] = process.argv;
+
+function usage() {
+  console.log(`va-orchestrate — Universal Agent Task Protocol Orchestrator
+
+Usage:
+  va-orchestrate dispatch --task <task.json>   Dispatch a task
+  va-orchestrate status                        Show running tasks
+  va-orchestrate agents                        List registered agents
+  va-orchestrate --help                        Show this help
+
+Protocol: va-agent-protocol v0.1.0`);
+}
+
+function parseArgs(args) {
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--") && i + 1 < args.length) {
+      opts[args[i].slice(2)] = args[i + 1];
+      i++;
+    }
+  }
+  return opts;
+}
+
+async function main() {
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    process.exit(0);
+  }
+
+  // Dynamic import to support ESM build output
+  const {
+    AgentRegistry,
+    Orchestrator,
+    VaAutoPilotAdapter,
+  } = await import("../dist/index.js");
+
+  switch (command) {
+    case "dispatch": {
+      const opts = parseArgs(rest);
+      if (!opts.task) {
+        console.error("Error: --task <file.json> is required");
+        process.exit(1);
+      }
+
+      const taskPath = resolve(opts.task);
+      const task = JSON.parse(readFileSync(taskPath, "utf-8"));
+
+      const registry = new AgentRegistry();
+
+      // Auto-register va-auto-pilot if in a va-auto-pilot project
+      if (opts["project-root"]) {
+        const adapter = new VaAutoPilotAdapter({
+          projectRoot: resolve(opts["project-root"]),
+        });
+        registry.register(adapter);
+      }
+
+      const orchestrator = new Orchestrator(registry, {
+        onCompleted: (taskId, evidence) => {
+          console.log(`\nCompleted: ${taskId}`);
+          console.log(JSON.stringify(evidence, null, 2));
+          orchestrator.stop();
+        },
+        onFailed: (taskId, evidence) => {
+          console.error(`\nFailed: ${taskId}`);
+          console.error(JSON.stringify(evidence, null, 2));
+          orchestrator.stop();
+          process.exit(1);
+        },
+        onBlocked: (taskId, reason) => {
+          console.log(`\nBlocked: ${taskId} — ${reason}`);
+        },
+      });
+
+      const correlationId = await orchestrator.dispatchNow(task);
+      if (!correlationId) {
+        console.error("Failed to dispatch task. No capable agent found.");
+        process.exit(1);
+      }
+
+      console.log(`Dispatched: ${task.id} → correlation: ${correlationId}`);
+      console.log("Polling for completion...\n");
+      orchestrator.start();
+      break;
+    }
+
+    case "agents": {
+      const registry = new AgentRegistry();
+
+      // Register known adapters for discovery
+      if (rest.includes("--project-root")) {
+        const idx = rest.indexOf("--project-root");
+        const adapter = new VaAutoPilotAdapter({
+          projectRoot: resolve(rest[idx + 1]),
+        });
+        registry.register(adapter);
+      }
+
+      const agents = registry.list();
+      if (agents.length === 0) {
+        console.log("No agents registered. Use --project-root to auto-detect va-auto-pilot.");
+        break;
+      }
+
+      for (const agent of agents) {
+        const cap = agent.capability;
+        console.log(`${cap.agentId}`);
+        console.log(`  Name:         ${cap.name} v${cap.version}`);
+        console.log(`  Capabilities: ${cap.capabilities.join(", ")}`);
+        console.log(`  Model:        ${cap.modelRequirement ?? "any"}`);
+        console.log(`  Interface:    ${cap.interface.type} — ${cap.interface.command}`);
+        console.log(`  Concurrency:  ${cap.constraints?.maxConcurrent ?? 1}`);
+        console.log();
+      }
+      break;
+    }
+
+    case "status": {
+      console.log("Status tracking requires a running orchestrator instance.");
+      console.log("Use the TypeScript API for persistent orchestration.");
+      break;
+    }
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      usage();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/adapter/agent-adapter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * AgentAdapter — the universal interface that any CLI agent must implement.
+ *
+ * This is the "USB plug shape". If your agent can implement these methods,
+ * the orchestrator can dispatch tasks to it.
+ *
+ * Design principles:
+ * - CLI-first: adapters invoke agents via subprocess, not library import
+ * - Evidence-based: completion requires proof, not self-certification
+ * - Polling model (v0.1): orchestrator polls for progress. Future versions
+ *   may add push/streaming via stdio or webhooks.
+ */
+import type { AgentCapability, TaskUnit, Evidence, ProgressPayload, TaskState } from "../types/index.js";
+export interface DispatchResult {
+    correlationId: string;
+    accepted: boolean;
+    reason?: string;
+}
+export interface PollResult {
+    correlationId: string;
+    state: TaskState;
+    progress?: ProgressPayload;
+    evidence?: Evidence;
+}
+/**
+ * Abstract adapter interface. Implement this to wrap any CLI agent.
+ */
+export interface AgentAdapter {
+    /** Unique identifier for this adapter instance. */
+    readonly id: string;
+    /** Declare what this agent can do. */
+    capabilities(): AgentCapability;
+    /**
+     * Dispatch a task to this agent.
+     * Returns immediately with a correlation ID.
+     * The agent begins execution asynchronously.
+     */
+    dispatch(task: TaskUnit): Promise<DispatchResult>;
+    /**
+     * Poll the current state of a dispatched task.
+     * Returns the latest state + any progress info + evidence if terminal.
+     */
+    poll(correlationId: string): Promise<PollResult>;
+    /**
+     * Request cancellation of a running task.
+     * Best-effort: agent may not cancel immediately.
+     */
+    cancel(correlationId: string): Promise<void>;
+    /**
+     * Notify the agent that a blocked task has been unblocked.
+     * Optional — not all agents support external unblock signals.
+     * If implemented, the adapter should transition the task so subsequent
+     * polls reflect the resumed state.
+     */
+    unblock?(correlationId: string, resolution?: string): Promise<void>;
+    /**
+     * Clean up resources. Called when the adapter is being shut down.
+     */
+    dispose?(): Promise<void>;
+}
+/**
+ * Base class with shared utility methods for adapter implementations.
+ */
+export declare abstract class BaseAdapter implements AgentAdapter {
+    abstract readonly id: string;
+    abstract capabilities(): AgentCapability;
+    abstract dispatch(task: TaskUnit): Promise<DispatchResult>;
+    abstract poll(correlationId: string): Promise<PollResult>;
+    abstract cancel(correlationId: string): Promise<void>;
+    /** Track active executions: correlationId -> state */
+    protected executions: Map<string, {
+        taskId: string;
+        state: TaskState;
+        startedAt: string;
+    }>;
+    protected setExecution(correlationId: string, taskId: string, state: TaskState): void;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=agent-adapter.d.ts.map

package/dist/adapter/agent-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/agent-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,eAAe,EACf,SAAS,EACV,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,sCAAsC;IACtC,YAAY,IAAI,eAAe,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAElD;;;OAGG;IACH,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEjD;;;OAGG;IACH,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;OAEG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;GAEG;AACH,8BAAsB,WAAY,YAAW,YAAY;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,IAAI,eAAe;IACxC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC;IAC1D,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IACzD,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAErD,sDAAsD;IACtD,SAAS,CAAC,UAAU;gBAER,MAAM;eAAS,SAAS;mBAAa,MAAM;OACnD;IAEJ,SAAS,CAAC,YAAY,CACpB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,GACf,IAAI;IAaD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/adapter/agent-adapter.js

@@ -0,0 +1,36 @@
+/**
+ * AgentAdapter — the universal interface that any CLI agent must implement.
+ *
+ * This is the "USB plug shape". If your agent can implement these methods,
+ * the orchestrator can dispatch tasks to it.
+ *
+ * Design principles:
+ * - CLI-first: adapters invoke agents via subprocess, not library import
+ * - Evidence-based: completion requires proof, not self-certification
+ * - Polling model (v0.1): orchestrator polls for progress. Future versions
+ *   may add push/streaming via stdio or webhooks.
+ */
+/**
+ * Base class with shared utility methods for adapter implementations.
+ */
+export class BaseAdapter {
+    /** Track active executions: correlationId -> state */
+    executions = new Map();
+    setExecution(correlationId, taskId, state) {
+        const existing = this.executions.get(correlationId);
+        if (existing) {
+            existing.state = state;
+        }
+        else {
+            this.executions.set(correlationId, {
+                taskId,
+                state,
+                startedAt: new Date().toISOString(),
+            });
+        }
+    }
+    async dispose() {
+        this.executions.clear();
+    }
+}
+//# sourceMappingURL=agent-adapter.js.map

package/dist/adapter/agent-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-adapter.js","sourceRoot":"","sources":["../../src/adapter/agent-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkEH;;GAEG;AACH,MAAM,OAAgB,WAAW;IAO/B,sDAAsD;IAC5C,UAAU,GAAG,IAAI,GAAG,EAG3B,CAAC;IAEM,YAAY,CACpB,aAAqB,EACrB,MAAc,EACd,KAAgB;QAEhB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACpD,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,EAAE;gBACjC,MAAM;gBACN,KAAK;gBACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/adapter/codex-adapter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * CodexAdapter — wraps OpenAI Codex CLI as a protocol-compliant agent.
+ *
+ * This is a REAL adapter (not simulated). It spawns actual `codex` processes
+ * and collects real evidence from their execution.
+ *
+ * Key design:
+ * - `dispatch()` → spawns `codex exec --full-auto` as a child process
+ * - `poll()` → checks process exit status, reads stdout/stderr as progress
+ * - `cancel()` → sends SIGTERM to the process
+ * - Quality gates run after codex completes (typecheck, codex review)
+ */
+import type { AgentCapability, TaskUnit } from "../types/index.js";
+import type { Logger } from "../utils/logger.js";
+import type { DispatchResult, PollResult } from "./agent-adapter.js";
+import { BaseAdapter } from "./agent-adapter.js";
+export interface CodexAdapterOptions {
+    /** Working directory for codex execution. */
+    workingDirectory: string;
+    /** Path to the codex binary. Defaults to 'codex'. */
+    codexPath?: string;
+    /** Model to use. Defaults to codex CLI default. */
+    model?: string;
+    /** Timeout per task in ms. Defaults to 120000 (2 min). */
+    taskTimeoutMs?: number;
+    /** Quality gate commands to run after codex completes. Each is a shell command. */
+    qualityGates?: string[];
+    /** Whether to run `codex review --uncommitted` as a gate. Defaults to true. */
+    enableCodexReview?: boolean;
+    /** Logger instance. Defaults to console-based logger. */
+    logger?: Logger;
+}
+export declare class CodexAdapter extends BaseAdapter {
+    readonly id: string;
+    private readonly workingDirectory;
+    private readonly codexPath;
+    private readonly model?;
+    private readonly taskTimeoutMs;
+    private readonly qualityGates;
+    private readonly enableCodexReview;
+    private readonly log;
+    private codexExecutions;
+    constructor(options: CodexAdapterOptions);
+    capabilities(): AgentCapability;
+    dispatch(task: TaskUnit): Promise<DispatchResult>;
+    poll(correlationId: string): Promise<PollResult>;
+    cancel(correlationId: string): Promise<void>;
+    dispose(): Promise<void>;
+    private buildPrompt;
+    private runQualityGates;
+    private gateNameFromCommand;
+    private extractFailureHypothesis;
+}
+//# sourceMappingURL=codex-adapter.d.ts.map

package/dist/adapter/codex-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/codex-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EAGT,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD,qBAAa,YAAa,SAAQ,WAAW;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,eAAe,CAAqC;gBAEhD,OAAO,EAAE,mBAAmB;IAYxC,YAAY,IAAI,eAAe;IAyBzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC;IAmEjD,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAyJhD,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAanC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAavC,OAAO,CAAC,WAAW;YA0CL,eAAe;IAyF7B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,wBAAwB;CAgBjC"}