@reclaimprotocol/agent 0.1.36 → 0.1.37

package/src/authoring/tools.ts

@@ -20,8 +20,15 @@ import { proposeTool } from '../mcp/tools/agent/propose.ts'
 import { replayTool } from '../mcp/tools/agent/replay.ts'
 import type { CapturedRequest } from '../provider/schema.ts'
 import { defineTool, type RegisteredTool } from '../tools/registry.ts'
-import type { AuthoringBackend } from './backend.ts'
-import { objectSchema, publicRequest, type ResolveBackend } from './util.ts'
+import type { AuthoringBackend, ProveOptions } from './backend.ts'
+import {
+	DEFAULT_MAX_CHARS,
+	objectSchema,
+	publicRequest,
+	type ResolveBackend,
+	TEXT_WINDOW_PROPERTIES,
+	textWindow,
+} from './util.ts'
 
 const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
 
@@ -155,13 +162,40 @@ export function authoringTools(
 					+ '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.',
+					+ 'only the values you need, never cookies or tokens. A result '
+					+ `longer than ${DEFAULT_MAX_CHARS} characters comes back `
+					+ 'truncated (objects as JSON text) with `valueTruncation`; page '
+					+ 'with `offset`, or pass `maxChars` or `full`.',
 				inputSchema: objectSchema(
-					{ expression: { type: 'string' } }, ['expression'],
+					{ expression: { type: 'string' }, ...TEXT_WINDOW_PROPERTIES },
+					['expression'],
 				),
 				annotations: { openWorldHint: true, destructiveHint: false },
 			},
-			(args) => evalInPage(resolveBackend(args), String(args.expression)),
+			async(args) => {
+				const res = await evalInPage(
+					resolveBackend(args), String(args.expression),
+				)
+				if(res.value === undefined) {
+					return res
+				}
+
+				const text = typeof res.value === 'string'
+					? res.value
+					: JSON.stringify(res.value)
+				const slice = textWindow(text, args)
+				if(!slice.truncation) {
+					return res
+				}
+
+				return {
+					value: slice.text,
+					valueTruncation: {
+						...slice.truncation,
+						...(typeof res.value === 'string' ? {} : { format: 'json' }),
+					},
+				}
+			},
 		),
 		defineTool<Record<string, unknown>>(
 			{
@@ -484,7 +518,10 @@ export function authoringTools(
 					+ '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.',
+					+ 'of the site, not a bug in the draft. HTTP 403/406/429/503 or a '
+					+ 'challenge page from the attestor while the replay succeeded '
+					+ 'means the site blocks non-browser clients: copying headers or '
+					+ 'cookies will not help, so try a different endpoint or stop.',
 				inputSchema: objectSchema({ draftId: { type: 'string' } }, ['draftId']),
 				annotations: { openWorldHint: true, destructiveHint: false },
 			},
@@ -500,7 +537,7 @@ export function authoringTools(
 					throw new Error(`no draft ${String(args.draftId)}`)
 				}
 
-				const opts: { ownerAddress?: string, attestorUrl?: string } = {}
+				const opts: ProveOptions = {}
 				if(typeof args.ownerAddress === 'string') {
 					opts.ownerAddress = args.ownerAddress
 				}
@@ -509,6 +546,10 @@ export function authoringTools(
 					opts.attestorUrl = args.attestorUrl
 				}
 
+				if(typeof args.geoLocation === 'string') {
+					opts.geoLocation = args.geoLocation
+				}
+
 				return backend.prove(draft, opts)
 			},
 		),

package/src/authoring/util.ts

@@ -43,3 +43,67 @@ export function publicRequest(r: CapturedRequest) {
 		...(r.graphqlOp ? { graphqlOp: r.graphqlOp } : {}),
 	}
 }
+
+/** Characters a long text field returns by default (about 20 KB of ASCII),
+ *  so one page body or eval result can't flood the caller's context. */
+export const DEFAULT_MAX_CHARS = 20_000
+
+export interface TextWindowArgs {
+	maxChars?: unknown
+	offset?: unknown
+	full?: unknown
+}
+
+/** Input properties that let a caller page through, or opt out of, the
+ *  window {@link textWindow} applies. */
+export const TEXT_WINDOW_PROPERTIES = {
+	maxChars: {
+		type: 'integer',
+		minimum: 1,
+		description: `Maximum characters to return. Default ${DEFAULT_MAX_CHARS}.`,
+	},
+	offset: {
+		type: 'integer',
+		minimum: 0,
+		description: 'Character offset to start from, such as a previous '
+			+ '`nextOffset`. Default 0.',
+	},
+	full: {
+		type: 'boolean',
+		description: 'Return the whole text, ignoring `maxChars`. It can be '
+			+ 'megabytes, so prefer paging with `offset`.',
+	},
+} satisfies Record<string, JSONSchema.BaseSchema>
+
+/**
+ * Returns characters `[offset, offset + maxChars)` of `text`. When that isn't
+ * the whole text, `truncation` reports the total size and how to get the rest.
+ */
+export function textWindow(text: string, args: TextWindowArgs) {
+	const totalChars = text.length
+	const offset = Math.min(Math.max(Number(args.offset) || 0, 0), totalChars)
+	const maxChars = args.full === true
+		? totalChars
+		: Math.max(Number(args.maxChars) || DEFAULT_MAX_CHARS, 1)
+	const end = Math.min(offset + maxChars, totalChars)
+	if(offset === 0 && end === totalChars) {
+		return { text }
+	}
+
+	const part = text.slice(offset, end)
+	const more = end < totalChars
+	return {
+		text: part,
+		truncation: {
+			totalChars,
+			offset,
+			returnedChars: part.length,
+			...(more ? { nextOffset: end } : {}),
+			note: `Returned characters ${offset}-${end} of ${totalChars}.`
+				+ (more
+					? ` Call again with offset: ${end} for more, or full: true `
+						+ 'for the whole text.'
+					: ''),
+		},
+	}
+}

