@reclaimprotocol/agent 0.1.5 → 0.1.7

package/lib/authoring/backend.d.ts

@@ -69,27 +69,3 @@ export interface AuthoringBackend {
         withoutSecrets?: boolean;
     }): Promise<unknown>;
 }
-/**
- * How a host (MCP / cloud) supplies its environment to the shared authoring
- * tools, which are authored once with the common `defineTool` primitive and
- * built per host by `buildAuthoringTools(host)`:
- *   - `resolveBackend`: hand back the backend for one call. The MCP resolves it
- *     from `args.captureId` (multi-session); the cloud returns its one run
- *     backend.
- *   - `sessionSchema`: input-schema props merged into EVERY tool (the MCP adds
- *     `captureId`; the cloud adds nothing — the backend is implicit).
- *   - `toolExtras`: per-tool schema/description additions (the MCP's rich,
- *     credential-aware `run_proof` contract).
- */
-export interface AuthoringHost {
-    resolveBackend(args: Record<string, unknown>): AuthoringBackend;
-    sessionSchema?: {
-        properties: Record<string, unknown>;
-        required?: string[];
-    };
-    toolExtras?: Record<string, {
-        description?: string;
-        properties?: Record<string, unknown>;
-        required?: string[];
-    }>;
-}

package/lib/authoring/find.d.ts

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../tools/registry.ts';
+import { type ResolveBackend } from './util.ts';
+export declare function findTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/find.js

@@ -0,0 +1,54 @@
+/**
+ * `find_requests_containing` — search captured responses for any encoding of a
+ * value and rank the requests that return it. Authored once as a plain
+ * {@link RegisteredTool}; the MCP and cloud loop each pass their own backend
+ * resolver (see tools.ts / mcp/tools/agent/shared.ts). Server-side: response
+ * bodies stay here, only metadata + a short snippet leave.
+ */
+import { normalizeCandidates } from "../provider/normalize.js";
+import { defineTool } from "../tools/registry.js";
+import { objectSchema, publicRequest } from "./util.js";
+export function findTool(resolveBackend) {
+    return defineTool({
+        name: 'find_requests_containing',
+        description: 'Search captured responses for any encoding of `value` (raw, '
+            + 'URL/JSON/HTML-escaped, …). Returns a ranked candidate list with '
+            + 'the matched variant, score, and a short snippet — used to locate '
+            + 'the request that returns a target. Server-side; bodies stay here.',
+        inputSchema: objectSchema({ value: { type: 'string' }, limit: { type: 'number' } }, ['value']),
+    }, async (args) => {
+        const backend = resolveBackend(args);
+        const variants = normalizeCandidates(String(args.value));
+        const ranked = [];
+        for (const r of backend.capture.requests.values()) {
+            if (!r.responseBody) {
+                continue;
+            }
+            let hit;
+            for (const v of variants) {
+                const idx = r.responseBody.indexOf(v);
+                if (idx >= 0) {
+                    const start = Math.max(0, idx - 40);
+                    const end = Math.min(r.responseBody.length, idx + v.length + 40);
+                    hit = { snippet: r.responseBody.slice(start, end), variant: v };
+                    break;
+                }
+            }
+            if (!hit) {
+                continue;
+            }
+            // Prefer JSON responses + smaller bodies (likely API endpoints).
+            const score = (r.contentType.includes('json') ? 10 : 0)
+                + Math.max(0, 5 - Math.log10(Math.max(r.size, 1)));
+            ranked.push({
+                ...publicRequest(r),
+                matchedVariant: hit.variant,
+                snippet: hit.snippet,
+                score,
+            });
+        }
+        ranked.sort((a, b) => b.score - a.score);
+        const limit = Number(args.limit) || 10;
+        return { candidates: ranked.slice(0, limit) };
+    });
+}

package/lib/authoring/index.d.ts

@@ -1,4 +1,4 @@
-export type { AuthoringBackend, AuthoringHost, Draft, DraftStore, ProveOptions, SecretParams, } from './backend.ts';
+export type { AuthoringBackend, Draft, DraftStore, ProveOptions, SecretParams, } from './backend.ts';
 export { makeDraftStore } from './backend.ts';
-export { buildAuthoringTools } from './tools.ts';
-export { defineTool, type RegisteredTool, type ToolDefinition, } from '../tools/registry.ts';
+export { authoringTools } from './tools.ts';
+export { defineTool, extendTool, type RegisteredTool, type ToolDefinition, } from '../tools/registry.ts';

