@three-ws/mcp-server 1.1.0

package/src/tools/agenc-client.js

@@ -0,0 +1,136 @@
+// Shared AgenC read-only client used by the agenc-* MCP tools.
+//
+// Constructs an Anchor `Program` bound to the AgenC coordination protocol
+// (agenc.tech, Tetsuo Corp) so the read-only helpers in @tetsuo-ai/sdk can be
+// invoked without forcing every tool to know about Anchor's wallet plumbing.
+//
+// Cluster + RPC are resolved at call time so a single MCP server process can
+// service both mainnet and devnet tools.
+
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+import { AnchorProvider, Program } from '@coral-xyz/anchor';
+import { AGENC_COORDINATION_IDL } from '@tetsuo-ai/protocol';
+import { DEVNET_RPC, MAINNET_RPC, PROGRAM_ID } from '@tetsuo-ai/sdk';
+
+import { resilientFetch } from '../lib/resilient-fetch.js';
+
+// Devnet program ID validated by the AgenC team on 2026-03-22.
+// Source: https://docs.agenc.tech/docs/runtime/api/.
+export const AGENC_DEVNET_PROGRAM_ID = new PublicKey(
+	'6UcJzbTEemBz3aY5wK5qKHGMD7bdRsmR4smND29gB2ab',
+);
+export const AGENC_MAINNET_PROGRAM_ID = PROGRAM_ID;
+
+function pickRpc(cluster) {
+	const override = (process.env.AGENC_RPC_URL || '').trim();
+	if (override) return override;
+	if (cluster === 'devnet') {
+		return (process.env.SOLANA_DEVNET_RPC_URL || '').trim() || DEVNET_RPC;
+	}
+	return (process.env.SOLANA_RPC_URL || '').trim() || MAINNET_RPC;
+}
+
+function buildReadOnlyWallet() {
+	// Anchor's Wallet interface needs a payer slot + publicKey to construct a
+	// provider; we hold an ephemeral keypair purely for type satisfaction and
+	// refuse to sign anything with it. The MCP tools only expose read paths.
+	const ephemeral = Keypair.generate();
+	const refuse = () => {
+		throw new Error(
+			'agenc-client read-only wallet refuses to sign — this tool exposes read paths only.',
+		);
+	};
+	return {
+		payer: ephemeral,
+		publicKey: ephemeral.publicKey,
+		async signTransaction(_tx) {
+			refuse();
+		},
+		async signAllTransactions(_txs) {
+			refuse();
+		},
+	};
+}
+
+/**
+ * Build a read-only AgenC client for `cluster` ("mainnet" | "devnet").
+ * Returns { connection, program, programId, cluster, rpcUrl }.
+ */
+export function getAgenCClient(cluster = 'mainnet') {
+	const c = cluster === 'devnet' ? 'devnet' : 'mainnet';
+	const rpcUrl = pickRpc(c);
+	const connection = new Connection(rpcUrl, {
+		commitment: 'confirmed',
+		// Bound every RPC call (web3.js otherwise inherits Node's unbounded
+		// default — the source of indefinite hangs) and replay a single
+		// transient blip. AgenC reads are idempotent queries, so retry is safe.
+		fetch: (url, init) =>
+			resilientFetch(url, init, {
+				timeoutMs: 12_000,
+				retries: 1,
+				retryNonIdempotent: true,
+				label: `agenc-rpc ${rpcUrl}`,
+			}),
+	});
+	const provider = new AnchorProvider(connection, buildReadOnlyWallet(), {
+		commitment: 'confirmed',
+		preflightCommitment: 'confirmed',
+	});
+	const programId = c === 'devnet' ? AGENC_DEVNET_PROGRAM_ID : AGENC_MAINNET_PROGRAM_ID;
+	const program = new Program(AGENC_COORDINATION_IDL, provider);
+	return { connection, program, programId, cluster: c, rpcUrl };
+}
+
+/** Normalize a base58 pubkey string. Returns a PublicKey or throws. */
+export function parsePubkey(s, label = 'pubkey') {
+	if (!s || typeof s !== 'string') {
+		throw new Error(`${label} must be a base58 string`);
+	}
+	return new PublicKey(s.trim());
+}
+
+/** Convert bigint values inside an object to strings so JSON.stringify works. */
+export function serializeBigInts(value) {
+	if (value === null || value === undefined) return value;
+	if (typeof value === 'bigint') return value.toString();
+	if (value instanceof Uint8Array) return Buffer.from(value).toString('hex');
+	if (value instanceof PublicKey) return value.toBase58();
+	if (Array.isArray(value)) return value.map(serializeBigInts);
+	if (typeof value === 'object') {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) {
+			out[k] = serializeBigInts(v);
+		}
+		return out;
+	}
+	return value;
+}
+
+/** Translate a TaskState enum value to a human label. Matches @tetsuo-ai/sdk. */
+export function taskStateLabel(state) {
+	const map = {
+		0: 'Open',
+		1: 'Claimed',
+		2: 'Completed',
+		3: 'Cancelled',
+		4: 'Disputed',
+		5: 'Expired',
+	};
+	if (typeof state === 'number') return map[state] ?? `Unknown(${state})`;
+	if (state && typeof state === 'object') {
+		const key = Object.keys(state)[0];
+		return key ? key[0].toUpperCase() + key.slice(1) : 'Unknown';
+	}
+	return String(state);
+}
+
+/** Translate an AgentStatus enum value to a label. */
+export function agentStatusLabel(status) {
+	const map = { 0: 'Inactive', 1: 'Active', 2: 'Busy', 3: 'Suspended' };
+	if (typeof status === 'number') return map[status] ?? `Unknown(${status})`;
+	if (status && typeof status === 'object') {
+		const key = Object.keys(status)[0];
+		return key ? key[0].toUpperCase() + key.slice(1) : 'Unknown';
+	}
+	return String(status);
+}

