va-agent-protocol 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * va-agent-protocol — TypeScript type definitions
+ *
+ * These types mirror the JSON Schemas in /schemas/.
+ * Schemas are the source of truth; these provide compile-time safety.
+ */
+export interface Pitfall {
+    id: string;
+    failureType: "gate" | "acceptance" | "review" | "timeout" | "crash" | "unknown";
+    attempted: string;
+    hypothesis: string;
+    missingContext?: string;
+}
+export interface TaskContext {
+    codebaseRoot?: string;
+    files?: string[];
+    history?: string[];
+    pitfalls?: Pitfall[];
+}
+export type Priority = "P0" | "P1" | "P2" | "P3";
+/** Reference to an output from a dependency task. Resolved by orchestrator before dispatch. */
+export interface InputRef {
+    fromTask: string;
+    outputKey: string;
+}
+/** Check if a value is an InputRef (fromTask reference). */
+export declare function isInputRef(value: unknown): value is InputRef;
+export interface OutputContract {
+    /** Output keys this task promises to produce (stored in evidence.outputs). */
+    keys: string[];
+}
+export interface TaskUnit {
+    id: string;
+    objective: string;
+    constraints?: string[];
+    acceptanceCriteria: string[];
+    context?: TaskContext;
+    priority?: Priority;
+    dependsOn?: string[];
+    timeout?: number;
+    /** Named inputs. Values are static (any JSON) or InputRef (resolved by orchestrator from dependency outputs). */
+    inputs?: Record<string, unknown>;
+    /** Declares what structured outputs this task will produce. */
+    outputContract?: OutputContract;
+    metadata?: Record<string, unknown>;
+}
+export type InterfaceType = "cli" | "http" | "stdio";
+export type ModelRequirement = "frontier" | "strong" | "any";
+export interface AgentInterface {
+    type: InterfaceType;
+    command: string;
+    workingDirectory?: string;
+    env?: Record<string, string>;
+}
+export interface AgentConstraints {
+    maxConcurrent?: number;
+    requiresNetwork?: boolean;
+    requiresHumanApproval?: string[];
+    maxRetries?: number;
+}
+export interface AgentCapability {
+    agentId: string;
+    name: string;
+    version: string;
+    capabilities: string[];
+    modelRequirement?: ModelRequirement;
+    interface: AgentInterface;
+    constraints?: AgentConstraints;
+}
+export type TaskState = "pending" | "running" | "completed" | "failed" | "blocked" | "cancelled";
+export declare const VALID_TRANSITIONS: Record<TaskState, TaskState[]>;
+export interface StateTransition {
+    from: TaskState;
+    to: TaskState;
+    timestamp: string;
+    reason?: string;
+    actor?: string;
+}
+export interface TaskExecution {
+    taskId: string;
+    correlationId: string;
+    agentId?: string;
+    currentState: TaskState;
+    attempt?: number;
+    transitions: StateTransition[];
+    startedAt?: string;
+    completedAt?: string;
+}
+export type ArtifactType = "file" | "commit" | "report" | "diff" | "log";
+export interface Artifact {
+    type: ArtifactType;
+    path?: string;
+    description: string;
+}
+export type GateType = "command" | "model-evaluation";
+export type GateSeverity = "error" | "warning";
+export interface GateResult {
+    gate: string;
+    /** Gate type. 'command' = CLI exit code. 'model-evaluation' = agent/model-as-judge with score. */
+    type?: GateType;
+    /** CLI command that was run. Required for type='command'. */
+    command?: string;
+    exitCode?: number;
+    passed: boolean;
+    output?: string;
+    durationMs?: number;
+    /** Agent/model ID that performed evaluation. For type='model-evaluation'. */
+    evaluator?: string;
+    /** Evaluation score (0.0–1.0). For type='model-evaluation'. */
+    score?: number;
+    /** Score threshold for passing. score >= threshold → passed. */
+    threshold?: number;
+    /** Soft threshold. Score between softThreshold and threshold = warning, not hard fail. */
+    softThreshold?: number;
+    /** When passed=false: 'error' = hard fail (retry), 'warning' = soft fail (consider blocked). */
+    severity?: GateSeverity;
+    /** Human-readable explanation. For type='model-evaluation'. */
+    rationale?: string;
+}
+export type FailureType = "gate" | "acceptance" | "review" | "timeout" | "crash" | "unknown";
+export interface DimensionFeedback {
+    score?: number;
+    status: "ok" | "mismatch" | "missing";
+    detail?: string;
+}
+export interface FailureDetail {
+    failureType: FailureType;
+    attempted: string;
+    hypothesis: string;
+    missingContext?: string;
+    /** Per-dimension breakdown. Enables targeted retry on specific dimensions. */
+    dimensions?: Record<string, DimensionFeedback>;
+}
+export type BlockType = "human-decision" | "external-resource" | "dependency" | "permission";
+export interface BlockReason {
+    type: BlockType;
+    description: string;
+    requiredAction?: string;
+}
+export type EvidenceStatus = "completed" | "failed" | "blocked";
+export interface Evidence {
+    taskId: string;
+    status: EvidenceStatus;
+    artifacts?: Artifact[];
+    gateResults?: GateResult[];
+    verification?: string;
+    failureDetail?: FailureDetail;
+    blockReason?: BlockReason;
+    /** Structured outputs produced by this task. Downstream tasks reference these via inputs[].fromTask. */
+    outputs?: Record<string, unknown>;
+}
+export type MessageType = "dispatch" | "accepted" | "progress" | "completed" | "failed" | "blocked" | "cancel";
+export interface DispatchPayload {
+    task: TaskUnit;
+}
+export interface AcceptedPayload {
+    taskId: string;
+    estimatedCapabilities?: string[];
+}
+export interface ProgressPayload {
+    taskId: string;
+    phase?: string;
+    summary?: string;
+    completionEstimate?: number;
+    /** Structured log entries from the agent's execution. */
+    logs?: ProgressLog[];
+    /** Key-value data the agent wants to expose to the orchestrator/UI. */
+    data?: Record<string, unknown>;
+    /** The agent currently handling this task (populated by orchestrator). */
+    agentId?: string;
+}
+export interface ProgressLog {
+    timestamp: string;
+    level: "info" | "warn" | "error" | "debug";
+    message: string;
+}
+export interface CompletedPayload {
+    evidence: Evidence;
+}
+export interface FailedPayload {
+    evidence: Evidence;
+    retryable?: boolean;
+}
+export interface BlockedPayload {
+    evidence: Evidence;
+}
+export interface CancelPayload {
+    taskId: string;
+    reason?: string;
+}
+export type MessagePayload = DispatchPayload | AcceptedPayload | ProgressPayload | CompletedPayload | FailedPayload | BlockedPayload | CancelPayload;
+export interface ProtocolMessage<T extends MessagePayload = MessagePayload> {
+    protocol: "va-agent-protocol";
+    version: string;
+    type: MessageType;
+    timestamp: string;
+    correlationId: string;
+    sourceId?: string;
+    payload: T;
+}
+export declare const PROTOCOL_NAME: "va-agent-protocol";
+export declare const PROTOCOL_VERSION: "0.1.0";
+/** Create a protocol message with defaults filled in. */
+export declare function createMessage<T extends MessagePayload>(type: MessageType, correlationId: string, payload: T, sourceId?: string): ProtocolMessage<T>;
+/** Validate a state transition. */
+export declare function isValidTransition(from: TaskState, to: TaskState): boolean;
+/** Generate a correlation ID. */
+export declare function generateCorrelationId(): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/index.js

