account-pool-mcp 0.1.0

package/dist/pool.d.ts

@@ -0,0 +1,50 @@
+import type { Db } from './db.js';
+import { type LeaseResult, type PoolStatus, type ReleaseResult, type RenewResult } from './types.js';
+export interface AccountPoolOptions {
+    db: Db;
+    defaultTtlSeconds: number;
+    /** Injectable clock (epoch SECONDS) so TTL tests don't rely on sleep. */
+    now?: () => number;
+    /** Environment used to resolve credential `{ env: "X" }` indirection. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class AccountPool {
+    private readonly db;
+    private readonly defaultTtl;
+    private readonly now;
+    private readonly env;
+    private readonly stmtReclaim;
+    private readonly stmtSelectFree;
+    private readonly stmtMarkLeased;
+    private readonly stmtRelease;
+    private readonly stmtByToken;
+    private readonly stmtRenew;
+    private readonly stmtPoolCounts;
+    private readonly stmtStatusRows;
+    constructor(opts: AccountPoolOptions);
+    /**
+     * Single atomic attempt to lease one free account. Returns the lease or `null` if the pool has no
+     * free account right now (caller applies the exhaustion policy — see {@link acquire}).
+     */
+    lease(pool: string, holder?: string, ttlSeconds?: number): LeaseResult | null;
+    /**
+     * Lease one account, applying the exhaustion policy. `waitMs === 0` → fail fast with a structured
+     * {@link PoolExhaustedError}. `waitMs > 0` → block-and-wait, polling with jittered backoff up to
+     * `waitMs` before failing.
+     */
+    acquire(args: {
+        pool: string;
+        holder?: string;
+        ttlSeconds?: number;
+        waitMs?: number;
+    }): Promise<LeaseResult>;
+    /** Release a leased account. Idempotent: an unknown/already-free/expired token returns false. */
+    release(leaseToken: string): ReleaseResult;
+    /** Extend a live lease. A token that is unknown OR already expired returns `renewed: false`. */
+    renew(leaseToken: string, ttlSeconds?: number): RenewResult;
+    /** Observability. Never returns credential values. */
+    status(pool?: string): PoolStatus[];
+    private poolCounts;
+    private nowMs;
+    private validateTtl;
+}

package/dist/pool.js