package/src/tools/agenc-get-agent.js

@@ -0,0 +1,145 @@
+// `agenc_get_agent` — paid MCP tool that looks up an AgenC agent's on-chain
+// registration. Returns capability bitmask, status, endpoint, reputation,
+// stake, and active-task count.
+//
+// Pricing: $0.001 USDC, settled `exact` in USDC on Solana mainnet.
+
+import { z } from 'zod';
+import { PublicKey } from '@solana/web3.js';
+import { createHash } from 'node:crypto';
+import { deriveAgentPda, getAgent } from '@tetsuo-ai/sdk';
+
+import { paid, toolError } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+import {
+	getAgenCClient,
+	parsePubkey,
+	serializeBigInts,
+	agentStatusLabel,
+} from './agenc-client.js';
+
+const TOOL_NAME = 'agenc_get_agent';
+const TOOL_DESCRIPTION =
+	'Look up an AgenC agent\'s on-chain registration. Pass either agentPda (the derived account address) OR agentId (32-byte hex, "0x"-prefixed hex, or any UTF-8 label which is hashed via SHA-256). Returns the agent\'s authority wallet, capability bitmask, endpoint URL, status, reputation, stake, and active task count. AgenC = agenc.tech (Tetsuo Corp). Paid: $0.001 USDC.';
+
+function resolveAgentId(input) {
+	const s = String(input).trim();
+	if (s.startsWith('0x') || s.startsWith('0X')) {
+		const hex = s.slice(2);
+		if (hex.length !== 64) throw new Error('hex agentId must be 32 bytes');
+		return Uint8Array.from(Buffer.from(hex, 'hex'));
+	}
+	if (/^[0-9a-fA-F]{64}$/.test(s)) {
+		return Uint8Array.from(Buffer.from(s, 'hex'));
+	}
+	return Uint8Array.from(createHash('sha256').update(s, 'utf8').digest());
+}
+
+// Single source of truth: Zod shape carries descriptions + bounds + cluster
+// enum; JSON Schema derived. (No required fields — the handler enforces
+// "agentPda OR agentId".)
+const inputZodShape = {
+	agentPda: z
+		.string()
+		.min(32)
+		.max(44)
+		.describe('Base58 agent account PDA. Mutually exclusive with agentId.')
+		.optional(),
+	agentId: z
+		.string()
+		.min(1)
+		.max(256)
+		.describe('32-byte agent id as 64-char hex, "0x"-prefixed hex, or any UTF-8 label (SHA-256 hashed).')
+		.optional(),
+	cluster: z.enum(['mainnet', 'devnet']).describe('Solana cluster. Defaults to mainnet.').optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+export async function buildAgenCGetAgentTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			scheme: 'exact',
+			priceUsd: '$0.001',
+			inputSchema: inputJsonSchema,
+			example: { agentId: 'my-three-ws-bot', cluster: 'devnet' },
+			outputExample: {
+				ok: true,
+				cluster: 'devnet',
+				agentPda: '7p…',
+				agent: {
+					agentId: 'a3…',
+					authority: '5y…',
+					capabilities: '1',
+					status: 'Active',
+					endpoint: 'https://three.ws/agents/my-bot',
+					reputation: 0,
+					stakeAmount: '1000000',
+					activeTasks: 0,
+					registeredAt: 1716000000,
+				},
+			},
+		},
+		async ({ agentPda, agentId, cluster }) => {
+			const client = getAgenCClient(cluster);
+			let pda;
+			if (agentPda) {
+				pda = parsePubkey(agentPda, 'agentPda');
+			} else if (agentId) {
+				pda = deriveAgentPda(resolveAgentId(agentId), client.programId);
+			} else {
+				return toolError('missing_input', 'Provide either agentPda or agentId.');
+			}
+
+			const agent = await getAgent(client.program, pda);
+			if (!agent) {
+				return serializeBigInts({
+					ok: false,
+					error: 'not_found',
+					cluster: client.cluster,
+					programId: client.programId.toBase58(),
+					agentPda: pda.toBase58(),
+					message: 'no agent account at that PDA on this cluster',
+				});
+			}
+
+			return serializeBigInts({
+				ok: true,
+				cluster: client.cluster,
+				rpcUrl: client.rpcUrl,
+				programId: client.programId.toBase58(),
+				agentPda: pda.toBase58(),
+				agent: {
+					agentId: Buffer.from(agent.agentId).toString('hex'),
+					authority: agent.authority.toBase58(),
+					capabilities: agent.capabilities.toString(),
+					status: agentStatusLabel(agent.status),
+					statusRaw: typeof agent.status === 'number' ? agent.status : null,
+					endpoint: agent.endpoint,
+					metadataUri: agent.metadataUri,
+					stakeAmount: agent.stakeAmount.toString(),
+					activeTasks: agent.activeTasks,
+					reputation: agent.reputation,
+					registeredAt: agent.registeredAt,
+				},
+				fetchedAt: new Date().toISOString(),
+			});
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: 'AgenC get agent ($0.001)',
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Read-only on-chain registry lookup — agent stats (tasks, reputation)
+		// change between calls, so not idempotent.
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false,
+			openWorldHint: true,
+		},
+		handler,
+	};
+}

