@reclaimprotocol/agent 0.1.32 → 0.1.34

package/lib/authoring/backend.d.ts

@@ -21,6 +21,16 @@ export interface Draft {
      *  validate each against its own selector. */
     extractions: Extraction[];
 }
+/** A navigation script installed for every later page load of the authoring
+ *  session. `identifier` is the CDP registration, so it can be removed. */
+export interface KeptScript {
+    script: string;
+    identifier?: string;
+}
+/** Holds the session's kept script, replaced by each `keep` call. */
+export interface KeptScriptRef {
+    keptScript?: KeptScript;
+}
 /** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
 export interface DraftStore {
     put(draft: Draft): string;
@@ -46,6 +56,9 @@ export interface AuthoringBackend {
      * out. Cloud authoring enables this; local MCP keeps its existing
      * behavior. */
     readonly readOnlyPageEval?: boolean;
+    /** Where `test_user_script` keeps its script. Absent for hosts that do not
+     * publish it (the cloud loop synthesizes its own navigation script). */
+    readonly kept?: KeptScriptRef;
     /** Send a raw CDP command scoped to this session's page. */
     sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
     /** Resolve once `method` (a CDP event) fires on this session's page, or

package/lib/authoring/index.d.ts

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

package/lib/authoring/tools.js

@@ -14,6 +14,7 @@
  * draft (recipe + secrets) is held server-side; the model only sees an opaque
  * `draftId` and the secret-free provider.
  */
+import assert from 'node:assert';
 import { findTool } from "../mcp/tools/agent/find.js";
 import { proposeTool } from "../mcp/tools/agent/propose.js";
 import { replayTool } from "../mcp/tools/agent/replay.js";
