@a5c-ai/agent-runtime 5.0.1-staging.016f0b0e8119

package/dist/observability/webhooks.d.ts

@@ -0,0 +1,68 @@
+/**
+ * GAP-OBS-NEW-001: Dashboard Webhook and Alert System.
+ *
+ * Webhook registration, event filtering, and alert evaluation
+ * for run health changes. Pure functions for registry management
+ * and alert level computation.
+ */
+import type { RunHealthSnapshot } from "./types";
+export type AlertLevel = "info" | "warn" | "critical";
+export type WebhookEventType = "run.health_changed" | "run.completed" | "run.failed" | "run.stuck" | "effect.pending_timeout";
+export interface WebhookRegistration {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    runId?: string;
+    alertLevels?: AlertLevel[];
+    secret?: string;
+    createdAt: string;
+    enabled: boolean;
+}
+export interface WebhookEvent {
+    id: string;
+    type: WebhookEventType;
+    runId: string;
+    alertLevel: AlertLevel;
+    payload: Record<string, unknown>;
+    occurredAt: string;
+}
+export interface WebhookDeliveryResult {
+    webhookId: string;
+    success: boolean;
+    statusCode?: number;
+    error?: string;
+    deliveredAt: string;
+}
+export interface WebhookRegistry {
+    schemaVersion: string;
+    registrations: WebhookRegistration[];
+}
+export type WebhookRegistrationInput = Omit<WebhookRegistration, "id" | "createdAt">;
+export declare const WEBHOOK_SCHEMA_VERSION = "2026.01.webhooks-v1";
+/**
+ * Register a new webhook in the registry.
+ * Mutates the registry and returns the created registration.
+ */
+export declare function registerWebhook(registry: WebhookRegistry, input: WebhookRegistrationInput): WebhookRegistration;
+/**
+ * Remove a webhook by id. Throws if not found.
+ */
+export declare function unregisterWebhook(registry: WebhookRegistry, id: string): void;
+/**
+ * List webhooks, optionally filtered by runId.
+ */
+export declare function listWebhooks(registry: WebhookRegistry, runId?: string): WebhookRegistration[];
+/**
+ * Build a webhook event from a health snapshot.
+ */
+export declare function buildWebhookEvent(type: WebhookEventType, runId: string, snapshot: RunHealthSnapshot): WebhookEvent;
+/**
+ * Evaluate whether a health transition warrants an alert.
+ * Returns the alert level, or null if no alert is needed.
+ */
+export declare function evaluateAlertLevel(prev: RunHealthSnapshot | null, next: RunHealthSnapshot): AlertLevel | null;
+/**
+ * Filter registrations for a given event type and optional alert level.
+ */
+export declare function filterRegistrations(registrations: WebhookRegistration[], eventType: WebhookEventType, alertLevel?: AlertLevel): WebhookRegistration[];
+//# sourceMappingURL=webhooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/observability/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,SAAS,CAAC;AAMlE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,eAAe,GACf,YAAY,GACZ,WAAW,GACX,wBAAwB,CAAC;AAE7B,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,mBAAmB,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC;AAMrF,eAAO,MAAM,sBAAsB,wBAAwB,CAAC;AA0B5D;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,wBAAwB,GAC9B,mBAAmB,CAQrB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,eAAe,EACzB,EAAE,EAAE,MAAM,GACT,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,mBAAmB,EAAE,CAGvB;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,iBAAiB,GAC1B,YAAY,CAad;AAMD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,GAAG,IAAI,EAC9B,IAAI,EAAE,iBAAiB,GACtB,UAAU,GAAG,IAAI,CAgBnB;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,mBAAmB,EAAE,EACpC,SAAS,EAAE,gBAAgB,EAC3B,UAAU,CAAC,EAAE,UAAU,GACtB,mBAAmB,EAAE,CASvB"}