package/lib/authoring/index.js

@@ -1,5 +1,6 @@
 export { makeDraftStore } from "./backend.js";
-export { buildAuthoringTools } from "./tools.js";
+export { authoringTools } from "./tools.js";
 // The shared tool primitive — re-exported so consumers (the cloud loop) get the
-// RegisteredTool type/`defineTool` without importing the MCP subsystem.
-export { defineTool, } from "../tools/registry.js";
+// RegisteredTool type/`defineTool`/`extendTool` without importing the MCP
+// subsystem.
+export { defineTool, extendTool, } from "../tools/registry.js";

package/lib/authoring/propose.d.ts

@@ -0,0 +1,3 @@
+import { type RegisteredTool } from '../tools/registry.ts';
+import { type ResolveBackend } from './util.ts';
+export declare function proposeTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/propose.js

@@ -0,0 +1,109 @@
+/**
+ * `propose_provider` — draft a provider (recipe + captured secrets) from ONE
+ * captured request, one match + redaction per target value. Authored once as a
+ * plain {@link RegisteredTool}; hosts pass their own backend resolver. The
+ * draft (recipe + real secret header values) is held server-side under an
+ * opaque `draftId`; the result carries only the secret-free provider.
+ */
+import { draftProvider } from "../provider/draft.js";
+import { OPRF_MAX_BYTES } from "../provider/matcher.js";
+import { verificationWarnings } from "../provider/verification-checks.js";
+import { defineTool } from "../tools/registry.js";
+import { objectSchema } from "./util.js";
+export function proposeTool(resolveBackend) {
+    return defineTool({
+        name: 'propose_provider',
+        description: 'Draft a provider from ONE captured request. Pass `targets` (an '
+            + 'array): one entry per value to extract, each with its `value` '
+            + '(verbatim) and a distinct `name` (its param). The provider gets '
+            + 'one match + redaction per target. Returns a draftId + recipe '
+            + '(never secrets). Prefer a SINGLE request holding ALL values. '
+            + 'Single-value shorthand: `target` + `name`. Per-target `hash` '
+            + 'OPRF-hashes that value.',
+        inputSchema: objectSchema({
+            requestId: { type: 'string' },
+            name: { type: 'string' },
+            targets: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        value: { type: 'string' },
+                        name: { type: 'string' },
+                        hash: {
+                            type: 'string',
+                            enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
+                        },
+                    },
+                    required: ['value', 'name'],
+                },
+            },
+            target: { type: 'string' },
+            hash: { type: 'string', enum: ['oprf-raw', 'oprf', 'oprf-mpc'] },
+        }, ['requestId', 'name']),
+    }, async (args) => {
+        const backend = resolveBackend(args);
+        const requestId = String(args.requestId);
+        const providerName = String(args.name);
+        const defaultHash = args.hash;
+        // Explicit multi-value `targets`, else the single `target` shorthand.
+        const raw = Array.isArray(args.targets) ? args.targets : [];
+        const targets = raw.length
+            ? raw.map((t) => {
+                const o = t;
+                return {
+                    value: String(o.value),
+                    name: String(o.name),
+                    ...(typeof o.hash === 'string'
+                        ? { hash: o.hash }
+                        : {}),
+                };
+            })
+            : typeof args.target === 'string'
+                ? [{
+                        value: args.target,
+                        name: providerName,
+                        ...(defaultHash ? { hash: defaultHash } : {}),
+                    }]
+                : [];
+        if (targets.length === 0) {
+            throw new Error('propose_provider needs a `target` value or a non-empty '
+                + '`targets` array');
+        }
+        for (const t of targets) {
+            if ((t.hash ?? defaultHash) !== undefined
+                && t.value.length > OPRF_MAX_BYTES) {
+                throw new Error(`OPRF caps hashed values at ${OPRF_MAX_BYTES} bytes; got `
+                    + `${t.value.length}-byte "${t.value}". Use a tighter `
+                    + 'target or drop `hash`.');
+            }
+        }
+        const captured = backend.capture.requests.get(requestId);
+        if (!captured) {
+            throw new Error(`no captured request ${requestId}`);
+        }
+        if (!captured.responseBody) {
+            throw new Error(`request body unavailable for ${requestId}`);
+        }
+        const { provider, secretRefs, extractions } = draftProvider(captured, targets, providerName, defaultHash);
+        // Materialize the real secret header values for later replay/prove;
+        // they stay in the server-side draft, never in this result.
+        const secrets = {};
+        for (const ref of secretRefs) {
+            const real = captured.requestHeaders[ref.name];
+            if (real !== undefined) {
+                secrets[ref.name] = real;
+            }
+        }
+        const draftId = backend.drafts.put({
+            provider, secretRefs, secrets, requestId, extractions,
+        });
+        const warnings = verificationWarnings(provider);
+        return {
+            draftId,
+            provider,
+            secretRefs,
+            ...(warnings.length ? { verificationWarnings: warnings } : {}),
+        };
+    });
+}