@@ -0,0 +1,45 @@
+/**
+ * va-agent-protocol — TypeScript type definitions
+ *
+ * These types mirror the JSON Schemas in /schemas/.
+ * Schemas are the source of truth; these provide compile-time safety.
+ */
+/** Check if a value is an InputRef (fromTask reference). */
+export function isInputRef(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "fromTask" in value &&
+        "outputKey" in value);
+}
+export const VALID_TRANSITIONS = {
+    pending: ["running", "cancelled"],
+    running: ["completed", "failed", "blocked", "cancelled"],
+    blocked: ["running", "failed", "cancelled"],
+    completed: [],
+    failed: ["running"],
+    cancelled: [],
+};
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+export const PROTOCOL_NAME = "va-agent-protocol";
+export const PROTOCOL_VERSION = "0.1.0";
+/** Create a protocol message with defaults filled in. */
+export function createMessage(type, correlationId, payload, sourceId) {
+    return {
+        protocol: PROTOCOL_NAME,
+        version: PROTOCOL_VERSION,
+        type,
+        timestamp: new Date().toISOString(),
+        correlationId,
+        sourceId,
+        payload,
+    };
+}
+/** Validate a state transition. */
+export function isValidTransition(from, to) {
+    return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+}
+/** Generate a correlation ID. */
+export function generateCorrelationId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2BH,4DAA4D;AAC5D,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,UAAU,IAAI,KAAK;QACnB,WAAW,IAAI,KAAK,CACrB,CAAC;AACJ,CAAC;AA8DD,MAAM,CAAC,MAAM,iBAAiB,GAAmC;IAC/D,OAAO,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC;IACjC,OAAO,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,CAAC;IACxD,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC3C,SAAS,EAAE,EAAE;IACb,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,SAAS,EAAE,EAAE;CACd,CAAC;AAuLF,gFAAgF;AAEhF,MAAM,CAAC,MAAM,aAAa,GAAG,mBAA4B,CAAC;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAgB,CAAC;AAEjD,yDAAyD;AACzD,MAAM,UAAU,aAAa,CAC3B,IAAiB,EACjB,aAAqB,EACrB,OAAU,EACV,QAAiB;IAEjB,OAAO;QACL,QAAQ,EAAE,aAAa;QACvB,OAAO,EAAE,gBAAgB;QACzB,IAAI;QACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,aAAa;QACb,QAAQ;QACR,OAAO;KACR,CAAC;AACJ,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,iBAAiB,CAAC,IAAe,EAAE,EAAa;IAC9D,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC;AACxD,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,qBAAqB;IACnC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Logger — configurable logging interface for library consumers.
+ *
+ * Libraries should never spam stdout. All internal logging goes through
+ * this interface so consumers can redirect, filter, or silence output.
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Default logger that delegates to console. */
+export declare const consoleLogger: Logger;
+/** Silent logger that discards all output. */
+export declare const noopLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAED,gDAAgD;AAChD,eAAO,MAAM,aAAa,EAAE,MAK3B,CAAC;AAEF,8CAA8C;AAC9C,eAAO,MAAM,UAAU,EAAE,MAKxB,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,21 @@
+/**
+ * Logger — configurable logging interface for library consumers.
+ *
+ * Libraries should never spam stdout. All internal logging goes through
+ * this interface so consumers can redirect, filter, or silence output.
+ */
+/** Default logger that delegates to console. */
+export const consoleLogger = {
+    debug: (message, ...args) => console.debug(message, ...args),
+    info: (message, ...args) => console.log(message, ...args),
+    warn: (message, ...args) => console.warn(message, ...args),
+    error: (message, ...args) => console.error(message, ...args),
+};
+/** Silent logger that discards all output. */
+export const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IAC5D,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IACzD,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;CAC7D,CAAC;AAEF,8CAA8C;AAC9C,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "va-agent-protocol",
+  "version": "0.1.0",
+  "description": "Universal agent task protocol — the USB interface for CLI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "va-orchestrate": "./bin/va-orchestrate.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./schemas/*": "./schemas/*"
+  },
+  "files": [
+    "dist/",
+    "schemas/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit",
+    "test": "node --test dist/**/*.test.js",
+    "test:schemas": "node dist/test/schema-validation.test.js",
+    "example": "npm run build && npx tsx examples/full-lifecycle.ts",
+    "example:codex": "npm run build && npx tsx examples/codex-real.ts"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "yaml": "^2.8.2"
+  },
+  "optionalDependencies": {
+    "va-auto-pilot": "file:../auto-pilot"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "agent-protocol",
+    "cli-agent",
+    "task-delegation",
+    "orchestration"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vadaski/va-agent-protocol.git"
+  },
+  "homepage": "https://github.com/Vadaski/va-agent-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/Vadaski/va-agent-protocol/issues"
+  },
+  "author": "Vadaski"
+}