package/dist/observability/webhooks.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * GAP-OBS-NEW-001: Dashboard Webhook and Alert System.
+ *
+ * Webhook registration, event filtering, and alert evaluation
+ * for run health changes. Pure functions for registry management
+ * and alert level computation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_SCHEMA_VERSION = void 0;
+exports.registerWebhook = registerWebhook;
+exports.unregisterWebhook = unregisterWebhook;
+exports.listWebhooks = listWebhooks;
+exports.buildWebhookEvent = buildWebhookEvent;
+exports.evaluateAlertLevel = evaluateAlertLevel;
+exports.filterRegistrations = filterRegistrations;
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+exports.WEBHOOK_SCHEMA_VERSION = "2026.01.webhooks-v1";
+// ---------------------------------------------------------------------------
+// ID generation
+// ---------------------------------------------------------------------------
+function generateId() {
+    // Use crypto.randomUUID for test isolation (no shared mutable counter)
+    return `wh-${crypto.randomUUID()}`;
+}
+// ---------------------------------------------------------------------------
+// Alert level mapping
+// ---------------------------------------------------------------------------
+const STATUS_ALERT_MAP = {
+    healthy: "info",
+    degraded: "warn",
+    stuck: "critical",
+    failed: "critical",
+};
+// ---------------------------------------------------------------------------
+// Registry management (pure, operates on mutable registry)
+// ---------------------------------------------------------------------------
+/**
+ * Register a new webhook in the registry.
+ * Mutates the registry and returns the created registration.
+ */
+function registerWebhook(registry, input) {
+    const registration = {
+        ...input,
+        id: generateId(),
+        createdAt: new Date().toISOString(),
+    };
+    registry.registrations.push(registration);
+    return registration;
+}
+/**
+ * Remove a webhook by id. Throws if not found.
+ */
+function unregisterWebhook(registry, id) {
+    const index = registry.registrations.findIndex((r) => r.id === id);
+    if (index === -1) {
+        throw new Error(`Webhook not found: ${id}`);
+    }
+    registry.registrations.splice(index, 1);
+}
+/**
+ * List webhooks, optionally filtered by runId.
+ */
+function listWebhooks(registry, runId) {
+    if (!runId)
+        return [...registry.registrations];
+    return registry.registrations.filter((r) => r.runId === runId);
+}
+// ---------------------------------------------------------------------------
+// Event building
+// ---------------------------------------------------------------------------
+/**
+ * Build a webhook event from a health snapshot.
+ */
+function buildWebhookEvent(type, runId, snapshot) {
+    return {
+        id: generateId(),
+        type,
+        runId,
+        alertLevel: STATUS_ALERT_MAP[snapshot.status],
+        payload: {
+            status: snapshot.status,
+            metrics: snapshot.metrics,
+            issues: snapshot.issues,
+        },
+        occurredAt: new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Alert level evaluation (pure)
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate whether a health transition warrants an alert.
+ * Returns the alert level, or null if no alert is needed.
+ */
+function evaluateAlertLevel(prev, next) {
+    const prevStatus = prev?.status ?? "healthy";
+    const nextStatus = next.status;
+    if (prevStatus === nextStatus)
+        return null;
+    // Recovery: anything → healthy
+    if (nextStatus === "healthy")
+        return "info";
+    // Degradation
+    if (nextStatus === "degraded")
+        return "warn";
+    // Critical states
+    if (nextStatus === "stuck" || nextStatus === "failed")
+        return "critical";
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Registration filtering
+// ---------------------------------------------------------------------------
+/**
+ * Filter registrations for a given event type and optional alert level.
+ */
+function filterRegistrations(registrations, eventType, alertLevel) {
+    return registrations.filter((r) => {
+        if (!r.enabled)
+            return false;
+        if (!r.events.includes(eventType))
+            return false;
+        if (alertLevel && r.alertLevels && r.alertLevels.length > 0) {
+            if (!r.alertLevels.includes(alertLevel))
+                return false;
+        }
+        return true;
+    });
+}

package/dist/resources/budget-tracker.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Generic budget tracker for token and cost budgets.
+ *
+ * Tracks consumption against a configured limit and fires callbacks
+ * when usage crosses registered threshold percentages.
+ */
+/** Thrown when a `consume` call would exceed the budget limit. */
+export declare class BudgetExceededError extends Error {
+    readonly limit: number;
+    readonly used: number;
+    readonly requested: number;
+    constructor(limit: number, used: number, requested: number);
+}
+/** Result of a `check()` call describing current budget health. */
+export interface BudgetCheck {
+    /** Whether further consumption is allowed. */
+    readonly allowed: boolean;
+    /** Units remaining before the limit is reached. */
+    readonly remaining: number;
+    /** Percentage of the budget consumed (0–100). */
+    readonly percentUsed: number;
+}
+export declare class BudgetTracker {
+    private _limit;
+    private _used;
+    private readonly _thresholds;
+    constructor(limit: number);
+    get limit(): number;
+    get used(): number;
+    get remaining(): number;
+    /**
+     * Consume `amount` units from the budget.
+     *
+     * @throws {BudgetExceededError} if `amount` exceeds `remaining`.
+     */
+    consume(amount: number): void;
+    /**
+     * Release previously consumed units back into the budget.
+     *
+     * The released amount is capped so that `used` never goes below zero.
+     */
+    release(amount: number): void;
+    /** Check the current budget state without mutating it. */
+    check(): BudgetCheck;
+    /**
+     * Register a callback that fires when usage crosses `percent`%.
+     *
+     * @param percent - Threshold percentage (0–100).
+     * @param callback - Function invoked once when the threshold is crossed.
+     */
+    onThreshold(percent: number, callback: () => void): void;
+    /** Reset all usage to zero and re-arm all thresholds. */
+    reset(): void;
+    private _evaluateThresholds;
+}
+//# sourceMappingURL=budget-tracker.d.ts.map

package/dist/resources/budget-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-tracker.d.ts","sourceRoot":"","sources":["../../src/resources/budget-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,kEAAkE;AAClE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAS3D;AAMD,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAkBD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;gBAExC,KAAK,EAAE,MAAM;IAUzB,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAID;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAW7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAe7B,0DAA0D;IAC1D,KAAK,IAAI,WAAW;IAUpB;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAgBxD,yDAAyD;IACzD,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,mBAAmB;CAU5B"}

package/dist/resources/budget-tracker.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Generic budget tracker for token and cost budgets.
+ *
+ * Tracks consumption against a configured limit and fires callbacks
+ * when usage crosses registered threshold percentages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BudgetTracker = exports.BudgetExceededError = void 0;
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+/** Thrown when a `consume` call would exceed the budget limit. */
+class BudgetExceededError extends Error {
+    limit;
+    used;
+    requested;
+    constructor(limit, used, requested) {
+        super(`Budget exceeded: requested ${requested} but only ${limit - used} remaining (limit=${limit}, used=${used})`);
+        this.name = "BudgetExceededError";
+        this.limit = limit;
+        this.used = used;
+        this.requested = requested;
+    }
+}
+exports.BudgetExceededError = BudgetExceededError;
+// ---------------------------------------------------------------------------
+// BudgetTracker
+// ---------------------------------------------------------------------------
+class BudgetTracker {
+    _limit;
+    _used;
+    _thresholds = [];
+    constructor(limit) {
+        if (limit < 0) {
+            throw new RangeError("Budget limit must be non-negative");
+        }
+        this._limit = limit;
+        this._used = 0;
+    }
+    // -- Getters --------------------------------------------------------------
+    get limit() {
+        return this._limit;
+    }
+    get used() {
+        return this._used;
+    }
+    get remaining() {
+        return Math.max(0, this._limit - this._used);
+    }
+    // -- Core API -------------------------------------------------------------
+    /**
+     * Consume `amount` units from the budget.
+     *
+     * @throws {BudgetExceededError} if `amount` exceeds `remaining`.
+     */
+    consume(amount) {
+        if (amount < 0) {
+            throw new RangeError("Consume amount must be non-negative");
+        }
+        if (amount > this.remaining) {
+            throw new BudgetExceededError(this._limit, this._used, amount);
+        }
+        this._used += amount;
+        this._evaluateThresholds();
+    }
+    /**
+     * Release previously consumed units back into the budget.
+     *
+     * The released amount is capped so that `used` never goes below zero.
+     */
+    release(amount) {
+        if (amount < 0) {
+            throw new RangeError("Release amount must be non-negative");
+        }
+        this._used = Math.max(0, this._used - amount);
+        // Re-arm any thresholds that are now above current usage.
+        for (const entry of this._thresholds) {
+            const currentPercent = this._limit === 0 ? 100 : (this._used / this._limit) * 100;
+            if (currentPercent < entry.percent) {
+                entry.fired = false;
+            }
+        }
+    }
+    /** Check the current budget state without mutating it. */
+    check() {
+        const percentUsed = this._limit === 0 ? 100 : (this._used / this._limit) * 100;
+        return {
+            allowed: this.remaining > 0,
+            remaining: this.remaining,
+            percentUsed: Math.min(100, percentUsed),
+        };
+    }
+    /**
+     * Register a callback that fires when usage crosses `percent`%.
+     *
+     * @param percent - Threshold percentage (0–100).
+     * @param callback - Function invoked once when the threshold is crossed.
+     */
+    onThreshold(percent, callback) {
+        if (percent < 0 || percent > 100) {
+            throw new RangeError("Threshold percent must be between 0 and 100");
+        }
+        const entry = { percent, callback, fired: false };
+        this._thresholds.push(entry);
+        // Fire immediately if already past threshold.
+        const currentPercent = this._limit === 0 ? 100 : (this._used / this._limit) * 100;
+        if (currentPercent >= percent) {
+            entry.fired = true;
+            callback();
+        }
+    }
+    /** Reset all usage to zero and re-arm all thresholds. */
+    reset() {
+        this._used = 0;
+        for (const entry of this._thresholds) {
+            entry.fired = false;
+        }
+    }
+    // -- Internals ------------------------------------------------------------
+    _evaluateThresholds() {
+        const currentPercent = this._limit === 0 ? 100 : (this._used / this._limit) * 100;
+        for (const entry of this._thresholds) {
+            if (!entry.fired && currentPercent >= entry.percent) {
+                entry.fired = true;
+                entry.callback();
+            }
+        }
+    }
+}
+exports.BudgetTracker = BudgetTracker;

package/dist/resources/concurrency-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Concurrency guard that limits the number of parallel slots in use.
+ *
+ * Provides both throwing (`acquire`) and non-throwing (`tryAcquire`)
+ * acquisition, as well as an async `waitForSlot` that resolves when a
+ * slot becomes available.
+ */
+/** Thrown when `acquire()` is called with no available slots. */
+export declare class ConcurrencyLimitError extends Error {
+    readonly limit: number;
+    readonly active: number;
+    constructor(limit: number, active: number);
+}
+export declare class ConcurrencyGuard {
+    private readonly _limit;
+    private _active;
+    /** Pending waiters, each resolved when a slot is freed. */
+    private readonly _waiters;
+    constructor(limit: number);
+    /** Number of slots currently in use. */
+    get active(): number;
+    /** Number of slots available for acquisition. */
+    get available(): number;
+    /** Maximum number of parallel slots. */
+    get limit(): number;
+    /**
+     * Acquire a concurrency slot.
+     *
+     * @throws {ConcurrencyLimitError} if no slots are available.
+     */
+    acquire(): void;
+    /**
+     * Try to acquire a concurrency slot without throwing.
+     *
+     * @returns `true` if a slot was acquired, `false` otherwise.
+     */
+    tryAcquire(): boolean;
+    /**
+     * Release a concurrency slot, waking the oldest waiter if any.
+     *
+     * No-ops if no slots are currently active (defensive).
+     */
+    release(): void;
+    /**
+     * Wait asynchronously until a slot becomes available, then acquire it.
+     *
+     * If a slot is already available, the returned promise resolves
+     * immediately (on the microtask queue).
+     *
+     * @param timeoutMs - Optional timeout in milliseconds. Rejects with a
+     *   `ConcurrencyLimitError` if no slot is freed within this duration.
+     */
+    waitForSlot(timeoutMs?: number): Promise<void>;
+}
+//# sourceMappingURL=concurrency-guard.d.ts.map

package/dist/resources/concurrency-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency-guard.d.ts","sourceRoot":"","sources":["../../src/resources/concurrency-guard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,iEAAiE;AACjE,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQ1C;AAMD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,OAAO,CAAS;IACxB,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAEtC,KAAK,EAAE,MAAM;IAUzB,wCAAwC;IACxC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,iDAAiD;IACjD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wCAAwC;IACxC,IAAI,KAAK,IAAI,MAAM,CAElB;IAID;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAOf;;;;OAIG;IACH,UAAU,IAAI,OAAO;IAQrB;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAYf;;;;;;;;OAQG;IACG,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAkCrD"}

package/dist/resources/concurrency-guard.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Concurrency guard that limits the number of parallel slots in use.
+ *
+ * Provides both throwing (`acquire`) and non-throwing (`tryAcquire`)
+ * acquisition, as well as an async `waitForSlot` that resolves when a
+ * slot becomes available.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConcurrencyGuard = exports.ConcurrencyLimitError = void 0;
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+/** Thrown when `acquire()` is called with no available slots. */
+class ConcurrencyLimitError extends Error {
+    limit;
+    active;
+    constructor(limit, active) {
+        super(`Concurrency limit reached: ${active}/${limit} slots in use`);
+        this.name = "ConcurrencyLimitError";
+        this.limit = limit;
+        this.active = active;
+    }
+}
+exports.ConcurrencyLimitError = ConcurrencyLimitError;
+// ---------------------------------------------------------------------------
+// ConcurrencyGuard
+// ---------------------------------------------------------------------------
+class ConcurrencyGuard {
+    _limit;
+    _active;
+    /** Pending waiters, each resolved when a slot is freed. */
+    _waiters = [];
+    constructor(limit) {
+        if (limit < 1) {
+            throw new RangeError("Concurrency limit must be at least 1");
+        }
+        this._limit = limit;
+        this._active = 0;
+    }
+    // -- Getters --------------------------------------------------------------
+    /** Number of slots currently in use. */
+    get active() {
+        return this._active;
+    }
+    /** Number of slots available for acquisition. */
+    get available() {
+        return this._limit - this._active;
+    }
+    /** Maximum number of parallel slots. */
+    get limit() {
+        return this._limit;
+    }
+    // -- Acquisition ----------------------------------------------------------
+    /**
+     * Acquire a concurrency slot.
+     *
+     * @throws {ConcurrencyLimitError} if no slots are available.
+     */
+    acquire() {
+        if (this._active >= this._limit) {
+            throw new ConcurrencyLimitError(this._limit, this._active);
+        }
+        this._active++;
+    }
+    /**
+     * Try to acquire a concurrency slot without throwing.
+     *
+     * @returns `true` if a slot was acquired, `false` otherwise.
+     */
+    tryAcquire() {
+        if (this._active >= this._limit) {
+            return false;
+        }
+        this._active++;
+        return true;
+    }
+    /**
+     * Release a concurrency slot, waking the oldest waiter if any.
+     *
+     * No-ops if no slots are currently active (defensive).
+     */
+    release() {
+        if (this._active <= 0) {
+            return;
+        }
+        this._active--;
+        // Wake the first waiter in line.
+        const waiter = this._waiters.shift();
+        if (waiter) {
+            waiter();
+        }
+    }
+    /**
+     * Wait asynchronously until a slot becomes available, then acquire it.
+     *
+     * If a slot is already available, the returned promise resolves
+     * immediately (on the microtask queue).
+     *
+     * @param timeoutMs - Optional timeout in milliseconds. Rejects with a
+     *   `ConcurrencyLimitError` if no slot is freed within this duration.
+     */
+    async waitForSlot(timeoutMs) {
+        // Fast path: slot available right now.
+        if (this._active < this._limit) {
+            this._active++;
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            let timer;
+            const onSlot = () => {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                this._active++;
+                resolve();
+            };
+            this._waiters.push(onSlot);
+            if (timeoutMs !== undefined && timeoutMs >= 0) {
+                timer = setTimeout(() => {
+                    // Remove this waiter from the queue.
+                    const idx = this._waiters.indexOf(onSlot);
+                    if (idx !== -1) {
+                        this._waiters.splice(idx, 1);
+                    }
+                    reject(new ConcurrencyLimitError(this._limit, this._active));
+                }, timeoutMs);
+            }
+        });
+    }
+}
+exports.ConcurrencyGuard = ConcurrencyGuard;

package/dist/resources/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resources module — budget, concurrency, and timeout management.
+ */
+export type { TokenBudget, CostBudget, ConcurrencyLimits, TimeoutConfig, ResourceSnapshot, BudgetKind, ResourceWarning, ResourceWarningCallback, ResourceManager, } from "./types";
+export { BudgetTracker, BudgetExceededError } from "./budget-tracker";
+export type { BudgetCheck } from "./budget-tracker";
+export { ConcurrencyGuard, ConcurrencyLimitError } from "./concurrency-guard";
+export { TimeoutCascade } from "./timeout-cascade";
+export type { TimeoutHandle } from "./timeout-cascade";
+export { ResourceManagerImpl } from "./manager";
+export type { ResourceManagerOptions } from "./manager";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EACV,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,uBAAuB,EACvB,eAAe,GAChB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACtE,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC"}

package/dist/resources/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Resources module — budget, concurrency, and timeout management.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceManagerImpl = exports.TimeoutCascade = exports.ConcurrencyLimitError = exports.ConcurrencyGuard = exports.BudgetExceededError = exports.BudgetTracker = void 0;
+// Budget tracking
+var budget_tracker_1 = require("./budget-tracker");
+Object.defineProperty(exports, "BudgetTracker", { enumerable: true, get: function () { return budget_tracker_1.BudgetTracker; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return budget_tracker_1.BudgetExceededError; } });
+// Concurrency
+var concurrency_guard_1 = require("./concurrency-guard");
+Object.defineProperty(exports, "ConcurrencyGuard", { enumerable: true, get: function () { return concurrency_guard_1.ConcurrencyGuard; } });
+Object.defineProperty(exports, "ConcurrencyLimitError", { enumerable: true, get: function () { return concurrency_guard_1.ConcurrencyLimitError; } });
+// Timeout cascade
+var timeout_cascade_1 = require("./timeout-cascade");
+Object.defineProperty(exports, "TimeoutCascade", { enumerable: true, get: function () { return timeout_cascade_1.TimeoutCascade; } });
+// Unified manager
+var manager_1 = require("./manager");
+Object.defineProperty(exports, "ResourceManagerImpl", { enumerable: true, get: function () { return manager_1.ResourceManagerImpl; } });

package/dist/resources/manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Unified resource manager that composes budget trackers, a concurrency
+ * guard, and a timeout cascade into the `ResourceManager` interface.
+ */
+import type { BudgetKind, CostBudget, ResourceManager, ResourceSnapshot, ResourceWarningCallback, TokenBudget } from "./types";
+import { ConcurrencyGuard } from "./concurrency-guard";
+import { TimeoutCascade } from "./timeout-cascade";
+/** Options for constructing a `ResourceManagerImpl`. */
+export interface ResourceManagerOptions {
+    /** Token budget limit. */
+    tokenLimit: number;
+    /** Cost budget limit. */
+    costLimit: number;
+    /** ISO 4217 currency code for cost budget. Defaults to "USD". */
+    costCurrency?: string;
+    /** Warning threshold percentage (0–100) for both budgets. */
+    warningThresholdPercent?: number;
+    /** Concurrency limits. */
+    concurrency?: {
+        maxParallelEffects?: number;
+        maxParallelRuns?: number;
+        maxParallelSessions?: number;
+    };
+}
+export declare class ResourceManagerImpl implements ResourceManager {
+    private readonly _tokenBudget;
+    private readonly _costBudget;
+    private readonly _costCurrency;
+    private readonly _warningThresholdPercent;
+    /** Concurrency guard for parallel effects. */
+    readonly effects: ConcurrencyGuard;
+    /** Concurrency guard for parallel runs. */
+    readonly runs: ConcurrencyGuard;
+    /** Concurrency guard for parallel sessions. */
+    readonly sessions: ConcurrencyGuard;
+    /** Timeout cascade for run / iteration / effect timeouts. */
+    readonly timeouts: TimeoutCascade;
+    private readonly _warningCallbacks;
+    constructor(options: ResourceManagerOptions);
+    checkBudget(kind: BudgetKind): TokenBudget | CostBudget;
+    consume(kind: BudgetKind, amount: number): void;
+    release(kind: BudgetKind, amount: number): void;
+    getSnapshot(): ResourceSnapshot;
+    onWarning(callback: ResourceWarningCallback): void;
+    private _trackerFor;
+    private _snapshot;
+    private _fireWarning;
+}
+//# sourceMappingURL=manager.d.ts.map