@a5c-ai/genty-platform 5.1.1-staging.0007199a1cb2

package/dist/microagents/discovery.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Microagent discovery.
+ *
+ * Scans filesystem directories for `microagent.json` manifest files
+ * and registers discovered manifests into a MicroagentRegistry.
+ * Also provides a helper to seed the registry with built-in manifests
+ * that ship with genty-core.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverMicroagents = discoverMicroagents;
+exports.registerBuiltInMicroagents = registerBuiltInMicroagents;
+exports.registerDiscoveredMicroagents = registerDiscoveredMicroagents;
+const genty_core_1 = require("@a5c-ai/genty-core");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Filesystem discovery
+// ---------------------------------------------------------------------------
+/**
+ * Walk the provided directories and collect every `microagent.json`
+ * manifest found in immediate subdirectories.
+ *
+ * Layout expected:
+ * ```
+ *   <dir>/
+ *     my-agent/
+ *       microagent.json   <-- picked up
+ *     other-agent/
+ *       microagent.json   <-- picked up
+ * ```
+ */
+function discoverMicroagents(dirs) {
+    const manifests = [];
+    for (const dir of dirs) {
+        if (!(0, node_fs_1.existsSync)(dir))
+            continue;
+        const entries = (0, node_fs_1.readdirSync)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const manifestPath = (0, node_path_1.join)(dir, entry.name, "microagent.json");
+            if (!(0, node_fs_1.existsSync)(manifestPath))
+                continue;
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf-8"));
+            manifests.push(raw);
+        }
+    }
+    return manifests;
+}
+// ---------------------------------------------------------------------------
+// Registration helpers
+// ---------------------------------------------------------------------------
+/**
+ * Register all 5 built-in microagents that ship with genty-core.
+ */
+function registerBuiltInMicroagents(registry) {
+    for (const manifest of genty_core_1.builtInManifests) {
+        registry.register(manifest);
+    }
+}
+/**
+ * Discover manifests from directories and register them.
+ * Returns the number of manifests registered.
+ */
+function registerDiscoveredMicroagents(registry, dirs) {
+    const manifests = discoverMicroagents(dirs);
+    for (const m of manifests) {
+        registry.register(m);
+    }
+    return manifests.length;
+}

package/dist/microagents/dispatch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Microagent Dispatcher.
+ *
+ * Wraps a MicroagentRegistry and MicroagentRunner from genty-core
+ * to provide a high-level dispatch API suitable for platform-level
+ * subprocess orchestration.
+ */
+import type { MicroagentInvocation, MicroagentResult } from "@a5c-ai/genty-core";
+/** Any object that can execute a microagent invocation. */
+export interface MicroagentRunnable {
+    run(invocation: MicroagentInvocation): Promise<MicroagentResult>;
+}
+export declare class MicroagentDispatcher {
+    private readonly runner;
+    constructor(runner: MicroagentRunnable);
+    /**
+     * Dispatch a single microagent invocation by name.
+     *
+     * Builds a {@link MicroagentInvocation} from the provided arguments
+     * and delegates to the runner.
+     */
+    dispatch(name: string, input: unknown, opts?: {
+        timeout?: number;
+        correlationId?: string;
+        parentAgentId?: string;
+    }): Promise<MicroagentResult>;
+    /**
+     * Dispatch multiple invocations with a concurrency limit.
+     *
+     * Results are returned in the order invocations complete
+     * (not necessarily the input order). Uses a simple semaphore
+     * pattern to cap concurrent subprocess spawns.
+     */
+    dispatchBatch(invocations: readonly MicroagentInvocation[], concurrency?: number): Promise<MicroagentResult[]>;
+}
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/microagents/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/microagents/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAM5B,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,UAAU,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAClE;AAMD,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,kBAAkB;IAG7C;;;;;OAKG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,gBAAgB,CAAC;IAW5B;;;;;;OAMG;IACG,aAAa,CACjB,WAAW,EAAE,SAAS,oBAAoB,EAAE,EAC5C,WAAW,SAAI,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAiB/B"}

