@reclaimprotocol/agent 0.1.4 → 0.1.6

package/src/provider/schema.ts

@@ -25,11 +25,13 @@ export type ResponseRedaction =
 	NonNullable<HttpParams['responseRedactions']>[number]
 
 /**
- * OPRF mode for hashed redactions. `oprf-raw` is what the dev-loop defaults
- * to when privacy is requested — the only variant that runs without external
- * deps (gnark for `oprf`, a TEE for `oprf-mpc`). It is the weakest of the
- * three (the attestor participates in hashing) and is meant to be swapped
- * out before production.
+ * OPRF mode for hashed redactions:
+ *  - `oprf-mpc` — TEE-based MPC OPRF. The default for the cloud/hosted flow: a
+ *    TEE attestor accepts (and expects) this and REJECTS `oprf-raw`.
+ *  - `oprf` — client-side ZK OPRF via gnark (needs the gnark deps).
+ *  - `oprf-raw` — server-side OPRF, no external deps; the local dev-loop
+ *    default (Windows / non-TEE). Weakest of the three (the attestor
+ *    participates in hashing) and not accepted by a TEE attestor.
  */
 export type OprfMode = NonNullable<ResponseRedaction['hash']>
 

package/src/tools/registry.ts

@@ -0,0 +1,92 @@
+/**
+ * The ONE tool primitive for the agent. A tool is authored once with
+ * {@link defineTool} — `{ definition, handler }`, where the handler receives
+ * args already parsed + validated against the definition's JSON Schema (via
+ * zod), so the schema shown to the model and the validation applied to inbound
+ * args cannot drift.
+ *
+ * This lives outside `mcp/` on purpose: it depends only on zod (NOT the MCP
+ * SDK), so non-MCP consumers — the cloud authoring loop — can author and run
+ * these tools without pulling in `@modelcontextprotocol/sdk`. The MCP-specific
+ * glue (`registerToolList` onto an `McpServer`) stays in `mcp/server.ts`, which
+ * re-exports this primitive for the MCP-side tool files.
+ */
+import type { JSONSchema } from 'zod/v4/core'
+import { toZod } from '../mcp/api/to-zod.ts'
+
+export interface ToolDefinition {
+	name: string
+	description: string
+	inputSchema: JSONSchema.ObjectSchema
+}
+
+export interface RegisteredTool {
+	definition: ToolDefinition
+	/**
+	 * @param args Tool arguments (already zod-validated against the schema).
+	 * @returns A JSON-stringifiable value to return to the LLM.
+	 * @throws Any error; the host (MCP `registerToolList` / the cloud loop)
+	 * catches it and surfaces it as an error tool-result.
+	 */
+	handler: (args: unknown) => Promise<unknown>
+}
+
+/**
+ * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
+ * The handler receives args already parsed and type-narrowed via a Zod schema
+ * derived from that same JSON Schema — so the description sent to the client
+ * and the validation applied to inbound args cannot drift.
+ */
+export function defineTool<TArgs>(
+	definition: ToolDefinition,
+	handler: (args: TArgs) => Promise<unknown>,
+): RegisteredTool {
+	const schema = toZod(definition.inputSchema)
+	return {
+		definition,
+		handler: async(raw) => {
+			const args = schema.parse(raw) as TArgs
+			return await handler(args)
+		},
+	}
+}
+
+/**
+ * Adapt a tool to a host by WIDENING its input schema — add properties, mark
+ * some required, optionally override the description — without touching the
+ * handler. A host maps whichever shared tools it needs through this (e.g. the
+ * MCP adds its `captureId` session handle + the credential-aware `run_proof`
+ * contract). Args parse loosely, so the extra fields flow through to the
+ * handler (its backend resolver reads them); the base tool stays untouched for
+ * hosts that don't need them.
+ */
+export function extendTool(
+	tool: RegisteredTool,
+	extra: {
+		description?: string
+		properties?: Record<string, unknown>
+		required?: string[]
+	},
+): RegisteredTool {
+	const base = tool.definition
+	const required = [
+		...(base.inputSchema.required ?? []),
+		...(extra.required ?? []),
+	]
+	const inputSchema = {
+		...base.inputSchema,
+		properties: {
+			...base.inputSchema.properties,
+			...extra.properties,
+		},
+		...(required.length ? { required } : {}),
+	} as unknown as JSONSchema.ObjectSchema
+	return {
+		definition: {
+			name: base.name,
+			description: extra.description ?? base.description,
+			inputSchema,
+		},
+		handler: tool.handler,
+	}
+}