/**
 * @name premium/session-manager
 * @description In-memory lifecycle manager for premium session plans.
 *
 * When an agent calls `sap_premium_create_session_plan` (via `premium-tools.ts`),
 * this module resolves the requested capability, clamps units/TTL to the
 * capability's pricing bounds, checks provider env readiness, calculates the
 * estimated USD price, and stores the resulting `PremiumSessionRecord` in an
 * in-memory `Map` keyed by session id.
 *
 * Session lifecycle states:
 *
 *   pending_payment → active → closed
 *   pending_payment → expired (if TTL passes before activation)
 *   blocked_requires_provider (if provider env vars are not set)
 *
 * Sessions auto-expire after their TTL and are pruned on every create/list
 * call. A hard cap of 1 000 concurrent session plans prevents unbounded growth.
 *
 * @flow
 *   1. MCP tool `sap_premium_session_start` → `createPremiumSessionPlan()`.
 *   2. MCP tool `sap_premium_activate_session` → `activateSession()`.
 *   3. MCP tool `sap_premium_close_session` → `closeSession()`.
 *   4. MCP tool `sap_premium_session_status` → `getPremiumSession()` / `listPremiumSessions()`.
 *
 * @module premium/session-manager
 */
import type { PremiumActivationResult, PremiumSessionRecord, PremiumSessionRequest } from './types.js';
/**
 * @name createPremiumSessionPlan
 * @description Create and store a premium session plan for a buyer request.
 *
 * Resolution steps:
 *   1. Prune expired/overflow sessions from the store.
 *   2. Look up the capability via `findPremiumCapability` (builtin + private).
 *   3. Clamp `requestedUnits` to [minUnits, maxUnits] and `ttlSeconds` to [60, 3600].
 *   4. Compute `estimatedPriceUsd = requestedUnits × unitPriceUsd`.
 *   5. Check whether all `providerEnv` vars are set in `process.env`.
 *   6. Set status to `blocked_requires_provider` if provider is not ready,
 *      otherwise `pending_payment`.
 *   7. Generate a `sap-premium-<uuid>` session id, store, and return the record.
 *
 * @param request - Buyer-provided session request (plugin, capability, units, TTL).
 * @returns The stored `PremiumSessionRecord` with server-generated fields.
 * @throws {Error} If the plugin/capability pair is not found in the catalog.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_session_start`
 */
export declare function createPremiumSessionPlan(request: PremiumSessionRequest): PremiumSessionRecord;
/**
 * @name getPremiumSession
 * @description Retrieve a session plan by id, lazily marking it as expired.
 *
 * If the session's `expiresAt` has passed and it is not already marked
 * `expired`, the stored record is updated in place and the expired version
 * is returned. A shallow copy is always returned to prevent external mutation
 * of the internal store.
 *
 * @param sessionId - The session id returned by `createPremiumSessionPlan`.
 * @returns The session record, or `null` if not found.
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_session_status`
 */
export declare function getPremiumSession(sessionId: string): PremiumSessionRecord | null;
/**
 * @name listPremiumSessions
 * @description List all non-null session plans after pruning expired entries.
 *
 * @returns Array of all current session records (including lazily-expired ones).
 *
 * @usedBy `premium-tools.ts` → MCP tool `sap_premium_session_status`
 */
export declare function listPremiumSessions(): PremiumSessionRecord[];
/**
 * @name activateSession
 * @description Transition a session from `pending_payment` to `active`.
 *
 * Called by the activation manager after the x402/pay.sh receipt has been
 * verified. The session's `nextAction` is updated to reflect the active state.
 * If the session is not in `pending_payment` status, activation is rejected.
 *
 * @param sessionId - The session id to activate.
 * @returns The activation result with `status=active` on success, or the
 *   blocking status on failure.
 *
 * @usedBy `activation-manager.ts:activateSession`
 */
export declare function activateSession(sessionId: string): PremiumActivationResult;
/**
 * @name closeSession
 * @description Transition an active session to `closed`.
 *
 * Called by the delivery rail when the unit quota is reached, when the buyer
 * explicitly closes the session, or when the server shuts down gracefully.
 *
 * @param sessionId - The session id to close.
 * @param reason    - Human-readable reason for closure.
 * @returns True if the session was closed, false if it was not found or not active.
 *
 * @usedBy `stream-broker.ts`, `webhook-engine.ts`, `premium-tools.ts`
 */
export declare function closeSession(sessionId: string, reason: string): boolean;
/**
 * @name decrementSessionQuota
 * @description Decrement the remaining units quota for an active session.
 *
 * Called by the stream broker / webhook engine after each delivered event.
 * When the quota reaches zero, the session is automatically closed.
 *
 * @param sessionId - The active session id.
 * @returns The remaining units after decrement, or -1 if the session is not active.
 *
 * @usedBy `stream-broker.ts`, `webhook-engine.ts`
 */
export declare function decrementSessionQuota(sessionId: string): number;
/**
 * @name clearAllSessions
 * @description Clear all sessions from the in-memory store.
 *
 * Used in tests and during graceful server shutdown.
 *
 * @internal
 */
export declare function clearAllSessions(): void;
//# sourceMappingURL=session-manager.d.ts.map