network-ai 3.2.11 → 3.3.0

package/dist/lib/fsm-journey.js

@@ -0,0 +1,476 @@
+"use strict";
+/**
+ * FSM Journey Layer — Phase 4: Behavioral Control Plane
+ *
+ * Implements state machine–based workflow authorization. Agents can only act
+ * in their designated states, and tools can only be called when the current
+ * workflow state permits it.
+ *
+ * @module fsm-journey
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComplianceViolationError = exports.ComplianceMiddleware = exports.JourneyFSM = exports.ToolAuthorizationMatrix = exports.WORKFLOW_STATES = void 0;
+exports.createDeliveryPipelineFSM = createDeliveryPipelineFSM;
+/** Built-in canonical workflow states for common agent pipelines. */
+exports.WORKFLOW_STATES = {
+    INTAKE: 'INTAKE',
+    VALIDATE: 'VALIDATE',
+    RESEARCH: 'RESEARCH',
+    PLAN: 'PLAN',
+    EXECUTE: 'EXECUTE',
+    REVIEW: 'REVIEW',
+    DELIVER: 'DELIVER',
+    COMPLETE: 'COMPLETE',
+    ERROR: 'ERROR',
+};
+// ============================================================================
+// TOOL AUTHORIZATION MATRIX
+// ============================================================================
+/**
+ * Standalone tool authorization matrix.
+ *
+ * Maps `agentId -> state -> allowedTools[]`.
+ * The FSM embeds one automatically, but you can also use this independently.
+ *
+ * @example
+ * ```typescript
+ * const matrix = new ToolAuthorizationMatrix();
+ * matrix.allow('data_analyst', 'RESEARCH', ['search_web', 'query_db']);
+ * matrix.allow('*', 'REVIEW', ['read_blackboard']);
+ * matrix.isAllowed('data_analyst', 'RESEARCH', 'query_db'); // true
+ * ```
+ */
+class ToolAuthorizationMatrix {
+    // agentId -> state -> Set<toolName>
+    rules = new Map();
+    /**
+     * Grant an agent permission to use a list of tools in a given state.
+     * Use `'*'` for agentId or toolNames to mean "all".
+     */
+    allow(agentId, state, tools) {
+        if (!this.rules.has(agentId))
+            this.rules.set(agentId, new Map());
+        const agentRules = this.rules.get(agentId);
+        if (!agentRules.has(state))
+            agentRules.set(state, new Set());
+        const toolSet = agentRules.get(state);
+        for (const t of tools)
+            toolSet.add(t);
+    }
+    /** Revoke a specific tool permission. */
+    revoke(agentId, state, tool) {
+        this.rules.get(agentId)?.get(state)?.delete(tool);
+    }
+    /**
+     * Check if an agent is allowed to use a tool in a given state.
+     * Checks exact agentId first, then falls back to '*' wildcard.
+     */
+    isAllowed(agentId, state, tool) {
+        return (this._check(agentId, state, tool) ||
+            this._check('*', state, tool) ||
+            this._check(agentId, '*', tool) ||
+            this._check('*', '*', tool));
+    }
+    _check(agentId, state, tool) {
+        const tools = this.rules.get(agentId)?.get(state);
+        if (!tools)
+            return false;
+        return tools.has(tool) || tools.has('*');
+    }
+    /** Dump current rules for debugging/audit. */
+    dump() {
+        const out = {};
+        for (const [agent, states] of this.rules) {
+            out[agent] = {};
+            for (const [state, tools] of states) {
+                out[agent][state] = Array.from(tools);
+            }
+        }
+        return out;
+    }
+}
+exports.ToolAuthorizationMatrix = ToolAuthorizationMatrix;
+// ============================================================================
+// JOURNEY FSM
+// ============================================================================
+/**
+ * Finite-state machine for workflow authorization.
+ *
+ * Governs which agents can act (and with which tools) based on the current
+ * workflow state. Integrates an inline `ComplianceMiddleware` and a
+ * `ToolAuthorizationMatrix`.
+ *
+ * @example
+ * ```typescript
+ * import { JourneyFSM, WORKFLOW_STATES } from 'network-ai';
+ *
+ * const fsm = new JourneyFSM({
+ *   states: [
+ *     { name: 'INTAKE',   authorizedAgents: ['orchestrator'],  authorizedTools: { orchestrator: ['read_intake'] } },
+ *     { name: 'RESEARCH', authorizedAgents: ['data_analyst'],  authorizedTools: { data_analyst: ['query_db', 'search_web'] } },
+ *     { name: 'DELIVER',  authorizedAgents: ['orchestrator'],  authorizedTools: { '*': ['write_blackboard'] } },
+ *   ],
+ *   transitions: [
+ *     { from: 'INTAKE',   event: 'start_research', to: 'RESEARCH', allowedBy: 'orchestrator' },
+ *     { from: 'RESEARCH', event: 'research_done',  to: 'DELIVER',  allowedBy: '*' },
+ *   ],
+ *   initialState: 'INTAKE',
+ * });
+ *
+ * fsm.transition('start_research', 'orchestrator'); // moves to RESEARCH
+ * fsm.canAgentAct('data_analyst'); // true — we're now in RESEARCH
+ * ```
+ */
+class JourneyFSM {
+    currentState;
+    stateMap = new Map();
+    transitions;
+    options;
+    stateEnteredAt = Date.now();
+    history = [];
+    /** Embedded tool authorization matrix (populated from state definitions). */
+    toolMatrix;
+    constructor(options) {
+        this.options = options;
+        this.transitions = options.transitions;
+        this.toolMatrix = new ToolAuthorizationMatrix();
+        // Index states
+        for (const s of options.states) {
+            this.stateMap.set(s.name, s);
+            // Populate the tool matrix from state definitions
+            if (s.authorizedTools) {
+                for (const [agentId, tools] of Object.entries(s.authorizedTools)) {
+                    this.toolMatrix.allow(agentId, s.name, tools);
+                }
+            }
+        }
+        if (!this.stateMap.has(options.initialState)) {
+            throw new Error(`Initial state "${options.initialState}" is not defined in states list`);
+        }
+        this.currentState = options.initialState;
+        this.history.push({ state: this.currentState, enteredAt: Date.now() });
+    }
+    // --------------------------------------------------------------------------
+    // State accessors
+    // --------------------------------------------------------------------------
+    /** Current workflow state name. */
+    get state() {
+        return this.currentState;
+    }
+    /** Full definition of the current state. */
+    get stateDefinition() {
+        return this.stateMap.get(this.currentState);
+    }
+    /** How long (ms) the FSM has been in the current state. */
+    get timeInCurrentState() {
+        return Date.now() - this.stateEnteredAt;
+    }
+    /** Whether the current state has timed out. */
+    get isTimedOut() {
+        const def = this.stateDefinition;
+        if (!def.timeoutMs)
+            return false;
+        return this.timeInCurrentState > def.timeoutMs;
+    }
+    /** Full transition history. */
+    get transitionHistory() {
+        return this.history;
+    }
+    // --------------------------------------------------------------------------
+    // Authorization checks
+    // --------------------------------------------------------------------------
+    /**
+     * Check if an agent is authorized to perform any action in the current state.
+     */
+    canAgentAct(agentId) {
+        const def = this.stateDefinition;
+        return def.authorizedAgents.includes('*') || def.authorizedAgents.includes(agentId);
+    }
+    /**
+     * Check if an agent is authorized to use a specific tool in the current state.
+     * Checks both the tool matrix AND agent authorization.
+     */
+    canAgentUseTool(agentId, tool) {
+        if (!this.canAgentAct(agentId))
+            return false;
+        return this.toolMatrix.isAllowed(agentId, this.currentState, tool);
+    }
+    /**
+     * Inline compliance check — call this BEFORE executing any agent action.
+     * Returns `{ allowed: true }` or `{ allowed: false, reason }`.
+     */
+    checkCompliance(agentId, tool) {
+        const canAct = this.canAgentAct(agentId);
+        if (!canAct) {
+            const result = {
+                allowed: false,
+                reason: `Agent "${agentId}" is not authorized in state "${this.currentState}". ` +
+                    `Authorized agents: [${this.stateDefinition.authorizedAgents.join(', ')}]`,
+                currentState: this.currentState,
+                agentId,
+                tool,
+            };
+            this.options.onViolation?.(result);
+            return result;
+        }
+        if (tool) {
+            const canUseTool = this.canAgentUseTool(agentId, tool);
+            if (!canUseTool) {
+                const result = {
+                    allowed: false,
+                    reason: `Agent "${agentId}" is not authorized to use tool "${tool}" in state "${this.currentState}"`,
+                    currentState: this.currentState,
+                    agentId,
+                    tool,
+                };
+                this.options.onViolation?.(result);
+                return result;
+            }
+        }
+        return { allowed: true, currentState: this.currentState, agentId, tool };
+    }
+    // --------------------------------------------------------------------------
+    // Transitions
+    // --------------------------------------------------------------------------
+    /**
+     * Fire a named event to transition the FSM to the next state.
+     * Returns a `TransitionResult` describing what happened.
+     */
+    transition(event, agentId) {
+        const match = this.transitions.find(t => t.from === this.currentState && t.event === event);
+        if (!match) {
+            const result = {
+                success: false,
+                previousState: this.currentState,
+                currentState: this.currentState,
+                reason: `No transition "${event}" defined from state "${this.currentState}"`,
+            };
+            this.options.onTransition?.(result, agentId);
+            return result;
+        }
+        // Check if this agent is allowed to fire this transition
+        if (match.allowedBy && match.allowedBy !== '*' && match.allowedBy !== agentId) {
+            const result = {
+                success: false,
+                previousState: this.currentState,
+                currentState: this.currentState,
+                reason: `Agent "${agentId}" cannot fire event "${event}" (only "${match.allowedBy}" can)`,
+            };
+            this.options.onTransition?.(result, agentId);
+            return result;
+        }
+        if (!this.stateMap.has(match.to)) {
+            const result = {
+                success: false,
+                previousState: this.currentState,
+                currentState: this.currentState,
+                reason: `Target state "${match.to}" is not defined`,
+            };
+            this.options.onTransition?.(result, agentId);
+            return result;
+        }
+        const previous = this.currentState;
+        // Mark exit time on current history entry
+        this.history[this.history.length - 1].exitedAt = Date.now();
+        this.history[this.history.length - 1].triggeredBy = agentId;
+        this.currentState = match.to;
+        this.stateEnteredAt = Date.now();
+        this.history.push({ state: this.currentState, enteredAt: this.stateEnteredAt });
+        const result = {
+            success: true,
+            previousState: previous,
+            currentState: this.currentState,
+        };
+        this.options.onTransition?.(result, agentId);
+        return result;
+    }
+    /**
+     * Returns all events available from the current state.
+     */
+    availableEvents() {
+        return this.transitions
+            .filter(t => t.from === this.currentState)
+            .map(t => t.event);
+    }
+    /**
+     * Returns which agents are authorized in a given state (defaults to current).
+     */
+    getAuthorizedAgents(stateName) {
+        return this.stateMap.get(stateName ?? this.currentState)?.authorizedAgents ?? [];
+    }
+    /**
+     * Reset the FSM to its initial state.
+     */
+    reset() {
+        this.history[this.history.length - 1].exitedAt = Date.now();
+        this.currentState = this.options.initialState;
+        this.stateEnteredAt = Date.now();
+        this.history.push({ state: this.currentState, enteredAt: this.stateEnteredAt });
+    }
+}
+exports.JourneyFSM = JourneyFSM;
+// ============================================================================
+// COMPLIANCE MIDDLEWARE
+// ============================================================================
+/**
+ * Wraps an async action and blocks its execution if the FSM denies it.
+ *
+ * @example
+ * ```typescript
+ * const middleware = new ComplianceMiddleware(fsm);
+ *
+ * const result = await middleware.enforce('data_analyst', 'query_db', async () => {
+ *   return await db.query('SELECT * FROM invoices');
+ * });
+ * ```
+ */
+class ComplianceMiddleware {
+    fsm;
+    constructor(fsm) {
+        this.fsm = fsm;
+    }
+    /**
+     * Enforce compliance before running `action`.
+     * Throws if not authorized; returns the action's result if allowed.
+     */
+    async enforce(agentId, tool, action) {
+        const check = this.fsm.checkCompliance(agentId, tool);
+        if (!check.allowed) {
+            throw new ComplianceViolationError(check.reason ?? 'Compliance check failed', check);
+        }
+        return action();
+    }
+    /**
+     * Synchronous version — use when the action is not async.
+     */
+    enforceSync(agentId, tool, action) {
+        const check = this.fsm.checkCompliance(agentId, tool);
+        if (!check.allowed) {
+            throw new ComplianceViolationError(check.reason ?? 'Compliance check failed', check);
+        }
+        return action();
+    }
+}
+exports.ComplianceMiddleware = ComplianceMiddleware;
+// ============================================================================
+// ERRORS
+// ============================================================================
+/** Thrown when ComplianceMiddleware blocks an action. */
+class ComplianceViolationError extends Error {
+    check;
+    constructor(message, check) {
+        super(message);
+        this.name = 'ComplianceViolationError';
+        this.check = check;
+    }
+}
+exports.ComplianceViolationError = ComplianceViolationError;
+// ============================================================================
+// FACTORY
+// ============================================================================
+/**
+ * Build a standard delivery pipeline FSM with sensible defaults.
+ * States: INTAKE → VALIDATE → RESEARCH → PLAN → EXECUTE → REVIEW → DELIVER → COMPLETE
+ *
+ * @example
+ * ```typescript
+ * const fsm = createDeliveryPipelineFSM({
+ *   orchestratorId: 'orchestrator',
+ *   researchAgentId: 'data_analyst',
+ *   executorId: 'code_writer',
+ * });
+ * ```
+ */
+function createDeliveryPipelineFSM(options) {
+    const orch = options.orchestratorId ?? 'orchestrator';
+    const analyst = options.researchAgentId ?? 'data_analyst';
+    const exec = options.executorId ?? 'code_writer';
+    const reviewer = options.reviewerId ?? 'reviewer';
+    return new JourneyFSM({
+        states: [
+            {
+                name: exports.WORKFLOW_STATES.INTAKE,
+                description: 'Receive and parse the incoming task',
+                authorizedAgents: [orch],
+                authorizedTools: { [orch]: ['read_intake', 'write_blackboard', 'parse_task'] },
+                timeoutMs: 30_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.VALIDATE,
+                description: 'Validate task feasibility and permissions',
+                authorizedAgents: [orch],
+                authorizedTools: { [orch]: ['check_permission', 'validate_schema', 'write_blackboard'] },
+                timeoutMs: 60_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.RESEARCH,
+                description: 'Gather information required for the task',
+                authorizedAgents: [analyst],
+                authorizedTools: { [analyst]: ['query_db', 'search_web', 'read_blackboard', 'write_blackboard'] },
+                timeoutMs: 120_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.PLAN,
+                description: 'Build execution plan from research results',
+                authorizedAgents: [orch],
+                authorizedTools: { [orch]: ['read_blackboard', 'write_blackboard', 'decompose_task'] },
+                timeoutMs: 60_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.EXECUTE,
+                description: 'Execute the planned steps',
+                authorizedAgents: [exec],
+                authorizedTools: { [exec]: ['run_code', 'call_api', 'write_blackboard', 'read_blackboard'] },
+                timeoutMs: 300_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.REVIEW,
+                description: 'Review execution output for quality',
+                authorizedAgents: [reviewer, orch],
+                authorizedTools: {
+                    [reviewer]: ['read_blackboard', 'quality_gate', 'write_review'],
+                    [orch]: ['read_blackboard', 'quality_gate'],
+                },
+                timeoutMs: 120_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.DELIVER,
+                description: 'Deliver results to requesting system',
+                authorizedAgents: [orch],
+                authorizedTools: { [orch]: ['write_output', 'notify', 'write_blackboard'] },
+                timeoutMs: 30_000,
+            },
+            {
+                name: exports.WORKFLOW_STATES.COMPLETE,
+                description: 'Terminal state — workflow complete',
+                authorizedAgents: ['*'],
+                authorizedTools: { '*': ['read_blackboard'] },
+            },
+            {
+                name: exports.WORKFLOW_STATES.ERROR,
+                description: 'Error recovery state',
+                authorizedAgents: [orch, '*'],
+                authorizedTools: { '*': ['read_blackboard', 'write_blackboard'] },
+            },
+        ],
+        transitions: [
+            { from: exports.WORKFLOW_STATES.INTAKE, event: 'validate', to: exports.WORKFLOW_STATES.VALIDATE, allowedBy: orch },
+            { from: exports.WORKFLOW_STATES.VALIDATE, event: 'start_research', to: exports.WORKFLOW_STATES.RESEARCH, allowedBy: orch },
+            { from: exports.WORKFLOW_STATES.VALIDATE, event: 'validation_fail', to: exports.WORKFLOW_STATES.ERROR, allowedBy: orch },
+            { from: exports.WORKFLOW_STATES.RESEARCH, event: 'research_done', to: exports.WORKFLOW_STATES.PLAN, allowedBy: analyst },
+            { from: exports.WORKFLOW_STATES.RESEARCH, event: 'research_fail', to: exports.WORKFLOW_STATES.ERROR, allowedBy: analyst },
+            { from: exports.WORKFLOW_STATES.PLAN, event: 'execute', to: exports.WORKFLOW_STATES.EXECUTE, allowedBy: orch },
+            { from: exports.WORKFLOW_STATES.EXECUTE, event: 'execution_done', to: exports.WORKFLOW_STATES.REVIEW, allowedBy: exec },
+            { from: exports.WORKFLOW_STATES.EXECUTE, event: 'execution_fail', to: exports.WORKFLOW_STATES.ERROR, allowedBy: exec },
+            { from: exports.WORKFLOW_STATES.REVIEW, event: 'approved', to: exports.WORKFLOW_STATES.DELIVER, allowedBy: '*' },
+            { from: exports.WORKFLOW_STATES.REVIEW, event: 'rejected', to: exports.WORKFLOW_STATES.EXECUTE, allowedBy: '*' },
+            { from: exports.WORKFLOW_STATES.DELIVER, event: 'delivered', to: exports.WORKFLOW_STATES.COMPLETE, allowedBy: orch },
+            { from: exports.WORKFLOW_STATES.ERROR, event: 'retry', to: exports.WORKFLOW_STATES.INTAKE, allowedBy: orch },
+            { from: exports.WORKFLOW_STATES.ERROR, event: 'abort', to: exports.WORKFLOW_STATES.COMPLETE, allowedBy: orch },
+        ],
+        initialState: exports.WORKFLOW_STATES.INTAKE,
+        onTransition: options.onTransition,
+        onViolation: options.onViolation,
+    });
+}
+//# sourceMappingURL=fsm-journey.js.map

