@sovovs/bycli 2.1.39 → 2.1.41

package/dist/src/adapter-coordination.js

@@ -0,0 +1,183 @@
+import { acquireAdapterLease, heartbeatAdapterLease, releaseAdapterLease, acquireAdapterResources, releaseAdapterResources, } from './browser/daemon-client.js';
+import { log } from './logger.js';
+import { AdapterCoordinationError } from './errors.js';
+import { getAdapterExecutionContext, runWithAdapterExecutionContext, } from './adapter-execution-context.js';
+export function getCurrentAdapterLease() {
+    return getAdapterExecutionContext()?.lease;
+}
+/**
+ * Renew the active lease immediately before an irreversible local publication.
+ * A restarted daemon or reclaimed lease rejects this fencing check.
+ */
+export async function assertCurrentAdapterLease(dependencies = {}) {
+    const context = getAdapterExecutionContext();
+    if (!context)
+        return;
+    try {
+        context.lease = await (dependencies.heartbeat ?? heartbeatAdapterLease)(context.lease);
+    }
+    catch (error) {
+        if (error instanceof AdapterCoordinationError && error.code === 'ADAPTER_LEASE_LOST')
+            throw error;
+        throw new AdapterCoordinationError('ADAPTER_LEASE_LOST', 'Adapter lease fencing failed before artifact publication.', true);
+    }
+}
+export async function settleAdapterOperationAfterTimeout(operation, timeoutMs, timeoutError, stop) {
+    const outcome = operation.then(value => ({ kind: 'value', value }), error => ({ kind: 'error', error }));
+    let timeout;
+    const first = await Promise.race([
+        outcome,
+        new Promise(resolve => {
+            timeout = setTimeout(() => resolve({ kind: 'timeout' }), timeoutMs);
+        }),
+    ]);
+    if (first.kind !== 'timeout') {
+        if (timeout)
+            clearTimeout(timeout);
+        if (first.kind === 'error')
+            throw first.error;
+        return first.value;
+    }
+    try {
+        await stop();
+    }
+    finally {
+        await outcome;
+    }
+    throw timeoutError;
+}
+export async function withAdapterResourceLocks(keys, operation, dependencies = {}) {
+    const lease = getCurrentAdapterLease();
+    if (!lease)
+        return operation();
+    const acquire = dependencies.acquire ?? acquireAdapterResources;
+    const release = dependencies.release ?? releaseAdapterResources;
+    const warn = dependencies.warn ?? ((message) => log.warn(message));
+    const scopedKeys = keys.map(key => key.startsWith('article:') || key.startsWith('data:')
+        ? `profile:${lease.contextId}:${key}`
+        : key);
+    const grant = await acquire(lease, scopedKeys, dependencies.timeoutMs ?? 300_000);
+    try {
+        return await operation();
+    }
+    finally {
+        let released = false;
+        let lastError;
+        for (let attempt = 0; attempt < 2 && !released; attempt++) {
+            try {
+                await release(lease, grant.grantId);
+                released = true;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        if (!released) {
+            warn(`Adapter resource release acknowledgement failed for ${grant.grantId}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+        }
+    }
+}
+export async function withAdapterCommandLease(request, operation, dependencies = {}) {
+    const acquire = dependencies.acquire ?? acquireAdapterLease;
+    const heartbeat = dependencies.heartbeat ?? heartbeatAdapterLease;
+    const release = dependencies.release ?? releaseAdapterLease;
+    const warn = dependencies.warn ?? ((message) => log.warn(message));
+    const heartbeatIntervalMs = dependencies.heartbeatIntervalMs ?? 10_000;
+    const context = { lease: await acquire(request) };
+    let releaseReason = 'error';
+    let leaseLost;
+    let stopAfterLeaseLoss;
+    let heartbeatTask;
+    const heartbeatTimer = setInterval(() => {
+        if (heartbeatTask || leaseLost)
+            return;
+        heartbeatTask = heartbeat(context.lease)
+            .then(next => { context.lease = next; })
+            .catch(error => {
+            const code = error && typeof error === 'object' ? error.code : undefined;
+            if (code === 'ADAPTER_LEASE_LOST') {
+                leaseLost = error;
+                stopAfterLeaseLoss = (dependencies.onLeaseLost?.() ?? Promise.resolve()).catch(stopError => {
+                    warn(`Adapter operation stop failed after lease loss for ${context.lease.requestId}: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                });
+            }
+            else {
+                warn(`Adapter lease heartbeat failed for ${context.lease.requestId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        })
+            .finally(() => { heartbeatTask = undefined; });
+    }, heartbeatIntervalMs);
+    heartbeatTimer.unref?.();
+    try {
+        let result;
+        try {
+            result = await runWithAdapterExecutionContext(context, operation);
+        }
+        catch (error) {
+            if (heartbeatTask)
+                await heartbeatTask;
+            if (stopAfterLeaseLoss)
+                await stopAfterLeaseLoss;
+            if (leaseLost)
+                throw leaseLost;
+            throw error;
+        }
+        if (heartbeatTask)
+            await heartbeatTask;
+        if (stopAfterLeaseLoss)
+            await stopAfterLeaseLoss;
+        if (leaseLost)
+            throw leaseLost;
+        releaseReason = classifyAdapterResult(result);
+        return result;
+    }
+    catch (error) {
+        releaseReason = classifyAdapterError(error);
+        throw error;
+    }
+    finally {
+        clearInterval(heartbeatTimer);
+        const payload = { ...context.lease, reason: releaseReason };
+        let released = false;
+        let lastError;
+        for (let attempt = 0; attempt < 2 && !released; attempt++) {
+            try {
+                await release(payload);
+                released = true;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        if (!released) {
+            warn(`Adapter lease release acknowledgement failed for ${payload.requestId}: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+        }
+    }
+}
+function classifyAdapterError(error) {
+    const code = error && typeof error === 'object' && typeof error.code === 'string'
+        ? error.code
+        : '';
+    if (code === 'AUTH_REQUIRED' || /CAPTCHA|MFA|VERIFICATION/.test(code))
+        return 'auth_gate';
+    if (code === 'RATE_LIMITED')
+        return 'rate_limited';
+    if (code === 'TIMEOUT')
+        return 'timeout';
+    return 'error';
+}
+function classifyAdapterResult(result) {
+    const rows = Array.isArray(result) ? result : [result];
+    const statuses = rows
+        .filter(row => row && typeof row === 'object')
+        .map(row => String(row.status ?? '').toLowerCase());
+    if (statuses.some(status => /auth|login|captcha|verification|mfa/.test(status)))
+        return 'auth_gate';
+    if (statuses.some(status => /rate.?limit/.test(status)))
+        return 'rate_limited';
+    if (statuses.some(status => status === 'partial'))
+        return 'partial';
+    if (statuses.length > 0 && statuses.every(status => status.startsWith('failed') || status.startsWith('failure')))
+        return 'failed';
+    return 'success';
+}

package/dist/src/adapter-coordination.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/adapter-execution-context.d.ts

@@ -0,0 +1,6 @@
+import type { AdapterLease } from './adapter-scheduler.js';
+export interface AdapterExecutionContext {
+    lease: AdapterLease;
+}
+export declare function getAdapterExecutionContext(): AdapterExecutionContext | undefined;
+export declare function runWithAdapterExecutionContext<T>(context: AdapterExecutionContext, operation: () => Promise<T>): Promise<T>;

package/dist/src/adapter-execution-context.js

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function getAdapterExecutionContext() {
+    return storage.getStore();
+}
+export function runWithAdapterExecutionContext(context, operation) {
+    return storage.run(context, operation);
+}

package/dist/src/adapter-scheduler.d.ts

@@ -0,0 +1,86 @@
+export type AdapterPoolCloseReason = 'auth_gate' | 'rate_limited';
+export type AdapterReleaseReason = 'success' | 'partial' | 'failed' | AdapterPoolCloseReason | 'timeout' | 'error' | 'cancelled';
+export interface AdapterLeaseRequest {
+    requestId: string;
+    contextId: string;
+    surface: 'adapter';
+    site: string;
+    adapterSession: string;
+    sessionKey: string;
+    queueTimeoutMs: number;
+    maxParallel: number;
+}
+export interface AdapterLease {
+    leaseId: string;
+    requestId: string;
+    poolKey: string;
+    contextId: string;
+    surface: 'adapter';
+    site: string;
+    adapterSession: string;
+    sessionKey: string;
+    generation: number;
+    grantedAt: number;
+    heartbeatDeadline: number;
+}
+export interface AdapterLeaseRelease extends AdapterLease {
+    reason: AdapterReleaseReason;
+}
+export declare class AdapterSchedulerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface AdapterResourceGrant {
+    grantId: string;
+    leaseId: string;
+    keys: string[];
+}
+export interface AdapterSchedulerOptions {
+    now?: () => number;
+    leaseExpiryMs?: number;
+    runtimeCeiling?: number;
+    releasedLeaseRetentionMs?: number;
+}
+export declare class AdapterScheduler {
+    private readonly now;
+    private readonly leaseExpiryMs;
+    private readonly runtimeCeiling;
+    private readonly releasedLeaseRetentionMs;
+    private readonly pools;
+    private readonly releasedLeaseIds;
+    private readonly generations;
+    private readonly resourceOwners;
+    private readonly resourceGrants;
+    private readonly resourceQueue;
+    private sequence;
+    constructor(options?: AdapterSchedulerOptions);
+    acquire(request: AdapterLeaseRequest): Promise<AdapterLease>;
+    heartbeat(identity: AdapterLease): AdapterLease;
+    assertLease(identity: AdapterLease): AdapterLease;
+    release(release: AdapterLeaseRelease): boolean;
+    acquireResources(leaseIdentity: AdapterLease, rawKeys: string[], timeoutMs: number): Promise<AdapterResourceGrant>;
+    releaseResources(leaseIdentity: AdapterLease, grantId: string): boolean;
+    cancel(requestId: string, code?: string): boolean;
+    sweepExpired(): void;
+    reset(): void;
+    snapshot(): {
+        running: number;
+        queued: number;
+        pools: number;
+    };
+    resourceSnapshot(): {
+        locked: number;
+        queued: number;
+        grants: number;
+    };
+    private schedule;
+    private scheduleResources;
+    private releaseAllResourcesForLease;
+    private pruneReleasedLeaseIds;
+    private rejectResourceWaitersForLease;
+    private requireLease;
+    private getOrCreatePool;
+    private removeDrainedPool;
+    private poolClosedError;
+    private validateRequest;
+}

package/dist/src/adapter-scheduler.js

@@ -0,0 +1,349 @@
+import * as crypto from 'node:crypto';
+export class AdapterSchedulerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AdapterSchedulerError';
+    }
+}
+export class AdapterScheduler {
+    now;
+    leaseExpiryMs;
+    runtimeCeiling;
+    releasedLeaseRetentionMs;
+    pools = new Map();
+    releasedLeaseIds = new Map();
+    generations = new Map();
+    resourceOwners = new Map();
+    resourceGrants = new Map();
+    resourceQueue = [];
+    sequence = 0;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.leaseExpiryMs = options.leaseExpiryMs ?? 45_000;
+        this.runtimeCeiling = options.runtimeCeiling ?? 3;
+        this.releasedLeaseRetentionMs = options.releasedLeaseRetentionMs ?? 300_000;
+    }
+    acquire(request) {
+        this.validateRequest(request);
+        const pool = this.getOrCreatePool(request);
+        if (pool.closed) {
+            return Promise.reject(this.poolClosedError(pool.closed));
+        }
+        pool.maxParallel = Math.min(pool.maxParallel, request.maxParallel, this.runtimeCeiling);
+        if ([...pool.running.values()].some(lease => lease.requestId === request.requestId)
+            || pool.queued.some(entry => entry.request.requestId === request.requestId)) {
+            return Promise.reject(new AdapterSchedulerError('ADAPTER_QUEUE_RESET', 'Duplicate Adapter lease request id'));
+        }
+        return new Promise((resolve, reject) => {
+            const enqueuedAt = this.now();
+            const pending = {
+                request,
+                enqueuedAt,
+                deadline: enqueuedAt + request.queueTimeoutMs,
+                sequence: ++this.sequence,
+                resolve,
+                reject,
+            };
+            pending.timer = setTimeout(() => this.sweepExpired(), request.queueTimeoutMs);
+            pending.timer.unref?.();
+            pool.queued.push(pending);
+            this.schedule(pool);
+        });
+    }
+    heartbeat(identity) {
+        const lease = this.requireLease(identity);
+        lease.heartbeatDeadline = this.now() + this.leaseExpiryMs;
+        return { ...lease };
+    }
+    assertLease(identity) {
+        return { ...this.requireLease(identity) };
+    }
+    release(release) {
+        this.pruneReleasedLeaseIds();
+        if (this.releasedLeaseIds.has(release.leaseId))
+            return false;
+        const lease = this.requireLease(release);
+        const pool = this.pools.get(lease.poolKey);
+        this.releaseAllResourcesForLease(lease.leaseId);
+        this.rejectResourceWaitersForLease(lease.leaseId);
+        pool.running.delete(lease.leaseId);
+        pool.activeSessions.delete(lease.adapterSession);
+        this.releasedLeaseIds.set(lease.leaseId, this.now() + this.releasedLeaseRetentionMs);
+        if (release.reason === 'auth_gate' || release.reason === 'rate_limited') {
+            pool.closed = release.reason;
+            const error = this.poolClosedError(release.reason);
+            for (const pending of pool.queued.splice(0)) {
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.reject(error);
+            }
+        }
+        else {
+            this.schedule(pool);
+        }
+        this.scheduleResources();
+        this.removeDrainedPool(pool);
+        return true;
+    }
+    acquireResources(leaseIdentity, rawKeys, timeoutMs) {
+        const lease = this.requireLease(leaseIdentity);
+        const keys = [...new Set(rawKeys.map(key => key.trim()).filter(Boolean))].sort();
+        if (keys.length === 0) {
+            return Promise.reject(new AdapterSchedulerError('ADAPTER_RESOURCE_TIMEOUT', 'At least one resource key is required'));
+        }
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+            return Promise.reject(new AdapterSchedulerError('ADAPTER_RESOURCE_TIMEOUT', 'Invalid Adapter resource timeout'));
+        }
+        return new Promise((resolve, reject) => {
+            const pending = {
+                lease: { ...lease },
+                keys,
+                deadline: this.now() + timeoutMs,
+                sequence: ++this.sequence,
+                resolve,
+                reject,
+            };
+            pending.timer = setTimeout(() => this.sweepExpired(), timeoutMs);
+            pending.timer.unref?.();
+            this.resourceQueue.push(pending);
+            this.scheduleResources();
+        });
+    }
+    releaseResources(leaseIdentity, grantId) {
+        const lease = this.requireLease(leaseIdentity);
+        const grant = this.resourceGrants.get(grantId);
+        if (!grant || grant.leaseId !== lease.leaseId) {
+            throw new AdapterSchedulerError('ADAPTER_LEASE_LOST', 'Adapter resource grant is no longer valid');
+        }
+        this.resourceGrants.delete(grantId);
+        for (const key of grant.keys) {
+            const owner = this.resourceOwners.get(key);
+            if (owner?.grantId === grantId)
+                this.resourceOwners.delete(key);
+        }
+        this.scheduleResources();
+        return true;
+    }
+    cancel(requestId, code = 'ADAPTER_QUEUE_RESET') {
+        for (const pool of this.pools.values()) {
+            const index = pool.queued.findIndex(entry => entry.request.requestId === requestId);
+            if (index === -1)
+                continue;
+            const [pending] = pool.queued.splice(index, 1);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new AdapterSchedulerError(code, 'Adapter lease request was cancelled'));
+            this.removeDrainedPool(pool);
+            return true;
+        }
+        return false;
+    }
+    sweepExpired() {
+        const now = this.now();
+        this.pruneReleasedLeaseIds(now);
+        for (const pool of [...this.pools.values()]) {
+            for (const pending of [...pool.queued]) {
+                if (pending.deadline > now)
+                    continue;
+                pool.queued.splice(pool.queued.indexOf(pending), 1);
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.reject(new AdapterSchedulerError('ADAPTER_QUEUE_TIMEOUT', 'Timed out waiting for an Adapter command lease'));
+            }
+            for (const lease of [...pool.running.values()]) {
+                if (lease.heartbeatDeadline > now)
+                    continue;
+                this.releaseAllResourcesForLease(lease.leaseId);
+                this.rejectResourceWaitersForLease(lease.leaseId);
+                pool.running.delete(lease.leaseId);
+                pool.activeSessions.delete(lease.adapterSession);
+            }
+            if (!pool.closed)
+                this.schedule(pool);
+            this.removeDrainedPool(pool);
+        }
+        for (const pending of [...this.resourceQueue]) {
+            if (pending.deadline > now)
+                continue;
+            this.resourceQueue.splice(this.resourceQueue.indexOf(pending), 1);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new AdapterSchedulerError('ADAPTER_RESOURCE_TIMEOUT', 'Timed out waiting for Adapter resource locks'));
+        }
+        this.scheduleResources();
+    }
+    reset() {
+        for (const pool of this.pools.values()) {
+            for (const pending of pool.queued) {
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.reject(new AdapterSchedulerError('ADAPTER_QUEUE_RESET', 'Adapter scheduler restarted'));
+            }
+        }
+        this.pools.clear();
+        for (const pending of this.resourceQueue.splice(0)) {
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new AdapterSchedulerError('ADAPTER_QUEUE_RESET', 'Adapter scheduler restarted'));
+        }
+        this.resourceOwners.clear();
+        this.resourceGrants.clear();
+        this.releasedLeaseIds.clear();
+    }
+    snapshot() {
+        let running = 0;
+        let queued = 0;
+        for (const pool of this.pools.values()) {
+            running += pool.running.size;
+            queued += pool.queued.length;
+        }
+        return { running, queued, pools: this.pools.size };
+    }
+    resourceSnapshot() {
+        return {
+            locked: this.resourceOwners.size,
+            queued: this.resourceQueue.length,
+            grants: this.resourceGrants.size,
+        };
+    }
+    schedule(pool) {
+        while (!pool.closed && pool.running.size < pool.maxParallel) {
+            const eligible = pool.queued
+                .filter(entry => !pool.activeSessions.has(entry.request.adapterSession)
+                && pool.running.size < pool.maxParallel)
+                .sort((a, b) => a.enqueuedAt - b.enqueuedAt || a.sequence - b.sequence)[0];
+            if (!eligible)
+                return;
+            pool.queued.splice(pool.queued.indexOf(eligible), 1);
+            if (eligible.timer)
+                clearTimeout(eligible.timer);
+            const grantedAt = this.now();
+            const lease = {
+                leaseId: crypto.randomUUID(),
+                requestId: eligible.request.requestId,
+                poolKey: pool.key,
+                contextId: eligible.request.contextId,
+                surface: 'adapter',
+                site: eligible.request.site,
+                adapterSession: eligible.request.adapterSession,
+                sessionKey: eligible.request.sessionKey,
+                generation: pool.generation,
+                grantedAt,
+                heartbeatDeadline: grantedAt + this.leaseExpiryMs,
+            };
+            pool.running.set(lease.leaseId, lease);
+            pool.activeSessions.add(lease.adapterSession);
+            eligible.resolve({ ...lease });
+        }
+    }
+    scheduleResources() {
+        for (const pending of [...this.resourceQueue].sort((a, b) => a.sequence - b.sequence)) {
+            try {
+                this.requireLease(pending.lease);
+            }
+            catch {
+                this.resourceQueue.splice(this.resourceQueue.indexOf(pending), 1);
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pending.reject(new AdapterSchedulerError('ADAPTER_LEASE_LOST', 'Adapter command lease was lost while waiting for resources'));
+                continue;
+            }
+            if (!pending.keys.every(key => !this.resourceOwners.has(key)))
+                continue;
+            this.resourceQueue.splice(this.resourceQueue.indexOf(pending), 1);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            const grant = {
+                grantId: crypto.randomUUID(),
+                leaseId: pending.lease.leaseId,
+                keys: pending.keys,
+            };
+            this.resourceGrants.set(grant.grantId, grant);
+            for (const key of grant.keys)
+                this.resourceOwners.set(key, { leaseId: grant.leaseId, grantId: grant.grantId });
+            pending.resolve({ ...grant, keys: [...grant.keys] });
+        }
+    }
+    releaseAllResourcesForLease(leaseId) {
+        for (const grant of [...this.resourceGrants.values()]) {
+            if (grant.leaseId !== leaseId)
+                continue;
+            this.resourceGrants.delete(grant.grantId);
+            for (const key of grant.keys) {
+                const owner = this.resourceOwners.get(key);
+                if (owner?.grantId === grant.grantId)
+                    this.resourceOwners.delete(key);
+            }
+        }
+    }
+    pruneReleasedLeaseIds(now = this.now()) {
+        for (const [leaseId, expiresAt] of this.releasedLeaseIds) {
+            if (expiresAt <= now)
+                this.releasedLeaseIds.delete(leaseId);
+        }
+    }
+    rejectResourceWaitersForLease(leaseId) {
+        for (const pending of [...this.resourceQueue]) {
+            if (pending.lease.leaseId !== leaseId)
+                continue;
+            this.resourceQueue.splice(this.resourceQueue.indexOf(pending), 1);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.reject(new AdapterSchedulerError('ADAPTER_LEASE_LOST', 'Adapter command lease ended while waiting for resources'));
+        }
+    }
+    requireLease(identity) {
+        const pool = this.pools.get(identity.poolKey);
+        const lease = pool?.running.get(identity.leaseId);
+        if (!lease
+            || lease.requestId !== identity.requestId
+            || lease.contextId !== identity.contextId
+            || lease.site !== identity.site
+            || lease.adapterSession !== identity.adapterSession
+            || lease.sessionKey !== identity.sessionKey
+            || lease.generation !== identity.generation) {
+            throw new AdapterSchedulerError('ADAPTER_LEASE_LOST', 'Adapter command lease is no longer valid');
+        }
+        return lease;
+    }
+    getOrCreatePool(request) {
+        const key = `${request.contextId}\u0000${request.surface}\u0000${request.site}`;
+        const existing = this.pools.get(key);
+        if (existing)
+            return existing;
+        const generation = (this.generations.get(key) ?? 0) + 1;
+        this.generations.set(key, generation);
+        const pool = {
+            key,
+            generation,
+            maxParallel: Math.min(request.maxParallel, this.runtimeCeiling),
+            running: new Map(),
+            activeSessions: new Set(),
+            queued: [],
+        };
+        this.pools.set(key, pool);
+        return pool;
+    }
+    removeDrainedPool(pool) {
+        if (pool.running.size === 0 && pool.queued.length === 0)
+            this.pools.delete(pool.key);
+    }
+    poolClosedError(reason) {
+        return reason === 'auth_gate'
+            ? new AdapterSchedulerError('ADAPTER_POOL_AUTH_GATE', 'Adapter pool stopped at an authentication or verification gate')
+            : new AdapterSchedulerError('ADAPTER_POOL_RATE_LIMITED', 'Adapter pool stopped after account rate limiting');
+    }
+    validateRequest(request) {
+        if (!request.requestId || !request.contextId || !request.site || !request.adapterSession || !request.sessionKey) {
+            throw new AdapterSchedulerError('ADAPTER_QUEUE_RESET', 'Invalid Adapter lease request');
+        }
+        if (!Number.isInteger(request.queueTimeoutMs) || request.queueTimeoutMs < 1) {
+            throw new AdapterSchedulerError('ADAPTER_QUEUE_RESET', 'Invalid Adapter queue timeout');
+        }
+        if (!Number.isInteger(request.maxParallel) || request.maxParallel < 1 || request.maxParallel > this.runtimeCeiling) {
+            throw new AdapterSchedulerError('ADAPTER_QUEUE_RESET', 'Invalid Adapter concurrency limit');
+        }
+    }
+}