package/lib/authoring/replay.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `replay_request` — validate a drafted recipe before proving: confirm its
+ * selectors extract the target(s), and (with `withoutSecrets`) that the
+ * endpoint is auth-bound. Authored once as a plain {@link RegisteredTool}; the
+ * backend does the actual replay (MCP re-runs locally, cloud re-issues in the
+ * TEE pod).
+ */
+import { type RegisteredTool } from '../tools/registry.ts';
+import { type ResolveBackend } from './util.ts';
+export declare function replayTool(resolveBackend: ResolveBackend): RegisteredTool;

package/lib/authoring/replay.js

@@ -0,0 +1,34 @@
+/**
+ * `replay_request` — validate a drafted recipe before proving: confirm its
+ * selectors extract the target(s), and (with `withoutSecrets`) that the
+ * endpoint is auth-bound. Authored once as a plain {@link RegisteredTool}; the
+ * backend does the actual replay (MCP re-runs locally, cloud re-issues in the
+ * TEE pod).
+ */
+import { defineTool } from "../tools/registry.js";
+import { objectSchema } from "./util.js";
+export function replayTool(resolveBackend) {
+    return defineTool({
+        name: 'replay_request',
+        description: 'Validate the drafted recipe before proving — confirm its selectors '
+            + 'extract the target value. Returns diagnostics; run before '
+            + 'proving. Set `withoutSecrets: true` for the AUTH-BOUND check: it '
+            + 're-issues the request with NO secrets/cookies (an anonymous '
+            + 'visitor). If the values still extract (valid:true), the endpoint '
+            + 'is PUBLIC and the proof would not bind to the user — reject it '
+            + 'and find an auth-bound request instead.',
+        inputSchema: objectSchema({
+            draftId: { type: 'string' },
+            withoutSecrets: { type: 'boolean' },
+        }, ['draftId']),
+    }, async (args) => {
+        const backend = resolveBackend(args);
+        const draft = backend.drafts.get(String(args.draftId));
+        if (!draft) {
+            throw new Error(`no draft ${String(args.draftId)}`);
+        }
+        return backend.replay(draft, {
+            withoutSecrets: Boolean(args.withoutSecrets),
+        });
+    });
+}

package/lib/authoring/tools.d.ts

@@ -1,9 +1,16 @@
 import { type RegisteredTool } from '../tools/registry.ts';
-import type { AuthoringHost } from './backend.ts';
+import { type ResolveBackend } from './util.ts';
 /**
- * Build the authoring tools for a host as plain {@link RegisteredTool}s — the
- * same primitive the MCP-only tools use. Each handler resolves the backend via
- * `host.resolveBackend(args)`; the schema merges the host's `sessionSchema`
- * (e.g. `captureId`) and any per-tool `toolExtras`.
+ * The authoring tools — navigate/inspect authored inline here; find/propose/
+ * replay live in their own files ({@link findTool}/{@link proposeTool}/
+ * {@link replayTool}) and are composed in below. Each is a plain `defineTool`
+ * primitive, so there is one canonical `RegisteredTool` per tool and no
+ * parallel tool shape. Every handler resolves its session backend via
+ * `resolveBackend(args)`: the cloud passes `() => backend` (one backend per
+ * run); the MCP passes an `args.captureId`-keyed resolver. Hosts that need
+ * extra input schema (the MCP's `captureId` session handle + the
+ * credential-aware `run_proof` contract) MAP these tools through `extendTool`
+ * (see mcp/tools/agent/shared.ts) — the tools themselves stay plain, and args
+ * parse loosely so the extra fields still reach the resolver/handler.
  */
-export declare function buildAuthoringTools(host: AuthoringHost): RegisteredTool[];
+export declare function authoringTools(resolveBackend: ResolveBackend): RegisteredTool[];