package/dist/microagents/dispatch.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Microagent Dispatcher.
+ *
+ * Wraps a MicroagentRegistry and MicroagentRunner from genty-core
+ * to provide a high-level dispatch API suitable for platform-level
+ * subprocess orchestration.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MicroagentDispatcher = void 0;
+// ---------------------------------------------------------------------------
+// Dispatcher
+// ---------------------------------------------------------------------------
+class MicroagentDispatcher {
+    runner;
+    constructor(runner) {
+        this.runner = runner;
+    }
+    /**
+     * Dispatch a single microagent invocation by name.
+     *
+     * Builds a {@link MicroagentInvocation} from the provided arguments
+     * and delegates to the runner.
+     */
+    async dispatch(name, input, opts) {
+        const invocation = {
+            microagentName: name,
+            input,
+            correlationId: opts?.correlationId,
+            parentAgentId: opts?.parentAgentId,
+            timeout: opts?.timeout,
+        };
+        return this.runner.run(invocation);
+    }
+    /**
+     * Dispatch multiple invocations with a concurrency limit.
+     *
+     * Results are returned in the order invocations complete
+     * (not necessarily the input order). Uses a simple semaphore
+     * pattern to cap concurrent subprocess spawns.
+     */
+    async dispatchBatch(invocations, concurrency = 4) {
+        const results = [];
+        const executing = new Set();
+        for (const invocation of invocations) {
+            const p = this.runner.run(invocation).then((r) => {
+                results.push(r);
+            });
+            executing.add(p);
+            p.finally(() => executing.delete(p));
+            if (executing.size >= concurrency) {
+                await Promise.race(executing);
+            }
+        }
+        await Promise.all(executing);
+        return results;
+    }
+}
+exports.MicroagentDispatcher = MicroagentDispatcher;