package/schemas/agent-capability.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://va-agent-protocol.dev/schemas/agent-capability.schema.json",
+  "title": "AgentCapability",
+  "description": "Declares what an agent can do and how to invoke it. Like a USB device descriptor.",
+  "type": "object",
+  "required": ["agentId", "name", "version", "capabilities", "interface"],
+  "additionalProperties": false,
+  "properties": {
+    "agentId": {
+      "type": "string",
+      "description": "Unique identifier for this agent instance."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable agent name."
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version of this agent."
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "What this agent can do. Well-known values: 'code-generation', 'code-review', 'testing', 'deployment', 'refactoring', 'documentation', 'security-audit', 'strategic-decomposition'. Custom values allowed."
+    },
+    "modelRequirement": {
+      "type": "string",
+      "enum": ["frontier", "strong", "any"],
+      "default": "any",
+      "description": "'frontier' = requires top-tier model (Opus 4.6+), 'strong' = requires capable model, 'any' = model-agnostic."
+    },
+    "interface": {
+      "$ref": "#/$defs/AgentInterface",
+      "description": "How to invoke this agent."
+    },
+    "constraints": {
+      "$ref": "#/$defs/AgentConstraints",
+      "description": "Operational limits."
+    }
+  },
+  "$defs": {
+    "AgentInterface": {
+      "type": "object",
+      "required": ["type", "command"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["cli", "http", "stdio"],
+          "description": "'cli' = invoke via subprocess, 'http' = REST endpoint, 'stdio' = stdin/stdout streaming."
+        },
+        "command": {
+          "type": "string",
+          "description": "Base command or URL. For CLI: the executable + base args. For HTTP: the base URL."
+        },
+        "workingDirectory": {
+          "type": "string",
+          "description": "Working directory for CLI agents."
+        },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Environment variables to set when invoking."
+        }
+      }
+    },
+    "AgentConstraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxConcurrent": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "Maximum concurrent tasks this agent can handle."
+        },
+        "requiresNetwork": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether the agent needs network access."
+        },
+        "requiresHumanApproval": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Actions that require human confirmation before execution."
+        },
+        "maxRetries": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 3,
+          "description": "Maximum retry attempts on failure."
+        }
+      }
+    }
+  }
+}