package/dist/src/adapter-scheduler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/daemon-client.d.ts

@@ -3,6 +3,7 @@
  *
  * Provides a typed send() function that posts a Command and returns a Result.
  */
+import type { AdapterLease, AdapterLeaseRelease, AdapterLeaseRequest, AdapterResourceGrant } from '../adapter-scheduler.js';
 export interface DaemonCommand {
     id: string;
     action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'ima-auth-start' | 'ima-auth-read' | 'ima-reader-request' | 'ima-auth-release' | 'wait-download' | 'cdp' | 'frames';
@@ -47,6 +48,8 @@ export interface DaemonCommand {
     frameIndex?: number;
     /** Browser profile/context to route the command to. */
     contextId?: string;
+    /** Active Adapter lease used by the daemon to fence every browser action. */
+    adapterLease?: AdapterLease;
 }
 export interface DaemonResult {
     id: string;
@@ -107,6 +110,12 @@ export type DaemonStatusProbe = {
 } | {
     kind: 'network_error';
 };
+export declare function acquireAdapterLease(request: AdapterLeaseRequest): Promise<AdapterLease>;
+export declare function heartbeatAdapterLease(lease: AdapterLease): Promise<AdapterLease>;
+export declare function releaseAdapterLease(release: AdapterLeaseRelease): Promise<boolean>;
+export declare function cancelAdapterLease(requestId: string): Promise<boolean>;
+export declare function acquireAdapterResources(lease: AdapterLease, keys: string[], timeoutMs: number): Promise<AdapterResourceGrant>;
+export declare function releaseAdapterResources(lease: AdapterLease, grantId: string): Promise<boolean>;
 export declare function probeDaemonStatus(opts?: {
     timeout?: number;
     contextId?: string;
@@ -139,6 +148,8 @@ export declare function getDaemonHealth(opts?: {
     timeout?: number;
     contextId?: string;
 }): Promise<DaemonHealth>;
+/** Resolve the concrete daemon profile used to key Adapter scheduler pools. */
+export declare function resolveAdapterLeaseContextId(requestedContextId?: string): Promise<string>;
 export declare function requestDaemonShutdown(opts?: {
     timeout?: number;
 }): Promise<boolean>;