package/src/tools/agenc-get-task.js

@@ -0,0 +1,187 @@
+// `agenc_get_task` — paid MCP tool that fetches the current state and lifecycle
+// timeline of a single AgenC task. Useful for any agent that wants to decide
+// whether to bid/claim, or for monitoring an in-flight job.
+//
+// Pricing: $0.001 USDC, settled `exact` in USDC on Solana mainnet.
+
+import { z } from 'zod';
+import { PublicKey } from '@solana/web3.js';
+import { createHash } from 'node:crypto';
+import {
+	deriveTaskPda,
+	getTask,
+	getTaskLifecycleSummary,
+} from '@tetsuo-ai/sdk';
+
+import { paid, toolError } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+import {
+	getAgenCClient,
+	parsePubkey,
+	serializeBigInts,
+	taskStateLabel,
+} from './agenc-client.js';
+
+const TOOL_NAME = 'agenc_get_task';
+const TOOL_DESCRIPTION =
+	'Fetch the on-chain state and lifecycle timeline of a single AgenC task. Pass either taskPda (the derived account address) OR the {creator, taskId} pair, where taskId may be a 64-char hex string or any UTF-8 label (hashed to 32 bytes). Returns state, reward, deadline, worker counts, lifecycle events, and reward mint. AgenC = agenc.tech (Tetsuo Corp). Paid: $0.001 USDC.';
+
+function resolveTaskId(input) {
+	const s = String(input).trim();
+	if (s.startsWith('0x') || s.startsWith('0X')) {
+		const hex = s.slice(2);
+		if (hex.length !== 64) throw new Error('hex taskId must be 32 bytes');
+		return Uint8Array.from(Buffer.from(hex, 'hex'));
+	}
+	if (/^[0-9a-fA-F]{64}$/.test(s)) {
+		return Uint8Array.from(Buffer.from(s, 'hex'));
+	}
+	return Uint8Array.from(createHash('sha256').update(s, 'utf8').digest());
+}
+
+// Single source of truth: Zod shape carries descriptions + bounds + cluster
+// enum; JSON Schema derived. (No required fields — the handler enforces
+// "taskPda OR {creator, taskId}".)
+const inputZodShape = {
+	taskPda: z
+		.string()
+		.min(32)
+		.max(44)
+		.describe('Base58 task account PDA. If omitted, supply creator + taskId.')
+		.optional(),
+	creator: z
+		.string()
+		.min(32)
+		.max(44)
+		.describe('Base58 task creator wallet (required if taskPda is omitted).')
+		.optional(),
+	taskId: z
+		.string()
+		.min(1)
+		.max(256)
+		.describe('32-byte task id as 64-char hex, "0x"-prefixed hex, or any UTF-8 label (hashed via SHA-256).')
+		.optional(),
+	cluster: z.enum(['mainnet', 'devnet']).describe('Solana cluster. Defaults to mainnet.').optional(),
+	includeLifecycle: z
+		.boolean()
+		.describe('When true (default), include the lifecycle event timeline. Set false for a cheaper read.')
+		.optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+export async function buildAgenCGetTaskTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			scheme: 'exact',
+			priceUsd: '$0.001',
+			inputSchema: inputJsonSchema,
+			example: { taskPda: '8xQ…', cluster: 'devnet' },
+			outputExample: {
+				ok: true,
+				cluster: 'devnet',
+				taskPda: '8xQ…',
+				task: {
+					taskId: 'a1b2…',
+					state: 'Claimed',
+					rewardAmount: '50000000',
+					currentWorkers: 1,
+					maxWorkers: 1,
+				},
+				lifecycle: {
+					timeline: [{ eventName: 'created', timestamp: 1716000000 }],
+				},
+			},
+		},
+		async ({ taskPda, creator, taskId, cluster, includeLifecycle }) => {
+			const client = getAgenCClient(cluster);
+			let pda;
+			if (taskPda) {
+				pda = parsePubkey(taskPda, 'taskPda');
+			} else {
+				if (!creator || !taskId) {
+					return toolError('missing_input', 'Provide either taskPda OR both creator and taskId.');
+				}
+				pda = deriveTaskPda(
+					parsePubkey(creator, 'creator'),
+					resolveTaskId(taskId),
+					client.programId,
+				);
+			}
+
+			const task = await getTask(client.program, pda);
+			if (!task) {
+				return serializeBigInts({
+					ok: false,
+					error: 'not_found',
+					cluster: client.cluster,
+					programId: client.programId.toBase58(),
+					taskPda: pda.toBase58(),
+					message: 'no task account at that PDA on this cluster',
+				});
+			}
+			const taskOut = {
+				taskId: Buffer.from(task.taskId).toString('hex'),
+				state: taskStateLabel(task.state),
+				stateRaw: typeof task.state === 'number' ? task.state : null,
+				creator: task.creator.toBase58(),
+				rewardAmount: task.rewardAmount.toString(),
+				rewardMint: task.rewardMint ? task.rewardMint.toBase58() : null,
+				deadline: task.deadline,
+				currentWorkers: task.currentWorkers,
+				maxWorkers: task.maxWorkers,
+				completedAt: task.completedAt,
+				constraintHash: task.constraintHash
+					? Buffer.from(task.constraintHash).toString('hex')
+					: null,
+				private: task.constraintHash != null,
+			};
+
+			let lifecycleOut = null;
+			if (includeLifecycle !== false) {
+				const lifecycle = await getTaskLifecycleSummary(client.program, pda);
+				if (lifecycle) {
+					lifecycleOut = {
+						currentState: taskStateLabel(lifecycle.currentState),
+						createdAt: lifecycle.createdAt,
+						currentWorkers: lifecycle.currentWorkers,
+						maxWorkers: lifecycle.maxWorkers,
+						timeline: lifecycle.timeline.map((e) => ({
+							eventName: e.eventName,
+							timestamp: e.timestamp,
+							txSignature: e.txSignature ?? null,
+							actor: e.actor ? e.actor.toBase58() : null,
+						})),
+					};
+				}
+			}
+
+			return serializeBigInts({
+				ok: true,
+				cluster: client.cluster,
+				rpcUrl: client.rpcUrl,
+				programId: client.programId.toBase58(),
+				taskPda: pda.toBase58(),
+				task: taskOut,
+				lifecycle: lifecycleOut,
+				fetchedAt: new Date().toISOString(),
+			});
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: 'AgenC get task ($0.001)',
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Read-only on-chain lookup — task status moves through its lifecycle
+		// between calls, so not idempotent.
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false,
+			openWorldHint: true,
+		},
+		handler,
+	};
+}

