@showrun/core 0.1.0 → 0.1.1-b

package/dist/requestSnapshot.js

@@ -0,0 +1,200 @@
+/**
+ * Request Snapshot types and utilities.
+ *
+ * Snapshots record the HTTP request/response details of `network_replay` steps
+ * so they can be replayed at runtime via direct HTTP calls — no browser needed.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { resolveTemplate } from './dsl/templating.js';
+// ---------------------------------------------------------------------------
+// Staleness
+// ---------------------------------------------------------------------------
+/**
+ * Check if a snapshot is stale based on its TTL.
+ * Returns false when `ttl` is null (indefinite).
+ */
+export function isSnapshotStale(snapshot) {
+    if (snapshot.ttl === null)
+        return false;
+    return Date.now() - snapshot.capturedAt > snapshot.ttl;
+}
+/**
+ * Validate an HTTP response against a snapshot's expected shape.
+ */
+export function validateResponse(snapshot, response) {
+    const v = snapshot.responseValidation;
+    if (response.status !== v.expectedStatus) {
+        return {
+            valid: false,
+            reason: `Expected status ${v.expectedStatus}, got ${response.status}`,
+        };
+    }
+    if (v.expectedContentType &&
+        response.contentType &&
+        !response.contentType.toLowerCase().startsWith(v.expectedContentType.toLowerCase())) {
+        return {
+            valid: false,
+            reason: `Expected content-type starting with "${v.expectedContentType}", got "${response.contentType}"`,
+        };
+    }
+    if (v.expectedKeys.length > 0) {
+        try {
+            const parsed = JSON.parse(response.body);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const bodyKeys = Object.keys(parsed);
+                const missing = v.expectedKeys.filter((k) => !bodyKeys.includes(k));
+                if (missing.length > 0) {
+                    return {
+                        valid: false,
+                        reason: `Missing expected keys: ${missing.join(', ')}`,
+                    };
+                }
+            }
+        }
+        catch {
+            // If we expected JSON keys but can't parse, that's a validation failure
+            return {
+                valid: false,
+                reason: 'Response body is not valid JSON but expectedKeys were specified',
+            };
+        }
+    }
+    return { valid: true };
+}
+// ---------------------------------------------------------------------------
+// Override application
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a template string using Nunjucks (same engine as the DSL interpreter).
+ * Supports {{inputs.x}}, {{vars.x}}, {{secret.x}} and filters like `| urlencode`.
+ */
+function resolveTemplateValue(template, ctx) {
+    return resolveTemplate(template, ctx);
+}
+/**
+ * Apply overrides from the snapshot to produce the final request parameters.
+ * Template expressions ({{inputs.x}}, {{vars.y}}, {{secret.z}}) are resolved
+ * using Nunjucks — the same engine as the DSL interpreter, including filters.
+ */
+export function applyOverrides(snapshot, inputs, vars, secrets) {
+    const ov = snapshot.overrides;
+    let url = snapshot.request.url;
+    let body = snapshot.request.body;
+    const method = snapshot.request.method;
+    const headers = { ...snapshot.request.headers };
+    if (!ov) {
+        return { url, method, headers, body };
+    }
+    const ctx = { inputs, vars, secrets: secrets ?? {} };
+    // urlReplace
+    if (ov.urlReplace) {
+        for (const r of ov.urlReplace) {
+            const find = resolveTemplateValue(r.find, ctx);
+            const replace = resolveTemplateValue(r.replace, ctx);
+            try {
+                url = url.replace(new RegExp(find, 'g'), replace);
+            }
+            catch {
+                // If regex is invalid, try literal replace
+                url = url.split(find).join(replace);
+            }
+        }
+    }
+    // setQuery
+    if (ov.setQuery) {
+        const u = new URL(url);
+        for (const [k, v] of Object.entries(ov.setQuery)) {
+            const resolved = resolveTemplateValue(v, ctx);
+            u.searchParams.set(k, resolved);
+        }
+        url = u.toString();
+    }
+    // setHeaders
+    if (ov.setHeaders) {
+        for (const [k, v] of Object.entries(ov.setHeaders)) {
+            headers[k] = resolveTemplateValue(v, ctx);
+        }
+    }
+    // Direct URL override (applied after urlReplace, matching networkCapture.ts)
+    if (ov.url != null) {
+        url = resolveTemplateValue(ov.url, ctx);
+    }
+    // bodyReplace
+    if (body && ov.bodyReplace) {
+        for (const r of ov.bodyReplace) {
+            const find = resolveTemplateValue(r.find, ctx);
+            const replace = resolveTemplateValue(r.replace, ctx);
+            try {
+                body = body.replace(new RegExp(find, 'g'), replace);
+            }
+            catch {
+                body = body.split(find).join(replace);
+            }
+        }
+    }
+    // Direct body override (applied after bodyReplace, matching networkCapture.ts)
+    if (ov.body != null) {
+        body = resolveTemplateValue(ov.body, ctx);
+    }
+    return { url, method, headers, body };
+}
+// ---------------------------------------------------------------------------
+// File I/O
+// ---------------------------------------------------------------------------
+const SNAPSHOTS_FILENAME = 'snapshots.json';
+/**
+ * Load snapshots.json from a pack directory. Returns null if not found.
+ */
+export function loadSnapshots(packPath) {
+    const filePath = join(packPath, SNAPSHOTS_FILENAME);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        if (data.version !== 1) {
+            console.warn(`[requestSnapshot] Unsupported snapshot version: ${data.version}`);
+            return null;
+        }
+        return data;
+    }
+    catch (err) {
+        console.warn(`[requestSnapshot] Failed to load snapshots.json: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Write snapshots.json to a pack directory.
+ */
+export function writeSnapshots(packPath, snapshots) {
+    const filePath = join(packPath, SNAPSHOTS_FILENAME);
+    writeFileSync(filePath, JSON.stringify(snapshots, null, 2), 'utf-8');
+}
+// ---------------------------------------------------------------------------
+// Capture helpers
+// ---------------------------------------------------------------------------
+const SENSITIVE_HEADER_NAMES = ['authorization', 'cookie', 'set-cookie', 'x-api-key', 'proxy-authorization'];
+/**
+ * Extract top-level keys from a JSON string. Returns empty array on parse failure.
+ */
+export function extractTopLevelKeys(jsonText) {
+    if (!jsonText)
+        return [];
+    try {
+        const parsed = JSON.parse(jsonText);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return Object.keys(parsed);
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Detect which headers in a record are sensitive (contain auth data).
+ */
+export function detectSensitiveHeaders(headers) {
+    return Object.keys(headers).filter((h) => SENSITIVE_HEADER_NAMES.includes(h.toLowerCase()));
+}

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAc,MAAM,YAAY,CAAC;AAElE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA6L5B"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAc,MAAM,YAAY,CAAC;AAElE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAWzC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,SAAS;IAClD;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAmQ5B"}

package/dist/runner.js

@@ -2,6 +2,8 @@ import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { InputValidator, RunContextFactory, runFlow, attachNetworkCapture, TaskPackLoader } from './index.js';
 import { launchBrowser } from './browserLauncher.js';
+import { isFlowHttpCompatible } from './httpReplay.js';
+import { writeSnapshots, extractTopLevelKeys, detectSensitiveHeaders, } from './requestSnapshot.js';
 /**
  * Runs a task pack with Playwright
  * This is a reusable function that can be used by both CLI and MCP server
@@ -10,8 +12,6 @@ export async function runTaskPack(taskPack, inputs, options) {
     const { runDir, logger, headless: requestedHeadless = true, packPath, secrets: providedSecrets } = options;
     const artifactsDir = join(runDir, 'artifacts');
     const eventsPath = join(runDir, 'events.jsonl');
-    // Load secrets from pack directory if not provided and packPath is given
-    const secrets = providedSecrets ?? (packPath ? TaskPackLoader.loadSecrets(packPath) : {});
     // Ensure directories exist
     mkdirSync(runDir, { recursive: true });
     mkdirSync(artifactsDir, { recursive: true });
@@ -24,14 +24,14 @@ export async function runTaskPack(taskPack, inputs, options) {
             'Falling back to headless mode. Set DISPLAY or use xvfb-run to enable headful mode.');
     }
     const startTime = Date.now();
-    let browserSession = null;
-    let page = null;
-    let runContext = null;
-    try {
-        // Apply defaults and validate inputs
-        const inputsWithDefaults = InputValidator.applyDefaults(inputs, taskPack.inputs);
-        InputValidator.validate(inputsWithDefaults, taskPack.inputs);
-        // Log run start
+    // Apply defaults and validate inputs early (needed for both HTTP and browser modes)
+    const inputsWithDefaults = InputValidator.applyDefaults(inputs, taskPack.inputs);
+    InputValidator.validate(inputsWithDefaults, taskPack.inputs);
+    // Load secrets early (needed for both modes)
+    const secrets = providedSecrets ?? (packPath ? TaskPackLoader.loadSecrets(packPath) : {});
+    // ─── HTTP-first execution ───────────────────────────────────────────
+    const snapshots = taskPack.snapshots ?? null;
+    if (isFlowHttpCompatible(taskPack.flow, snapshots)) {
         logger.log({
             type: 'run_started',
             data: {
@@ -40,6 +40,34 @@ export async function runTaskPack(taskPack, inputs, options) {
                 inputs: inputsWithDefaults,
             },
         });
+        try {
+            const httpResult = await runHttpOnly(taskPack, inputsWithDefaults, snapshots, secrets, logger, options);
+            const durationMs = Date.now() - startTime;
+            logger.log({ type: 'run_finished', data: { success: true, durationMs } });
+            return { ...httpResult, runDir, eventsPath, artifactsDir };
+        }
+        catch (httpError) {
+            // HTTP-only execution failed — fall through to browser mode
+            const reason = httpError instanceof Error ? httpError.message : String(httpError);
+            console.log(`[runner] HTTP-only mode failed (${reason}), falling back to browser mode`);
+        }
+    }
+    // ─── Browser execution (fallback or primary) ───────────────────────
+    let browserSession = null;
+    let page = null;
+    let runContext = null;
+    try {
+        // Log run start (only if not already logged above)
+        if (!isFlowHttpCompatible(taskPack.flow, snapshots)) {
+            logger.log({
+                type: 'run_started',
+                data: {
+                    packId: taskPack.metadata.id,
+                    packVersion: taskPack.metadata.version,
+                    inputs: inputsWithDefaults,
+                },
+            });
+        }
         // Launch browser with unified launcher
         browserSession = await launchBrowser({
             browserSettings: taskPack.browser,
@@ -93,6 +121,15 @@ export async function runTaskPack(taskPack, inputs, options) {
         if (flowResult._hints && flowResult._hints.length > 0) {
             result._hints = flowResult._hints;
         }
+        // Capture snapshots for network_replay steps after successful browser run
+        if (packPath && networkCapture) {
+            try {
+                captureSnapshots(taskPack, flowResult, networkCapture, packPath);
+            }
+            catch (snapErr) {
+                console.warn(`[runner] Failed to capture snapshots: ${snapErr instanceof Error ? snapErr.message : String(snapErr)}`);
+            }
+        }
         const durationMs = Date.now() - startTime;
         // Log run finish
         logger.log({
@@ -141,6 +178,18 @@ export async function runTaskPack(taskPack, inputs, options) {
                 console.error('Failed to save artifacts:', artifactError);
             }
         }
+        // Extract partial results from enriched error (set by interpreter)
+        const partialResult = error?.partialResult;
+        // Filter partial collectibles to only include declared ones
+        let partialCollectibles = {};
+        if (partialResult?.collectibles) {
+            const definedCollectibleNames = new Set((taskPack.collectibles || []).map(c => c.name));
+            for (const [key, value] of Object.entries(partialResult.collectibles)) {
+                if (definedCollectibleNames.has(key)) {
+                    partialCollectibles[key] = value;
+                }
+            }
+        }
         // Log run finish with failure
         logger.log({
             type: 'run_finished',
@@ -150,16 +199,21 @@ export async function runTaskPack(taskPack, inputs, options) {
             },
         });
         // Return partial result with paths even on error
-        return {
-            collectibles: {},
+        const failResult = {
+            collectibles: partialCollectibles,
             meta: {
                 durationMs,
-                notes: `Error: ${errorMessage}`,
+                notes: `Error at step "${partialResult?.failedStepId ?? 'unknown'}": ${errorMessage}`,
             },
             runDir,
             eventsPath,
             artifactsDir,
         };
+        // Include failedStepId for AI agents
+        if (partialResult?.failedStepId) {
+            failResult.failedStepId = partialResult.failedStepId;
+        }
+        return failResult;
     }
     finally {
         // Cleanup using unified browser session close
@@ -168,3 +222,145 @@ export async function runTaskPack(taskPack, inputs, options) {
         }
     }
 }
+// ---------------------------------------------------------------------------
+// HTTP-only execution helper
+// ---------------------------------------------------------------------------
+/**
+ * Run a flow in HTTP-only mode using request snapshots.
+ * No browser is launched; network_replay steps use Node fetch().
+ * Throws if any snapshot response fails validation (caller should fall back to browser mode).
+ */
+async function runHttpOnly(taskPack, inputs, snapshots, secrets, logger, options) {
+    console.log(`[runner] Running in HTTP-only mode (${Object.keys(snapshots.snapshots).length} snapshots)`);
+    // Build a minimal RunContext that doesn't require a browser.
+    // In HTTP mode the interpreter skips all DOM steps, so page/browser are never accessed.
+    const noopPage = null;
+    const noopBrowser = null;
+    const noopArtifacts = {
+        saveScreenshot: async () => '',
+        saveHTML: async () => '',
+    };
+    const runContext = {
+        page: noopPage,
+        browser: noopBrowser,
+        logger,
+        artifacts: noopArtifacts,
+    };
+    const flowResult = await runFlow(runContext, taskPack.flow, {
+        inputs,
+        auth: taskPack.auth,
+        sessionId: options.sessionId,
+        profileId: options.profileId,
+        cacheDir: options.cacheDir,
+        secrets,
+        httpMode: true,
+        snapshots,
+    });
+    // Validate responses: re-check each network_replay step's snapshot validation.
+    // The actual validation happens inside the step handler via replayFromSnapshot +
+    // validateResponse. If validation fails, the step throws and runFlow propagates
+    // the error, which the caller catches and falls back to browser mode.
+    // Filter collectibles to only include those defined in the pack
+    const definedCollectibleNames = new Set((taskPack.collectibles || []).map((c) => c.name));
+    const filteredCollectibles = {};
+    for (const [key, value] of Object.entries(flowResult.collectibles)) {
+        if (definedCollectibleNames.has(key)) {
+            filteredCollectibles[key] = value;
+        }
+    }
+    const result = {
+        collectibles: filteredCollectibles,
+        meta: {
+            durationMs: flowResult.meta.durationMs,
+            notes: `HTTP-only: ${flowResult.meta.stepsExecuted}/${flowResult.meta.stepsTotal} steps`,
+        },
+    };
+    if (flowResult._hints && flowResult._hints.length > 0) {
+        result._hints = flowResult._hints;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Snapshot capture helper
+// ---------------------------------------------------------------------------
+/**
+ * After a successful browser run, capture snapshots for all network_replay steps.
+ * Uses the resolved vars from the flow result to look up request IDs,
+ * then exports full entry data from the network capture buffer.
+ * Writes snapshots.json to the pack directory.
+ */
+function captureSnapshots(taskPack, flowResult, networkCapture, packPath) {
+    const replaySteps = taskPack.flow.filter((s) => s.type === 'network_replay');
+    if (replaySteps.length === 0)
+        return;
+    const vars = flowResult._vars ?? {};
+    const newSnapshots = {};
+    for (const step of replaySteps) {
+        if (step.type !== 'network_replay')
+            continue;
+        // Resolve the requestId template (e.g. "{{vars.reqId}}" → actual ID)
+        const rawRequestId = step.params.requestId;
+        let requestId;
+        // Check if it's a template reference
+        const varMatch = rawRequestId.match(/\{\{vars\.([^}]+)\}\}/);
+        if (varMatch) {
+            const varName = varMatch[1];
+            requestId = typeof vars[varName] === 'string' ? vars[varName] : undefined;
+        }
+        else {
+            // Literal request ID
+            requestId = rawRequestId;
+        }
+        if (!requestId)
+            continue;
+        // Export the full entry from the network capture buffer
+        const fullEntry = networkCapture.exportEntry(requestId);
+        if (!fullEntry || fullEntry.status === undefined)
+            continue;
+        // Build the snapshot
+        const snapshot = {
+            stepId: step.id,
+            capturedAt: Date.now(),
+            ttl: null, // indefinite by default
+            request: {
+                method: fullEntry.method,
+                url: fullEntry.url,
+                headers: fullEntry.requestHeadersFull,
+                body: fullEntry.postData ?? null,
+            },
+            overrides: step.params.overrides
+                ? {
+                    url: step.params.overrides.url,
+                    body: step.params.overrides.body,
+                    setQuery: step.params.overrides.setQuery
+                        ? Object.fromEntries(Object.entries(step.params.overrides.setQuery).map(([k, v]) => [k, String(v)]))
+                        : undefined,
+                    setHeaders: step.params.overrides.setHeaders,
+                    urlReplace: step.params.overrides.urlReplace
+                        ? (Array.isArray(step.params.overrides.urlReplace) ? step.params.overrides.urlReplace : [step.params.overrides.urlReplace])
+                        : undefined,
+                    bodyReplace: step.params.overrides.bodyReplace
+                        ? (Array.isArray(step.params.overrides.bodyReplace) ? step.params.overrides.bodyReplace : [step.params.overrides.bodyReplace])
+                        : undefined,
+                }
+                : undefined,
+            responseValidation: {
+                expectedStatus: fullEntry.status ?? 200,
+                expectedContentType: fullEntry.contentType ?? 'application/json',
+                expectedKeys: extractTopLevelKeys(fullEntry.responseBodyText),
+            },
+            sensitiveHeaders: detectSensitiveHeaders(fullEntry.requestHeadersFull),
+        };
+        newSnapshots[step.id] = snapshot;
+    }
+    if (Object.keys(newSnapshots).length > 0) {
+        // Merge with existing snapshots (update existing, add new)
+        const existing = taskPack.snapshots ?? { version: 1, snapshots: {} };
+        const merged = {
+            version: 1,
+            snapshots: { ...existing.snapshots, ...newSnapshots },
+        };
+        writeSnapshots(packPath, merged);
+        console.log(`[runner] Captured ${Object.keys(newSnapshots).length} snapshot(s) → snapshots.json`);
+    }
+}

package/dist/storage/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './keys.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './keys.js';

package/dist/storage/keys.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Produce a canonical, stable JSON representation of inputs.
+ * - Sorts object keys recursively
+ * - Strips `undefined` values
+ */
+export declare function canonicalizeInputs(inputs: Record<string, unknown>): string;
+/**
+ * Generate a deterministic result key from pack ID and inputs.
+ * Same packId + same inputs ⇒ same key (latest-wins cache).
+ */
+export declare function generateResultKey(packId: string, inputs: Record<string, unknown>): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/storage/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/storage/keys.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE1E;AAkBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAGR"}

package/dist/storage/keys.js

@@ -0,0 +1,39 @@
+/**
+ * Deterministic key generation for stored results.
+ *
+ * key = sha256(packId + ":" + canonicalized_inputs)[0..16]  (16-char hex)
+ */
+import { createHash } from 'crypto';
+/**
+ * Produce a canonical, stable JSON representation of inputs.
+ * - Sorts object keys recursively
+ * - Strips `undefined` values
+ */
+export function canonicalizeInputs(inputs) {
+    return JSON.stringify(sortKeys(inputs));
+}
+function sortKeys(obj) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(sortKeys);
+    if (typeof obj === 'object') {
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            const val = obj[key];
+            if (val !== undefined) {
+                sorted[key] = sortKeys(val);
+            }
+        }
+        return sorted;
+    }
+    return obj;
+}
+/**
+ * Generate a deterministic result key from pack ID and inputs.
+ * Same packId + same inputs ⇒ same key (latest-wins cache).
+ */
+export function generateResultKey(packId, inputs) {
+    const payload = packId + ':' + canonicalizeInputs(inputs);
+    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Pluggable Result Store — Pure interfaces (no external deps)
+ *
+ * Providers declare their capabilities so consumers (MCP tools)
+ * know which operations are available.
+ */
+export type StorageCapability = 'get' | 'store' | 'list' | 'delete' | 'filter' | 'search' | 'aggregate';
+/**
+ * Schema field describing a collectible column (for AI-friendly descriptions).
+ */
+export interface CollectibleSchemaField {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    description?: string;
+}
+/**
+ * A single stored run result.
+ */
+export interface StoredResult {
+    /** Deterministic hash of packId + inputs */
+    key: string;
+    packId: string;
+    toolName: string;
+    inputs: Record<string, unknown>;
+    collectibles: Record<string, unknown>;
+    meta: {
+        url?: string;
+        durationMs: number;
+        notes?: string;
+    };
+    collectibleSchema: CollectibleSchemaField[];
+    /** ISO 8601 — when the result was (last) stored */
+    storedAt: string;
+    /** ISO 8601 — when the run actually executed */
+    ranAt: string;
+    /** Incremented on overwrite (same key) */
+    version: number;
+}
+/**
+ * Options for listing stored results.
+ */
+export interface ListOptions {
+    limit?: number;
+    offset?: number;
+    sortBy?: 'storedAt' | 'ranAt';
+    sortDir?: 'asc' | 'desc';
+}
+/**
+ * Lightweight summary returned by list().
+ */
+export interface ResultSummary {
+    key: string;
+    packId: string;
+    toolName: string;
+    storedAt: string;
+    version: number;
+    fieldCount: number;
+}
+/**
+ * Filter/paginate within a single stored result's collectibles.
+ */
+export interface FilterOptions {
+    /** Which stored result to filter within */
+    key: string;
+    /** JMESPath expression for extraction/transform */
+    jmesPath?: string;
+    /** Limit items (for array results) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Field to sort by within collectibles */
+    sortBy?: string;
+    sortDir?: 'asc' | 'desc';
+}
+/**
+ * Full-text search options (for future vector/FTS providers).
+ */
+export interface SearchOptions {
+    query: string;
+    limit?: number;
+}
+export interface SearchHit {
+    key: string;
+    packId: string;
+    toolName: string;
+    score: number;
+    snippet?: string;
+}
+/**
+ * The pluggable store interface.
+ * Only `capabilities()`, `store()`, and `get()` are required.
+ * Optional methods should only be called if the corresponding capability is declared.
+ */
+export interface ResultStoreProvider {
+    capabilities(): StorageCapability[];
+    store(result: StoredResult): Promise<void>;
+    get(key: string): Promise<StoredResult | null>;
+    list?(options?: ListOptions): Promise<{
+        results: ResultSummary[];
+        total: number;
+    }>;
+    delete?(key: string): Promise<boolean>;
+    filter?(options: FilterOptions): Promise<{
+        data: unknown;
+        total?: number;
+    }>;
+    search?(options: SearchOptions): Promise<{
+        results: SearchHit[];
+    }>;
+    close?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

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