package/src/cdp/chrome-for-testing.ts

@@ -0,0 +1,66 @@
+import { failedDependency } from '@hapi/boom'
+import assert from 'node:assert'
+import { existsSync } from 'node:fs'
+import { arch, platform } from 'node:os'
+import { join } from 'node:path'
+import { LOGGER } from '../logger.ts'
+import { reclaimHomeDirPath } from '../paths.ts'
+
+export interface ChromeForTestingInstall {
+	executablePath: string
+	/** True when this call downloaded it; false when an earlier one had. */
+	downloaded: boolean
+}
+
+/** Where downloaded browsers live: `~/.reclaim/browsers`. */
+export function browsersDirPath() {
+	return join(reclaimHomeDirPath(), 'browsers')
+}
+
+/**
+ * Chrome for Testing, the fallback when no local Chromium-family browser is
+ * installed or the installed one will not start. Downloaded once into
+ * `~/.reclaim/browsers` and reused after that, so only the first fallback pays
+ * the ~150 MB download.
+ */
+export async function installChromeForTesting(
+	cacheDir = browsersDirPath(),
+): Promise<ChromeForTestingInstall> {
+	// Loaded on demand: only the fallback path needs it.
+	const {
+		Browser,
+		detectBrowserPlatform,
+		getInstalledBrowsers,
+		getVersionComparator,
+		install,
+		resolveBuildId,
+	} = await import('@puppeteer/browsers')
+	const browserPlatform = detectBrowserPlatform()
+	assert(browserPlatform, failedDependency(
+		`Chrome for Testing has no build for ${platform()}/${arch()}.`,
+	))
+
+	const compare = getVersionComparator(Browser.CHROME)
+	const all = await getInstalledBrowsers({ cacheDir })
+	const installed = all
+		.filter((b) => b.browser === Browser.CHROME
+			&& b.platform === browserPlatform
+			&& existsSync(b.executablePath))
+		.sort((a, b) => compare(a.buildId, b.buildId))
+	const newest = installed.at(-1)
+	if(newest) {
+		return { executablePath: newest.executablePath, downloaded: false }
+	}
+
+	const buildId = await resolveBuildId(
+		Browser.CHROME, browserPlatform, 'stable',
+	)
+	LOGGER.info({ buildId, cacheDir }, 'downloading Chrome for Testing')
+	const result = await install({
+		browser: Browser.CHROME,
+		platform: browserPlatform,
+		buildId,
+		cacheDir,
+	})
+	return { executablePath: result.executablePath, downloaded: true }
+}

package/src/cdp/geo.ts

@@ -5,6 +5,7 @@
  * public-IP country, resolved the same way reclaim-portal's `ip-geolocation`
  * util does.
  */
+import assert from 'node:assert'
 import { LOGGER } from '../logger.ts'
 
 export interface IpGeolocation {
@@ -24,29 +25,43 @@ export async function suggestCountryFromIp(
 	fetchImpl: typeof fetch = fetch,
 ): Promise<IpGeolocation> {
 	try {
-		const res = await fetchImpl(IPINFO_URL)
-		if(!res.ok) {
-			throw new Error(`ipinfo.io ${res.status}`)
-		}
-
-		const data = await res.json() as {
-			country?: string
-			region?: string
-			city?: string
-		}
-		const countryCode = data.country?.toUpperCase()
-		if(!countryCode) {
-			throw new Error('ipinfo.io response had no country')
-		}
-
-		return {
-			countryCode,
-			country: data.country,
-			region: data.region,
-			city: data.city,
-		}
+		return await fetchIpGeolocation(fetchImpl)
 	} catch(err) {
 		LOGGER.warn({ err }, 'suggestCountryFromIp failed; using fallback')
 		return { countryCode: FALLBACK_COUNTRY_CODE }
 	}
 }
+
+/** The calling machine's public-IP country, or undefined when the lookup
+ *  fails: unlike {@link suggestCountryFromIp}, no guessed fallback. */
+export async function lookupIpCountry(
+	fetchImpl: typeof fetch = fetch,
+): Promise<string | undefined> {
+	try {
+		const { countryCode } = await fetchIpGeolocation(fetchImpl)
+		return countryCode
+	} catch(err) {
+		LOGGER.warn({ err }, 'IP country lookup failed')
+		return undefined
+	}
+}
+
+async function fetchIpGeolocation(
+	fetchImpl: typeof fetch,
+): Promise<IpGeolocation> {
+	const res = await fetchImpl(IPINFO_URL)
+	assert(res.ok, new Error(`ipinfo.io ${res.status}`))
+	const data = await res.json() as {
+		country?: string
+		region?: string
+		city?: string
+	}
+	const countryCode = data.country?.toUpperCase()
+	assert(countryCode, new Error('ipinfo.io response had no country'))
+	return {
+		countryCode,
+		country: data.country,
+		region: data.region,
+		city: data.city,
+	}
+}