package/src/tools/agenc-list-tasks.js

@@ -0,0 +1,110 @@
+// `agenc_list_tasks` — paid MCP tool that lists every public AgenC task
+// created by a given Solana wallet on the AgenC coordination protocol.
+//
+// Pricing: $0.001 USDC, settled `exact` in USDC on Solana mainnet.
+//
+// AgenC = agenc.tech (Tetsuo Corp). Coordination protocol on Solana. This tool
+// surfaces the on-chain task marketplace so any MCP client (Claude Desktop,
+// Cursor, three.ws agents) can discover open jobs without standing up Anchor.
+
+import { z } from 'zod';
+import { getTasksByCreator } from '@tetsuo-ai/sdk';
+
+import { paid } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+import {
+	getAgenCClient,
+	parsePubkey,
+	serializeBigInts,
+	taskStateLabel,
+} from './agenc-client.js';
+
+const TOOL_NAME = 'agenc_list_tasks';
+const TOOL_DESCRIPTION =
+	'List every public AgenC task created by a given Solana wallet. AgenC (agenc.tech, by Tetsuo Corp) is a Solana coordination protocol where agents bid on, claim, and complete tasks with SOL/SPL escrow and optional zero-knowledge settlement. Returns task PDA, state, reward, deadline, worker counts, and reward mint for each task. Specify cluster="devnet" for the dev cluster (program 6UcJzbT...), otherwise mainnet. Paid: $0.001 USDC.';
+
+// Single source of truth: Zod shape carries descriptions + bounds + cluster
+// enum; JSON Schema derived.
+const inputZodShape = {
+	creator: z.string().min(32).max(44).describe('Base58 Solana pubkey of the task creator wallet.'),
+	cluster: z.enum(['mainnet', 'devnet']).describe('Solana cluster to query. Defaults to mainnet.').optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+export async function buildAgenCListTasksTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			scheme: 'exact',
+			priceUsd: '$0.001',
+			inputSchema: inputJsonSchema,
+			example: {
+				creator: '5yC9BM8KUsJTPbWPLfA2N8qH1s9V8DQ3Vcw1G6Jdpump',
+				cluster: 'devnet',
+			},
+			outputExample: {
+				ok: true,
+				cluster: 'devnet',
+				programId: '6UcJzbTEemBz3aY5wK5qKHGMD7bdRsmR4smND29gB2ab',
+				creator: '5yC9BM8KUsJTPbWPLfA2N8qH1s9V8DQ3Vcw1G6Jdpump',
+				count: 1,
+				tasks: [
+					{
+						taskId: '11d3...',
+						state: 'Open',
+						rewardAmount: '50000000',
+						rewardMint: null,
+						deadline: 1716508800,
+						currentWorkers: 0,
+						maxWorkers: 1,
+					},
+				],
+			},
+		},
+		async ({ creator, cluster }) => {
+			const creatorPk = parsePubkey(creator, 'creator');
+			const client = getAgenCClient(cluster);
+			const tasks = await getTasksByCreator(client.program, creatorPk);
+			const rows = tasks.map((t) => ({
+				taskId: Buffer.from(t.taskId).toString('hex'),
+				state: taskStateLabel(t.state),
+				stateRaw: typeof t.state === 'number' ? t.state : null,
+				rewardAmount: t.rewardAmount.toString(),
+				rewardMint: t.rewardMint ? t.rewardMint.toBase58() : null,
+				deadline: t.deadline,
+				currentWorkers: t.currentWorkers,
+				maxWorkers: t.maxWorkers,
+				completedAt: t.completedAt,
+				constraintHash: t.constraintHash
+					? Buffer.from(t.constraintHash).toString('hex')
+					: null,
+			}));
+			return serializeBigInts({
+				ok: true,
+				cluster: client.cluster,
+				rpcUrl: client.rpcUrl,
+				programId: client.programId.toBase58(),
+				creator: creatorPk.toBase58(),
+				count: rows.length,
+				tasks: rows,
+				fetchedAt: new Date().toISOString(),
+			});
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: 'AgenC list tasks ($0.001)',
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Read-only on-chain program scan — the task set changes as agents
+		// post/claim work, so not idempotent.
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false,
+			openWorldHint: true,
+		},
+		handler,
+	};
+}

