@reclaimprotocol/agent 0.1.32 → 0.1.34

package/src/mcp/tools/verification/result.ts

@@ -7,6 +7,7 @@ import assert from 'node:assert'
 import { apiUrl, orgSecret } from '../../../consts.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { resolveDecryptionKey } from '../authenticate/decrypt-key.ts'
+import { savedOrgKey } from '../authenticate/org-key-store.ts'
 
 /** Statuses that can carry a Builder-managed terminal result. */
 const TERMINAL = new Set([
@@ -17,19 +18,28 @@ const TERMINAL = new Set([
 	'expired',
 ])
 
+/** Events whose delivery is a signed result; the rest are plaintext event
+ *  notifications. Mirrors `verification_result_events()`. */
+const RESULT_EVENTS = new Set([
+	'verification_success',
+	'verification_rejected',
+	'verification_error',
+	'verification_cancelled',
+])
+
 /**
  * Resolve the org secret used to authenticate verification reads. Auth is a
- * single per-org bearer secret (`rorg_…`), not an eth signature — read it from
- * `RECLAIM_ORG_SECRET`.
+ * single per-org bearer secret (`rorg_…`), not an eth signature: the call's
+ * `orgToken`, else `RECLAIM_ORG_SECRET`.
  */
-function resolveOrgSecret(): string {
-	const secret = orgSecret()?.trim()
+function resolveOrgSecret(orgToken?: string): string {
+	const secret = orgToken?.trim() || orgSecret()?.trim() || savedOrgKey()
 	assert(
 		secret,
 		new Error(
-			'RECLAIM_ORG_SECRET is not set. Verification reads authenticate with ' +
-				'the org secret (rorg_…) — issue one from the dashboard ' +
-				'(POST /orgs/{orgId}/token) and export it as RECLAIM_ORG_SECRET.',
+			'No organization API key. Verification reads authenticate with the org '
+				+ 'secret (rorg_…): run issue_org_token to save a key, pass orgToken, '
+				+ 'or export RECLAIM_ORG_SECRET for the MCP server.',
 		),
 	)
 	return secret
@@ -46,12 +56,16 @@ function resolveOrgSecret(): string {
  * Decryption, when needed, happens here.
  */
 export function verificationResultTool(): RegisteredTool {
-	return defineTool<{ reclaimSessionId: string }>(
+	return defineTool<{ reclaimSessionId: string, orgToken?: string }>(
 		{
 			name: 'get_verification_result',
 			description:
-				'Fetches and verifies a terminal Builder result for one session. '
-				+ 'Requires `RECLAIM_ORG_SECRET`; encrypted deliveries also require '
+				'Fetches and verifies a terminal Builder result for one session, '
+				+ 'while Builder still holds it: until its callback is delivered, or '
+				+ '7 days undelivered. The callback is the normal way to get results. '
+				+ 'Authenticates with the org API key: `orgToken`, else '
+				+ '`RECLAIM_ORG_SECRET`, else the key saved by `issue_org_token`. '
+				+ 'Encrypted deliveries also require '
 				+ 'the matching ETH decryption key. Returns `ready: false` until a '
 				+ 'payload is available. Invalid results fail verification and are not '
 				+ 'returned. Use `list_verification_events` to diagnose '
@@ -65,11 +79,22 @@ export function verificationResultTool(): RegisteredTool {
 						description:
 							'The verification session id from create_verification_session.',
 					},
+					orgToken: {
+						type: 'string',
+						pattern: '^rorg_',
+						maxLength: 200,
+						description: 'The organization API key (`rorg_…`): from '
+							+ '`issue_org_token`, or the app\'s RECLAIM_ORG_SECRET. '
+							+ 'Defaults to the MCP server\'s RECLAIM_ORG_SECRET, then the '
+							+ 'key saved by `issue_org_token`. Never echo it back to the '
+							+ 'user.',
+					},
 				},
 			},
+			annotations: { readOnlyHint: true, openWorldHint: true },
 		},
 		async(args) => {
-			const secret = resolveOrgSecret()
+			const secret = resolveOrgSecret(args.orgToken)
 			// Optional eth decryption key — absent ⇒ plaintext-only.
 			const decryptionKey: DecryptionKey | undefined =
 				await resolveDecryptionKey()
@@ -91,14 +116,34 @@ export function verificationResultTool(): RegisteredTool {
 			const resultRes = await reclaim.api('GetVerificationResult', {
 				params: { sessionId: args.reclaimSessionId },
 			})
-			const { items } = resultRes.data
+			const signed = resultRes.data.items
+				.filter((item) => RESULT_EVENTS.has(item.event))
+			if(!signed.length) {
+				return {
+					reclaimSessionId: args.reclaimSessionId,
+					status,
+					ready: false,
+					note: 'Session is terminal but no result is stored: none submitted '
+						+ 'yet, or no callback subscription covers its ending event.',
+				}
+			}
 
+			// Builder keeps a result (which can carry proofs) only until its
+			// callback is delivered, or 7 days undelivered.
+			const items = signed.flatMap((item) => (
+				item.payload === null ? [] : [{ ...item, payload: item.payload }]
+			))
 			if(!items.length) {
 				return {
 					reclaimSessionId: args.reclaimSessionId,
 					status,
 					ready: false,
-					note: 'Session is terminal but no result has been submitted yet.',
+					delivered: signed.some((item) => (
+						item.deliveryStatus === 'delivered'
+					)),
+					note: 'Builder no longer holds this result: it was delivered to '
+						+ 'the callback (read it there), or went undelivered for 7 days. '
+						+ 'See list_verification_deliveries.',
 				}
 			}
 

package/src/tools/registry.ts

@@ -16,10 +16,23 @@ import { isProblemDetails, isProblemError } from '@reclaimprotocol/client/api'
 import type { JSONSchema } from 'zod/v4/core'
 import { toZod } from '../mcp/api/to-zod.ts'
 
+/** MCP tool hints that let a client decide when to ask for approval. */
+export interface ToolAnnotations {
+	/** The tool never changes state. */
+	readOnlyHint?: boolean
+	/** The tool can delete or overwrite state. */
+	destructiveHint?: boolean
+	/** Repeating a call with the same input has no further effect. */
+	idempotentHint?: boolean
+	/** The tool reaches systems outside this machine. */
+	openWorldHint?: boolean
+}
+
 export interface ToolDefinition {
 	name: string
 	description: string
 	inputSchema: JSONSchema.ObjectSchema
+	annotations?: ToolAnnotations
 }
 
 export interface RegisteredTool {
@@ -108,6 +121,7 @@ export function extendTool(
 			name: base.name,
 			description: extra.description ?? base.description,
 			inputSchema,
+			...(base.annotations ? { annotations: base.annotations } : {}),
 		},
 		handler: tool.handler,
 	}