package/dist/lib/fsm-journey.js.map

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

package/dist/lib/mcp-blackboard-tools.d.ts

@@ -0,0 +1,126 @@
+/**
+ * MCP Blackboard Tool Bindings — Phase 4: Behavioral Control Plane
+ *
+ * Exposes the shared blackboard as MCP-compatible tool definitions so any
+ * LLM agent can interact with shared state via standard tool calls.
+ *
+ * Tools exposed:
+ *   - blackboard_read    — read a single entry by key
+ *   - blackboard_write   — write a value to the blackboard
+ *   - blackboard_list    — list all keys (optionally filtered by prefix)
+ *   - blackboard_delete  — delete an entry by key
+ *   - blackboard_exists  — check whether a key is present and not expired
+ *
+ * @module mcp-blackboard-tools
+ */
+/** JSON Schema subset sufficient for MCP tool descriptors. */
+export interface MCPJsonSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: string[];
+    }>;
+    required?: string[];
+}
+/** MCP tool definition (matches Model Context Protocol spec). */
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: MCPJsonSchema;
+}
+/** Normalised result returned by every blackboard tool call. */
+export interface BlackboardToolResult {
+    ok: boolean;
+    tool: string;
+    data?: unknown;
+    error?: string;
+}
+/** Minimal interface required by the tool bindings. */
+export interface IBlackboard {
+    read(key: string): {
+        key: string;
+        value: unknown;
+        sourceAgent: string;
+        timestamp: string;
+        ttl: number | null;
+    } | null;
+    write(key: string, value: unknown, sourceAgent: string, ttl?: number, agentToken?: string): {
+        key: string;
+        value: unknown;
+        sourceAgent: string;
+        timestamp: string;
+        ttl: number | null;
+    };
+    exists(key: string): boolean;
+    getSnapshot(): Record<string, {
+        key: string;
+        value: unknown;
+        sourceAgent: string;
+        timestamp: string;
+        ttl: number | null;
+    }>;
+    delete?: (key: string) => void;
+    getScopedSnapshot?: (agentId: string) => Record<string, unknown>;
+}
+/** MCP tool definitions for all five blackboard operations. */
+export declare const BLACKBOARD_TOOL_DEFINITIONS: MCPToolDefinition[];
+/**
+ * MCP-compatible tool handler wrapping a {@link IBlackboard} instance.
+ *
+ * Register it with any MCP adapter to expose shared blackboard operations
+ * as callable tools for LLM agents.
+ *
+ * @example
+ * ```typescript
+ * import { BlackboardMCPTools } from 'network-ai';
+ *
+ * const tools = new BlackboardMCPTools(orchestrator.blackboard);
+ *
+ * // Register with the MCP adapter
+ * for (const def of tools.getDefinitions()) {
+ *   mcpAdapter.registerTool(def.name, (args) => tools.call(def.name, args), def);
+ * }
+ *
+ * // Or call directly for testing
+ * const result = await tools.call('blackboard_read', {
+ *   key: 'task:q3_analysis',
+ *   agent_id: 'data_analyst',
+ * });
+ * ```
+ */
+export declare class BlackboardMCPTools {
+    private readonly blackboard;
+    constructor(blackboard: IBlackboard);
+    /** Returns all MCP tool definitions for this blackboard instance. */
+    getDefinitions(): MCPToolDefinition[];
+    /**
+     * Dispatch a tool call by name. `args` should match the tool's inputSchema.
+     * All errors are caught and returned as `{ ok: false, error }`.
+     */
+    call(toolName: string, args: Record<string, unknown>): Promise<BlackboardToolResult>;
+    private _read;
+    private _write;
+    private _list;
+    private _delete;
+    private _exists;
+    private _requireString;
+}
+/**
+ * Convenience factory: create a `BlackboardMCPTools` instance and register
+ * all tools on an MCPAdapter in one call.
+ *
+ * @example
+ * ```typescript
+ * import { registerBlackboardTools } from 'network-ai';
+ *
+ * registerBlackboardTools(mcpAdapter, orchestrator.getBlackboard());
+ * ```
+ */
+export declare function registerBlackboardTools(mcpAdapter: {
+    registerTool(name: string, handler: (args: Record<string, unknown>) => Promise<unknown>, metadata?: {
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    }): void;
+}, blackboard: IBlackboard): BlackboardMCPTools;
+//# sourceMappingURL=mcp-blackboard-tools.d.ts.map

package/dist/lib/mcp-blackboard-tools.d.ts.map

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