package/src/tools/agent-delegate-action.js

@@ -0,0 +1,113 @@
+// `agent_delegate_action` — paid MCP tool that lets an external agent
+// send a message to any three.ws-registered agent and get its reply.
+//
+// Pricing: $0.01 USDC, settled `exact` in USDC on Solana mainnet.
+//
+// Implementation: calls POST /api/agents/talk with the target agentId
+// and message. The target's brain is driven by its embed_policy.brain
+// settings on three.ws (which model, system prompt). Agents whose owner
+// has set surfaces.mcp = false in their embed policy are refused.
+//
+// Recursion is prevented server-side via the x-delegate-depth header.
+
+import { z } from 'zod';
+
+import { paid, toolError } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+import { resilientFetch } from '../lib/resilient-fetch.js';
+
+const TOOL_NAME = 'agent_delegate_action';
+const TOOL_DESCRIPTION =
+	'Send a message to a three.ws-registered agent and receive its response. The target agent uses its configured brain (Claude model and system prompt set via its embed policy). Agents that have opted out of MCP delegation are refused. Useful for agent-to-agent collaboration and tool composition. Paid: $0.01 USDC.';
+
+function env(k, def) {
+	const v = process.env[k];
+	return v && String(v).trim() ? String(v).trim() : def;
+}
+
+// Single source of truth: Zod shape carries descriptions + bounds; JSON Schema
+// derived. The prior hand-written JSON Schema left `model` with no bounds; the
+// Zod (min 1, max 100) is stricter and now wins, surfacing those bounds in the
+// advertised schema too.
+const inputZodShape = {
+	agentId: z.string().min(1).max(120).describe('three.ws agent id (UUID).'),
+	message: z.string().min(1).max(4000),
+	model: z
+		.string()
+		.min(1)
+		.max(100)
+		.describe(
+			'Optional Claude model override (e.g. claude-sonnet-4-6). Must be in the allowlist.',
+		)
+		.optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+export async function buildAgentDelegateActionTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			scheme: 'exact',
+			priceUsd: '$0.01',
+			inputSchema: inputJsonSchema,
+			example: {
+				agentId: '5a4b3c2d-1234-5678-90ab-cdef01234567',
+				message: 'Summarise the latest pump.fun graduations in 3 bullets.',
+			},
+			outputExample: {
+				ok: true,
+				agentId: '5a4b3c2d-1234-5678-90ab-cdef01234567',
+				agentName: 'Pump Sage',
+				response: '...',
+				model: 'claude-haiku-4-5-20251001',
+				durationMs: 1840,
+			},
+		},
+		async ({ agentId, message, model }) => {
+			const endpoint = env('MCP_AGENT_TALK_ENDPOINT', 'https://three.ws/api/agents/talk');
+			let res;
+			try {
+				// Bounded timeout but NO retry: delivering a message to an agent is
+				// not idempotent, so a replay could double-send / double-bill the
+				// target. A long brain response is expected, so the timeout is
+				// generous.
+				res = await resilientFetch(
+					endpoint,
+					{
+						method: 'POST',
+						headers: { 'content-type': 'application/json' },
+						body: JSON.stringify({ agentId, message, model }),
+					},
+					{ timeoutMs: 60_000, retries: 0, label: 'agent-delegate' },
+				);
+			} catch (err) {
+				return toolError('upstream_unreachable', err?.message || 'fetch failed');
+			}
+			const data = await res.json().catch(() => null);
+			if (!res.ok || !data || data.ok === false) {
+				return toolError(
+					data?.code || data?.error || 'agent_delegate_failed',
+					data?.message || `endpoint returned ${res.status}`,
+				);
+			}
+			return data;
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: 'Agent delegate action ($0.01)',
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Dispatches a delegated action to an external agent — a write with
+		// side effects, but it never destroys existing state.
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true,
+		},
+		handler,
+	};
+}