@@ -80,10 +81,12 @@ export function authoringTools(resolveBackend) {
     return [
         defineTool({
             name: 'navigate',
-            description: 'Navigate the captured tab to a URL and wait for its load event. '
-                + 'Returns the URL the tab actually landed on, so you can detect a '
-                + 'redirect to a login page.',
+            description: 'Navigates the captured tab to a URL and waits for its load event. '
+                + 'Returns the URL the tab landed on, to detect a redirect to a '
+                + 'sign-in page. Any navigation script kept by `test_user_script` '
+                + 'runs on the page.',
             inputSchema: objectSchema({ url: { type: 'string' }, timeoutMs: { type: 'number' } }, ['url']),
+            annotations: { openWorldHint: true, destructiveHint: false },
         }, async (args) => {
             const backend = resolveBackend(args);
             const timeoutMs = Number(args.timeoutMs) || 30000;
@@ -100,19 +103,24 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             name: 'eval_in_page',
-            description: 'Evaluate a JavaScript expression in the page and return its value. '
-                + 'Use it to read the value being proven out of the DOM, to check '
-                + 'login state, or to trigger the target request (for example, '
-                + '`location.reload()`).',
+            description: 'Evaluates a JavaScript expression in the page of the remote '
+                + 'authoring browser, not on this machine, and returns its value. '
+                + 'Use it to read a data point from the DOM, check sign-in state, '
+                + 'or trigger the target request (for example, `location.reload()`). '
+                + 'The page cannot reach files or processes on this machine. Return '
+                + 'only the values you need, never cookies or tokens.',
             inputSchema: objectSchema({ expression: { type: 'string' } }, ['expression']),
+            annotations: { openWorldHint: true, destructiveHint: false },
         }, (args) => evalInPage(resolveBackend(args), String(args.expression))),
         defineTool({
             name: 'wait_for_page',
-            description: 'Poll a JavaScript expression once a second until it is truthy or '
-                + 'the timeout elapses. Use it to wait for content to appear. To '
-                + 'wait for a login, use wait_for_login instead — page JavaScript '
-                + 'cannot see the httpOnly session cookie.',
+            description: 'Evaluates a JavaScript expression in the remote authoring browser '
+                + 'once a second until it is truthy or the timeout elapses. Returns '
+                + '{ ready }. Use it to wait for content to appear. To wait for a '
+                + 'sign-in, use `wait_for_login`: page JavaScript cannot see the '
+                + 'httpOnly session cookie.',
             inputSchema: objectSchema({ expression: { type: 'string' }, timeoutMs: { type: 'number' } }, ['expression']),
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async (args) => {
             const backend = resolveBackend(args);
             const expr = String(args.expression);
@@ -128,24 +136,30 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             name: 'test_user_script',
-            description: 'Dry-run a USER SCRIPT (the `jsUserScripts` / `customInjection` '
-                + 'field) in the LIVE attached tab while authoring or after provider '
-                + 'creation. Installs '
-                + '`script` via CDP so it runs on the next navigation exactly as '
-                + 'the real field would, then reports whether it ran and what it '
-                + 'threw. With `navigateUrl`, it navigates there and removes the '
-                + 'script once the result is read — self-cleaning, safe to repeat. '
-                + 'WITHOUT `navigateUrl` the script stays installed (navigate '
-                + 'yourself, then re-call this tool or read '
-                + '`window.__reclaimUserScriptResult` via eval_in_page) and keeps '
-                + 'running on every later navigation until a call WITH '
-                + '`navigateUrl` removes it — so don\'t stack manual-mode calls. '
-                + 'Guide: how_it_works({ topic: "user-script" }).',
+            description: 'Installs a navigation script (the `jsUserScripts` field) in the '
+                + 'remote authoring browser, not on this machine, so it runs before '
+                + 'each page load, as it does at verification. Reports whether it '
+                + 'ran and what it threw. With `navigateUrl`, navigates there and '
+                + 'removes the script after reading the result, unless `keep` is '
+                + 'true. Without `navigateUrl`, the script stays installed for '
+                + 'later navigations until a call with `navigateUrl` removes it. '
+                + 'With `keep: true`, the script stays installed for every later '
+                + 'navigation in this session, replaces any earlier kept script, and '
+                + '`create_provider_version_from_capture` publishes it as '
+                + '`jsUserScripts` unless that call passes its own. '
+                + 'See how_it_works({ topic: "user-script" }).',
             inputSchema: objectSchema({
                 script: { type: 'string' },
                 navigateUrl: { type: 'string' },
                 timeoutMs: { type: 'number' },
+                keep: {
+                    type: 'boolean',
+                    description: 'Keep the script installed for every later navigation in '
+                        + 'this session and use it as the published navigation '
+                        + 'script.',
+                },
             }, ['script']),
+            annotations: { openWorldHint: true, destructiveHint: false },
         }, async (args) => {
             const backend = resolveBackend(args);
             const script = String(args.script);
@@ -169,10 +183,27 @@ export function authoringTools(resolveBackend) {
 						);
 					}
 				`;
+            const keep = args.keep === true;
+            const kept = keep ? backend.kept : undefined;
+            assert(!keep || kept, new Error('This host does not support `keep`.'));
+            // Replace, never stack: only one kept script runs.
+            const previous = kept?.keptScript?.identifier;
+            if (previous) {
+                await backend.sendCdp('Page.removeScriptToEvaluateOnNewDocument', { identifier: previous }).catch(() => { });
+            }
             const installed = (await backend.sendCdp('Page.addScriptToEvaluateOnNewDocument', { source: wrapped }));
+            if (kept) {
+                kept.keptScript = {
+                    script,
+                    ...(installed.identifier
+                        ? { identifier: installed.identifier }
+                        : {}),
+                };
+            }
             if (typeof args.navigateUrl !== 'string') {
                 return {
                     installed: true,
+                    ...(keep ? { kept: true } : {}),
                     note: 'Installed for the NEXT navigation only — it did not run on '
                         + 'the current page, and stays installed (runs on every later '
                         + 'navigation too) until a follow-up call with navigateUrl '
@@ -198,6 +229,7 @@ export function authoringTools(resolveBackend) {
                 const result = value;
                 return {
                     installed: true,
+                    ...(keep ? { kept: true } : {}),
                     navigated: true,
                     ran: result?.ran ?? false,
                     errors: result?.errors ?? [],
@@ -206,20 +238,21 @@ export function authoringTools(resolveBackend) {
             finally {
                 // One-shot test: remove it so it doesn't keep running (and
                 // potentially redirecting the tab) on every later navigation.
-                if (installed.identifier) {
+                if (installed.identifier && !keep) {
                     await backend.sendCdp('Page.removeScriptToEvaluateOnNewDocument', { identifier: installed.identifier });
                 }
             }
         }),
         defineTool({
             name: 'get_cookies',
-            description: 'List the NAMES of cookies currently set for the page (values are '
-                + 'NEVER returned). The most reliable, language- and DOM-independent '
-                + 'login signal: after the user logs in, an auth/session cookie '
-                + 'appears (for example, session, sid, token, auth, jwt, _user, '
-                + 'logged_in). '
-                + 'Includes httpOnly cookies the page JS cannot see.',
+            description: 'Returns the names, domains, and flags of the cookies set in the '
+                + 'remote authoring browser. Values are never returned; they stay '
+                + 'in the browser and on the server. A new auth or session cookie '
+                + '(for example, session, sid, auth, jwt) is a reliable sign-in '
+                + 'signal that does not depend on the page language or DOM. '
+                + 'Includes httpOnly cookies that page JavaScript cannot see.',
             inputSchema: objectSchema({}),
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async (args) => {
             const backend = resolveBackend(args);
             const res = (await backend.sendCdp('Network.getCookies'));
@@ -243,6 +276,7 @@ export function authoringTools(resolveBackend) {
                 + 'navigating to the login page. Does NOT navigate (never yanks '
                 + 'the user off login/2FA). Returns { loggedIn, newCookies }.',
             inputSchema: objectSchema({ timeoutMs: { type: 'number' } }),
+            annotations: { readOnlyHint: true, openWorldHint: true },
         }, async (args) => {
             const backend = resolveBackend(args);
             const deadline = Date.now() + (Number(args.timeoutMs) || 180000);
@@ -299,9 +333,10 @@ export function authoringTools(resolveBackend) {
         }),
         defineTool({
             name: 'list_requests',
-            description: 'List captured network requests (method/url/status/size), newest '
-                + 'last. Optionally filter by method / urlGlob / status range / '
-                + 'contentType / graphqlOp. Metadata only — secrets never included.',
+            description: 'Lists captured network requests (method, URL, status, size), '
+                + 'newest last. Filter by method, urlGlob, status range, '
+                + 'contentType, or graphqlOp. Returns metadata only, never '
+                + 'secrets.',
             inputSchema: objectSchema({
                 filter: {
                     type: 'object',
@@ -315,6 +350,7 @@ export function authoringTools(resolveBackend) {
                     },
                 },
             }),
+            annotations: { readOnlyHint: true, openWorldHint: false },
         }, async (args) => {
             const backend = resolveBackend(args);
             const filter = (args.filter ?? {});
@@ -327,15 +363,15 @@ export function authoringTools(resolveBackend) {
         replayTool(resolveBackend),
         defineTool({
             name: 'run_proof',
-            description: 'Prove the drafted recipe (zkTLS). Only call after replay_request '
-                + 'looks right. Returns the proof result. NOTE: unlike '
-                + 'replay_request (which re-issues from inside the live attached '
-                + 'browser tab), the ATTESTOR calls the target from its OWN '
-                + 'network/IP, separate from the browser\'s. A request that '
-                + 'replayed fine can still fail here for geo/IP-bound content '
-                + '(country-locked pages, IP-allowlisted APIs) — if that happens, '
-                + 'it\'s a property of the site, not a bug in the draft.',
+            description: 'Proves the drafted recipe (zkTLS). Call it after `replay_request` '
+                + 'looks right. Returns the proof result. Unlike `replay_request`, '
+                + 'which re-sends from inside the attached browser tab, the '
+                + 'attestor calls the target from its own network and IP. A request '
+                + 'that replayed can still fail here for geo- or IP-bound content '
+                + '(country-locked pages, IP-allowlisted APIs); that is a property '
+                + 'of the site, not a bug in the draft.',
             inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
+            annotations: { openWorldHint: true, destructiveHint: false },
         }, 
         // The backend shapes its own result: the cloud returns a lean,
         // secret-free summary (and records the proven recipe for publish); the

package/lib/config/store.d.ts

@@ -16,6 +16,8 @@ export interface ReclaimAgentConfig {
  *   - `old_devtools`  — externally-supplied identity for OLD-devtools mode
  *                       (USE_OLD_DEVTOOLS); independent of `session`'s
  *                       builder token. Deletable with the rest of `src/old/`.
+ *   - `org_keys`      — organization API keys saved by `issue_org_token`, so
+ *                       the org-key tools work without the key in a transcript
  * Sections are persisted independently via `ConfigStore.write`, which
  * merges rather than replaces, so one subsystem never clobbers another's.
  *
@@ -29,6 +31,14 @@ export interface ReclaimConfig {
     browser_agent?: ReclaimAgentConfig;
     session?: CachedSession;
     old_devtools?: OldIdentity;
+    org_keys?: SavedOrgKeys;
+}
+/** Organization API keys (`rorg_…`) saved by `issue_org_token`. */
+export interface SavedOrgKeys {
+    /** Key by organization ID. */
+    byOrg: Record<string, string>;
+    /** The organization whose key was saved last. */
+    recent?: string;
 }
 /** Which backend the MCP server targets. See `resolveOldMode` in consts.ts. */
 export type DevtoolsMode = 'old' | 'builder';