@inteleion-ai/afmx 1.3.0

package/README.md

@@ -0,0 +1,154 @@
+# @agentdyne9/afmx
+
+> TypeScript SDK for [AFMX](https://github.com/inteleion-ai/AFMX) — Agent Flow Matrix Execution Engine
+
+[![npm](https://img.shields.io/npm/v/@agentdyne9/afmx)](https://www.npmjs.com/package/@agentdyne9/afmx)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green)](../../LICENSE)
+
+Type-safe client for the AFMX REST API. Works in Node.js 18+, browsers, and edge runtimes (Cloudflare Workers, Vercel Edge, Deno).
+
+## Install
+
+```bash
+npm install @agentdyne9/afmx
+# or
+pnpm add @agentdyne9/afmx
+# or
+yarn add @agentdyne9/afmx
+```
+
+## Quick start
+
+```typescript
+import { AFMXClient, ExecutionMode, CognitiveLayer, NodeType, buildNode, buildEdge } from '@agentdyne9/afmx';
+
+const client = new AFMXClient({ baseUrl: 'http://localhost:8100' });
+
+// Build a DIAGONAL matrix — AFMX auto-routes cheap/premium models by layer
+const result = await client.execute({
+  matrix: {
+    name: 'risk-analysis',
+    mode: ExecutionMode.DIAGONAL,
+    nodes: [
+      buildNode({
+        id: 'retrieve',
+        name: 'retrieve-market-data',
+        handler: 'data_retriever',
+        layer: CognitiveLayer.RETRIEVE,  // → Haiku / gpt-4o-mini (cheap)
+        role: 'QUANT',
+      }),
+      buildNode({
+        id: 'analyse',
+        name: 'analyse-risk',
+        handler: 'risk_analyser',
+        layer: CognitiveLayer.REASON,    // → Opus / gpt-4o (premium)
+        role: 'RISK_MANAGER',
+      }),
+    ],
+    edges: [buildEdge('retrieve', 'analyse')],
+  },
+  input: { ticker: 'AAPL', lookback_days: 30 },
+});
+
+console.log(result.status, result.duration_ms + 'ms');
+console.log(result.node_results);
+```
+
+## API
+
+### `new AFMXClient(config)`
+
+```typescript
+const client = new AFMXClient({
+  baseUrl:    'http://localhost:8100',   // AFMX server URL
+  apiKey:     'afmx_....',              // optional — if RBAC enabled
+  timeoutMs:  30_000,                   // default: 30 s
+});
+```
+
+### Execution
+
+| Method | Description |
+|--------|-------------|
+| `execute(req)` | Execute synchronously, wait for result |
+| `executeAsync(req)` | Fire-and-forget, returns `execution_id` |
+| `pollUntilDone(id, opts?)` | Poll until terminal state |
+| `getStatus(id)` | Poll once |
+| `getResult(id)` | Full result with node outputs |
+| `cancel(id)` | Cancel a running execution |
+| `retry(id)` | Retry a failed execution |
+| `resume(id)` | Resume from last checkpoint |
+
+### Cognitive Matrix
+
+```typescript
+// Get the 2D heatmap for a completed execution:
+// CognitiveLayer × AgentRole, with model tier + cost per cell
+const view = await client.matrixView(executionId);
+
+view.cells['REASON:RISK_MANAGER']
+// → { status: 'SUCCESS', model_tier: 'premium', duration_ms: 847 }
+```
+
+### Domain packs
+
+```typescript
+const domains = await client.listDomains();
+// → { count: 5, domains: [{ name: 'finance', roles: {...} }, ...] }
+
+const finance = await client.getDomain('finance');
+// → { name: 'finance', roles: { QUANT: '...', RISK_MANAGER: '...' } }
+```
+
+### Async with polling
+
+```typescript
+const { execution_id } = await client.executeAsync({ matrix, input });
+
+// Poll every 500 ms, timeout after 5 minutes
+const result = await client.pollUntilDone(execution_id, {
+  intervalMs: 500,
+  timeoutMs:  300_000,
+});
+```
+
+## Types
+
+All AFMX domain types are exported:
+
+```typescript
+import type {
+  ExecutionMatrix,
+  ExecutionResponse,
+  Node,
+  Edge,
+  MatrixViewResponse,
+  DomainPack,
+} from '@agentdyne9/afmx';
+
+import {
+  CognitiveLayer,   // PERCEIVE | RETRIEVE | REASON | PLAN | ACT | EVALUATE | REPORT
+  ExecutionMode,    // SEQUENTIAL | PARALLEL | HYBRID | DIAGONAL
+  NodeType,         // TOOL | AGENT | FUNCTION | MCP
+  ExecutionStatus,  // QUEUED | RUNNING | COMPLETED | FAILED | ABORTED | TIMEOUT | PARTIAL
+  AFMXError,        // thrown on HTTP errors — has .status and .detail
+} from '@agentdyne9/afmx';
+```
+
+## CognitiveLayer routing
+
+AFMX automatically routes cheap models to high-frequency layers and premium models to reasoning layers:
+
+| Layer | Typical use | Default model tier |
+|-------|------------|-------------------|
+| `PERCEIVE` | Ingest signals, alerts | Cheap (Haiku, gpt-4o-mini) |
+| `RETRIEVE` | RAG, DB lookups | Cheap |
+| `REASON` | Analysis, synthesis | **Premium** (Opus, gpt-4o) |
+| `PLAN` | Strategy, runbooks | **Premium** |
+| `ACT` | Execute tools, APIs | Cheap |
+| `EVALUATE` | Validate, audit | **Premium** |
+| `REPORT` | Summarise, alert | Cheap |
+
+## License
+
+Apache 2.0 — see [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,450 @@
+/**
+ * @agentdyne9/afmx — TypeScript SDK for AFMX
+ *
+ * Type-safe client for the AFMX REST API.
+ * Works in Node.js 18+, browser (with fetch), and edge runtimes.
+ *
+ * @example
+ * ```typescript
+ * import { AFMXClient, ExecutionMode, CognitiveLayer } from '@agentdyne9/afmx';
+ *
+ * const client = new AFMXClient({ baseUrl: 'http://localhost:8100' });
+ *
+ * const result = await client.execute({
+ *   matrix: {
+ *     name: 'risk-analysis',
+ *     mode: ExecutionMode.DIAGONAL,
+ *     nodes: [
+ *       {
+ *         id: 'retrieve',
+ *         name: 'retrieve-data',
+ *         type: 'AGENT',
+ *         handler: 'data_retriever',
+ *         cognitive_layer: CognitiveLayer.RETRIEVE,
+ *         agent_role: 'QUANT',
+ *       },
+ *       {
+ *         id: 'analyse',
+ *         name: 'analyse-risk',
+ *         type: 'AGENT',
+ *         handler: 'risk_analyser',
+ *         cognitive_layer: CognitiveLayer.REASON,
+ *         agent_role: 'RISK_MANAGER',
+ *       },
+ *     ],
+ *     edges: [{ from: 'retrieve', to: 'analyse' }],
+ *   },
+ *   input: { ticker: 'AAPL', lookback_days: 30 },
+ * });
+ *
+ * console.log(result.status, result.duration_ms);
+ * ```
+ */
+/** Cognitive layer for automatic LLM tier routing. */
+export declare enum CognitiveLayer {
+    /** Ingest signals, alerts, documents, telemetry — cheap model. */
+    PERCEIVE = "PERCEIVE",
+    /** Fetch knowledge, RAG, DB lookups — cheap model. */
+    RETRIEVE = "RETRIEVE",
+    /** Analysis, correlation, synthesis — premium model. */
+    REASON = "REASON",
+    /** Strategy, fix plans, runbooks — premium model. */
+    PLAN = "PLAN",
+    /** Execute tools, APIs, deployments — cheap model. */
+    ACT = "ACT",
+    /** Validate, test, audit, verify — premium model. */
+    EVALUATE = "EVALUATE",
+    /** Summarise, escalate, alert — cheap model. */
+    REPORT = "REPORT"
+}
+/** Execution mode for the matrix. */
+export declare enum ExecutionMode {
+    /** One node at a time in topological order. */
+    SEQUENTIAL = "SEQUENTIAL",
+    /** All nodes concurrently. */
+    PARALLEL = "PARALLEL",
+    /** DAG level-sets: parallel within each level, sequential across levels. */
+    HYBRID = "HYBRID",
+    /** Grouped by CognitiveLayer; each layer's nodes run in parallel. */
+    DIAGONAL = "DIAGONAL"
+}
+/** Node type. */
+export declare enum NodeType {
+    TOOL = "TOOL",
+    AGENT = "AGENT",
+    FUNCTION = "FUNCTION",
+    MCP = "MCP"
+}
+/** Execution status. */
+export declare enum ExecutionStatus {
+    QUEUED = "QUEUED",
+    RUNNING = "RUNNING",
+    COMPLETED = "COMPLETED",
+    FAILED = "FAILED",
+    ABORTED = "ABORTED",
+    TIMEOUT = "TIMEOUT",
+    PARTIAL = "PARTIAL"
+}
+/** Retry policy for a node. */
+export interface RetryPolicy {
+    retries?: number;
+    backoff_seconds?: number;
+    backoff_multiplier?: number;
+    max_backoff_seconds?: number;
+    jitter?: boolean;
+}
+/** Timeout policy for a node. */
+export interface TimeoutPolicy {
+    timeout_seconds: number;
+    hard_kill?: boolean;
+}
+/** Edge connecting two nodes. */
+export interface Edge {
+    /** Source node ID. */
+    from: string;
+    /** Target node ID. */
+    to: string;
+    /** Optional condition expression. */
+    condition?: string;
+    /** Optional label for the dashboard. */
+    label?: string;
+}
+/** A single execution node. */
+export interface Node {
+    id: string;
+    name: string;
+    type: NodeType | string;
+    handler: string;
+    cognitive_layer?: CognitiveLayer | string;
+    agent_role?: string;
+    priority?: number;
+    retry_policy?: RetryPolicy;
+    timeout_policy?: TimeoutPolicy;
+    fallback_node_id?: string;
+    metadata?: Record<string, unknown>;
+    config?: {
+        params?: Record<string, unknown>;
+        env?: Record<string, string>;
+        tags?: string[];
+    };
+}
+/** An execution matrix — the primary AFMX orchestration primitive. */
+export interface ExecutionMatrix {
+    id?: string;
+    name: string;
+    version?: string;
+    mode?: ExecutionMode | string;
+    nodes: Node[];
+    edges?: Edge[];
+    abort_policy?: 'FAIL_FAST' | 'CONTINUE' | 'CRITICAL_ONLY';
+    max_parallelism?: number;
+    global_timeout_seconds?: number;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+}
+/** Result of a single node execution. */
+export interface NodeResult {
+    node_id: string;
+    node_name: string;
+    status: string;
+    output?: unknown;
+    error?: string | null;
+    error_type?: string | null;
+    attempt?: number;
+    duration_ms?: number | null;
+    started_at?: number | null;
+    finished_at?: number | null;
+    metadata?: Record<string, unknown>;
+}
+/** Full execution response. */
+export interface ExecutionResponse {
+    execution_id: string;
+    matrix_id: string;
+    matrix_name: string;
+    status: ExecutionStatus | string;
+    total_nodes: number;
+    completed_nodes: number;
+    failed_nodes: number;
+    skipped_nodes: number;
+    duration_ms?: number | null;
+    error?: string | null;
+    error_node_id?: string | null;
+    node_results: Record<string, NodeResult>;
+    queued_at: number;
+    started_at?: number | null;
+    finished_at?: number | null;
+    tags?: string[];
+}
+/** Status-only response for polling. */
+export interface ExecutionStatusResponse {
+    execution_id: string;
+    status: ExecutionStatus | string;
+    matrix_id: string;
+    matrix_name: string;
+    total_nodes: number;
+    completed_nodes: number;
+    failed_nodes: number;
+    skipped_nodes: number;
+    duration_ms?: number | null;
+    error?: string | null;
+    queued_at: number;
+    started_at?: number | null;
+    finished_at?: number | null;
+}
+/** Cognitive Matrix view for an execution. */
+export interface MatrixViewCell {
+    node_id: string;
+    node_name: string;
+    status: string;
+    duration_ms?: number | null;
+    model_tier?: string | null;
+    model?: string | null;
+    error?: string | null;
+    attempt?: number;
+}
+export interface MatrixViewSummary {
+    total_possible: number;
+    active_cells: number;
+    success_cells: number;
+    failed_cells: number;
+    coverage_pct: number;
+    success_rate: number;
+}
+export interface MatrixViewResponse {
+    execution_id: string;
+    matrix_name: string;
+    status: string;
+    layers: string[];
+    roles: string[];
+    role_meta: Record<string, {
+        description?: string;
+        domain?: string;
+    }>;
+    cells: Record<string, MatrixViewCell>;
+    summary: MatrixViewSummary;
+}
+/** Execute request body. */
+export interface ExecuteRequest {
+    matrix: ExecutionMatrix;
+    input?: unknown;
+    memory?: Record<string, unknown>;
+    variables?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    triggered_by?: string;
+    tags?: string[];
+}
+/** Async execute response. */
+export interface AsyncExecuteResponse {
+    execution_id: string;
+    status: string;
+    message: string;
+    poll_url: string;
+    stream_url: string;
+}
+/** Domain pack. */
+export interface DomainPack {
+    name: string;
+    description: string;
+    roles: Record<string, string>;
+    tags: string[];
+}
+/** Validation response. */
+export interface ValidateResponse {
+    valid: boolean;
+    errors: string[];
+    node_count: number;
+    edge_count: number;
+    execution_order: string[];
+}
+/** HTTP error from the AFMX API. */
+export declare class AFMXError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail: string);
+}
+export interface AFMXClientConfig {
+    /**
+     * Base URL of the AFMX server (e.g. ``"http://localhost:8100"``).
+     * Do NOT include the ``/afmx`` path prefix — the client adds it.
+     */
+    baseUrl: string;
+    /**
+     * Optional API key for RBAC authentication.
+     * Set the ``AFMX_RBAC_ENABLED=true`` env var on the server to require this.
+     */
+    apiKey?: string;
+    /**
+     * Request timeout in milliseconds (default: 30 000).
+     */
+    timeoutMs?: number;
+    /**
+     * Custom fetch implementation (default: globalThis.fetch).
+     * Useful for Node.js 16 environments where fetch is not global.
+     *
+     * @example
+     * ```typescript
+     * import fetch from 'node-fetch';
+     * const client = new AFMXClient({ baseUrl: '...', fetch });
+     * ```
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Type-safe AFMX REST API client.
+ *
+ * Works in any environment with a global ``fetch`` (Node 18+, browser,
+ * Deno, Cloudflare Workers, Vercel Edge).
+ *
+ * @example
+ * ```typescript
+ * const client = new AFMXClient({ baseUrl: 'http://localhost:8100' });
+ *
+ * // Execute synchronously
+ * const result = await client.execute({ matrix, input });
+ *
+ * // Execute asynchronously and poll
+ * const { execution_id } = await client.executeAsync({ matrix, input });
+ * const final = await client.pollUntilDone(execution_id);
+ * ```
+ */
+export declare class AFMXClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly _fetch;
+    constructor(config: AFMXClientConfig);
+    /**
+     * Execute a matrix synchronously.
+     *
+     * Waits for the execution to complete before returning.
+     * For long-running matrices, use {@link executeAsync} + {@link pollUntilDone}.
+     */
+    execute(request: ExecuteRequest): Promise<ExecutionResponse>;
+    /**
+     * Execute a matrix asynchronously (fire-and-forget).
+     *
+     * Returns immediately with an ``execution_id``. Poll via {@link getStatus}
+     * or use {@link pollUntilDone} for a blocking wait.
+     */
+    executeAsync(request: ExecuteRequest): Promise<AsyncExecuteResponse>;
+    /**
+     * Get the current status of an execution.
+     */
+    getStatus(executionId: string): Promise<ExecutionStatusResponse>;
+    /**
+     * Get the full result of a completed execution.
+     */
+    getResult(executionId: string): Promise<ExecutionResponse>;
+    /**
+     * Cancel a running execution.
+     */
+    cancel(executionId: string): Promise<{
+        message: string;
+        status: string;
+    }>;
+    /**
+     * Retry a failed execution.
+     */
+    retry(executionId: string): Promise<{
+        original_execution_id: string;
+        new_execution_id: string;
+        status: string;
+        duration_ms?: number | null;
+    }>;
+    /**
+     * Resume a failed/partial execution from its last checkpoint.
+     */
+    resume(executionId: string): Promise<{
+        original_execution_id: string;
+        new_execution_id: string;
+        status: string;
+        resumed_from_node_count: number;
+        duration_ms?: number | null;
+    }>;
+    /**
+     * Poll an execution until it reaches a terminal state.
+     *
+     * @param executionId  The execution ID from {@link executeAsync}.
+     * @param options.intervalMs  Poll interval (default: 500 ms).
+     * @param options.timeoutMs   Max wait time (default: 300 000 ms / 5 min).
+     *
+     * @throws {AFMXError} if the timeout is exceeded.
+     */
+    pollUntilDone(executionId: string, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<ExecutionResponse>;
+    /**
+     * Validate a matrix definition without executing it.
+     */
+    validate(matrix: ExecutionMatrix): Promise<ValidateResponse>;
+    /**
+     * List recent executions.
+     */
+    listExecutions(options?: {
+        limit?: number;
+        status?: string;
+        matrix_name?: string;
+    }): Promise<{
+        count: number;
+        executions: ExecutionStatusResponse[];
+    }>;
+    /**
+     * Get the Cognitive Matrix view for a completed execution.
+     *
+     * Returns a 2D cell map: ``CognitiveLayer × AgentRole``.
+     * Includes per-cell model tier, cost, duration, and status.
+     */
+    matrixView(executionId: string): Promise<MatrixViewResponse>;
+    /**
+     * List all registered domain packs (tech, finance, healthcare, legal, manufacturing).
+     */
+    listDomains(): Promise<{
+        count: number;
+        domains: DomainPack[];
+    }>;
+    /**
+     * Get a specific domain pack by name.
+     */
+    getDomain(name: string): Promise<DomainPack>;
+    /**
+     * Check AFMX server health.
+     */
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    private _get;
+    private _post;
+}
+/**
+ * Build a simple AFMX node with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const node = buildNode({
+ *   id: 'analyst',
+ *   name: 'analyse-risk',
+ *   handler: 'risk_analyser',
+ *   layer: CognitiveLayer.REASON,
+ *   role: 'RISK_MANAGER',
+ * });
+ * ```
+ */
+export declare function buildNode(opts: {
+    id: string;
+    name: string;
+    handler: string;
+    layer?: CognitiveLayer | string;
+    role?: string;
+    type?: NodeType | string;
+    retries?: number;
+    timeoutSeconds?: number;
+    fallbackNodeId?: string;
+    metadata?: Record<string, unknown>;
+}): Node;
+/**
+ * Build an edge between two nodes.
+ */
+export declare function buildEdge(from: string, to: string, condition?: string): Edge;
+//# 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":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH,sDAAsD;AACtD,oBAAY,cAAc;IACxB,kEAAkE;IAClE,QAAQ,aAAc;IACtB,sDAAsD;IACtD,QAAQ,aAAc;IACtB,wDAAwD;IACxD,MAAM,WAAc;IACpB,qDAAqD;IACrD,IAAI,SAAc;IAClB,sDAAsD;IACtD,GAAG,QAAc;IACjB,qDAAqD;IACrD,QAAQ,aAAc;IACtB,gDAAgD;IAChD,MAAM,WAAc;CACrB;AAED,qCAAqC;AACrC,oBAAY,aAAa;IACvB,+CAA+C;IAC/C,UAAU,eAAe;IACzB,8BAA8B;IAC9B,QAAQ,aAAe;IACvB,4EAA4E;IAC5E,MAAM,WAAe;IACrB,qEAAqE;IACrE,QAAQ,aAAe;CACxB;AAED,iBAAiB;AACjB,oBAAY,QAAQ;IAClB,IAAI,SAAa;IACjB,KAAK,UAAa;IAClB,QAAQ,aAAa;IACrB,GAAG,QAAa;CACjB;AAED,wBAAwB;AACxB,oBAAY,eAAe;IACzB,MAAM,WAAc;IACpB,OAAO,YAAc;IACrB,SAAS,cAAc;IACvB,MAAM,WAAc;IACpB,OAAO,YAAc;IACrB,OAAO,YAAc;IACrB,OAAO,YAAc;CACtB;AAID,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,iCAAiC;AACjC,MAAM,WAAW,IAAI;IACnB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+BAA+B;AAC/B,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;CACH;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC;IAC9B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,YAAY,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,eAAe,CAAC;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACtC,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mBAAmB;AACnB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,2BAA2B;AAC3B,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAID,oCAAoC;AACpC,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM3C;AAID,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,MAAM,EAAE,gBAAgB;IAgBpC;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIlE;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI1E;;OAEG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAItE;;OAEG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIhE;;OAEG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAI/E;;OAEG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QACxC,qBAAqB,EAAE,MAAM,CAAC;QAC9B,gBAAgB,EAAE,MAAM,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IAIF;;OAEG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QACzC,qBAAqB,EAAE,MAAM,CAAC;QAC9B,gBAAgB,EAAE,MAAM,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,uBAAuB,EAAE,MAAM,CAAC;QAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC;IAIF;;;;;;;;OAQG;IACG,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACxD,OAAO,CAAC,iBAAiB,CAAC;IAyB7B;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIlE;;OAEG;IACG,cAAc,CAAC,OAAO,GAAE;QAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,uBAAuB,EAAE,CAAA;KAAE,CAAC;IAW1E;;;;;OAKG;IACG,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMlE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAItE;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAMlD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;YAM9C,IAAI;YAiBJ,KAAK;CAiBpB;AAwBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,IAAI,CAiBP;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAE5E"}

package/dist/index.js

@@ -0,0 +1,380 @@
+"use strict";
+// Copyright 2026 Agentdyne9
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFMXClient = exports.AFMXError = exports.ExecutionStatus = exports.NodeType = exports.ExecutionMode = exports.CognitiveLayer = void 0;
+exports.buildNode = buildNode;
+exports.buildEdge = buildEdge;
+/**
+ * @agentdyne9/afmx — TypeScript SDK for AFMX
+ *
+ * Type-safe client for the AFMX REST API.
+ * Works in Node.js 18+, browser (with fetch), and edge runtimes.
+ *
+ * @example
+ * ```typescript
+ * import { AFMXClient, ExecutionMode, CognitiveLayer } from '@agentdyne9/afmx';
+ *
+ * const client = new AFMXClient({ baseUrl: 'http://localhost:8100' });
+ *
+ * const result = await client.execute({
+ *   matrix: {
+ *     name: 'risk-analysis',
+ *     mode: ExecutionMode.DIAGONAL,
+ *     nodes: [
+ *       {
+ *         id: 'retrieve',
+ *         name: 'retrieve-data',
+ *         type: 'AGENT',
+ *         handler: 'data_retriever',
+ *         cognitive_layer: CognitiveLayer.RETRIEVE,
+ *         agent_role: 'QUANT',
+ *       },
+ *       {
+ *         id: 'analyse',
+ *         name: 'analyse-risk',
+ *         type: 'AGENT',
+ *         handler: 'risk_analyser',
+ *         cognitive_layer: CognitiveLayer.REASON,
+ *         agent_role: 'RISK_MANAGER',
+ *       },
+ *     ],
+ *     edges: [{ from: 'retrieve', to: 'analyse' }],
+ *   },
+ *   input: { ticker: 'AAPL', lookback_days: 30 },
+ * });
+ *
+ * console.log(result.status, result.duration_ms);
+ * ```
+ */
+// ─── Enums ────────────────────────────────────────────────────────────────────
+/** Cognitive layer for automatic LLM tier routing. */
+var CognitiveLayer;
+(function (CognitiveLayer) {
+    /** Ingest signals, alerts, documents, telemetry — cheap model. */
+    CognitiveLayer["PERCEIVE"] = "PERCEIVE";
+    /** Fetch knowledge, RAG, DB lookups — cheap model. */
+    CognitiveLayer["RETRIEVE"] = "RETRIEVE";
+    /** Analysis, correlation, synthesis — premium model. */
+    CognitiveLayer["REASON"] = "REASON";
+    /** Strategy, fix plans, runbooks — premium model. */
+    CognitiveLayer["PLAN"] = "PLAN";
+    /** Execute tools, APIs, deployments — cheap model. */
+    CognitiveLayer["ACT"] = "ACT";
+    /** Validate, test, audit, verify — premium model. */
+    CognitiveLayer["EVALUATE"] = "EVALUATE";
+    /** Summarise, escalate, alert — cheap model. */
+    CognitiveLayer["REPORT"] = "REPORT";
+})(CognitiveLayer || (exports.CognitiveLayer = CognitiveLayer = {}));
+/** Execution mode for the matrix. */
+var ExecutionMode;
+(function (ExecutionMode) {
+    /** One node at a time in topological order. */
+    ExecutionMode["SEQUENTIAL"] = "SEQUENTIAL";
+    /** All nodes concurrently. */
+    ExecutionMode["PARALLEL"] = "PARALLEL";
+    /** DAG level-sets: parallel within each level, sequential across levels. */
+    ExecutionMode["HYBRID"] = "HYBRID";
+    /** Grouped by CognitiveLayer; each layer's nodes run in parallel. */
+    ExecutionMode["DIAGONAL"] = "DIAGONAL";
+})(ExecutionMode || (exports.ExecutionMode = ExecutionMode = {}));
+/** Node type. */
+var NodeType;
+(function (NodeType) {
+    NodeType["TOOL"] = "TOOL";
+    NodeType["AGENT"] = "AGENT";
+    NodeType["FUNCTION"] = "FUNCTION";
+    NodeType["MCP"] = "MCP";
+})(NodeType || (exports.NodeType = NodeType = {}));
+/** Execution status. */
+var ExecutionStatus;
+(function (ExecutionStatus) {
+    ExecutionStatus["QUEUED"] = "QUEUED";
+    ExecutionStatus["RUNNING"] = "RUNNING";
+    ExecutionStatus["COMPLETED"] = "COMPLETED";
+    ExecutionStatus["FAILED"] = "FAILED";
+    ExecutionStatus["ABORTED"] = "ABORTED";
+    ExecutionStatus["TIMEOUT"] = "TIMEOUT";
+    ExecutionStatus["PARTIAL"] = "PARTIAL";
+})(ExecutionStatus || (exports.ExecutionStatus = ExecutionStatus = {}));
+// ─── Error types ──────────────────────────────────────────────────────────────
+/** HTTP error from the AFMX API. */
+class AFMXError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`AFMX API error ${status}: ${detail}`);
+        this.name = 'AFMXError';
+        this.status = status;
+        this.detail = detail;
+    }
+}
+exports.AFMXError = AFMXError;
+// ─── Main client ──────────────────────────────────────────────────────────────
+/**
+ * Type-safe AFMX REST API client.
+ *
+ * Works in any environment with a global ``fetch`` (Node 18+, browser,
+ * Deno, Cloudflare Workers, Vercel Edge).
+ *
+ * @example
+ * ```typescript
+ * const client = new AFMXClient({ baseUrl: 'http://localhost:8100' });
+ *
+ * // Execute synchronously
+ * const result = await client.execute({ matrix, input });
+ *
+ * // Execute asynchronously and poll
+ * const { execution_id } = await client.executeAsync({ matrix, input });
+ * const final = await client.pollUntilDone(execution_id);
+ * ```
+ */
+class AFMXClient {
+    baseUrl;
+    headers;
+    timeoutMs;
+    _fetch;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '') + '/afmx';
+        this.timeoutMs = config.timeoutMs ?? 30_000;
+        this._fetch = config.fetch ?? globalThis.fetch;
+        this.headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': '@agentdyne9/afmx/1.3.0',
+        };
+        if (config.apiKey) {
+            this.headers['X-API-Key'] = config.apiKey;
+        }
+    }
+    // ── Execution ─────────────────────────────────────────────────────────────
+    /**
+     * Execute a matrix synchronously.
+     *
+     * Waits for the execution to complete before returning.
+     * For long-running matrices, use {@link executeAsync} + {@link pollUntilDone}.
+     */
+    async execute(request) {
+        return this._post('/execute', request);
+    }
+    /**
+     * Execute a matrix asynchronously (fire-and-forget).
+     *
+     * Returns immediately with an ``execution_id``. Poll via {@link getStatus}
+     * or use {@link pollUntilDone} for a blocking wait.
+     */
+    async executeAsync(request) {
+        return this._post('/execute/async', request);
+    }
+    /**
+     * Get the current status of an execution.
+     */
+    async getStatus(executionId) {
+        return this._get(`/status/${executionId}`);
+    }
+    /**
+     * Get the full result of a completed execution.
+     */
+    async getResult(executionId) {
+        return this._get(`/result/${executionId}`);
+    }
+    /**
+     * Cancel a running execution.
+     */
+    async cancel(executionId) {
+        return this._post(`/cancel/${executionId}`, {});
+    }
+    /**
+     * Retry a failed execution.
+     */
+    async retry(executionId) {
+        return this._post(`/retry/${executionId}`, {});
+    }
+    /**
+     * Resume a failed/partial execution from its last checkpoint.
+     */
+    async resume(executionId) {
+        return this._post(`/resume/${executionId}`, {});
+    }
+    /**
+     * Poll an execution until it reaches a terminal state.
+     *
+     * @param executionId  The execution ID from {@link executeAsync}.
+     * @param options.intervalMs  Poll interval (default: 500 ms).
+     * @param options.timeoutMs   Max wait time (default: 300 000 ms / 5 min).
+     *
+     * @throws {AFMXError} if the timeout is exceeded.
+     */
+    async pollUntilDone(executionId, options = {}) {
+        const interval = options.intervalMs ?? 500;
+        const timeoutMs = options.timeoutMs ?? 300_000;
+        const deadline = Date.now() + timeoutMs;
+        const terminal = new Set([
+            'COMPLETED', 'FAILED', 'ABORTED', 'TIMEOUT', 'PARTIAL',
+        ]);
+        while (Date.now() < deadline) {
+            const status = await this.getStatus(executionId);
+            if (terminal.has(status.status)) {
+                return this.getResult(executionId);
+            }
+            await _sleep(interval);
+        }
+        throw new AFMXError(408, `Execution '${executionId}' did not complete within ${timeoutMs}ms`);
+    }
+    // ── Matrix management ─────────────────────────────────────────────────────
+    /**
+     * Validate a matrix definition without executing it.
+     */
+    async validate(matrix) {
+        return this._post('/validate', { matrix });
+    }
+    /**
+     * List recent executions.
+     */
+    async listExecutions(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options.status !== undefined)
+            params.set('status_filter', options.status);
+        if (options.matrix_name !== undefined)
+            params.set('matrix_name', options.matrix_name);
+        const qs = params.toString();
+        return this._get(`/executions${qs ? '?' + qs : ''}`);
+    }
+    // ── Cognitive Matrix view ─────────────────────────────────────────────────
+    /**
+     * Get the Cognitive Matrix view for a completed execution.
+     *
+     * Returns a 2D cell map: ``CognitiveLayer × AgentRole``.
+     * Includes per-cell model tier, cost, duration, and status.
+     */
+    async matrixView(executionId) {
+        return this._get(`/matrix-view/${executionId}`);
+    }
+    // ── Domain packs ──────────────────────────────────────────────────────────
+    /**
+     * List all registered domain packs (tech, finance, healthcare, legal, manufacturing).
+     */
+    async listDomains() {
+        return this._get('/domains');
+    }
+    /**
+     * Get a specific domain pack by name.
+     */
+    async getDomain(name) {
+        return this._get(`/domains/${encodeURIComponent(name)}`);
+    }
+    // ── Health ────────────────────────────────────────────────────────────────
+    /**
+     * Check AFMX server health.
+     */
+    async health() {
+        return this._get('/../health');
+    }
+    // ── Internal ──────────────────────────────────────────────────────────────
+    async _get(path) {
+        const url = this.baseUrl + path;
+        const ctrl = new AbortController();
+        const tid = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            const resp = await this._fetch(url, {
+                method: 'GET',
+                headers: this.headers,
+                signal: ctrl.signal,
+            });
+            return _handleResponse(resp);
+        }
+        finally {
+            clearTimeout(tid);
+        }
+    }
+    async _post(path, body) {
+        const url = this.baseUrl + path;
+        const ctrl = new AbortController();
+        const tid = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            const resp = await this._fetch(url, {
+                method: 'POST',
+                headers: this.headers,
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+            });
+            return _handleResponse(resp);
+        }
+        finally {
+            clearTimeout(tid);
+        }
+    }
+}
+exports.AFMXClient = AFMXClient;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+async function _handleResponse(resp) {
+    if (resp.ok) {
+        return (await resp.json());
+    }
+    let detail = `HTTP ${resp.status}`;
+    try {
+        const body = await resp.json();
+        detail = body.detail ?? detail;
+    }
+    catch {
+        // ignore parse failures
+    }
+    throw new AFMXError(resp.status, detail);
+}
+function _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── Convenience builder ──────────────────────────────────────────────────────
+/**
+ * Build a simple AFMX node with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * const node = buildNode({
+ *   id: 'analyst',
+ *   name: 'analyse-risk',
+ *   handler: 'risk_analyser',
+ *   layer: CognitiveLayer.REASON,
+ *   role: 'RISK_MANAGER',
+ * });
+ * ```
+ */
+function buildNode(opts) {
+    return {
+        id: opts.id,
+        name: opts.name,
+        type: opts.type ?? NodeType.AGENT,
+        handler: opts.handler,
+        cognitive_layer: opts.layer,
+        agent_role: opts.role,
+        fallback_node_id: opts.fallbackNodeId,
+        metadata: opts.metadata,
+        ...(opts.retries !== undefined && {
+            retry_policy: { retries: opts.retries },
+        }),
+        ...(opts.timeoutSeconds !== undefined && {
+            timeout_policy: { timeout_seconds: opts.timeoutSeconds },
+        }),
+    };
+}
+/**
+ * Build an edge between two nodes.
+ */
+function buildEdge(from, to, condition) {
+    return { from, to, ...(condition !== undefined && { condition }) };
+}
+// All types are already exported directly above via 'export interface' / 'export class'.
+// No re-export block needed — adding one causes TS2484 (conflicting declarations).
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@inteleion-ai/afmx",
+  "version": "1.3.0",
+  "description": "TypeScript SDK for AFMX — Agent Flow Matrix Execution Engine",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "afmx", "agents", "ai", "orchestration", "multi-agent",
+    "langchain", "openai", "mcp", "model-context-protocol",
+    "semantic-kernel", "google-adk", "bedrock",
+    "cognitive", "matrix", "agentdyne9"
+  ],
+  "author": "Agentdyne9 <hello@agentdyne9.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/inteleion-ai/AFMX.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/inteleion-ai/AFMX/tree/main/sdk/typescript",
+  "bugs": {
+    "url": "https://github.com/inteleion-ai/AFMX/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=18.0.0" },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": ["**/*.test.ts"],
+    "collectCoverageFrom": ["src/**/*.ts"]
+  }
+}