network-ai 5.10.1 → 5.11.0

package/dist/esm/lib/lifecycle-hooks.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * OrchestratorLifecycleHooks — Orchestrator-level agent lifecycle hooks.
+ *
+ * Unlike AdapterHookManager (which wraps individual adapter calls), these
+ * hooks wrap the full delegation pipeline: auth → injection scan → adapter
+ * execution → quality gate → result.
+ *
+ * Three phases: `beforeSpawn`, `afterComplete`, `onFailure`.
+ *
+ * @module OrchestratorLifecycleHooks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrchestratorLifecycleHooks = void 0;
+// ============================================================================
+// LIFECYCLE HOOKS MANAGER
+// ============================================================================
+/**
+ * Registry and runner for orchestrator-level lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * const hooks = new OrchestratorLifecycleHooks();
+ *
+ * hooks.beforeSpawn('log-spawn', (ctx) => {
+ *   console.log(`Spawning ${ctx.agentId}: ${ctx.instruction}`);
+ * });
+ *
+ * hooks.afterComplete('track-cost', (ctx) => {
+ *   costTracker.record(ctx.agentId, ctx.tokensUsed, ctx.durationMs);
+ * });
+ *
+ * hooks.onFailure('alert', (ctx) => {
+ *   alerting.send(`${ctx.agentId} failed: ${ctx.error}`);
+ * });
+ * ```
+ */
+class OrchestratorLifecycleHooks {
+    hooks = new Map([
+        ['beforeSpawn', []],
+        ['afterComplete', []],
+        ['onFailure', []],
+    ]);
+    /**
+     * Register a beforeSpawn hook.
+     * Can modify context or set `aborted = true` to block execution.
+     */
+    beforeSpawn(name, handler, priority = 0) {
+        this.register({ name, phase: 'beforeSpawn', priority, handler: handler });
+    }
+    /**
+     * Register an afterComplete hook.
+     * Receives the approved result after quality gate.
+     */
+    afterComplete(name, handler, priority = 0) {
+        this.register({ name, phase: 'afterComplete', priority, handler: handler });
+    }
+    /**
+     * Register an onFailure hook.
+     * Can set `suppress = true` to silently absorb the error.
+     */
+    onFailure(name, handler, priority = 0) {
+        this.register({ name, phase: 'onFailure', priority, handler: handler });
+    }
+    /** Remove a hook by name */
+    unregister(name) {
+        let found = false;
+        for (const [phase, list] of this.hooks) {
+            const idx = list.findIndex(h => h.name === name);
+            if (idx >= 0) {
+                list.splice(idx, 1);
+                this.hooks.set(phase, list);
+                found = true;
+            }
+        }
+        return found;
+    }
+    /** List all registered hooks */
+    list() {
+        const all = [];
+        for (const list of this.hooks.values())
+            all.push(...list);
+        return all;
+    }
+    /** Number of registered hooks */
+    size() {
+        let count = 0;
+        for (const list of this.hooks.values())
+            count += list.length;
+        return count;
+    }
+    /** Clear all hooks */
+    clear() {
+        for (const list of this.hooks.values())
+            list.length = 0;
+    }
+    /**
+     * Run all beforeSpawn hooks in priority order.
+     * Returns the (potentially mutated) context.
+     */
+    async runBeforeSpawn(ctx) {
+        return this.runPhase('beforeSpawn', ctx);
+    }
+    /**
+     * Run all afterComplete hooks in priority order.
+     */
+    async runAfterComplete(ctx) {
+        return this.runPhase('afterComplete', ctx);
+    }
+    /**
+     * Run all onFailure hooks in priority order.
+     * Returns the (potentially mutated) context.
+     */
+    async runOnFailure(ctx) {
+        return this.runPhase('onFailure', ctx);
+    }
+    // --------------------------------------------------------------------------
+    // INTERNAL
+    // --------------------------------------------------------------------------
+    register(entry) {
+        const list = this.hooks.get(entry.phase);
+        if (!list)
+            throw new Error(`Unknown lifecycle phase: ${entry.phase}`);
+        const existing = list.findIndex(h => h.name === entry.name);
+        if (existing >= 0) {
+            list[existing] = entry; // overwrite
+        }
+        else {
+            list.push(entry);
+        }
+        list.sort((a, b) => b.priority - a.priority);
+    }
+    async runPhase(phase, ctx) {
+        const list = this.hooks.get(phase) ?? [];
+        for (const hook of list) {
+            try {
+                await hook.handler(ctx);
+            }
+            catch {
+                // Hook errors are swallowed to prevent one bad hook from
+                // blocking the entire delegation pipeline.
+            }
+        }
+        return ctx;
+    }
+}
+exports.OrchestratorLifecycleHooks = OrchestratorLifecycleHooks;
+//# sourceMappingURL=lifecycle-hooks.js.map

package/dist/esm/lib/lifecycle-hooks.js.map

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