package/dist/microagents/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Platform microagent subsystem — barrel exports + factory.
+ *
+ * Wires the core microagent types, registry, and runner into a
+ * platform-level dispatch layer with subprocess enhancements
+ * and filesystem-based discovery.
+ */
+export { MicroagentDispatcher, type MicroagentRunnable } from "./dispatch";
+export { SubprocessMicroagentRunner, type SubprocessRunnerOptions, type SubprocessObserver, } from "./subprocess";
+export { discoverMicroagents, registerBuiltInMicroagents, registerDiscoveredMicroagents, } from "./discovery";
+import { MicroagentRegistry } from "@a5c-ai/genty-core";
+import { MicroagentDispatcher } from "./dispatch";
+import { SubprocessMicroagentRunner } from "./subprocess";
+export interface MicroagentSystemOptions {
+    /** Additional directories to scan for `microagent.json` manifests. */
+    discoveryDirs?: string[];
+    /** Working directory for subprocess spawns. */
+    cwd?: string;
+    /** Max concurrent subprocess microagents. */
+    maxConcurrent?: number;
+}
+/**
+ * Bootstrap a complete microagent system:
+ *
+ * 1. Creates a fresh registry
+ * 2. Seeds it with built-in manifests from genty-core
+ * 3. Optionally discovers additional manifests from disk
+ * 4. Constructs the subprocess runner and dispatcher
+ */
+export declare function createMicroagentSystem(options?: MicroagentSystemOptions): {
+    registry: MicroagentRegistry;
+    runner: SubprocessMicroagentRunner;
+    dispatcher: MicroagentDispatcher;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/microagents/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EACL,0BAA0B,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAU1D,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,uBAAuB;;;;EAevE"}

package/dist/microagents/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Platform microagent subsystem — barrel exports + factory.
+ *
+ * Wires the core microagent types, registry, and runner into a
+ * platform-level dispatch layer with subprocess enhancements
+ * and filesystem-based discovery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDiscoveredMicroagents = exports.registerBuiltInMicroagents = exports.discoverMicroagents = exports.SubprocessMicroagentRunner = exports.MicroagentDispatcher = void 0;
+exports.createMicroagentSystem = createMicroagentSystem;
+var dispatch_1 = require("./dispatch");
+Object.defineProperty(exports, "MicroagentDispatcher", { enumerable: true, get: function () { return dispatch_1.MicroagentDispatcher; } });
+var subprocess_1 = require("./subprocess");
+Object.defineProperty(exports, "SubprocessMicroagentRunner", { enumerable: true, get: function () { return subprocess_1.SubprocessMicroagentRunner; } });
+var discovery_1 = require("./discovery");
+Object.defineProperty(exports, "discoverMicroagents", { enumerable: true, get: function () { return discovery_1.discoverMicroagents; } });
+Object.defineProperty(exports, "registerBuiltInMicroagents", { enumerable: true, get: function () { return discovery_1.registerBuiltInMicroagents; } });
+Object.defineProperty(exports, "registerDiscoveredMicroagents", { enumerable: true, get: function () { return discovery_1.registerDiscoveredMicroagents; } });
+const genty_core_1 = require("@a5c-ai/genty-core");
+const dispatch_2 = require("./dispatch");
+const subprocess_2 = require("./subprocess");
+const discovery_2 = require("./discovery");
+/**
+ * Bootstrap a complete microagent system:
+ *
+ * 1. Creates a fresh registry
+ * 2. Seeds it with built-in manifests from genty-core
+ * 3. Optionally discovers additional manifests from disk
+ * 4. Constructs the subprocess runner and dispatcher
+ */
+function createMicroagentSystem(options) {
+    const registry = new genty_core_1.MicroagentRegistry();
+    (0, discovery_2.registerBuiltInMicroagents)(registry);
+    if (options?.discoveryDirs) {
+        (0, discovery_2.registerDiscoveredMicroagents)(registry, options.discoveryDirs);
+    }
+    const runner = new subprocess_2.SubprocessMicroagentRunner(registry, {
+        cwd: options?.cwd,
+        maxConcurrent: options?.maxConcurrent,
+    });
+    const dispatcher = new dispatch_2.MicroagentDispatcher(runner);
+    return { registry, runner, dispatcher };
+}

package/dist/microagents/subprocess.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Platform-enhanced subprocess runner for microagents.
+ *
+ * Wraps (composes) the core MicroagentRunner to add platform-specific
+ * features: working directory override, concurrency limiting, and
+ * observability hooks.
+ */
+import type { MicroagentInvocation, MicroagentResult } from "@a5c-ai/genty-core";
+import { MicroagentRegistry } from "@a5c-ai/genty-core";
+export interface SubprocessRunnerOptions {
+    /** Working directory for subprocess spawns. */
+    cwd?: string;
+    /** Whether to inherit the parent process environment (default: true). */
+    inheritEnv?: boolean;
+    /** Maximum number of concurrent microagent subprocesses. */
+    maxConcurrent?: number;
+}
+/** Called before and after a microagent subprocess run. */
+export interface SubprocessObserver {
+    onStart?(invocation: MicroagentInvocation): void;
+    onComplete?(invocation: MicroagentInvocation, result: MicroagentResult): void;
+}
+export declare class SubprocessMicroagentRunner {
+    private readonly inner;
+    private readonly options;
+    private activeCount;
+    private waitQueue;
+    private observer?;
+    constructor(registry: MicroagentRegistry, options?: SubprocessRunnerOptions);
+    /** Attach an observer for lifecycle hooks. */
+    setObserver(observer: SubprocessObserver): void;
+    /** Execute a microagent invocation with platform enhancements. */
+    run(invocation: MicroagentInvocation): Promise<MicroagentResult>;
+    /** Current number of in-flight microagent subprocesses. */
+    get active(): number;
+    /** The resolved options this runner was constructed with. */
+    get resolvedOptions(): Readonly<Required<SubprocessRunnerOptions>>;
+    private acquireSlot;
+    private releaseSlot;
+}
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/microagents/subprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/microagents/subprocess.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAoB,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAM1E,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACjD,UAAU,CAAC,CAAC,UAAU,EAAE,oBAAoB,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/E;AAMD,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAC,CAAqB;gBAGpC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,uBAAuB;IAUnC,8CAA8C;IAC9C,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAI/C,kEAAkE;IAC5D,GAAG,CAAC,UAAU,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IActE,2DAA2D;IAC3D,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,6DAA6D;IAC7D,IAAI,eAAe,IAAI,QAAQ,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAC,CAEjE;IAID,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,WAAW;CAKpB"}

package/dist/microagents/subprocess.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Platform-enhanced subprocess runner for microagents.
+ *
+ * Wraps (composes) the core MicroagentRunner to add platform-specific
+ * features: working directory override, concurrency limiting, and
+ * observability hooks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubprocessMicroagentRunner = void 0;
+const genty_core_1 = require("@a5c-ai/genty-core");
+// ---------------------------------------------------------------------------
+// Runner (composition over inheritance — MicroagentRunner is concrete)
+// ---------------------------------------------------------------------------
+class SubprocessMicroagentRunner {
+    inner;
+    options;
+    activeCount = 0;
+    waitQueue = [];
+    observer;
+    constructor(registry, options) {
+        this.inner = new genty_core_1.MicroagentRunner(registry);
+        this.options = {
+            cwd: options?.cwd ?? process.cwd(),
+            inheritEnv: options?.inheritEnv ?? true,
+            maxConcurrent: options?.maxConcurrent ?? 8,
+        };
+    }
+    /** Attach an observer for lifecycle hooks. */
+    setObserver(observer) {
+        this.observer = observer;
+    }
+    /** Execute a microagent invocation with platform enhancements. */
+    async run(invocation) {
+        // Concurrency gate
+        await this.acquireSlot();
+        try {
+            this.observer?.onStart?.(invocation);
+            const result = await this.inner.run(invocation);
+            this.observer?.onComplete?.(invocation, result);
+            return result;
+        }
+        finally {
+            this.releaseSlot();
+        }
+    }
+    /** Current number of in-flight microagent subprocesses. */
+    get active() {
+        return this.activeCount;
+    }
+    /** The resolved options this runner was constructed with. */
+    get resolvedOptions() {
+        return this.options;
+    }
+    // ---- Concurrency semaphore ----
+    acquireSlot() {
+        if (this.activeCount < this.options.maxConcurrent) {
+            this.activeCount++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waitQueue.push(() => {
+                this.activeCount++;
+                resolve();
+            });
+        });
+    }
+    releaseSlot() {
+        this.activeCount--;
+        const next = this.waitQueue.shift();
+        if (next)
+            next();
+    }
+}
+exports.SubprocessMicroagentRunner = SubprocessMicroagentRunner;

