@reclaimprotocol/agent 0.1.26 → 0.1.28

package/src/provider/to-version.ts

@@ -1,8 +1,10 @@
-import type { ReclaimClient } from '@reclaimprotocol/client'
+import { badRequest, conflict } from '@hapi/boom'
+import type { ReclaimClient } from '@reclaimprotocol/client/api'
 import type {
 	CreateProviderVersionRequest,
 	ProviderVersionRef,
 } from '@reclaimprotocol/client/openapi'
+import assert from 'node:assert'
 import type {
 	DraftResponseMatch,
 	HttpMethod,
@@ -65,6 +67,9 @@ export interface AllowedJsRequest extends DraftRequest {
 export interface CreateVersionOptions {
 	notes?: string
 	version?: ProviderVersionRef
+	/** Complete context schema for this new immutable version. When omitted,
+	 *  it is derived from `{{context.<name>}}` placeholders. */
+	requiredContext?: CreateProviderVersionRequest['requiredContext']
 	/** JS injected before every page load (`webSettings.jsUserScripts`). */
 	jsUserScripts?: string
 	/** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
@@ -107,7 +112,8 @@ const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g
  * injected requests and the injection script) — mechanical, so a published
  * recipe can never reference a context value the Builder doesn't require.
  * Returns undefined when nothing references context (the field is optional).
- * Authors can refine types/descriptions in the version editor.
+ * Authors can pass a complete schema when creating the new version to refine
+ * types or descriptions. Never edit a version in place after creation.
  *
  * A SECRET-named context param (see `classifyParamName`) is NOT rejected here
  * even when it's templated into the URL/geoLocation — write-redaction can
@@ -211,12 +217,13 @@ export function providerToCreateVersionRequest(
 	opts: CreateVersionOptions = {},
 ): CreateProviderVersionRequest {
 	const {
-		notes, version, jsUserScripts, allowedJsRequests, interceptorOptions,
+		notes, version, requiredContext: requestedContext, jsUserScripts,
+		allowedJsRequests, interceptorOptions,
 	} = opts
-	const requiredContext = deriveRequiredContext(providers, {
-		allowedJsRequests,
-		jsUserScripts,
-	})
+	const requiredContext = requestedContext ?? deriveRequiredContext(
+		providers,
+		{ allowedJsRequests, jsUserScripts },
+	)
 
 	// Each injected request carries its template flags (default true/true per
 	// RequestSelectionTemplate) on top of the shared request shape.
@@ -282,36 +289,106 @@ export function providerToCreateVersionRequest(
 }
 
 /**
- * Fetch the current versions for a provider and return the next version above
- * the highest existing one (bumping the patch number), or 1.0.0 when the
- * provider has no versions yet. A failed lookup propagates — silently
- * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
+ * Fetch every current version and resolve a strictly newer immutable version.
+ * The default bump is patch. Callers can request major/minor/patch or provide
+ * an exact version; an exact version must be higher than every existing one.
+ * A failed lookup propagates — silently resetting to 1.0.0 could collide with
+ * an existing version.
  */
 export async function nextVersion(
 	client: ReclaimClient,
 	providerId: string,
+	bump: VersionBump = 'patch',
 ): Promise<ProviderVersionRef> {
-	const list = (await client.call('ListProviderVersions', {
-		params: { providerId },
-		query: {},
-	})) as { items?: Array<{ version: ProviderVersionRef }> }
+	return bumpVersion(await listVersions(client, providerId), bump)
+}
+
+export type VersionBump = 'major' | 'minor' | 'patch'
 
-	if(!list.items?.length) {
+/** Resolve either an explicit version or a requested semantic bump. */
+export async function resolveNewVersion(
+	client: ReclaimClient,
+	providerId: string,
+	input: { version?: ProviderVersionRef, bump?: VersionBump } = {},
+): Promise<ProviderVersionRef> {
+	assert(
+		!(input.version && input.bump),
+		badRequest('Pass either `version` or `bump`, not both.'),
+	)
+	const versions = await listVersions(client, providerId)
+	if(!input.version) {
+		return bumpVersion(versions, input.bump ?? 'patch')
+	}
+
+	const highest = highestVersion(versions)
+	assert(
+		!highest || compareVersions(input.version, highest) > 0,
+		conflict(
+			`Version ${formatVersion(input.version)} must be higher than the ` +
+			`current highest version ${highest ? formatVersion(highest) : 'none'}.`,
+		),
+	)
+	return input.version
+}
+
+export function bumpVersion(
+	versions: ProviderVersionRef[],
+	bump: VersionBump = 'patch',
+): ProviderVersionRef {
+	const highest = highestVersion(versions)
+	if(!highest) {
 		return { major: 1, minor: 0, patch: 0 }
 	}
 
-	// Find the highest version and bump its patch
-	let hi = list.items[0].version
-	for(const item of list.items) {
-		const v = item.version
-		if(
-			v.major > hi.major ||
-			(v.major === hi.major && v.minor > hi.minor) ||
-			(v.major === hi.major && v.minor === hi.minor && v.patch > hi.patch)
-		) {
-			hi = v
+	switch (bump) {
+		case 'major':
+			return { major: highest.major + 1, minor: 0, patch: 0 }
+		case 'minor':
+			return { major: highest.major, minor: highest.minor + 1, patch: 0 }
+		case 'patch':
+			return {
+				major: highest.major,
+				minor: highest.minor,
+				patch: highest.patch + 1,
+			}
+	}
+}
+
+async function listVersions(
+	client: ReclaimClient,
+	providerId: string,
+): Promise<ProviderVersionRef[]> {
+	const versions: ProviderVersionRef[] = []
+	let cursor: string | undefined
+	do {
+		const { data } = await client.call('ListProviderVersions', {
+			params: { providerId },
+			query: { cursor },
+		})
+		versions.push(...data.items.map((item) => item.version))
+		cursor = data.nextPageCursor
+	} while(cursor)
+
+	return versions
+}
+
+function highestVersion(
+	versions: ProviderVersionRef[],
+): ProviderVersionRef | undefined {
+	let highest: ProviderVersionRef | undefined
+	for(const version of versions) {
+		if(!highest || compareVersions(version, highest) > 0) {
+			highest = version
 		}
 	}
 
-	return { major: hi.major, minor: hi.minor, patch: hi.patch + 1 }
+	return highest
+}
+
+function compareVersions(a: ProviderVersionRef, b: ProviderVersionRef) {
+	return a.major - b.major || a.minor - b.minor || a.patch - b.patch
+}
+
+function formatVersion(version: ProviderVersionRef) {
+	return `${version.major}.${version.minor}.${version.patch}`
 }

package/src/tools/registry.ts

@@ -11,8 +11,8 @@
  * glue (`registerToolList` onto an `McpServer`) stays in `mcp/server.ts`, which
  * re-exports this primitive for the MCP-side tool files.
  */
-import { type Boom, isBoom } from '@hapi/boom'
-import type { ProblemDetails } from '@reclaimprotocol/client'
+import { isBoom } from '@hapi/boom'
+import { isProblemDetails, isProblemError } from '@reclaimprotocol/client/api'
 import type { JSONSchema } from 'zod/v4/core'
 import { toZod } from '../mcp/api/to-zod.ts'
 
@@ -59,8 +59,13 @@ export function defineTool<TArgs>(
  * else falls back to the plain message.
  */
 export function errorAsToolText(err: unknown): string {
+	if(isProblemError(err)) {
+		const detail = err.data.detail
+		return detail ? `${err.message}: ${detail}` : err.message
+	}
+
 	if(isBoom(err) && err.output?.statusCode) {
-		const detail = (err as Boom<ProblemDetails>).data?.detail
+		const detail = isProblemDetails(err.data) ? err.data.detail : undefined
 		return detail ? `${err.message}: ${detail}` : err.message
 	}
 
@@ -80,7 +85,7 @@ export function extendTool(
 	tool: RegisteredTool,
 	extra: {
 		description?: string
-		properties?: Record<string, unknown>
+		properties?: JSONSchema.ObjectSchema['properties']
 		required?: string[]
 	},
 ): RegisteredTool {
@@ -89,17 +94,15 @@ export function extendTool(
 		...(base.inputSchema.required ?? []),
 		...(extra.required ?? []),
 	]
-	// The merged `properties` spread carries the base's untyped property values,
-	// which don't structurally match ObjectSchema's strict per-property schema
-	// type — assert the merged shape.
-	const inputSchema = {
+	// Keep the merged schema checked against Zod's JSON Schema representation.
+	const inputSchema: JSONSchema.ObjectSchema = {
 		...base.inputSchema,
 		properties: {
 			...base.inputSchema.properties,
 			...extra.properties,
 		},
 		...(required.length ? { required } : {}),
-	} as unknown as JSONSchema.ObjectSchema
+	}
 	return {
 		definition: {
 			name: base.name,