@@ -0,0 +1,190 @@
+// Core leasing logic — the part that must be exactly right.
+//
+// The concurrency guarantee comes from running every mutation inside a `BEGIN IMMEDIATE`
+// transaction (better-sqlite3's `.immediate()` variant). IMMEDIATE takes the write lock BEFORE the
+// SELECT that picks an account, so two simultaneous lease attempts can never read the same free row
+// and both claim it (no time-of-check / time-of-use gap). Combined with WAL + busy_timeout, this
+// holds across many independent processes sharing one database file.
+import { randomBytes } from 'node:crypto';
+import { resolveCredentials } from './config.js';
+import { PoolExhaustedError, } from './types.js';
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class AccountPool {
+    db;
+    defaultTtl;
+    now;
+    env;
+    // Prepared statements (compiled once).
+    stmtReclaim;
+    stmtSelectFree;
+    stmtMarkLeased;
+    stmtRelease;
+    stmtByToken;
+    stmtRenew;
+    stmtPoolCounts;
+    stmtStatusRows;
+    constructor(opts) {
+        this.db = opts.db;
+        this.defaultTtl = opts.defaultTtlSeconds;
+        this.now = opts.now ?? nowSeconds;
+        this.env = opts.env ?? process.env;
+        this.stmtReclaim = this.db.prepare(`UPDATE accounts
+         SET leased_by = NULL, lease_token = NULL, leased_at = NULL, ttl_seconds = NULL
+       WHERE pool = ? AND leased_by IS NOT NULL AND (leased_at + ttl_seconds) < ?`);
+        this.stmtSelectFree = this.db.prepare('SELECT id, credentials FROM accounts WHERE pool = ? AND leased_by IS NULL LIMIT 1');
+        this.stmtMarkLeased = this.db.prepare(`UPDATE accounts
+         SET leased_by = ?, lease_token = ?, leased_at = ?, ttl_seconds = ?,
+             lease_count = lease_count + 1
+       WHERE id = ?`);
+        this.stmtRelease = this.db.prepare(`UPDATE accounts
+         SET leased_by = NULL, lease_token = NULL, leased_at = NULL, ttl_seconds = NULL
+       WHERE lease_token = ? RETURNING id`);
+        this.stmtByToken = this.db.prepare('SELECT id, leased_at, ttl_seconds FROM accounts WHERE lease_token = ?');
+        this.stmtRenew = this.db.prepare('UPDATE accounts SET leased_at = ?, ttl_seconds = ? WHERE lease_token = ? RETURNING id');
+        this.stmtPoolCounts = this.db.prepare(`SELECT COUNT(*) AS total,
+              COALESCE(SUM(CASE WHEN leased_by IS NOT NULL THEN 1 ELSE 0 END), 0) AS leased
+       FROM accounts WHERE pool = ?`);
+        this.stmtStatusRows = this.db.prepare('SELECT id, pool, leased_by, leased_at, ttl_seconds FROM accounts');
+    }
+    /**
+     * Single atomic attempt to lease one free account. Returns the lease or `null` if the pool has no
+     * free account right now (caller applies the exhaustion policy — see {@link acquire}).
+     */
+    lease(pool, holder = 'unknown', ttlSeconds) {
+        const ttl = this.validateTtl(ttlSeconds ?? this.defaultTtl);
+        const now = this.now();
+        const txn = this.db.transaction(() => {
+            // 1) reclaim anything in this pool whose lease has expired
+            this.stmtReclaim.run(pool, now);
+            // 2) grab one free account
+            const row = this.stmtSelectFree.get(pool);
+            if (!row)
+                return null;
+            // 3) resolve credentials BEFORE committing the claim — a missing env var rolls the whole
+            //    transaction back so we never leave an account leased-but-unusable.
+            const creds = resolveCredentials(JSON.parse(row.credentials), row.id, this.env);
+            // 4) mark it leased
+            const token = randomBytes(12).toString('hex');
+            this.stmtMarkLeased.run(holder, token, now, ttl, row.id);
+            return {
+                account_id: row.id,
+                pool,
+                credentials: creds,
+                lease_token: token,
+                expires_at: now + ttl,
+            };
+        });
+        // IMMEDIATE: take the write lock before the read so two leases can't pick the same row.
+        return txn.immediate();
+    }
+    /**
+     * Lease one account, applying the exhaustion policy. `waitMs === 0` → fail fast with a structured
+     * {@link PoolExhaustedError}. `waitMs > 0` → block-and-wait, polling with jittered backoff up to
+     * `waitMs` before failing.
+     */
+    async acquire(args) {
+        const { pool, holder, ttlSeconds } = args;
+        const waitMs = args.waitMs ?? 0;
+        const deadline = this.nowMs() + waitMs;
+        let backoff = 250;
+        for (;;) {
+            const result = this.lease(pool, holder, ttlSeconds);
+            if (result)
+                return result;
+            if (this.nowMs() >= deadline) {
+                const { total, leased } = this.poolCounts(pool);
+                throw new PoolExhaustedError(pool, total, leased);
+            }
+            // jittered backoff, capped, never overshooting the deadline
+            const jitter = Math.floor(Math.random() * 100);
+            const wait = Math.min(backoff + jitter, Math.max(0, deadline - this.nowMs()));
+            await sleep(wait);
+            backoff = Math.min(backoff * 2, 2000);
+        }
+    }
+    /** Release a leased account. Idempotent: an unknown/already-free/expired token returns false. */
+    release(leaseToken) {
+        const txn = this.db.transaction(() => {
+            const row = this.stmtRelease.get(leaseToken);
+            return row ? { released: true, account_id: row.id } : { released: false };
+        });
+        return txn.immediate();
+    }
+    /** Extend a live lease. A token that is unknown OR already expired returns `renewed: false`. */
+    renew(leaseToken, ttlSeconds) {
+        const ttl = this.validateTtl(ttlSeconds ?? this.defaultTtl);
+        const now = this.now();
+        const txn = this.db.transaction(() => {
+            const row = this.stmtByToken.get(leaseToken);
+            const expired = !row || row.leased_at === null || row.ttl_seconds === null
+                ? true
+                : row.leased_at + row.ttl_seconds < now;
+            if (!row || expired) {
+                return {
+                    renewed: false,
+                    message: 'Lease is unknown or already expired and may now be held by another session. ' +
+                        'Call lease_account again to get a fresh account.',
+                };
+            }
+            this.stmtRenew.run(now, ttl, leaseToken);
+            return { renewed: true, expires_at: now + ttl };
+        });
+        return txn.immediate();
+    }
+    /** Observability. Never returns credential values. */
+    status(pool) {
+        const now = this.now();
+        const rows = this.stmtStatusRows.all();
+        const byPool = new Map();
+        for (const r of rows) {
+            if (pool && r.pool !== pool)
+                continue;
+            let ps = byPool.get(r.pool);
+            if (!ps) {
+                ps = { pool: r.pool, total: 0, available: 0, leased: 0, accounts: [] };
+                byPool.set(r.pool, ps);
+            }
+            ps.total++;
+            if (r.leased_by === null) {
+                ps.available++;
+                ps.accounts.push({ account_id: r.id, state: 'free' });
+            }
+            else {
+                const expired = r.leased_at === null || r.ttl_seconds === null || r.leased_at + r.ttl_seconds < now;
+                if (expired) {
+                    ps.available++; // an expired lease is reclaimable on the next lease attempt
+                    ps.accounts.push({ account_id: r.id, state: 'expired', holder: r.leased_by });
+                }
+                else {
+                    ps.leased++;
+                    ps.accounts.push({
+                        account_id: r.id,
+                        state: 'leased',
+                        holder: r.leased_by,
+                        expires_at: r.leased_at + r.ttl_seconds,
+                    });
+                }
+            }
+        }
+        // An explicit pool filter that matches nothing still yields an (empty) entry for clarity.
+        if (pool && !byPool.has(pool)) {
+            byPool.set(pool, { pool, total: 0, available: 0, leased: 0, accounts: [] });
+        }
+        return [...byPool.values()].sort((a, b) => a.pool.localeCompare(b.pool));
+    }
+    poolCounts(pool) {
+        return this.stmtPoolCounts.get(pool);
+    }
+    nowMs() {
+        // Wall-clock for backoff timing; independent of the injectable second-clock used for TTL logic.
+        return Date.now();
+    }
+    validateTtl(ttl) {
+        if (!Number.isInteger(ttl) || ttl <= 0) {
+            throw new Error(`ttl_seconds must be a positive integer, got ${ttl}.`);
+        }
+        return ttl;
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/pool.js.map

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

package/dist/schemas.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+export declare const leaseInput: {
+    pool: z.ZodString;
+    holder: z.ZodOptional<z.ZodString>;
+    ttl_seconds: z.ZodOptional<z.ZodNumber>;
+    wait_ms: z.ZodOptional<z.ZodNumber>;
+};
+export declare const releaseInput: {
+    lease_token: z.ZodString;
+};
+export declare const renewInput: {
+    lease_token: z.ZodString;
+    ttl_seconds: z.ZodOptional<z.ZodNumber>;
+};
+export declare const statusInput: {
+    pool: z.ZodOptional<z.ZodString>;
+};
+export declare const leaseInputSchema: z.ZodObject<{
+    pool: z.ZodString;
+    holder: z.ZodOptional<z.ZodString>;
+    ttl_seconds: z.ZodOptional<z.ZodNumber>;
+    wait_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    pool: string;
+    holder?: string | undefined;
+    ttl_seconds?: number | undefined;
+    wait_ms?: number | undefined;
+}, {
+    pool: string;
+    holder?: string | undefined;
+    ttl_seconds?: number | undefined;
+    wait_ms?: number | undefined;
+}>;
+export declare const releaseInputSchema: z.ZodObject<{
+    lease_token: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    lease_token: string;
+}, {
+    lease_token: string;
+}>;
+export declare const renewInputSchema: z.ZodObject<{
+    lease_token: z.ZodString;
+    ttl_seconds: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    lease_token: string;
+    ttl_seconds?: number | undefined;
+}, {
+    lease_token: string;
+    ttl_seconds?: number | undefined;
+}>;
+export declare const statusInputSchema: z.ZodObject<{
+    pool: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    pool?: string | undefined;
+}, {
+    pool?: string | undefined;
+}>;

package/dist/schemas.js

@@ -0,0 +1,43 @@
+// Zod input shapes for the four MCP tools. Kept as raw shapes so they can be passed straight to the
+// MCP SDK's tool registration (which derives the JSON Schema the agent sees).
+import { z } from 'zod';
+export const leaseInput = {
+    pool: z.string().min(1).describe('Which pool to lease from, e.g. "realtor" or "admin".'),
+    holder: z
+        .string()
+        .optional()
+        .describe('A label for who is holding it (e.g. a Jira ticket id). Observability only.'),
+    ttl_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Lease lifetime in seconds. Defaults to the server default TTL.'),
+    wait_ms: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Override the block-and-wait timeout for this call. 0 = fail fast on an empty pool.'),
+};
+export const releaseInput = {
+    lease_token: z.string().min(1).describe('The lease_token returned by lease_account.'),
+};
+export const renewInput = {
+    lease_token: z.string().min(1).describe('The lease_token returned by lease_account.'),
+    ttl_seconds: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('New lease lifetime in seconds from now. Defaults to the server default TTL.'),
+};
+export const statusInput = {
+    pool: z.string().optional().describe('Limit to one pool. Omit for all pools.'),
+};
+// Re-exported for tests / typing.
+export const leaseInputSchema = z.object(leaseInput);
+export const releaseInputSchema = z.object(releaseInput);
+export const renewInputSchema = z.object(renewInput);
+export const statusInputSchema = z.object(statusInput);
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,8EAA8E;AAE9E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IACxF,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4EAA4E,CAAC;IACzF,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,gEAAgE,CAAC;IAC7E,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,WAAW,EAAE;SACb,QAAQ,EAAE;SACV,QAAQ,CAAC,oFAAoF,CAAC;CAClG,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC;CACtF,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACrF,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,6EAA6E,CAAC;CAC3F,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;CAC/E,CAAC;AAEF,kCAAkC;AAClC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACrD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AccountPool } from './pool.js';
+import type { AppConfig } from './types.js';
+export declare function buildServer(pool: AccountPool, config: AppConfig): McpServer;

package/dist/server.js

@@ -0,0 +1,75 @@
+// MCP server: registers the four tools and maps them onto the AccountPool. Tool descriptions are
+// agent-facing — the wording is deliberate because the model reads it to decide how to behave.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { logger, redact } from './logger.js';
+import { leaseInput, releaseInput, renewInput, statusInput } from './schemas.js';
+import { PoolExhaustedError } from './types.js';
+function ok(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+    };
+}
+function fail(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+        isError: true,
+    };
+}
+export function buildServer(pool, config) {
+    const server = new McpServer({ name: 'account-pool-mcp', version: '0.1.0' });
+    server.tool('lease_account', 'Lease one account from the pool for browser login, EXCLUSIVELY, until you release it or the ' +
+        'lease expires. No other session can be handed the same account while you hold it. You MUST ' +
+        'call release_account with the returned lease_token when finished. If your task may run ' +
+        'longer than the lease TTL, call renew_lease periodically to keep it.', leaseInput, async (args) => {
+        try {
+            const result = await pool.acquire({
+                pool: args.pool,
+                holder: args.holder,
+                ttlSeconds: args.ttl_seconds,
+                waitMs: args.wait_ms ?? config.leaseWaitMs,
+            });
+            logger.info('leased', {
+                account_id: result.account_id,
+                pool: result.pool,
+                holder: args.holder ?? 'unknown',
+                expires_at: result.expires_at,
+            });
+            return ok(result);
+        }
+        catch (err) {
+            if (err instanceof PoolExhaustedError) {
+                return fail({
+                    error: 'pool_exhausted',
+                    pool: err.pool,
+                    total: err.total,
+                    leased: err.leased,
+                    message: err.message,
+                });
+            }
+            logger.error('lease_account failed', { message: err.message });
+            return fail({ error: 'lease_failed', message: err.message });
+        }
+    });
+    server.tool('release_account', 'Release a leased account so others can use it. Idempotent: releasing an already-released, ' +
+        'expired, or unknown token returns released:false rather than erroring.', releaseInput, async (args) => {
+        const result = pool.release(args.lease_token);
+        logger.info('released', result);
+        return ok(result);
+    });
+    server.tool('renew_lease', 'Extend (heartbeat) the current lease so long-running work is not reclaimed out from under you. ' +
+        'If the lease already expired and was reclaimed (or the token is unknown), returns ' +
+        'renewed:false — do NOT assume you still hold the account; call lease_account again.', renewInput, async (args) => {
+        const result = pool.renew(args.lease_token, args.ttl_seconds);
+        return ok(result);
+    });
+    server.tool('pool_status', 'Observability for the pools: totals, how many are available vs leased, and per-account state ' +
+        '(free / leased / expired). Credential values are NEVER returned.', statusInput, async (args) => {
+        const pools = pool.status(args.pool);
+        // redact() is belt-and-suspenders: status() already omits credentials.
+        return ok({ pools: redact(pools) });
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A credential value is either a literal (string/number/bool) or an indirection
+ * `{ env: "VAR_NAME" }` that is resolved from the process environment **at lease time**,
+ * so real secrets never have to live in the seed file in plaintext.
+ */
+export type CredentialValue = string | number | boolean | {
+    env: string;
+};
+/** Arbitrary credential blob — not hardwired to username/password. */
+export type Credentials = Record<string, CredentialValue>;
+/** Resolved credentials (after env indirection) handed back to a lease holder. */
+export type ResolvedCredentials = Record<string, string | number | boolean>;
+export interface AccountSeed {
+    id: string;
+    credentials: Credentials;
+}
+export interface PoolsSeed {
+    pools: Record<string, AccountSeed[]>;
+}
+/** A single account row as stored in SQLite. */
+export interface AccountRow {
+    id: string;
+    pool: string;
+    credentials: string;
+    leased_by: string | null;
+    lease_token: string | null;
+    leased_at: number | null;
+    ttl_seconds: number | null;
+    lease_count: number;
+}
+export type ExhaustionPolicy = 'fail-fast' | 'block-and-wait';
+export interface AppConfig {
+    dbPath: string;
+    accountsFile: string;
+    defaultTtlSeconds: number;
+    /** Max time to wait for a free account before failing. 0 = fail-fast. */
+    leaseWaitMs: number;
+    /** Clear all lease state on startup. */
+    resetLeases: boolean;
+}
+export interface LeaseResult {
+    account_id: string;
+    pool: string;
+    credentials: ResolvedCredentials;
+    lease_token: string;
+    expires_at: number;
+}
+export interface ReleaseResult {
+    released: boolean;
+    account_id?: string;
+}
+export interface RenewResult {
+    renewed: boolean;
+    expires_at?: number;
+    message?: string;
+}
+export type AccountState = 'free' | 'leased' | 'expired';
+export interface AccountStatus {
+    account_id: string;
+    state: AccountState;
+    holder?: string;
+    expires_at?: number;
+}
+export interface PoolStatus {
+    pool: string;
+    total: number;
+    available: number;
+    leased: number;
+    accounts: AccountStatus[];
+}
+/** Thrown when a pool has no free account and policy is fail-fast (or wait timed out). */
+export declare class PoolExhaustedError extends Error {
+    readonly pool: string;
+    readonly total: number;
+    readonly leased: number;
+    constructor(pool: string, total: number, leased: number);
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+// Shared types for account-pool-mcp.
+/** Thrown when a pool has no free account and policy is fail-fast (or wait timed out). */
+export class PoolExhaustedError extends Error {
+    pool;
+    total;
+    leased;
+    constructor(pool, total, leased) {
+        super(total === 0
+            ? `Pool "${pool}" does not exist or has no accounts.`
+            : `Pool "${pool}" is exhausted: all ${total} account(s) are currently leased (${leased} in use). Wait for a release, raise APM_LEASE_WAIT_MS to block-and-wait, or add more accounts.`);
+        this.name = 'PoolExhaustedError';
+        this.pool = pool;
+        this.total = total;
+        this.leased = leased;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAoFrC,0FAA0F;AAC1F,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAS;IACb,KAAK,CAAS;IACd,MAAM,CAAS;IACxB,YAAY,IAAY,EAAE,KAAa,EAAE,MAAc;QACrD,KAAK,CACH,KAAK,KAAK,CAAC;YACT,CAAC,CAAC,SAAS,IAAI,sCAAsC;YACrD,CAAC,CAAC,SAAS,IAAI,uBAAuB,KAAK,qCAAqC,MAAM,gGAAgG,CACzL,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/examples/accounts.example.json

@@ -0,0 +1,21 @@
+{
+  "_comment": "Copy to accounts.json (gitignored) and edit. Each pool is a list of accounts; each account has a stable id and an arbitrary credentials blob. A credential value may be a literal, or { \"env\": \"VAR\" } which is resolved from the environment at lease time so real secrets never live in this file.",
+  "pools": {
+    "realtor": [
+      {
+        "id": "realtor_01",
+        "credentials": { "username": "qa.realtor01@example.com", "password": { "env": "REALTOR_01_PW" } }
+      },
+      {
+        "id": "realtor_02",
+        "credentials": { "username": "qa.realtor02@example.com", "password": { "env": "REALTOR_02_PW" } }
+      }
+    ],
+    "admin": [
+      {
+        "id": "admin_01",
+        "credentials": { "username": "qa.admin01@example.com", "password": { "env": "ADMIN_01_PW" } }
+      }
+    ]
+  }
+}

package/examples/claude-mcp-config.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "Drop the account-pool stanza into your MCP client config (e.g. .mcp.json) alongside your other servers. Every independent agent session that loads this config talks to the SAME database file (APM_DB_PATH), which is how unrelated sessions coordinate. Point APM_DB_PATH at a stable, shared path.",
+  "mcpServers": {
+    "account-pool": {
+      "command": "npx",
+      "args": ["-y", "account-pool-mcp"],
+      "env": {
+        "APM_ACCOUNTS_FILE": "./accounts.json",
+        "APM_DB_PATH": "./account-pool.db",
+        "APM_DEFAULT_TTL_SECONDS": "1800",
+        "APM_LEASE_WAIT_MS": "0"
+      }
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--isolated"]
+    }
+  }
+}

package/examples/playwright-usage.md

@@ -0,0 +1,48 @@
+# Using account-pool-mcp with Playwright (agent flow)
+
+The pattern any agent (Claude or otherwise) should follow when it needs to log in: **lease → use →
+release**, with a heartbeat for long work. Because the lease is exclusive and atomic, no other
+session can be handed the same account while you hold it.
+
+## The flow
+
+```
+1. lease_account({ pool: "realtor", holder: "QA-1234" })
+      → { account_id, credentials: { username, password }, lease_token, expires_at }
+
+2. Drive Playwright with the leased credentials:
+      - log in as `username` / `password`
+      - (or load a pre-saved storage state keyed by account_id / username)
+      - run your test flow in an ISOLATED browser context
+
+3. If the work may outlast the TTL, periodically:
+      renew_lease({ lease_token })          # heartbeat — call between test cases / every few minutes
+
+4. When finished (success OR failure):
+      release_account({ lease_token })       # hand the account back to the pool
+```
+
+## Why each step matters
+
+- **Exclusive lease** — two sessions can never drive the same account at once, so they can't corrupt
+  each other's server-side state (carts, drafts, folders, search state). This is the whole point.
+- **Heartbeat (`renew_lease`)** — a lease has a TTL so a crashed session can't strand an account
+  forever. If your real work runs longer than the TTL, renew to keep your hold. If `renew_lease`
+  returns `renewed: false`, the lease already expired and may now be held by someone else — stop and
+  `lease_account` again; do not keep using the old account.
+- **Release** — returns the account immediately instead of waiting for the TTL. Always release in a
+  finally/teardown step. If your process dies before releasing, the TTL reclaims it automatically —
+  that's the crash-safety net, not the happy path.
+
+## Empty pool
+
+If every account is leased, `lease_account` either fails fast with a structured error (default) or
+blocks-and-waits up to `APM_LEASE_WAIT_MS` before failing. Handle the failure by reporting "no
+accounts available" rather than proceeding without an exclusive account.
+
+## Storage-state variant (no live password in the flow)
+
+If you pre-bake a Playwright storage state per account, the lease only needs to tell you *which*
+account is yours: lease a pool whose credentials contain just a `username`/account id, then load the
+matching saved storage-state blob and skip the live login entirely. The exclusivity guarantee is the
+same — you just use the lease to pick the storage state instead of to log in.