package/dist/observability/alertWebhooks.d.ts

@@ -0,0 +1,35 @@
+export interface WebhookConfig {
+    id: string;
+    url: string;
+    events: string[];
+    headers?: Record<string, string>;
+    retryCount?: number;
+}
+export interface AlertRule {
+    condition: 'budget_exceeded' | 'run_failed' | 'stall_detected' | string;
+    webhookId: string;
+    template?: string;
+}
+export interface WebhookEvent {
+    type: string;
+    data: unknown;
+    timestamp: string;
+}
+export declare class WebhookDispatcher {
+    private webhooks;
+    private alertRules;
+    register(config: WebhookConfig): void;
+    unregister(id: string): boolean;
+    addAlertRule(rule: AlertRule): void;
+    dispatch(event: WebhookEvent): Promise<{
+        sent: number;
+        failed: number;
+    }>;
+    evaluateAlerts(runState: {
+        status?: string;
+        budgetExceeded?: boolean;
+        stalled?: boolean;
+    }): WebhookEvent[];
+    private sendWithRetry;
+}
+//# sourceMappingURL=alertWebhooks.d.ts.map

package/dist/observability/alertWebhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alertWebhooks.d.ts","sourceRoot":"","sources":["../../src/observability/alertWebhooks.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,iBAAiB,GAAG,YAAY,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,UAAU,CAAmB;IAErC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIrC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI7B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAW9E,cAAc,CAAC,QAAQ,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,YAAY,EAAE;YAc5F,aAAa;CAmB5B"}

