@aumos/agent-mesh-router 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,106 @@
+/**
+ * HTTP client for the agent-mesh-router service API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMeshRouterClient } from "@aumos/agent-mesh-router";
+ *
+ * const client = createAgentMeshRouterClient({ baseUrl: "http://localhost:8080" });
+ *
+ * // Send a task message to an agent
+ * const result = await client.sendMessage({
+ *   recipient_id: "summarizer-agent",
+ *   message_type: "task",
+ *   payload: { text: "Summarize the quarterly report." },
+ * });
+ *
+ * if (result.ok) {
+ *   console.log("Message dispatched:", result.data.message_id);
+ * }
+ *
+ * // Execute a sequential workflow
+ * const workflow = await client.routeTask({
+ *   pattern: "sequential",
+ *   steps: [
+ *     { agent_id: "reader", action: "extract", params: {}, timeout_seconds: 30, depends_on: [] },
+ *     { agent_id: "writer", action: "summarize", params: {}, timeout_seconds: 60, depends_on: [] },
+ *   ],
+ * });
+ * ```
+ */
+import type { AgentRoute, ApiResult, CircuitBreakerStatus, ConflictResolution, Message, MeshTopology, ResolveConflictRequest, RouteTaskRequest, SendMessageRequest } from "./types.js";
+/** Configuration options for the AgentMeshRouterClient. */
+export interface AgentMeshRouterClientConfig {
+    /** Base URL of the agent-mesh-router server (e.g. "http://localhost:8080"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-mesh-router service. */
+export interface AgentMeshRouterClient {
+    /**
+     * Dispatch a message to a target agent in the mesh.
+     *
+     * Supports all MessageType variants (task, query, broadcast, etc.).
+     * Returns the created Message record including the assigned message_id.
+     *
+     * @param request - Message dispatch payload with recipient and type.
+     * @returns The created Message record with message_id and metadata.
+     */
+    sendMessage(request: SendMessageRequest): Promise<ApiResult<Message>>;
+    /**
+     * Execute a multi-step workflow through the agent mesh.
+     *
+     * The workflow pattern controls how steps are coordinated:
+     * - sequential: steps run one after another in order
+     * - parallel: all steps run concurrently with fan-out/fan-in
+     * - hierarchical: a supervisor agent delegates to sub-agents
+     * - competitive: all steps race; first result wins
+     * - consensus: results are collected and voted upon
+     *
+     * @param request - Workflow execution request with pattern and steps.
+     * @returns AgentRoute with per-step results, status, and total duration.
+     */
+    routeTask(request: RouteTaskRequest): Promise<ApiResult<AgentRoute>>;
+    /**
+     * Retrieve the current mesh topology including all registered agent nodes.
+     *
+     * @returns MeshTopology snapshot with nodes, counts, and capture timestamp.
+     */
+    getTopology(): Promise<ApiResult<MeshTopology>>;
+    /**
+     * Retrieve the status of a named circuit breaker.
+     *
+     * Circuit breakers protect mesh routes from cascading failures. This
+     * endpoint returns the current state (closed/open/half_open) and
+     * cumulative call/rejection counts.
+     *
+     * @param circuitName - The human-readable circuit breaker name.
+     * @returns CircuitBreakerStatus snapshot with state and counters.
+     */
+    getCircuitBreakerStatus(circuitName: string): Promise<ApiResult<CircuitBreakerStatus>>;
+    /**
+     * Resolve a conflict between competing agent outputs.
+     *
+     * Used after competitive or consensus workflows produce disagreeing results.
+     * The configured resolution strategy (majority, weighted, supervisor, etc.)
+     * determines how a winner is selected or synthesized.
+     *
+     * @param request - Conflict resolution request with competing outputs.
+     * @returns ConflictResolution with the resolved output and winning agent.
+     */
+    resolveConflict(request: ResolveConflictRequest): Promise<ApiResult<ConflictResolution>>;
+}
+/**
+ * Create a typed HTTP client for the agent-mesh-router service.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentMeshRouterClient instance.
+ */
+export declare function createAgentMeshRouterClient(config: AgentMeshRouterClientConfig): AgentMeshRouterClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EACV,UAAU,EAEV,SAAS,EACT,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,EACP,YAAY,EACZ,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAMpB,2DAA2D;AAC3D,MAAM,WAAW,2BAA2B;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,2DAA2D;AAC3D,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAEtE;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAErE;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAEhD;;;;;;;;;OASG;IACH,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAEvF;;;;;;;;;OASG;IACH,eAAe,CACb,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,CAAC;CAC3C;AAMD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,GAClC,qBAAqB,CA+DvB"}

package/dist/client.js

@@ -0,0 +1,116 @@
+/**
+ * HTTP client for the agent-mesh-router service API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMeshRouterClient } from "@aumos/agent-mesh-router";
+ *
+ * const client = createAgentMeshRouterClient({ baseUrl: "http://localhost:8080" });
+ *
+ * // Send a task message to an agent
+ * const result = await client.sendMessage({
+ *   recipient_id: "summarizer-agent",
+ *   message_type: "task",
+ *   payload: { text: "Summarize the quarterly report." },
+ * });
+ *
+ * if (result.ok) {
+ *   console.log("Message dispatched:", result.data.message_id);
+ * }
+ *
+ * // Execute a sequential workflow
+ * const workflow = await client.routeTask({
+ *   pattern: "sequential",
+ *   steps: [
+ *     { agent_id: "reader", action: "extract", params: {}, timeout_seconds: 30, depends_on: [] },
+ *     { agent_id: "writer", action: "summarize", params: {}, timeout_seconds: 60, depends_on: [] },
+ *   ],
+ * });
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-mesh-router service.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentMeshRouterClient instance.
+ */
+export function createAgentMeshRouterClient(config) {
+    const { baseUrl, timeoutMs = 30000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async sendMessage(request) {
+            return fetchJson(`${baseUrl}/messages`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async routeTask(request) {
+            return fetchJson(`${baseUrl}/workflows`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async getTopology() {
+            return fetchJson(`${baseUrl}/topology`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async getCircuitBreakerStatus(circuitName) {
+            return fetchJson(`${baseUrl}/circuit-breakers/${encodeURIComponent(circuitName)}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async resolveConflict(request) {
+            return fetchJson(`${baseUrl}/conflicts/resolve`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-mesh-router
+ *
+ * TypeScript client for the AumOS agent-mesh-router service.
+ * Provides HTTP client and type definitions for multi-agent messaging,
+ * workflow orchestration, circuit breaker inspection, and conflict resolution.
+ */
+export type { AgentMeshRouterClient, AgentMeshRouterClientConfig } from "./client.js";
+export { createAgentMeshRouterClient } from "./client.js";
+export type { MessageType, MessagePriority, Message, SendMessageRequest, WorkflowPattern, WorkflowStep, StepResult, WorkflowStatus, AgentRoute, RouteTaskRequest, AgentStatus, MeshNode, MeshTopology, CircuitBreakerState, CircuitBreakerStatus, ResolveConflictRequest, ConflictResolution, RoutingConfig, ApiError, ApiResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAG1D,YAAY,EACV,WAAW,EACX,eAAe,EACf,OAAO,EACP,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,UAAU,EACV,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-mesh-router
+ *
+ * TypeScript client for the AumOS agent-mesh-router service.
+ * Provides HTTP client and type definitions for multi-agent messaging,
+ * workflow orchestration, circuit breaker inspection, and conflict resolution.
+ */
+export { createAgentMeshRouterClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * TypeScript interfaces for the agent-mesh-router service.
+ *
+ * Mirrors the Python dataclasses and enums defined in:
+ *   agent_mesh_router.messages.types
+ *   agent_mesh_router.workflows.base
+ *   agent_mesh_router.routing.table
+ *   agent_mesh_router.fleet.registry
+ *   agent_mesh_router.resilience.circuit_breaker
+ *
+ * All interfaces use readonly fields to match Python's frozen dataclasses.
+ */
+/**
+ * Discriminator for inter-agent message semantics.
+ * Maps to MessageType enum in agent_mesh_router.messages.types.
+ */
+export type MessageType = "task" | "query" | "response" | "result" | "handoff" | "broadcast" | "heartbeat" | "error" | "cancel" | "ack";
+/**
+ * Message priority levels compatible with asyncio.PriorityQueue ordering.
+ * Lower numeric values are processed first.
+ * Maps to Priority enum in agent_mesh_router.messages.types.
+ */
+export type MessagePriority = "CRITICAL" | "HIGH" | "NORMAL" | "LOW" | "BATCH";
+/**
+ * An inter-agent message routed through the mesh.
+ * Encompasses all MessageType variants.
+ */
+export interface Message {
+    /** Unique message identifier (UUID4). */
+    readonly message_id: string;
+    /** Discriminator for message semantics. */
+    readonly message_type: MessageType;
+    /** Agent identifier of the sender. */
+    readonly sender_id: string;
+    /** Agent identifier of the intended recipient (empty for broadcasts). */
+    readonly recipient_id: string;
+    /** Message payload — arbitrary key-value pairs. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    /** Priority level controlling queue ordering. */
+    readonly priority: MessagePriority;
+    /** ISO-8601 UTC timestamp when the message was created. */
+    readonly created_at: string;
+    /** Optional correlation ID linking related messages (e.g. request/response). */
+    readonly correlation_id?: string;
+    /** Optional topic string used for broadcast fan-out. */
+    readonly topic?: string;
+}
+/**
+ * Request payload for dispatching a message into the mesh.
+ */
+export interface SendMessageRequest {
+    /** Target agent identifier. */
+    readonly recipient_id: string;
+    /** Message type discriminator. */
+    readonly message_type: MessageType;
+    /** Message payload. */
+    readonly payload: Readonly<Record<string, unknown>>;
+    /** Priority level (default "NORMAL"). */
+    readonly priority?: MessagePriority;
+    /** Optional correlation ID for request/response linking. */
+    readonly correlation_id?: string;
+}
+/**
+ * Workflow coordination pattern.
+ * Maps to WorkflowExecutor subclass names in agent_mesh_router.workflows.
+ */
+export type WorkflowPattern = "sequential" | "parallel" | "hierarchical" | "competitive" | "consensus";
+/**
+ * A single step within a workflow.
+ * Maps to WorkflowStep dataclass in agent_mesh_router.workflows.base.
+ */
+export interface WorkflowStep {
+    /** Unique identifier for this step (UUID4). */
+    readonly step_id: string;
+    /** Agent responsible for executing this step. */
+    readonly agent_id: string;
+    /** Action or operation name (e.g. "summarize", "translate"). */
+    readonly action: string;
+    /** Parameters passed to the agent for this action. */
+    readonly params: Readonly<Record<string, unknown>>;
+    /** Maximum seconds allowed for this step (null = no per-step timeout). */
+    readonly timeout_seconds: number | null;
+    /** step_id values that must complete before this step may execute. */
+    readonly depends_on: readonly string[];
+}
+/**
+ * Outcome of executing a single WorkflowStep.
+ * Maps to StepResult dataclass in agent_mesh_router.workflows.base.
+ */
+export interface StepResult {
+    /** Matches the WorkflowStep.step_id that produced this result. */
+    readonly step_id: string;
+    /** True when the step completed without error. */
+    readonly success: boolean;
+    /** Data returned by the agent for this step (null on failure). */
+    readonly output: Readonly<Record<string, unknown>> | null;
+    /** Wall-clock milliseconds taken to execute this step. */
+    readonly duration_ms: number;
+    /** Error description when success is false (null on success). */
+    readonly error: string | null;
+}
+/**
+ * Overall status of a workflow execution.
+ * Maps to WorkflowStatus enum in agent_mesh_router.workflows.base.
+ */
+export type WorkflowStatus = "success" | "partial" | "failed" | "cancelled";
+/**
+ * Aggregate outcome of a complete workflow execution.
+ * Maps to WorkflowResult dataclass in agent_mesh_router.workflows.base.
+ */
+export interface AgentRoute {
+    /** Unique identifier for this workflow run (UUID4). */
+    readonly workflow_id: string;
+    /** Ordered list of individual step outcomes. */
+    readonly step_results: readonly StepResult[];
+    /** Overall workflow status. */
+    readonly status: WorkflowStatus;
+    /** Total wall-clock milliseconds from first step start to last step end. */
+    readonly duration_ms: number;
+}
+/**
+ * Request payload for executing a multi-step workflow through the mesh.
+ */
+export interface RouteTaskRequest {
+    /** Coordination pattern for this workflow. */
+    readonly pattern: WorkflowPattern;
+    /** Ordered list of steps to execute. */
+    readonly steps: readonly Omit<WorkflowStep, "step_id">[];
+    /** Optional workflow-level timeout in seconds. */
+    readonly timeout_seconds?: number;
+}
+/**
+ * Lifecycle status of an agent node in the fleet.
+ * Maps to AgentStatus enum in agent_mesh_router.fleet.registry.
+ */
+export type AgentStatus = "HEALTHY" | "UNHEALTHY" | "DEGRADED" | "STARTING" | "STOPPING";
+/**
+ * A single agent node in the fleet registry.
+ * Maps to AgentNode dataclass in agent_mesh_router.fleet.registry.
+ */
+export interface MeshNode {
+    /** Unique agent identifier. */
+    readonly agent_id: string;
+    /** Capability strings this agent exposes. */
+    readonly capabilities: readonly string[];
+    /** Current lifecycle status. */
+    readonly status: AgentStatus;
+    /** Normalized load in [0.0, 1.0]; 0.0 = idle, 1.0 = fully loaded. */
+    readonly load_score: number;
+    /** Unix epoch seconds of the most recent heartbeat received. */
+    readonly last_heartbeat: number;
+    /** Free-form key-value metadata (region, version, model, etc.). */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * Snapshot of the full mesh topology returned by getTopology().
+ */
+export interface MeshTopology {
+    /** All currently registered agent nodes. */
+    readonly nodes: readonly MeshNode[];
+    /** Total number of registered nodes. */
+    readonly total_count: number;
+    /** Number of nodes with HEALTHY status. */
+    readonly healthy_count: number;
+    /** ISO-8601 UTC timestamp when this snapshot was captured. */
+    readonly captured_at: string;
+}
+/**
+ * Possible states of a circuit breaker.
+ * Maps to CircuitState enum in agent_mesh_router.resilience.circuit_breaker.
+ */
+export type CircuitBreakerState = "closed" | "open" | "half_open";
+/**
+ * Status snapshot for a single circuit breaker instance.
+ * Maps to CircuitBreaker properties in agent_mesh_router.resilience.circuit_breaker.
+ */
+export interface CircuitBreakerStatus {
+    /** Human-readable name for this circuit breaker. */
+    readonly name: string;
+    /** Current state of the circuit breaker. */
+    readonly state: CircuitBreakerState;
+    /** Consecutive failure count in the current CLOSED window. */
+    readonly failure_count: number;
+    /** Total calls attempted (not counting rejected calls). */
+    readonly total_calls: number;
+    /** Total calls rejected because the circuit was open. */
+    readonly total_rejected: number;
+    /** Number of failures required to open the circuit. */
+    readonly failure_threshold: number;
+    /** Seconds the circuit stays OPEN before transitioning to HALF_OPEN. */
+    readonly recovery_timeout_seconds: number;
+}
+/**
+ * Request payload for resolving a conflict between competing agent outputs.
+ */
+export interface ResolveConflictRequest {
+    /** Identifier of the workflow or task producing conflicting outputs. */
+    readonly workflow_id: string;
+    /** Competing outputs from different agents, keyed by agent_id. */
+    readonly outputs: Readonly<Record<string, unknown>>;
+    /** Resolution strategy hint (e.g. "majority", "weighted", "supervisor"). */
+    readonly strategy?: string;
+}
+/**
+ * Result of conflict resolution between competing agent outputs.
+ */
+export interface ConflictResolution {
+    /** The workflow that produced conflicting outputs. */
+    readonly workflow_id: string;
+    /** The resolved output selected or synthesized from competing outputs. */
+    readonly resolved_output: Readonly<Record<string, unknown>>;
+    /** Agent ID whose output was selected (null for synthesized results). */
+    readonly winning_agent_id: string | null;
+    /** Resolution strategy that was applied. */
+    readonly strategy_applied: string;
+    /** Confidence score for the resolution in [0.0, 1.0]. */
+    readonly confidence: number;
+}
+/**
+ * Configuration for the mesh router.
+ * Maps to router configuration options across agent_mesh_router.
+ */
+export interface RoutingConfig {
+    /** Default workflow pattern to use when not specified. */
+    readonly default_pattern: WorkflowPattern;
+    /** Default message priority level. */
+    readonly default_priority: MessagePriority;
+    /** Maximum retries for failed message delivery. */
+    readonly max_retries: number;
+    /** Whether to enable circuit breaker protection on all routes. */
+    readonly circuit_breaker_enabled: boolean;
+    /** Seconds before an agent is considered stale (missed heartbeats). */
+    readonly heartbeat_timeout_seconds: number;
+}
+/** Standard error payload returned by the agent-mesh-router API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * TypeScript interfaces for the agent-mesh-router service.
+ *
+ * Mirrors the Python dataclasses and enums defined in:
+ *   agent_mesh_router.messages.types
+ *   agent_mesh_router.workflows.base
+ *   agent_mesh_router.routing.table
+ *   agent_mesh_router.fleet.registry
+ *   agent_mesh_router.resilience.circuit_breaker
+ *
+ * All interfaces use readonly fields to match Python's frozen dataclasses.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aumos/agent-mesh-router",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-mesh-router — multi-agent messaging, workflow orchestration, circuit breakers, and topology inspection",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-mesh-router",
+    "mesh",
+    "routing",
+    "circuit-breaker",
+    "workflow",
+    "multi-agent",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-mesh-router"
+  }
+}

package/src/client.ts

@@ -0,0 +1,256 @@
+/**
+ * HTTP client for the agent-mesh-router service API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMeshRouterClient } from "@aumos/agent-mesh-router";
+ *
+ * const client = createAgentMeshRouterClient({ baseUrl: "http://localhost:8080" });
+ *
+ * // Send a task message to an agent
+ * const result = await client.sendMessage({
+ *   recipient_id: "summarizer-agent",
+ *   message_type: "task",
+ *   payload: { text: "Summarize the quarterly report." },
+ * });
+ *
+ * if (result.ok) {
+ *   console.log("Message dispatched:", result.data.message_id);
+ * }
+ *
+ * // Execute a sequential workflow
+ * const workflow = await client.routeTask({
+ *   pattern: "sequential",
+ *   steps: [
+ *     { agent_id: "reader", action: "extract", params: {}, timeout_seconds: 30, depends_on: [] },
+ *     { agent_id: "writer", action: "summarize", params: {}, timeout_seconds: 60, depends_on: [] },
+ *   ],
+ * });
+ * ```
+ */
+
+import type {
+  AgentRoute,
+  ApiError,
+  ApiResult,
+  CircuitBreakerStatus,
+  ConflictResolution,
+  Message,
+  MeshTopology,
+  ResolveConflictRequest,
+  RouteTaskRequest,
+  SendMessageRequest,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentMeshRouterClient. */
+export interface AgentMeshRouterClientConfig {
+  /** Base URL of the agent-mesh-router server (e.g. "http://localhost:8080"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-mesh-router service. */
+export interface AgentMeshRouterClient {
+  /**
+   * Dispatch a message to a target agent in the mesh.
+   *
+   * Supports all MessageType variants (task, query, broadcast, etc.).
+   * Returns the created Message record including the assigned message_id.
+   *
+   * @param request - Message dispatch payload with recipient and type.
+   * @returns The created Message record with message_id and metadata.
+   */
+  sendMessage(request: SendMessageRequest): Promise<ApiResult<Message>>;
+
+  /**
+   * Execute a multi-step workflow through the agent mesh.
+   *
+   * The workflow pattern controls how steps are coordinated:
+   * - sequential: steps run one after another in order
+   * - parallel: all steps run concurrently with fan-out/fan-in
+   * - hierarchical: a supervisor agent delegates to sub-agents
+   * - competitive: all steps race; first result wins
+   * - consensus: results are collected and voted upon
+   *
+   * @param request - Workflow execution request with pattern and steps.
+   * @returns AgentRoute with per-step results, status, and total duration.
+   */
+  routeTask(request: RouteTaskRequest): Promise<ApiResult<AgentRoute>>;
+
+  /**
+   * Retrieve the current mesh topology including all registered agent nodes.
+   *
+   * @returns MeshTopology snapshot with nodes, counts, and capture timestamp.
+   */
+  getTopology(): Promise<ApiResult<MeshTopology>>;
+
+  /**
+   * Retrieve the status of a named circuit breaker.
+   *
+   * Circuit breakers protect mesh routes from cascading failures. This
+   * endpoint returns the current state (closed/open/half_open) and
+   * cumulative call/rejection counts.
+   *
+   * @param circuitName - The human-readable circuit breaker name.
+   * @returns CircuitBreakerStatus snapshot with state and counters.
+   */
+  getCircuitBreakerStatus(circuitName: string): Promise<ApiResult<CircuitBreakerStatus>>;
+
+  /**
+   * Resolve a conflict between competing agent outputs.
+   *
+   * Used after competitive or consensus workflows produce disagreeing results.
+   * The configured resolution strategy (majority, weighted, supervisor, etc.)
+   * determines how a winner is selected or synthesized.
+   *
+   * @param request - Conflict resolution request with competing outputs.
+   * @returns ConflictResolution with the resolved output and winning agent.
+   */
+  resolveConflict(
+    request: ResolveConflictRequest,
+  ): Promise<ApiResult<ConflictResolution>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-mesh-router service.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentMeshRouterClient instance.
+ */
+export function createAgentMeshRouterClient(
+  config: AgentMeshRouterClientConfig,
+): AgentMeshRouterClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async sendMessage(
+      request: SendMessageRequest,
+    ): Promise<ApiResult<Message>> {
+      return fetchJson<Message>(
+        `${baseUrl}/messages`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async routeTask(request: RouteTaskRequest): Promise<ApiResult<AgentRoute>> {
+      return fetchJson<AgentRoute>(
+        `${baseUrl}/workflows`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getTopology(): Promise<ApiResult<MeshTopology>> {
+      return fetchJson<MeshTopology>(
+        `${baseUrl}/topology`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async getCircuitBreakerStatus(
+      circuitName: string,
+    ): Promise<ApiResult<CircuitBreakerStatus>> {
+      return fetchJson<CircuitBreakerStatus>(
+        `${baseUrl}/circuit-breakers/${encodeURIComponent(circuitName)}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async resolveConflict(
+      request: ResolveConflictRequest,
+    ): Promise<ApiResult<ConflictResolution>> {
+      return fetchJson<ConflictResolution>(
+        `${baseUrl}/conflicts/resolve`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @aumos/agent-mesh-router
+ *
+ * TypeScript client for the AumOS agent-mesh-router service.
+ * Provides HTTP client and type definitions for multi-agent messaging,
+ * workflow orchestration, circuit breaker inspection, and conflict resolution.
+ */
+
+// Client and configuration
+export type { AgentMeshRouterClient, AgentMeshRouterClientConfig } from "./client.js";
+export { createAgentMeshRouterClient } from "./client.js";
+
+// Core types
+export type {
+  MessageType,
+  MessagePriority,
+  Message,
+  SendMessageRequest,
+  WorkflowPattern,
+  WorkflowStep,
+  StepResult,
+  WorkflowStatus,
+  AgentRoute,
+  RouteTaskRequest,
+  AgentStatus,
+  MeshNode,
+  MeshTopology,
+  CircuitBreakerState,
+  CircuitBreakerStatus,
+  ResolveConflictRequest,
+  ConflictResolution,
+  RoutingConfig,
+  ApiError,
+  ApiResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,318 @@
+/**
+ * TypeScript interfaces for the agent-mesh-router service.
+ *
+ * Mirrors the Python dataclasses and enums defined in:
+ *   agent_mesh_router.messages.types
+ *   agent_mesh_router.workflows.base
+ *   agent_mesh_router.routing.table
+ *   agent_mesh_router.fleet.registry
+ *   agent_mesh_router.resilience.circuit_breaker
+ *
+ * All interfaces use readonly fields to match Python's frozen dataclasses.
+ */
+
+// ---------------------------------------------------------------------------
+// Message types and priority
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminator for inter-agent message semantics.
+ * Maps to MessageType enum in agent_mesh_router.messages.types.
+ */
+export type MessageType =
+  | "task"
+  | "query"
+  | "response"
+  | "result"
+  | "handoff"
+  | "broadcast"
+  | "heartbeat"
+  | "error"
+  | "cancel"
+  | "ack";
+
+/**
+ * Message priority levels compatible with asyncio.PriorityQueue ordering.
+ * Lower numeric values are processed first.
+ * Maps to Priority enum in agent_mesh_router.messages.types.
+ */
+export type MessagePriority = "CRITICAL" | "HIGH" | "NORMAL" | "LOW" | "BATCH";
+
+// ---------------------------------------------------------------------------
+// Message
+// ---------------------------------------------------------------------------
+
+/**
+ * An inter-agent message routed through the mesh.
+ * Encompasses all MessageType variants.
+ */
+export interface Message {
+  /** Unique message identifier (UUID4). */
+  readonly message_id: string;
+  /** Discriminator for message semantics. */
+  readonly message_type: MessageType;
+  /** Agent identifier of the sender. */
+  readonly sender_id: string;
+  /** Agent identifier of the intended recipient (empty for broadcasts). */
+  readonly recipient_id: string;
+  /** Message payload — arbitrary key-value pairs. */
+  readonly payload: Readonly<Record<string, unknown>>;
+  /** Priority level controlling queue ordering. */
+  readonly priority: MessagePriority;
+  /** ISO-8601 UTC timestamp when the message was created. */
+  readonly created_at: string;
+  /** Optional correlation ID linking related messages (e.g. request/response). */
+  readonly correlation_id?: string;
+  /** Optional topic string used for broadcast fan-out. */
+  readonly topic?: string;
+}
+
+// ---------------------------------------------------------------------------
+// SendMessageRequest
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for dispatching a message into the mesh.
+ */
+export interface SendMessageRequest {
+  /** Target agent identifier. */
+  readonly recipient_id: string;
+  /** Message type discriminator. */
+  readonly message_type: MessageType;
+  /** Message payload. */
+  readonly payload: Readonly<Record<string, unknown>>;
+  /** Priority level (default "NORMAL"). */
+  readonly priority?: MessagePriority;
+  /** Optional correlation ID for request/response linking. */
+  readonly correlation_id?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow pattern and steps
+// ---------------------------------------------------------------------------
+
+/**
+ * Workflow coordination pattern.
+ * Maps to WorkflowExecutor subclass names in agent_mesh_router.workflows.
+ */
+export type WorkflowPattern =
+  | "sequential"
+  | "parallel"
+  | "hierarchical"
+  | "competitive"
+  | "consensus";
+
+/**
+ * A single step within a workflow.
+ * Maps to WorkflowStep dataclass in agent_mesh_router.workflows.base.
+ */
+export interface WorkflowStep {
+  /** Unique identifier for this step (UUID4). */
+  readonly step_id: string;
+  /** Agent responsible for executing this step. */
+  readonly agent_id: string;
+  /** Action or operation name (e.g. "summarize", "translate"). */
+  readonly action: string;
+  /** Parameters passed to the agent for this action. */
+  readonly params: Readonly<Record<string, unknown>>;
+  /** Maximum seconds allowed for this step (null = no per-step timeout). */
+  readonly timeout_seconds: number | null;
+  /** step_id values that must complete before this step may execute. */
+  readonly depends_on: readonly string[];
+}
+
+/**
+ * Outcome of executing a single WorkflowStep.
+ * Maps to StepResult dataclass in agent_mesh_router.workflows.base.
+ */
+export interface StepResult {
+  /** Matches the WorkflowStep.step_id that produced this result. */
+  readonly step_id: string;
+  /** True when the step completed without error. */
+  readonly success: boolean;
+  /** Data returned by the agent for this step (null on failure). */
+  readonly output: Readonly<Record<string, unknown>> | null;
+  /** Wall-clock milliseconds taken to execute this step. */
+  readonly duration_ms: number;
+  /** Error description when success is false (null on success). */
+  readonly error: string | null;
+}
+
+/**
+ * Overall status of a workflow execution.
+ * Maps to WorkflowStatus enum in agent_mesh_router.workflows.base.
+ */
+export type WorkflowStatus = "success" | "partial" | "failed" | "cancelled";
+
+/**
+ * Aggregate outcome of a complete workflow execution.
+ * Maps to WorkflowResult dataclass in agent_mesh_router.workflows.base.
+ */
+export interface AgentRoute {
+  /** Unique identifier for this workflow run (UUID4). */
+  readonly workflow_id: string;
+  /** Ordered list of individual step outcomes. */
+  readonly step_results: readonly StepResult[];
+  /** Overall workflow status. */
+  readonly status: WorkflowStatus;
+  /** Total wall-clock milliseconds from first step start to last step end. */
+  readonly duration_ms: number;
+}
+
+// ---------------------------------------------------------------------------
+// RouteTaskRequest
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for executing a multi-step workflow through the mesh.
+ */
+export interface RouteTaskRequest {
+  /** Coordination pattern for this workflow. */
+  readonly pattern: WorkflowPattern;
+  /** Ordered list of steps to execute. */
+  readonly steps: readonly Omit<WorkflowStep, "step_id">[];
+  /** Optional workflow-level timeout in seconds. */
+  readonly timeout_seconds?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Mesh topology
+// ---------------------------------------------------------------------------
+
+/**
+ * Lifecycle status of an agent node in the fleet.
+ * Maps to AgentStatus enum in agent_mesh_router.fleet.registry.
+ */
+export type AgentStatus = "HEALTHY" | "UNHEALTHY" | "DEGRADED" | "STARTING" | "STOPPING";
+
+/**
+ * A single agent node in the fleet registry.
+ * Maps to AgentNode dataclass in agent_mesh_router.fleet.registry.
+ */
+export interface MeshNode {
+  /** Unique agent identifier. */
+  readonly agent_id: string;
+  /** Capability strings this agent exposes. */
+  readonly capabilities: readonly string[];
+  /** Current lifecycle status. */
+  readonly status: AgentStatus;
+  /** Normalized load in [0.0, 1.0]; 0.0 = idle, 1.0 = fully loaded. */
+  readonly load_score: number;
+  /** Unix epoch seconds of the most recent heartbeat received. */
+  readonly last_heartbeat: number;
+  /** Free-form key-value metadata (region, version, model, etc.). */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+/**
+ * Snapshot of the full mesh topology returned by getTopology().
+ */
+export interface MeshTopology {
+  /** All currently registered agent nodes. */
+  readonly nodes: readonly MeshNode[];
+  /** Total number of registered nodes. */
+  readonly total_count: number;
+  /** Number of nodes with HEALTHY status. */
+  readonly healthy_count: number;
+  /** ISO-8601 UTC timestamp when this snapshot was captured. */
+  readonly captured_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Circuit breaker
+// ---------------------------------------------------------------------------
+
+/**
+ * Possible states of a circuit breaker.
+ * Maps to CircuitState enum in agent_mesh_router.resilience.circuit_breaker.
+ */
+export type CircuitBreakerState = "closed" | "open" | "half_open";
+
+/**
+ * Status snapshot for a single circuit breaker instance.
+ * Maps to CircuitBreaker properties in agent_mesh_router.resilience.circuit_breaker.
+ */
+export interface CircuitBreakerStatus {
+  /** Human-readable name for this circuit breaker. */
+  readonly name: string;
+  /** Current state of the circuit breaker. */
+  readonly state: CircuitBreakerState;
+  /** Consecutive failure count in the current CLOSED window. */
+  readonly failure_count: number;
+  /** Total calls attempted (not counting rejected calls). */
+  readonly total_calls: number;
+  /** Total calls rejected because the circuit was open. */
+  readonly total_rejected: number;
+  /** Number of failures required to open the circuit. */
+  readonly failure_threshold: number;
+  /** Seconds the circuit stays OPEN before transitioning to HALF_OPEN. */
+  readonly recovery_timeout_seconds: number;
+}
+
+// ---------------------------------------------------------------------------
+// Conflict resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Request payload for resolving a conflict between competing agent outputs.
+ */
+export interface ResolveConflictRequest {
+  /** Identifier of the workflow or task producing conflicting outputs. */
+  readonly workflow_id: string;
+  /** Competing outputs from different agents, keyed by agent_id. */
+  readonly outputs: Readonly<Record<string, unknown>>;
+  /** Resolution strategy hint (e.g. "majority", "weighted", "supervisor"). */
+  readonly strategy?: string;
+}
+
+/**
+ * Result of conflict resolution between competing agent outputs.
+ */
+export interface ConflictResolution {
+  /** The workflow that produced conflicting outputs. */
+  readonly workflow_id: string;
+  /** The resolved output selected or synthesized from competing outputs. */
+  readonly resolved_output: Readonly<Record<string, unknown>>;
+  /** Agent ID whose output was selected (null for synthesized results). */
+  readonly winning_agent_id: string | null;
+  /** Resolution strategy that was applied. */
+  readonly strategy_applied: string;
+  /** Confidence score for the resolution in [0.0, 1.0]. */
+  readonly confidence: number;
+}
+
+// ---------------------------------------------------------------------------
+// Routing configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the mesh router.
+ * Maps to router configuration options across agent_mesh_router.
+ */
+export interface RoutingConfig {
+  /** Default workflow pattern to use when not specified. */
+  readonly default_pattern: WorkflowPattern;
+  /** Default message priority level. */
+  readonly default_priority: MessagePriority;
+  /** Maximum retries for failed message delivery. */
+  readonly max_retries: number;
+  /** Whether to enable circuit breaker protection on all routes. */
+  readonly circuit_breaker_enabled: boolean;
+  /** Seconds before an agent is considered stale (missed heartbeats). */
+  readonly heartbeat_timeout_seconds: number;
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper (shared pattern)
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-mesh-router API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2020", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}