@reclaimprotocol/agent 0.1.32 → 0.1.34

package/src/authoring/tools.ts

@@ -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.ts'
 import { proposeTool } from '../mcp/tools/agent/propose.ts'
 import { replayTool } from '../mcp/tools/agent/replay.ts'
@@ -117,13 +118,15 @@ export function authoringTools(
 			{
 				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.',
+					'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)
@@ -147,13 +150,16 @@ export function authoringTools(
 			{
 				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()`).',
+					'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)),
 		),
@@ -161,14 +167,16 @@ export function authoringTools(
 			{
 				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.',
+					'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)
@@ -190,27 +198,34 @@ export function authoringTools(
 			{
 				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" }).',
+					'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)
@@ -235,13 +250,37 @@ export function authoringTools(
 						);
 					}
 				`
+				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 },
 				)) as { identifier?: string }
+				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 '
@@ -276,6 +315,7 @@ export function authoringTools(
 						value as { ran?: boolean, errors?: string[] } | undefined
 					return {
 						installed: true,
+						...(keep ? { kept: true } : {}),
 						navigated: true,
 						ran: result?.ran ?? false,
 						errors: result?.errors ?? [],
@@ -283,7 +323,7 @@ export function authoringTools(
 				} 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 },
@@ -296,13 +336,14 @@ export function authoringTools(
 			{
 				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.',
+					'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)
@@ -337,6 +378,7 @@ export function authoringTools(
 					+ '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)
@@ -402,9 +444,10 @@ export function authoringTools(
 			{
 				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.',
+					'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',
@@ -418,6 +461,7 @@ export function authoringTools(
 						},
 					},
 				}),
+				annotations: { readOnlyHint: true, openWorldHint: false },
 			},
 			async(args) => {
 				const backend = resolveBackend(args)
@@ -434,15 +478,15 @@ export function authoringTools(
 			{
 				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.',
+					'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/src/config/store.ts

@@ -27,6 +27,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.
  *
@@ -40,6 +42,15 @@ 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. */