package/dist/observability/alertWebhooks.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookDispatcher = void 0;
+class WebhookDispatcher {
+    webhooks = new Map();
+    alertRules = [];
+    register(config) {
+        this.webhooks.set(config.id, config);
+    }
+    unregister(id) {
+        return this.webhooks.delete(id);
+    }
+    addAlertRule(rule) {
+        this.alertRules.push(rule);
+    }
+    async dispatch(event) {
+        let sent = 0;
+        let failed = 0;
+        for (const [, config] of this.webhooks) {
+            if (!config.events.includes(event.type) && !config.events.includes('*'))
+                continue;
+            const ok = await this.sendWithRetry(config, event);
+            if (ok)
+                sent++;
+            else
+                failed++;
+        }
+        return { sent, failed };
+    }
+    evaluateAlerts(runState) {
+        const events = [];
+        for (const rule of this.alertRules) {
+            let match = false;
+            if (rule.condition === 'budget_exceeded' && runState.budgetExceeded)
+                match = true;
+            if (rule.condition === 'run_failed' && runState.status === 'failed')
+                match = true;
+            if (rule.condition === 'stall_detected' && runState.stalled)
+                match = true;
+            if (match) {
+                events.push({ type: `alert:${rule.condition}`, data: runState, timestamp: new Date().toISOString() });
+            }
+        }
+        return events;
+    }
+    async sendWithRetry(config, event) {
+        const maxRetries = config.retryCount ?? 2;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await fetch(config.url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', ...config.headers },
+                    body: JSON.stringify(event),
+                });
+                if (response.ok)
+                    return true;
+            }
+            catch {
+                // retry
+            }
+            if (attempt < maxRetries) {
+                await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 100));
+            }
+        }
+        return false;
+    }
+}
+exports.WebhookDispatcher = WebhookDispatcher;

