va-agent-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vadaski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,558 @@
+# va-agent-protocol
+
+[![CI](https://github.com/Vadaski/va-agent-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/Vadaski/va-agent-protocol/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/va-agent-protocol.svg)](https://www.npmjs.com/package/va-agent-protocol)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/Vadaski/va-agent-protocol?style=social)](https://github.com/Vadaski/va-agent-protocol)
+
+**The USB interface for AI agents — dispatch, verify, orchestrate.**
+
+```
+┌─────────────────────────────────────────┐
+│  Orchestrator                           │
+│  (dispatch, schedule, monitor, retry)   │
+└──────────────────┬──────────────────────┘
+                   │  ← va-agent-protocol
+┌──────────────────┴──────────────────────┐
+│  ┌───────────┐ ┌──────────┐ ┌─────────┐│
+│  │ Claude    │ │ Codex    │ │ Your    ││
+│  │ Code      │ │          │ │ Agent   ││
+│  └───────────┘ └──────────┘ └─────────┘│
+│          Any CLI agent                   │
+└──────────────────────────────────────────┘
+```
+
+### Try it now
+
+```bash
+npx va-orchestrate agents --project-root .
+```
+
+---
+
+## Protocol Comparison
+
+How does va-agent-protocol relate to MCP and A2A? They are **complementary**, not competing:
+
+| Dimension | MCP (Anthropic) | A2A (Google) | va-agent-protocol |
+|-----------|----------------|-------------|-------------------|
+| **Focus** | Tool-level context | Agent discovery + coordination | Long-task execution + evidence verification |
+| **Task type** | Short synchronous tool calls | Discovery + routing | Long tasks + auto-topology + scheduler |
+| **Time model** | Synchronous | Async (push) | Async (polling; v0.2 push) |
+| **Verification** | Return value = result | Weak | CLI gates + model-eval + pitfall |
+| **Orchestration** | None | Basic routing | Topological sort + capability match + concurrency control |
+| **Failure learning** | None | None | Pitfall compounding |
+| **Interop** | — | MCP-compatible | Complements MCP & A2A |
+
+> **TL;DR** — MCP connects models to tools. A2A connects agents to agents. va-agent-protocol makes sure the work actually gets done right.
+
+---
+
+## Why
+
+AI agents can autonomously write code, review it, and test it. But every agent has its own interface. There's no standard way to:
+
+- **Dispatch** a task to an agent with objectives and constraints
+- **Monitor** progress in real-time as the agent works
+- **Collect evidence** that the task was actually completed (not just self-certified)
+- **Retry** with context from previous failures
+- **Compose** multiple agents with different capabilities
+
+va-agent-protocol solves this with a **JSON Schema-based contract** — comply with the spec, and your agent plugs into any orchestrator.
+
+---
+
+## Why Frontier Models Need This
+
+2026 frontier models (Claude Opus 4, GPT-5, Gemini 2.5 Pro) bring extraordinary capabilities: autonomous multi-step reasoning, million-token context windows, and native tool calling. va-agent-protocol is designed to **amplify these strengths** and **guard against remaining weaknesses**.
+
+### Amplifying strengths
+
+- **Objective-driven delegation** — Tasks define WHAT to achieve, never HOW. The model's reasoning ability is fully unleashed.
+- **Parallel task scheduling** — The orchestrator dispatches independent tasks concurrently, leaning into frontier models' native parallel tool orchestration.
+- **Long-context awareness** — Task contracts, pitfall guides, and evidence payloads are designed for models that can hold entire projects in context.
+
+### Guarding against weaknesses
+
+- **Evidence gates prevent hallucination** — Agents cannot self-certify completion. CLI commands and model-evaluation gates produce objective pass/fail signals. "I think it's done" is not the same as "it is done."
+- **Pitfall compounding prevents repeated mistakes** — Structured failure metadata from past attempts is injected into retries as hard constraints. The system gets harder to fool over time.
+- **Model-evaluation gates** — For subjective quality (code style, content tone), AI judges with score thresholds and three-tier decisions (pass / blocked for human / fail+retry).
+
+> **One sentence:** Trust the model's reasoning power; use deterministic mechanisms to catch its blind spots.
+
+---
+
+## Design Principles
+
+Inherited from [va-auto-pilot](https://github.com/Vadaski/va-auto-pilot):
+
+1. **Objective-driven, not step-driven** — Tasks define WHAT to achieve, never HOW
+2. **CLI-first** — Agents are invoked via subprocess, not library import
+3. **Evidence-based completion** — "Prove it's done" with gate results and artifacts, not "trust me"
+4. **Convention over configuration** — Comply with the JSON Schema, you're compatible
+5. **Failure knowledge compounds** — Each retry receives pitfalls from previous failures
+
+---
+
+## Quick Start
+
+```bash
+npm install va-agent-protocol
+```
+
+### 1. Define a Task
+
+```typescript
+import type { TaskUnit } from "va-agent-protocol";
+
+const task: TaskUnit = {
+  id: "TASK-001",
+  objective: "Implement user authentication with JWT",
+  constraints: [
+    "Use bcrypt for password hashing",
+    "Tokens expire in 24 hours",
+  ],
+  acceptanceCriteria: [
+    "npm run typecheck passes",
+    "npm test passes with all auth tests",
+    "No CRITICAL findings in code review",
+  ],
+  priority: "P1",
+};
+```
+
+### 2. Implement an Adapter (or use built-in)
+
+The adapter is the "USB plug" — it translates between the protocol and your agent's CLI:
+
+```typescript
+import type {
+  AgentAdapter,
+  AgentCapability,
+  DispatchResult,
+  PollResult,
+  TaskUnit,
+} from "va-agent-protocol";
+import { generateCorrelationId } from "va-agent-protocol";
+
+class MyAgentAdapter implements AgentAdapter {
+  readonly id = "my-agent";
+
+  capabilities(): AgentCapability {
+    return {
+      agentId: this.id,
+      name: "My Custom Agent",
+      version: "1.0.0",
+      capabilities: ["code-generation", "testing"],
+      modelRequirement: "frontier",
+      interface: {
+        type: "cli",
+        command: "my-agent-cli",
+      },
+      constraints: {
+        maxConcurrent: 2,
+        maxRetries: 3,
+      },
+    };
+  }
+
+  async dispatch(task: TaskUnit): Promise<DispatchResult> {
+    const correlationId = generateCorrelationId();
+    // Spawn your agent process here
+    return { correlationId, accepted: true };
+  }
+
+  async poll(correlationId: string): Promise<PollResult> {
+    // Check your agent's state
+    return {
+      correlationId,
+      state: "running",
+      progress: {
+        taskId: "TASK-001",
+        phase: "implementing",
+        summary: "Writing authentication middleware...",
+        completionEstimate: 0.4,
+        logs: [{
+          timestamp: new Date().toISOString(),
+          level: "info",
+          message: "Created src/auth/middleware.ts",
+        }],
+        data: { linesWritten: 87 },
+      },
+    };
+  }
+
+  async cancel(correlationId: string): Promise<void> {
+    // Kill the agent process
+  }
+}
+```
+
+### 3. Orchestrate
+
+```typescript
+import {
+  AgentRegistry,
+  Orchestrator,
+} from "va-agent-protocol";
+
+const registry = new AgentRegistry();
+registry.register(new MyAgentAdapter());
+
+const orchestrator = new Orchestrator(registry, {
+  pollIntervalMs: 3000,
+  maxRetries: 3,
+
+  onProgress: (taskId, progress) => {
+    console.log(`${taskId}: ${progress.phase} (${Math.round((progress.completionEstimate ?? 0) * 100)}%)`);
+  },
+
+  onCompleted: (taskId, evidence) => {
+    console.log(`${taskId} completed!`);
+    for (const gate of evidence.gateResults ?? []) {
+      console.log(`  ${gate.passed ? "✓" : "✗"} ${gate.gate}`);
+    }
+  },
+
+  onFailed: (taskId, evidence) => {
+    console.error(`${taskId} failed: ${evidence.failureDetail?.hypothesis}`);
+  },
+
+  onBlocked: (taskId, reason) => {
+    console.log(`${taskId} needs human input: ${reason}`);
+  },
+});
+
+orchestrator.enqueue(task);
+orchestrator.start();
+```
+
+---
+
+## Protocol Schemas
+
+The protocol is defined by 5 JSON Schemas in `schemas/`:
+
+| Schema | Purpose |
+|--------|---------|
+| [`task-unit.schema.json`](schemas/task-unit.schema.json) | The universal task contract (objective + constraints + acceptance criteria) |
+| [`agent-capability.schema.json`](schemas/agent-capability.schema.json) | Agent self-description (capabilities, interface, constraints) |
+| [`lifecycle.schema.json`](schemas/lifecycle.schema.json) | Task state machine and valid transitions |
+| [`evidence.schema.json`](schemas/evidence.schema.json) | Completion proof (gate results, artifacts, failure details) |
+| [`message.schema.json`](schemas/message.schema.json) | Communication envelope between orchestrator and agent |
+
+### Task Lifecycle
+
+```
+pending → running → completed
+            ↓
+          blocked → running (after human input)
+            ↓
+          failed → running (retry with pitfall context)
+```
+
+### Evidence-Based Completion
+
+Tasks don't self-certify completion. They must provide **evidence**:
+
+```json
+{
+  "taskId": "TASK-001",
+  "status": "completed",
+  "gateResults": [
+    {
+      "gate": "typecheck",
+      "command": "npm run typecheck",
+      "exitCode": 0,
+      "passed": true,
+      "durationMs": 1200
+    },
+    {
+      "gate": "unit-tests",
+      "command": "npm test",
+      "exitCode": 0,
+      "passed": true,
+      "output": "42 tests passed, 0 failed"
+    }
+  ],
+  "artifacts": [
+    { "type": "commit", "path": "a1b2c3d", "description": "Implement JWT auth" }
+  ],
+  "verification": "All 3 quality gates passed."
+}
+```
+
+### Model-Evaluation Gates
+
+Not all quality gates are CLI commands. For subjective or AI-judged evaluations (style consistency, code quality scoring, content review), gates support a `model-evaluation` type:
+
+```json
+{
+  "gate": "style-consistency",
+  "type": "model-evaluation",
+  "evaluator": "style-similarity-agent",
+  "score": 0.85,
+  "threshold": 0.8,
+  "softThreshold": 0.65,
+  "passed": true,
+  "rationale": "Sentence rhythm and vocabulary match. Tone slightly more formal."
+}
+```
+
+When `passed: false`, the `severity` field controls the response:
+- `"error"` → hard fail (orchestrator retries)
+- `"warning"` → soft fail (orchestrator may route to `blocked` for human review)
+
+The `softThreshold` enables a three-tier decision: below soft = fail+retry, between soft and hard = blocked for human, above hard = pass.
+
+### Task Inputs/Outputs
+
+Tasks can declare typed inputs and outputs. The orchestrator automatically resolves data references between dependent tasks:
+
+```typescript
+const extractSchema: TaskUnit = {
+  id: "SCHEMA-001",
+  objective: "Extract API schema definitions",
+  outputContract: { keys: ["apiSchema"] },  // Declares what this task produces
+  // ...
+};
+
+const generateClient: TaskUnit = {
+  id: "CLIENT-001",
+  dependsOn: ["SCHEMA-001"],
+  inputs: {
+    schema: { fromTask: "SCHEMA-001", outputKey: "apiSchema" },  // Resolved by orchestrator
+    language: "typescript",  // Static input
+  },
+  // ...
+};
+```
+
+### Failure → Pitfall → Retry
+
+When a task fails, the orchestrator captures structured failure metadata and injects it as `pitfalls` into the retry context:
+
+```
+Attempt 1: Agent implements feature → tests fail on edge case
+    ↓ failureDetail captured
+Attempt 2: Agent receives pitfall context →
+    "Previous attempt failed: missing null check for empty array input"
+    → Agent handles edge case → tests pass
+```
+
+---
+
+## Progress Reporting
+
+Agents report progress through `ProgressPayload`:
+
+```typescript
+{
+  taskId: "TASK-001",
+  phase: "implementing",           // Current execution phase
+  summary: "Writing auth module",  // Human-readable status
+  completionEstimate: 0.4,         // 0.0 → 1.0
+  logs: [{                         // Structured log entries
+    timestamp: "2026-02-24T...",
+    level: "info",
+    message: "Created src/auth/middleware.ts"
+  }],
+  data: {                          // Arbitrary structured data
+    linesWritten: 87,
+    currentFile: "src/auth/middleware.ts"
+  }
+}
+```
+
+---
+
+## Multi-Agent Scheduling
+
+Register agents with different capabilities. The scheduler matches tasks to the best-fit agent:
+
+```typescript
+registry.register(codeAgent);     // capabilities: ["code-generation", "testing"]
+registry.register(reviewAgent);   // capabilities: ["code-review", "security-audit"]
+
+// Scheduler auto-routes:
+// "Implement feature X" → codeAgent (matched "code-generation")
+// "Audit API security"  → reviewAgent (matched "security-audit")
+```
+
+Concurrency limits are respected. If an agent is at max capacity, tasks queue until a slot opens.
+
+---
+
+## Task Dependencies
+
+Tasks can declare dependencies. The orchestrator dispatches them in topological order:
+
+```typescript
+const tasks = [
+  { id: "TASK-001", objective: "Build core module", ... },
+  { id: "TASK-002", objective: "Add tests", dependsOn: ["TASK-001"], ... },
+  { id: "TASK-003", objective: "Write docs", ... }, // No deps, runs in parallel
+];
+
+orchestrator.enqueue(...tasks);
+// TASK-001 and TASK-003 dispatch immediately (parallel)
+// TASK-002 waits for TASK-001 to complete
+```
+
+---
+
+## Built-in: va-auto-pilot Adapter
+
+The first adapter wraps [va-auto-pilot](https://github.com/Vadaski/va-auto-pilot)'s sprint-board CLI:
+
+```typescript
+import { VaAutoPilotAdapter, AgentRegistry, Orchestrator } from "va-agent-protocol";
+
+const adapter = new VaAutoPilotAdapter({
+  projectRoot: "/path/to/your/project",
+});
+
+const registry = new AgentRegistry();
+registry.register(adapter);
+```
+
+---
+
+## CLI
+
+```bash
+# List registered agents
+npx va-orchestrate agents --project-root ./my-project
+
+# Dispatch a task from JSON file
+npx va-orchestrate dispatch --task task.json --project-root ./my-project
+```
+
+---
+
+## Run the Example
+
+```bash
+npm run example
+```
+
+This shows multi-agent registration, capability matching, task dependency ordering, real-time progress, quality gate evidence, failure → pitfall → retry, blocked state escalation, and a live terminal dashboard.
+
+---
+
+## Implementing Your Own Adapter
+
+The adapter is the "USB plug" — the only code you write to make your agent protocol-compatible. Implement the `AgentAdapter` interface:
+
+```typescript
+import type {
+  AgentAdapter,
+  AgentCapability,
+  DispatchResult,
+  PollResult,
+  TaskUnit,
+} from "va-agent-protocol";
+import { generateCorrelationId } from "va-agent-protocol";
+
+class MyAgentAdapter implements AgentAdapter {
+  readonly id = "my-agent";
+
+  capabilities(): AgentCapability {
+    return {
+      agentId: this.id,
+      name: "My Agent",
+      version: "1.0.0",
+      capabilities: ["code-generation"],
+      interface: { type: "cli", command: "my-agent-cli" },
+      constraints: { maxConcurrent: 2 },
+    };
+  }
+
+  async dispatch(task: TaskUnit): Promise<DispatchResult> {
+    const correlationId = generateCorrelationId();
+    return { correlationId, accepted: true };
+  }
+
+  async poll(correlationId: string): Promise<PollResult> {
+    return { correlationId, state: "running" };
+  }
+
+  async cancel(correlationId: string): Promise<void> {}
+}
+```
+
+See `src/adapter/codex-adapter.ts` for a complete real-world example.
+
+---
+
+## Architecture
+
+```
+va-agent-protocol/
+├── schemas/                    # JSON Schema definitions (THE SPEC)
+│   ├── task-unit.schema.json
+│   ├── agent-capability.schema.json
+│   ├── lifecycle.schema.json
+│   ├── evidence.schema.json
+│   └── message.schema.json
+├── src/
+│   ├── types/                  # TypeScript types (mirror schemas)
+│   ├── adapter/                # Agent adapter interface + implementations
+│   │   ├── agent-adapter.ts        # The "USB plug shape"
+│   │   ├── codex-adapter.ts        # OpenAI Codex CLI adapter
+│   │   └── va-auto-pilot-adapter.ts
+│   ├── orchestrator/           # Dispatch loop + scheduling
+│   │   ├── registry.ts             # Agent discovery
+│   │   ├── scheduler.ts            # Task → agent matching
+│   │   └── orchestrator.ts         # Core loop
+│   └── utils/
+│       └── logger.ts               # Configurable logger interface
+├── examples/
+│   └── full-lifecycle.ts       # Comprehensive demo
+└── bin/
+    └── va-orchestrate.mjs      # CLI entry point
+```
+
+---
+
+## Roadmap
+
+### v0.2
+
+- **MCP Server Adapter** — expose va-agent-protocol as an MCP tool server
+- **Persistence** — SQLite-backed orchestrator state with crash recovery
+- **Push-based progress** — Agent-initiated progress via stdio/WebSocket, replacing polling
+- **Sub-orchestration** — Agents can spawn sub-tasks that feed back into the orchestrator
+- **Web Dashboard** — real-time task visualization and monitoring
+- **Extension points** — `metadata` fields on more schema objects, relaxed `additionalProperties`
+
+### v0.3
+
+- **REST / gRPC adapter** for non-CLI integrations
+- **Governance** — cost guardrails + permission scoping
+- **A2A bridge** — bidirectional agent discovery and task delegation with Google A2A
+
+### Future
+
+- **Multi-language SDKs** — Python, Go implementations of the protocol
+- **Distributed orchestration** — Multiple orchestrator instances with shared state
+- **Adapter ecosystem** — Claude Code, Cursor, Aider, and other CLI agent adapters
+- **Agentic AI Foundation** contribution
+
+---
+
+## v0.1 Known Limitations
+
+These are deliberate scope constraints for v0.1, not bugs:
+
+- **In-memory state only** — Persistence/recovery is planned for v0.2
+- **Polling-based progress** — Agent-initiated push is planned for v0.2+
+- **Strict schemas** — `additionalProperties: false`; v0.2 will introduce extension points
+- **No sub-orchestration** — v0.2+ feature
+- **Single scheduler heuristic** — Capability matching uses keyword inference; production deployments should provide explicit capability tags
+
+---
+
+## License
+
+MIT