webpeel 0.20.5 → 0.20.6

package/dist/cli/commands/fetch.js

@@ -7,9 +7,40 @@ import { getProfilePath, loadStorageState, touchProfile } from '../../core/profi
 import { peel, cleanup } from '../../index.js';
 import { checkUsage, showUsageFooter, loadConfig } from '../../cli-auth.js';
 import { getCache, setCache, parseTTL } from '../../cache.js';
-import { estimateTokens } from '../../core/markdown.js';
+import { estimateTokens, htmlToMarkdown } from '../../core/markdown.js';
 import { distillToBudget, budgetListings } from '../../core/budget.js';
 import { parseActions, formatError, fetchViaApi, outputResult, writeStdout, buildEnvelope, classifyErrorCode, formatListingsCsv, normaliseExtractedToRows, } from '../utils.js';
+// ─── readStdin ────────────────────────────────────────────────────────────────
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+// ─── runStdin ─────────────────────────────────────────────────────────────────
+// Read HTML from stdin, convert to markdown, and output
+async function runStdin(options) {
+    try {
+        const html = await readStdin();
+        if (!html.trim()) {
+            process.stderr.write('Error: No input received on stdin\n');
+            process.exit(1);
+        }
+        const markdown = htmlToMarkdown(html, { raw: false, prune: true });
+        if (options.json) {
+            const tokens = estimateTokens(markdown);
+            process.stdout.write(JSON.stringify({ success: true, content: markdown, tokens }) + '\n');
+        }
+        else {
+            process.stdout.write(markdown + '\n');
+        }
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exit(1);
+    }
+}
 // ─── runFetch ─────────────────────────────────────────────────────────────────
 // Main fetch handler — shared with the `pipe` and `ask` subcommands
 export async function runFetch(url, options) {
@@ -1045,7 +1076,12 @@ export function registerFetchCommands(program) {
         .option('--format <type>', 'Output format: markdown (default), text, html, json')
         .option('--content-only', 'Output only the raw content field (no metadata, no JSON wrapper) — ideal for piping to LLMs')
         .option('--progress', 'Show engine escalation steps (simple → browser → stealth) with timing')
+        .option('--stdin', 'Read HTML from stdin instead of fetching a URL — converts to markdown')
         .action(async (url, options) => {
+        if (options.stdin) {
+            await runStdin(options);
+            return;
+        }
         await runFetch(url, options);
     });
     // ── read subcommand (explicit readable mode) ─────────────────────────────

package/dist/server/routes/agent.d.ts

@@ -1,5 +1,7 @@
 /**
- * POST /v1/agent
+ * POST /v1/agent           — single autonomous agent query
+ * POST /v1/agent/batch     — parallel batch of agent queries (max 50)
+ * GET  /v1/agent/batch/:id — poll batch job status
  *
  * Autonomous web agent — search → fetch → extract (LLM or BM25)
  *
@@ -11,9 +13,7 @@
  *
  * Returns: { success, data|answer, sources, method, elapsed, tokensUsed }
  *
- * Two modes:
- *   - agent-llm:  schema + llmApiKey → LLM extraction (BYOK)
- *   - agent-bm25: no LLM key → BM25 text answer (always free)
+ * Webhook support: pass `webhook` URL to get async delivery with HMAC-SHA256 signing.
  *
  * 5-minute in-memory cache. Max 10 sources per request.
  */

package/dist/server/routes/agent.js

@@ -1,5 +1,7 @@
 /**
- * POST /v1/agent
+ * POST /v1/agent           — single autonomous agent query
+ * POST /v1/agent/batch     — parallel batch of agent queries (max 50)
+ * GET  /v1/agent/batch/:id — poll batch job status
  *
  * Autonomous web agent — search → fetch → extract (LLM or BM25)
  *
@@ -11,9 +13,7 @@
  *
  * Returns: { success, data|answer, sources, method, elapsed, tokensUsed }
  *
- * Two modes:
- *   - agent-llm:  schema + llmApiKey → LLM extraction (BYOK)
- *   - agent-bm25: no LLM key → BM25 text answer (always free)
+ * Webhook support: pass `webhook` URL to get async delivery with HMAC-SHA256 signing.
  *
  * 5-minute in-memory cache. Max 10 sources per request.
  */
@@ -22,9 +22,42 @@ import { peel } from '../../index.js';
 import { extractWithLLM } from '../../core/llm-extract.js';
 import { getBestSearchProvider } from '../../core/search-provider.js';
 import { quickAnswer } from '../../core/quick-answer.js';
+import { sendWebhook } from './webhooks.js';
 import { createLogger } from '../../core/logger.js';
 import crypto from 'crypto';
 const log = createLogger('agent');
+const batchJobs = new Map();
+const BATCH_TTL = 60 * 60 * 1000; // 1 hour
+// GC stale batch jobs every 10 minutes
+setInterval(() => {
+    const now = Date.now();
+    for (const [id, job] of batchJobs) {
+        if (now - job.createdAt > BATCH_TTL)
+            batchJobs.delete(id);
+    }
+}, 10 * 60 * 1000).unref();
+// Simple concurrency limiter
+class Semaphore {
+    max;
+    queue = [];
+    running = 0;
+    constructor(max) {
+        this.max = max;
+    }
+    async acquire() {
+        if (this.running < this.max) {
+            this.running++;
+            return;
+        }
+        return new Promise((resolve) => this.queue.push(() => { this.running++; resolve(); }));
+    }
+    release() {
+        this.running--;
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+}
 const cache = new Map();
 const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
 function getCached(key) {
@@ -48,191 +81,175 @@ function setCache(key, result) {
     }
     cache.set(key, { result, expiresAt: Date.now() + CACHE_TTL });
 }
+async function runAgentQuery(params) {
+    const { prompt, schema, llmApiKey, llmProvider, llmModel, urls, sources: maxSources } = params;
+    const startMs = Date.now();
+    const numSources = Math.min(maxSources || 5, 10);
+    // Cache check
+    const cacheKey = `${prompt.trim()}:${JSON.stringify(schema || {})}`;
+    const cached = getCached(cacheKey);
+    if (cached)
+        return { ...cached, cached: true };
+    // Step 1: Resolve source URLs
+    let sourceUrls = [];
+    if (Array.isArray(urls) && urls.length > 0) {
+        sourceUrls = urls.map((u) => ({ url: u }));
+    }
+    else {
+        log.info(`Searching web for: "${prompt}"`);
+        const { provider, apiKey: searchApiKey } = getBestSearchProvider();
+        try {
+            const searchResults = await provider.searchWeb(prompt.trim(), { count: numSources, apiKey: searchApiKey });
+            sourceUrls = searchResults.slice(0, numSources).map((r) => ({ url: r.url, title: r.title, snippet: r.snippet }));
+        }
+        catch (err) {
+            log.warn('Search failed:', err.message);
+        }
+    }
+    if (sourceUrls.length === 0) {
+        return { success: false, error: { type: 'no_sources', message: 'Could not find relevant pages for this query' }, prompt, elapsed: Date.now() - startMs };
+    }
+    // Step 2: Fetch pages in parallel
+    log.info(`Fetching ${sourceUrls.length} sources in parallel`);
+    const PER_SOURCE_TIMEOUT_MS = 5000;
+    const fetchPromises = sourceUrls.map(async (source) => {
+        try {
+            const result = await Promise.race([
+                peel(source.url, { render: false, noEscalate: true, format: 'markdown', timeout: PER_SOURCE_TIMEOUT_MS, budget: 3000 }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('per-source timeout')), PER_SOURCE_TIMEOUT_MS)),
+            ]);
+            return { url: source.url, title: result.title || source.title || '', content: (result.content || '').slice(0, 15000), tokens: result.tokens || 0 };
+        }
+        catch {
+            return null;
+        }
+    });
+    const fetchResults = (await Promise.allSettled(fetchPromises))
+        .map((r) => (r.status === 'fulfilled' ? r.value : null))
+        .filter(Boolean);
+    if (fetchResults.length === 0) {
+        return { success: false, error: { type: 'fetch_failed', message: 'Could not fetch any of the found pages' }, prompt, sources: sourceUrls.map((s) => ({ url: s.url })), elapsed: Date.now() - startMs };
+    }
+    // Step 3: Extract or answer
+    const combinedContent = fetchResults.map((r) => `### ${r.title || r.url}\nURL: ${r.url}\n\n${r.content}`).join('\n\n---\n\n');
+    const totalTokens = fetchResults.reduce((sum, r) => sum + r.tokens, 0);
+    let result;
+    if (schema && llmApiKey) {
+        log.info('Using LLM extraction');
+        const extracted = await extractWithLLM({
+            content: combinedContent.slice(0, 30000), schema, llmApiKey, llmProvider: (llmProvider || 'openai'), llmModel,
+            prompt: `Based on these web pages, ${prompt}`, url: fetchResults[0].url,
+        });
+        const llmTokensUsed = (extracted.tokensUsed?.input ?? 0) + (extracted.tokensUsed?.output ?? 0);
+        result = { success: true, data: extracted.items, sources: fetchResults.map((r) => ({ url: r.url, title: r.title })), method: 'agent-llm',
+            llm: { provider: extracted.provider || llmProvider || 'openai', model: extracted.model || llmModel || 'default' }, tokensUsed: totalTokens + llmTokensUsed, elapsed: Date.now() - startMs };
+    }
+    else {
+        log.info('Using BM25 text extraction');
+        const qa = quickAnswer({ question: prompt, content: combinedContent, maxPassages: 3, maxChars: 2000 });
+        result = { success: true, answer: qa.answer || combinedContent.slice(0, 2000), confidence: qa.confidence ?? 0,
+            sources: fetchResults.map((r) => ({ url: r.url, title: r.title })), method: 'agent-bm25', tokensUsed: totalTokens, elapsed: Date.now() - startMs };
+    }
+    setCache(cacheKey, result);
+    return result;
+}
 // ---------------------------------------------------------------------------
 // Route factory
 // ---------------------------------------------------------------------------
 export function createAgentRouter() {
     const router = Router();
+    // ── POST /v1/agent — single query (with optional webhook) ──────────────
     router.post('/', async (req, res) => {
-        const { prompt, schema, llmApiKey, llmProvider, llmModel, urls, sources: maxSources, } = req.body || {};
-        // Validate required param
+        const { prompt, schema, llmApiKey, llmProvider, llmModel, urls, sources: maxSources, webhook } = req.body || {};
+        const requestId = req.requestId || crypto.randomUUID();
         if (!prompt?.trim()) {
             return res.status(400).json({
                 success: false,
-                error: {
-                    type: 'missing_prompt',
-                    message: 'Provide a prompt describing what you want to find',
-                    hint: 'POST /v1/agent { "prompt": "Find Stripe pricing plans" }',
-                    docs: 'https://webpeel.dev/docs/api-reference',
-                },
-                requestId: req.requestId || crypto.randomUUID(),
+                error: { type: 'missing_prompt', message: 'Provide a prompt describing what you want to find',
+                    hint: 'POST /v1/agent { "prompt": "Find Stripe pricing plans" }', docs: 'https://webpeel.dev/docs/api-reference' },
+                requestId,
             });
         }
-        const startMs = Date.now();
-        const numSources = Math.min(maxSources || 5, 10);
-        const requestId = req.requestId || crypto.randomUUID();
-        // Cache check
-        const cacheKey = `${prompt.trim()}:${JSON.stringify(schema || {})}`;
-        const cached = getCached(cacheKey);
-        if (cached) {
-            return res.json({ ...cached, cached: true, requestId });
+        // Async mode: webhook provided → return immediately, deliver result later
+        if (webhook) {
+            const jobId = crypto.randomUUID();
+            res.json({ success: true, id: jobId, status: 'processing', requestId });
+            // Fire-and-forget agent query + webhook delivery
+            runAgentQuery({ prompt, schema, llmApiKey, llmProvider, llmModel, urls, sources: maxSources })
+                .then((result) => sendWebhook(webhook, 'agent.completed', { id: jobId, ...result, requestId }))
+                .catch((err) => {
+                log.error('Async agent error:', err.message);
+                sendWebhook(webhook, 'agent.failed', { id: jobId, error: err.message, requestId }).catch(() => { });
+            });
+            return;
         }
+        // Synchronous mode: wait for result
         try {
-            // -----------------------------------------------------------------------
-            // Step 1: Resolve source URLs — use caller-provided or search the web
-            // -----------------------------------------------------------------------
-            let sourceUrls = [];
-            if (Array.isArray(urls) && urls.length > 0) {
-                sourceUrls = urls.map((u) => ({ url: u }));
-            }
-            else {
-                log.info(`Searching web for: "${prompt}"`);
-                const { provider, apiKey: searchApiKey } = getBestSearchProvider();
-                let searchResults = [];
-                try {
-                    searchResults = await provider.searchWeb(prompt.trim(), {
-                        count: numSources,
-                        apiKey: searchApiKey,
-                    });
-                }
-                catch (err) {
-                    log.warn('Search failed:', err.message);
-                }
-                sourceUrls = searchResults.slice(0, numSources).map((r) => ({
-                    url: r.url,
-                    title: r.title,
-                    snippet: r.snippet,
-                }));
-            }
-            if (sourceUrls.length === 0) {
-                return res.json({
-                    success: false,
-                    error: {
-                        type: 'no_sources',
-                        message: 'Could not find relevant pages for this query',
-                    },
-                    prompt,
-                    elapsed: Date.now() - startMs,
-                    requestId,
-                });
-            }
-            // -----------------------------------------------------------------------
-            // Step 2: Fetch pages in parallel (HTTP only, no browser, 5s timeout)
-            // -----------------------------------------------------------------------
-            log.info(`Fetching ${sourceUrls.length} sources in parallel`);
-            const PER_SOURCE_TIMEOUT_MS = 5000;
-            const fetchPromises = sourceUrls.map(async (source) => {
-                try {
-                    const result = await Promise.race([
-                        peel(source.url, {
-                            render: false,
-                            noEscalate: true,
-                            format: 'markdown',
-                            timeout: PER_SOURCE_TIMEOUT_MS,
-                            budget: 3000,
-                        }),
-                        new Promise((_, reject) => setTimeout(() => reject(new Error('per-source timeout')), PER_SOURCE_TIMEOUT_MS)),
-                    ]);
-                    return {
-                        url: source.url,
-                        title: result.title || source.title || '',
-                        content: (result.content || '').slice(0, 15000),
-                        tokens: result.tokens || 0,
-                    };
-                }
-                catch {
-                    return null;
-                }
-            });
-            const fetchSettled = await Promise.allSettled(fetchPromises);
-            const fetchResults = fetchSettled
-                .map((r) => (r.status === 'fulfilled' ? r.value : null))
-                .filter(Boolean);
-            if (fetchResults.length === 0) {
-                return res.json({
-                    success: false,
-                    error: {
-                        type: 'fetch_failed',
-                        message: 'Could not fetch any of the found pages',
-                    },
-                    prompt,
-                    sources: sourceUrls.map((s) => ({ url: s.url })),
-                    elapsed: Date.now() - startMs,
-                    requestId,
-                });
-            }
-            // -----------------------------------------------------------------------
-            // Step 3: Extract or answer
-            // -----------------------------------------------------------------------
-            const combinedContent = fetchResults
-                .map((r) => `### ${r.title || r.url}\nURL: ${r.url}\n\n${r.content}`)
-                .join('\n\n---\n\n');
-            const totalTokens = fetchResults.reduce((sum, r) => sum + r.tokens, 0);
-            let result;
-            if (schema && llmApiKey) {
-                // ── LLM extraction path ──────────────────────────────────────────────
-                log.info('Using LLM extraction');
-                const extracted = await extractWithLLM({
-                    content: combinedContent.slice(0, 30000),
-                    schema,
-                    llmApiKey,
-                    llmProvider: llmProvider || 'openai',
-                    llmModel,
-                    prompt: `Based on these web pages, ${prompt}`,
-                    url: fetchResults[0].url,
-                });
-                const llmTokensUsed = (extracted.tokensUsed?.input ?? 0) + (extracted.tokensUsed?.output ?? 0);
-                result = {
-                    success: true,
-                    data: extracted.items,
-                    sources: fetchResults.map((r) => ({ url: r.url, title: r.title })),
-                    method: 'agent-llm',
-                    llm: {
-                        provider: extracted.provider || llmProvider || 'openai',
-                        model: extracted.model || llmModel || 'default',
-                    },
-                    tokensUsed: totalTokens + llmTokensUsed,
-                    elapsed: Date.now() - startMs,
-                    requestId,
-                };
-            }
-            else {
-                // ── BM25 text answer path (no LLM needed) ───────────────────────────
-                log.info('Using BM25 text extraction');
-                const qa = quickAnswer({
-                    question: prompt,
-                    content: combinedContent,
-                    maxPassages: 3,
-                    maxChars: 2000,
-                });
-                result = {
-                    success: true,
-                    answer: qa.answer || combinedContent.slice(0, 2000),
-                    confidence: qa.confidence ?? 0,
-                    sources: fetchResults.map((r) => ({ url: r.url, title: r.title })),
-                    method: 'agent-bm25',
-                    tokensUsed: totalTokens,
-                    elapsed: Date.now() - startMs,
-                    requestId,
-                };
-            }
-            // Cache the result
-            setCache(cacheKey, result);
-            return res.json(result);
+            const result = await runAgentQuery({ prompt, schema, llmApiKey, llmProvider, llmModel, urls, sources: maxSources });
+            return res.json({ ...result, requestId });
         }
         catch (err) {
             log.error('Agent error:', err.message);
             return res.status(500).json({
-                success: false,
-                error: {
-                    type: 'agent_error',
-                    message: err.message || 'An unexpected error occurred',
-                },
-                prompt,
-                elapsed: Date.now() - startMs,
-                requestId,
+                success: false, error: { type: 'agent_error', message: err.message || 'An unexpected error occurred' },
+                prompt, elapsed: 0, requestId,
+            });
+        }
+    });
+    // ── POST /v1/agent/batch — parallel batch queries ─────────────────────
+    router.post('/batch', async (req, res) => {
+        const { prompts, schema, llmApiKey, llmProvider, llmModel, sources, webhook } = req.body || {};
+        const requestId = req.requestId || crypto.randomUUID();
+        if (!Array.isArray(prompts) || prompts.length === 0) {
+            return res.status(400).json({
+                success: false, error: { type: 'missing_prompts', message: 'Provide an array of prompts',
+                    hint: 'POST /v1/agent/batch { "prompts": ["Find X", "Find Y"] }' }, requestId,
+            });
+        }
+        if (prompts.length > 50) {
+            return res.status(400).json({
+                success: false, error: { type: 'too_many_prompts', message: `Max 50 prompts per batch (got ${prompts.length})` }, requestId,
             });
         }
+        const jobId = crypto.randomUUID();
+        const job = { id: jobId, status: 'processing', total: prompts.length, completed: 0, results: [], webhook, createdAt: Date.now() };
+        batchJobs.set(jobId, job);
+        // Return immediately, then process in background
+        res.json({ success: true, id: jobId, status: 'processing', total: prompts.length, requestId });
+        // Process in background with concurrency limit of 5
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        const sem = new Semaphore(5);
+        const tasks = prompts.map(async (prompt) => {
+            await sem.acquire();
+            try {
+                const result = await runAgentQuery({ prompt, schema, llmApiKey, llmProvider, llmModel, sources });
+                job.results.push({ prompt, success: !!result.success, answer: result.answer,
+                    data: result.data, sources: result.sources, method: result.method, elapsed: result.elapsed });
+            }
+            catch (err) {
+                job.results.push({ prompt, success: false, error: err.message });
+            }
+            finally {
+                job.completed++;
+                sem.release();
+            }
+        });
+        Promise.allSettled(tasks).then(() => {
+            job.status = job.results.every((r) => r.success) ? 'completed' : 'completed';
+            if (webhook) {
+                sendWebhook(webhook, 'agent.batch.completed', { id: jobId, total: job.total, completed: job.completed, results: job.results })
+                    .catch((err) => log.error('Batch webhook failed:', err.message));
+            }
+        });
+        return;
+    });
+    // ── GET /v1/agent/batch/:id — poll batch status ───────────────────────
+    router.get('/batch/:id', async (req, res) => {
+        const job = batchJobs.get(req.params.id);
+        if (!job) {
+            return res.status(404).json({ success: false, error: { type: 'not_found', message: 'Batch job not found or expired' } });
+        }
+        return res.json({ success: true, id: job.id, status: job.status, total: job.total, completed: job.completed, results: job.results });
     });
     return router;
 }

package/dist/server/routes/session.d.ts

@@ -6,9 +6,11 @@
  * POST   /v1/session/:id/navigate   → navigate to URL { url }
  * POST   /v1/session/:id/act        → execute PageActions array
  * GET    /v1/session/:id/screenshot → take screenshot (image/png)
+ * GET    /v1/session/:id/cookies    → export cookies from session context
+ * POST   /v1/session/:id/cookies    → inject cookies into session context
  * DELETE /v1/session/:id            → close session
  *
- * Use cases: login flows, multi-step automation, UI testing.
+ * Use cases: login flows, multi-step automation, UI testing, cookie persistence.
  * This is what Browserbase charges $500/mo for — built into WebPeel.
  */
 import { Router } from 'express';

package/dist/server/routes/session.js

@@ -6,9 +6,11 @@
  * POST   /v1/session/:id/navigate   → navigate to URL { url }
  * POST   /v1/session/:id/act        → execute PageActions array
  * GET    /v1/session/:id/screenshot → take screenshot (image/png)
+ * GET    /v1/session/:id/cookies    → export cookies from session context
+ * POST   /v1/session/:id/cookies    → inject cookies into session context
  * DELETE /v1/session/:id            → close session
  *
- * Use cases: login flows, multi-step automation, UI testing.
+ * Use cases: login flows, multi-step automation, UI testing, cookie persistence.
  * This is what Browserbase charges $500/mo for — built into WebPeel.
  */
 import { Router } from 'express';
@@ -17,13 +19,15 @@ import { normalizeActions, executeActions } from '../../core/actions.js';
 import { ANTI_DETECTION_ARGS, getRandomViewport, getRandomUserAgent, applyStealthScripts, } from '../../core/browser-pool.js';
 import { extractReadableContent } from '../../core/readability.js';
 const sessions = new Map();
-const SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes idle TTL
+const DEFAULT_SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes idle TTL (default)
+const MAX_SESSION_TTL_MS = 60 * 60 * 1000; // 60 minutes (persist / max)
+const MIN_SESSION_TTL_MS = 1 * 60 * 1000; // 1 minute minimum
 const MAX_SESSIONS_PER_USER = 3; // prevent abuse
 // Cleanup expired sessions every minute
 const _cleanupInterval = setInterval(() => {
     const now = Date.now();
     for (const [id, session] of sessions) {
-        if (now - session.lastUsedAt > SESSION_TTL_MS) {
+        if (now - session.lastUsedAt > session.ttlMs) {
             session.browser.close().catch(() => { });
             sessions.delete(id);
         }
@@ -73,7 +77,18 @@ function extractReadableText(html, url) {
 // ── Router ────────────────────────────────────────────────────────────────────
 export function createSessionRouter() {
     const router = Router();
-    // ── POST /v1/session — create session ────────────────────────────────────────
+    /**
+     * POST /v1/session — create a stateful browser session
+     *
+     * Body params:
+     *   url?     {string}  Initial URL to navigate to (optional).
+     *   ttl?     {number}  Session idle TTL in minutes (1–60, default 5).
+     *                      Timer resets on every request that touches the session.
+     *   persist? {boolean} Shorthand for ttl=60. Enables long-lived sessions
+     *                      for login flows where cookies must persist.
+     *
+     * Returns: { sessionId, currentUrl, expiresAt, ttlMinutes }
+     */
     router.post('/v1/session', async (req, res) => {
         const ownerId = getOwnerId(req);
         if (!ownerId) {
@@ -95,7 +110,15 @@ export function createSessionRouter() {
             });
             return;
         }
-        const { url } = req.body;
+        const { url, ttl, persist } = req.body;
+        // Resolve TTL: persist=true → 60 min max, ttl overrides default, clamp to [1, 60] min
+        let ttlMs = DEFAULT_SESSION_TTL_MS;
+        if (persist) {
+            ttlMs = MAX_SESSION_TTL_MS;
+        }
+        else if (typeof ttl === 'number') {
+            ttlMs = Math.min(MAX_SESSION_TTL_MS, Math.max(MIN_SESSION_TTL_MS, ttl * 60 * 1000));
+        }
         let browser = null;
         try {
             browser = await launchBrowser();
@@ -137,11 +160,13 @@ export function createSessionRouter() {
                 createdAt: now,
                 lastUsedAt: now,
                 currentUrl: page.url(),
+                ttlMs,
             });
             res.status(201).json({
                 sessionId: id,
                 currentUrl: page.url(),
-                expiresAt: new Date(now + SESSION_TTL_MS).toISOString(),
+                expiresAt: new Date(now + ttlMs).toISOString(),
+                ttlMinutes: ttlMs / 60_000,
             });
         }
         catch (err) {
@@ -188,7 +213,8 @@ export function createSessionRouter() {
                 currentUrl: session.page.url(),
                 title,
                 content,
-                expiresAt: new Date(session.lastUsedAt + SESSION_TTL_MS).toISOString(),
+                expiresAt: new Date(session.lastUsedAt + session.ttlMs).toISOString(),
+                ttlMinutes: session.ttlMs / 60_000,
             });
         }
         catch (err) {
@@ -242,7 +268,8 @@ export function createSessionRouter() {
             res.json({
                 currentUrl: session.page.url(),
                 title: await session.page.title(),
-                expiresAt: new Date(session.lastUsedAt + SESSION_TTL_MS).toISOString(),
+                expiresAt: new Date(session.lastUsedAt + session.ttlMs).toISOString(),
+                ttlMinutes: session.ttlMs / 60_000,
             });
         }
         catch (err) {
@@ -327,7 +354,8 @@ export function createSessionRouter() {
                 title,
                 screenshot,
                 actionsExecuted: normalizedActions.length,
-                expiresAt: new Date(session.lastUsedAt + SESSION_TTL_MS).toISOString(),
+                expiresAt: new Date(session.lastUsedAt + session.ttlMs).toISOString(),
+                ttlMinutes: session.ttlMs / 60_000,
             });
         }
         catch (err) {
@@ -367,6 +395,7 @@ export function createSessionRouter() {
             session.lastUsedAt = Date.now();
             res.setHeader('Content-Type', 'image/png');
             res.setHeader('Cache-Control', 'no-store');
+            res.setHeader('X-Session-Expires-At', new Date(session.lastUsedAt + session.ttlMs).toISOString());
             res.send(buf);
         }
         catch (err) {
@@ -382,6 +411,128 @@ export function createSessionRouter() {
             });
         }
     });
+    /**
+     * GET /v1/session/:id/cookies — export all cookies from the session's browser context
+     *
+     * Returns: { sessionId, cookies: Cookie[], count: number, expiresAt: string }
+     *
+     * Each cookie follows the Playwright Cookie shape:
+     *   { name, value, domain, path, expires, httpOnly, secure, sameSite }
+     *
+     * Use this to snapshot cookies after a login flow, then re-inject them later
+     * via POST /v1/session/:id/cookies to skip re-authentication.
+     */
+    router.get('/v1/session/:id/cookies', async (req, res) => {
+        const ownerId = getOwnerId(req);
+        const session = getSession(req.params['id'], ownerId);
+        if (!session) {
+            res.status(404).json({
+                success: false,
+                error: {
+                    type: 'session_not_found',
+                    message: 'Session not found or has expired.',
+                    hint: 'Create a new session via POST /v1/session.',
+                    docs: 'https://webpeel.dev/docs/errors#session-not-found',
+                },
+                requestId: req.requestId || randomUUID(),
+            });
+            return;
+        }
+        try {
+            // Playwright context.cookies() returns all cookies for all URLs by default
+            const cookies = await session.context.cookies();
+            session.lastUsedAt = Date.now();
+            res.json({
+                sessionId: session.id,
+                cookies,
+                count: cookies.length,
+                expiresAt: new Date(session.lastUsedAt + session.ttlMs).toISOString(),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            res.status(500).json({
+                success: false,
+                error: {
+                    type: 'cookie_export_failed',
+                    message: msg,
+                    docs: 'https://webpeel.dev/docs/errors#cookie-export-failed',
+                },
+                requestId: req.requestId || randomUUID(),
+            });
+        }
+    });
+    /**
+     * POST /v1/session/:id/cookies — inject cookies into the session's browser context
+     *
+     * Body params:
+     *   cookies {Cookie[]} Array of Playwright-compatible cookie objects.
+     *                      Required fields: name, value, domain (or url).
+     *                      Optional: path, expires, httpOnly, secure, sameSite.
+     *
+     * Returns: { sessionId, injected: number, expiresAt: string }
+     *
+     * Typical cookie-persistence workflow:
+     *   1. POST /v1/session { url: "https://example.com", persist: true }
+     *   2. POST /v1/session/:id/act  (complete login flow)
+     *   3. GET  /v1/session/:id/cookies  → save cookies array to your storage
+     *   4. Later: POST /v1/session/:id/cookies { cookies: [...] }
+     *   5. GET  /v1/session/:id  → page loads authenticated (no re-login needed)
+     */
+    router.post('/v1/session/:id/cookies', async (req, res) => {
+        const ownerId = getOwnerId(req);
+        const session = getSession(req.params['id'], ownerId);
+        if (!session) {
+            res.status(404).json({
+                success: false,
+                error: {
+                    type: 'session_not_found',
+                    message: 'Session not found or has expired.',
+                    hint: 'Create a new session via POST /v1/session.',
+                    docs: 'https://webpeel.dev/docs/errors#session-not-found',
+                },
+                requestId: req.requestId || randomUUID(),
+            });
+            return;
+        }
+        const { cookies } = req.body;
+        if (!Array.isArray(cookies) || cookies.length === 0) {
+            res.status(400).json({
+                success: false,
+                error: {
+                    type: 'bad_request',
+                    message: '`cookies` must be a non-empty array of cookie objects.',
+                    hint: 'Pass cookies exported from GET /v1/session/:id/cookies or a compatible Cookie[] array.',
+                    docs: 'https://webpeel.dev/docs/errors#bad-request',
+                },
+                requestId: req.requestId || randomUUID(),
+            });
+            return;
+        }
+        try {
+            // Playwright's addCookies validates the shape internally; invalid cookies will throw
+            await session.context.addCookies(cookies);
+            session.lastUsedAt = Date.now();
+            res.json({
+                sessionId: session.id,
+                injected: cookies.length,
+                expiresAt: new Date(session.lastUsedAt + session.ttlMs).toISOString(),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            res.status(400).json({
+                success: false,
+                error: {
+                    type: 'cookie_inject_failed',
+                    message: msg,
+                    hint: 'Ensure each cookie has at minimum: name, value, and domain (or url).',
+                    docs: 'https://webpeel.dev/docs/errors#cookie-inject-failed',
+                },
+                requestId: req.requestId || randomUUID(),
+            });
+        }
+    });
     // ── DELETE /v1/session/:id ───────────────────────────────────────────────────
     router.delete('/v1/session/:id', async (req, res) => {
         const ownerId = getOwnerId(req);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webpeel",
-  "version": "0.20.5",
+  "version": "0.20.6",
   "description": "Fast web fetcher for AI agents - stealth mode, crawl mode, page actions, structured extraction, PDF parsing, smart escalation from simple HTTP to headless browser",
   "author": "Jake Liu",
   "license": "AGPL-3.0-only",