package/dist/observability/analytics.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Analytics and feature flags (GAP-OBS-006).
+ *
+ * Provides a FeatureFlagStore for conditional feature enablement and an
+ * AnalyticsCollector for lightweight event tracking within agent sessions.
+ */
+export interface FeatureFlag {
+    id: string;
+    enabled: boolean;
+    /** Rollout percentage (0–100). When set, `enabled` must be true and the flag
+     *  is only active for a fraction of evaluations based on context hashing. */
+    rolloutPercent?: number;
+    description?: string;
+}
+export interface FeatureFlagContext {
+    /** A stable identifier (e.g. user id, session id) for deterministic rollout. */
+    stableId?: string;
+    [key: string]: unknown;
+}
+export declare class FeatureFlagStore {
+    private flags;
+    /**
+     * Check if a flag is enabled, optionally accounting for rollout percentage.
+     */
+    isEnabled(flagId: string, context?: FeatureFlagContext): boolean;
+    /**
+     * Set a flag's enabled state.
+     */
+    setFlag(id: string, enabled: boolean): void;
+    /**
+     * Register or update a full flag definition.
+     */
+    registerFlag(flag: FeatureFlag): void;
+    /**
+     * List all registered flags.
+     */
+    listFlags(): FeatureFlag[];
+    /**
+     * Load flags from a JSON config file. The file should contain an array of
+     * FeatureFlag objects or an object `{ flags: FeatureFlag[] }`.
+     */
+    loadFromConfig(configPath: string): void;
+}
+export interface AnalyticsEvent {
+    type: string;
+    properties: Record<string, unknown>;
+    timestamp: number;
+    sessionId: string;
+}
+export declare class AnalyticsCollector {
+    private events;
+    /**
+     * Track a single analytics event.
+     */
+    track(event: AnalyticsEvent): void;
+    /**
+     * Flush all collected events and reset the internal buffer.
+     * Returns the flushed events for upstream processing.
+     */
+    flush(): AnalyticsEvent[];
+    /**
+     * Get all currently buffered events (without flushing).
+     */
+    getEvents(): readonly AnalyticsEvent[];
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/observability/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/observability/analytics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB;iFAC6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAkBD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,KAAK,CAAkC;IAE/C;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO;IAahE;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAS3C;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAIrC;;OAEG;IACH,SAAS,IAAI,WAAW,EAAE;IAI1B;;;OAGG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAUzC;AAMD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAwB;IAEtC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIlC;;;OAGG;IACH,KAAK,IAAI,cAAc,EAAE;IAMzB;;OAEG;IACH,SAAS,IAAI,SAAS,cAAc,EAAE;CAGvC"}

package/dist/observability/analytics.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Analytics and feature flags (GAP-OBS-006).
+ *
+ * Provides a FeatureFlagStore for conditional feature enablement and an
+ * AnalyticsCollector for lightweight event tracking within agent sessions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsCollector = exports.FeatureFlagStore = void 0;
+const node_fs_1 = require("node:fs");
+// ---------------------------------------------------------------------------
+// Simple deterministic hash for rollout bucketing
+// ---------------------------------------------------------------------------
+function hashToBucket(input) {
+    let h = 0;
+    for (let i = 0; i < input.length; i++) {
+        h = ((h << 5) - h + input.charCodeAt(i)) | 0;
+    }
+    return Math.abs(h) % 100;
+}
+// ---------------------------------------------------------------------------
+// FeatureFlagStore
+// ---------------------------------------------------------------------------
+class FeatureFlagStore {
+    flags = new Map();
+    /**
+     * Check if a flag is enabled, optionally accounting for rollout percentage.
+     */
+    isEnabled(flagId, context) {
+        const flag = this.flags.get(flagId);
+        if (!flag || !flag.enabled)
+            return false;
+        if (flag.rolloutPercent != null && flag.rolloutPercent < 100) {
+            const stableId = context?.stableId ?? flagId;
+            const bucket = hashToBucket(`${flagId}:${stableId}`);
+            return bucket < flag.rolloutPercent;
+        }
+        return true;
+    }
+    /**
+     * Set a flag's enabled state.
+     */
+    setFlag(id, enabled) {
+        const existing = this.flags.get(id);
+        if (existing) {
+            existing.enabled = enabled;
+        }
+        else {
+            this.flags.set(id, { id, enabled });
+        }
+    }
+    /**
+     * Register or update a full flag definition.
+     */
+    registerFlag(flag) {
+        this.flags.set(flag.id, flag);
+    }
+    /**
+     * List all registered flags.
+     */
+    listFlags() {
+        return Array.from(this.flags.values());
+    }
+    /**
+     * Load flags from a JSON config file. The file should contain an array of
+     * FeatureFlag objects or an object `{ flags: FeatureFlag[] }`.
+     */
+    loadFromConfig(configPath) {
+        const raw = (0, node_fs_1.readFileSync)(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const flagArray = Array.isArray(parsed) ? parsed : (parsed.flags ?? []);
+        for (const flag of flagArray) {
+            if (flag.id) {
+                this.flags.set(flag.id, flag);
+            }
+        }
+    }
+}
+exports.FeatureFlagStore = FeatureFlagStore;
+class AnalyticsCollector {
+    events = [];
+    /**
+     * Track a single analytics event.
+     */
+    track(event) {
+        this.events.push(event);
+    }
+    /**
+     * Flush all collected events and reset the internal buffer.
+     * Returns the flushed events for upstream processing.
+     */
+    flush() {
+        const flushed = this.events;
+        this.events = [];
+        return flushed;
+    }
+    /**
+     * Get all currently buffered events (without flushing).
+     */
+    getEvents() {
+        return this.events;
+    }
+}
+exports.AnalyticsCollector = AnalyticsCollector;