@ola-893/agentpay-cli 0.2.0 → 0.4.0

package/src/copy-activity.mjs

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { usdc } from './settings.mjs';
+
+export const activities = Object.freeze({
+  'spot-trading': 'Mirror an eligible spot swap.',
+  'staking-moves': 'Follow validator or staking pool allocations.',
+  'liquidity-ranges': 'Mirror concentrated-liquidity ranges.',
+  'prediction-markets': 'Mirror outcome positions.',
+  'portfolio-rebalance': 'Follow portfolio target weights.',
+  'yield-reallocation': 'Follow lending or yield-vault allocations.',
+  'reward-reinvestment': 'Compound rewards following a published strategy.',
+});
+
+export const spot = 'spot-trading';
+export const assetId = value => typeof value === 'string' && /^[a-z0-9][a-z0-9:._-]{0,155}$/i.test(value);
+export const rawAmount = value => typeof value === 'string' && /^[1-9][0-9]{0,37}$/.test(value);
+
+export function spotOrder({ from, to, amount }) {
+  if (!assetId(from) || !assetId(to) || from === to || !rawAmount(amount)) throw new Error('Specify distinct --from and --to asset IDs and --amount-raw in the input asset’s atomic units.');
+  return { origin_asset: from, destination_asset: to, amount };
+}
+
+export function executionPolicy(flags, previous = {}) {
+  const assets = flags.assets?.split(',') ?? previous.assets;
+  const maxInput = flags['max-input-raw'] ?? previous.maxInput;
+  const inputAsset = flags['input-asset'] ?? previous.inputAsset;
+  const fixedInput = flags['copy-input-raw'] ?? previous.fixedInput;
+  const maxAge = Number(flags['max-age'] ?? previous.maxAge ?? 60);
+  const slippageBps = Number(flags['max-slippage-bps'] ?? previous.slippageBps ?? 50);
+  if (!assets?.length || assets.length > 32 || !assets.every(assetId) || !assets.includes(inputAsset) || !rawAmount(maxInput) || !rawAmount(fixedInput) || BigInt(fixedInput) > BigInt(maxInput)) throw new Error('Set --assets, --input-asset, --max-input-raw and --copy-input-raw. Use one input asset so caps have a consistent unit.');
+  if (!Number.isInteger(maxAge) || maxAge < 1 || maxAge > 3600 || !Number.isInteger(slippageBps) || slippageBps < 0 || slippageBps > 500) throw new Error('Use --max-age 1–3600 seconds and --max-slippage-bps 0–500.');
+  return { assets: [...new Set(assets)], inputAsset, maxInput, fixedInput, maxAge, slippageBps,
+    ...(flags['max-notional'] ? { maxNotionalRawUSDC: usdc(flags['max-notional']) } : previous.maxNotionalRawUSDC ? { maxNotionalRawUSDC: previous.maxNotionalRawUSDC } : {}) };
+}
+
+export function proposedOrder(action, policy, now = Date.now()) {
+  if (!policy) return { reason: 'EXECUTION_POLICY_REQUIRED' };
+  if (action.at > now + 5000 || now - action.at > policy.maxAge * 1000 || now >= action.expiresAt) return { reason: 'ACTION_EXPIRED' };
+  if (action.from !== policy.inputAsset || !policy.assets.includes(action.to)) return { reason: 'ASSET_NOT_ALLOWED' };
+  return { order: spotOrder({ from: action.from, to: action.to, amount: policy.fixedInput }) };
+}
+
+export function checkQuote(quote, order, action, policy) {
+  if (!rawAmount(quote.amountOut) || !rawAmount(quote.amountIn) || quote.amountIn !== order.amount) return 'UNUSABLE_QUOTE';
+  const expected = BigInt(action.amountOut) * BigInt(order.amount);
+  const observed = BigInt(quote.amountOut) * BigInt(action.amountIn);
+  if (observed * 10000n < expected * BigInt(10000 - policy.slippageBps)) return 'PRICE_MOVED';
+  if (policy.maxNotionalRawUSDC) {
+    let usd;
+    try { usd = BigInt(usdc(String(quote.amountInUsd))); } catch { return 'USD_PRICE_UNAVAILABLE'; }
+    if (usd > BigInt(policy.maxNotionalRawUSDC)) return 'NOTIONAL_LIMIT';
+  }
+  return null;
+}
+
+export const operationKey = (agentId, actionId) => createHash('sha256').update(`${agentId}:${actionId}`).digest('hex');

package/src/copy-commands.mjs

@@ -0,0 +1,220 @@
+import { resolve } from 'node:path';
+import { readAgentState, withAgentState, agentSetupState, createAgent, listAgents, selectAgent } from './agents.mjs';
+import { initProject } from './config.mjs';
+import { activities, executionPolicy, spot, spotOrder } from './copy-activity.mjs';
+import { intentsConfig } from './copy-intents.mjs';
+import { configurePublish, getListing, originOf, publicationHistory, subscribers } from './copy-feed.mjs';
+import { changeMode, decideAction, previewCopy, reconcileCopy, runCopyAgent, runSpotTask, startCopy, stopCopy } from './copy-runtime.mjs';
+import { settings, setLimits, setRuntime, reconcileLimits, usdc } from './settings.mjs';
+import { setupTestnet } from './setup.mjs';
+import { payout, reconcilePayouts } from './vault-money.mjs';
+import { readKey } from '@ola-893/agentpay-core/internal-config';
+import { inspectNearProfile, NearAgentPayClient } from '@ola-893/agentpay-core/near';
+
+export const copyFlags = {
+  'agent:create': '', 'agent:list': '', 'agent:use': '', 'agent:show': '',
+  'agent:setup': 'network deployment owner-id owner-key recipient vault-name agent-name rpc service deploy',
+  'task:list': '', 'task:enable': 'intents-agent-id intents-key-env intents-grant-env live confidential', 'task:disable': '',
+  'task:run': 'from to amount-raw execute',
+  'publish:set': 'activities url port rate duration recipient nova-group nova-account nova-network nova-key-env performance-file',
+  'publish:start': '', 'publish:stop': '', 'publish:status': '', 'publish:history': '',
+  'earnings:show': '', 'earnings:claim': 'from recipient-key', discover: 'activity url id',
+  'copy:preview': 'url', 'copy:start': 'url activity', 'copy:mode': '', 'copy:pending': '', 'copy:approve': '', 'copy:reject': '',
+  'copy:pause': '', 'copy:resume': '', 'copy:stop': '', 'copy:status': '', 'copy:history': '',
+  'guard:show': '', 'guard:set': 'budget max-stream max-rate max-duration recipient owner-key max-5xx max-transport-errors max-health-failures idle-timeout max-requests reuse poll-seconds close-on-exit failure-cooldown assets input-asset max-input-raw copy-input-raw max-age max-slippage-bps max-notional stale-seconds feed-failures',
+  withdraw: 'owner-key', balance: '', status: '',
+};
+
+export const copyPositionals = new Set(['agent:create', 'agent:use', 'agent:show', 'task:enable', 'task:disable', 'task:run', 'copy:start', 'copy:mode', 'copy:approve', 'copy:reject', 'guard:set']);
+const paymentLimits = { budget: 'budget', 'max-stream': 'max_deposit', 'max-rate': 'max_rate', 'max-duration': 'max_duration_seconds', recipient: 'recipients' };
+const runtimeLimits = { 'max-5xx': 'maxConsecutive5xx', 'max-transport-errors': 'maxConsecutiveTransportErrors', 'max-health-failures': 'maxConsecutiveHealthFailures', 'idle-timeout': 'idleTimeoutSeconds', 'max-requests': 'maxRequestsPerStream', 'poll-seconds': 'healthPollSeconds', 'failure-cooldown': 'failureCooldownSeconds', reuse: 'reuseStream', 'close-on-exit': 'closeOnExit' };
+const executionFlags = 'assets input-asset max-input-raw copy-input-raw max-age max-slippage-bps max-notional'.split(' ');
+const txLink = hash => `https://testnet.nearblocks.io/txns/${hash}`;
+
+function positive(value, max = 3600) {
+  const n = Number(value);
+  if (!/^\d+$/.test(value ?? '') || !Number.isInteger(n) || n < 1 || n > max) throw new Error(`Use an integer from 1 to ${max}.`);
+  return n;
+}
+
+async function guard(agent, scope, flags, provided) {
+  const payment = Object.keys(paymentLimits), runtime = Object.keys(runtimeLimits);
+  const accepted = { payment: [...payment, ...runtime, 'owner-key'], execution: executionFlags, feed: ['stale-seconds', 'feed-failures'] }[scope];
+  if (!accepted) throw new Error('Use guard set payment, execution or feed.');
+  for (const flag of provided) if (!accepted.includes(flag)) throw new Error(`--${flag} does not apply to the ${scope} guard.`);
+  if (!provided.length) throw new Error('Supply at least one guardrail. See --help.');
+  return withAgentState(agent, async state => {
+    if (scope === 'execution') return { execution: state.executionPolicy = executionPolicy(flags, state.executionPolicy) };
+    if (scope === 'feed') {
+      const prior = state.feedGuard ?? { staleSeconds: 45, failures: 3 };
+      return { feed: state.feedGuard = {
+        staleSeconds: flags['stale-seconds'] ? positive(flags['stale-seconds']) : prior.staleSeconds,
+        failures: flags['feed-failures'] ? positive(flags['feed-failures'], 100) : prior.failures,
+      } };
+    }
+    const financial = {}, local = {};
+    for (const flag of payment.filter(k => flags[k] !== undefined)) {
+      financial[paymentLimits[flag]] = flag === 'recipient' ? flags[flag].split(',') : flag === 'max-duration' ? positive(flags[flag]) : usdc(flags[flag]);
+    }
+    for (const flag of runtime.filter(k => flags[k] !== undefined)) {
+      if (['reuse', 'close-on-exit'].includes(flag)) {
+        if (!['true', 'false'].includes(flags[flag])) throw new Error(`Use true or false for --${flag}.`);
+        local[runtimeLimits[flag]] = flags[flag] === 'true';
+      } else local[runtimeLimits[flag]] = positive(flags[flag], 1000000);
+    }
+    if (Object.keys(financial).length && Object.keys(local).length) throw new Error('Set on-chain limits and local runtime thresholds in separate commands.');
+    if (Object.keys(financial).length) return setLimits(agent.path, financial, flags['owner-key']);
+    return setRuntime(agent.path, local);
+  });
+}
+
+async function vaultBalance(project) {
+  const { profile, config } = await settings(project);
+  const { client } = await inspectNearProfile(profile.configPath, profile.stateRoot);
+  const [vault, ownerWallet] = await Promise.all([client.getVault(), client.tokenBalance(config.ownerId, config.tokenId)]);
+  return { network: config.network, vaultId: config.vaultId, units: 'raw USDC (1 USDC = 1000000)', ownerWallet, vault };
+}
+
+async function withdrawal(agent, project, amount, keyFile) {
+  if (!keyFile || !amount) throw new Error('Use withdraw AMOUNT --owner-key PATH.');
+  const raw = usdc(amount);
+  if (raw === '0') throw new Error('Withdrawal amount must be positive.');
+  const { profile, config } = await settings(project);
+  const { client: reader } = await inspectNearProfile(profile.configPath, profile.stateRoot);
+  const owner = await readKey(resolve(keyFile));
+  const vault = await reader.getVault();
+  if (owner.accountId !== config.ownerId || owner.accountId !== vault.owner_id) throw new Error('OWNER_CREDENTIAL_MISMATCH');
+  if (vault.active_session) throw new Error('CLOSE_STREAM_BEFORE_WITHDRAWAL');
+  const client = new NearAgentPayClient({ vaultId: config.vaultId, rpcUrl: config.rpcUrl, accountId: owner.accountId, privateKey: owner.privateKey });
+  if (agent) return { amountRawUSDC: raw, ...await payout(agent, client, 'withdraw_available', { amount: raw }) };
+  const receipt = await client.withdraw(raw);
+  if (receipt.receiptFailures.length) throw new Error(`WITHDRAWAL_RECEIPT_FAILED: ${txLink(receipt.hash)}`);
+  return { amountRawUSDC: raw, transactionHash: receipt.hash, explorerUrl: txLink(receipt.hash), result: receipt.value };
+}
+
+async function earnings(agent, action, flags) {
+  const items = await subscribers(agent);
+  if (action === 'show') {
+    const sessions = await Promise.all(items.map(async item => {
+      const client = new NearAgentPayClient({ rpcUrl: item.rpcUrl, vaultId: item.vaultId });
+      const stream = await client.getStream(item.sessionId);
+      return { vaultId: item.vaultId, sessionId: item.sessionId, recipient: item.recipient, stream };
+    }));
+    const vaults = await Promise.all([...new Map(items.map(item => [`${item.vaultId}:${item.recipient}`, item])).values()].map(async item => {
+      const client = new NearAgentPayClient({ rpcUrl: item.rpcUrl, vaultId: item.vaultId });
+      return { vaultId: item.vaultId, recipient: item.recipient, claimableRawUSDC: await client.getClaim(item.recipient) };
+    }));
+    return { network: 'testnet', sessions, vaults };
+  }
+  const item = items.find(sub => sub.vaultId === flags.from);
+  if (!item || !flags['recipient-key']) throw new Error('Use earnings claim --from a vault listed by earnings show --recipient-key PATH.');
+  const recipient = await readKey(resolve(flags['recipient-key']));
+  if (!items.some(sub => sub.vaultId === item.vaultId && sub.recipient === recipient.accountId)) throw new Error('RECIPIENT_CREDENTIAL_MISMATCH');
+  const client = new NearAgentPayClient({ vaultId: item.vaultId, rpcUrl: item.rpcUrl, accountId: recipient.accountId, privateKey: recipient.privateKey });
+  if (BigInt(await client.getClaim(recipient.accountId)) === 0n) return { reason: 'NOTHING_CLAIMABLE' };
+  return payout(agent, client, 'claim');
+}
+
+export async function runCopyCommand(command, p, v, workspace, agent, emit, provided) {
+  const arg = p[2];
+  switch (command) {
+    case 'agent:create': return createAgent(workspace, arg);
+    case 'agent:list': return listAgents(workspace);
+    case 'agent:use': if (!arg) throw new Error('Supply an agent name.'); return selectAgent(workspace, arg);
+    case 'balance': return vaultBalance(agent?.path ?? workspace);
+    case 'withdraw': return withdrawal(agent, agent?.path ?? workspace, p[1], v['owner-key']);
+  }
+  if (!agent) throw new Error('Run agentpay agent create NAME or select an existing agent.');
+  const state = await readAgentState(agent);
+  switch (command) {
+    case 'agent:show': {
+      const { path, ...identity } = agent;
+      return { ...identity, setup: await agentSetupState(agent) };
+    }
+    case 'agent:setup': {
+      if (v.network && v.network !== 'testnet') throw new Error('Only native NEAR testnet is supported.');
+      if (v.deployment && v.deploy) throw new Error('Choose --deployment or --deploy.');
+      if (v.deployment) return initProject(agent.path, { deployment: v.deployment });
+      const suffix = agent.id.slice(3, 11);
+      const result = await setupTestnet(agent.path, {
+        ownerId: v['owner-id'], ownerKeyFile: v['owner-key'], recipientId: v.recipient,
+        vaultLabel: provided.includes('vault-name') ? v['vault-name'] : 'v' + suffix,
+        agentLabel: provided.includes('agent-name') ? v['agent-name'] : 'a' + suffix,
+        rpcUrl: v.rpc, serviceUrl: v.service, deploy: v.deploy, setupCommand: 'agentpay agent setup',
+      });
+      if (result.readyToDeploy === false) process.exitCode = 1;
+      return result;
+    }
+    case 'agent:run': return runCopyAgent(agent, { once: v.once, rpc: v.rpc, emit });
+    case 'task:list': return { activities: Object.entries(activities).map(([id, description]) => ({ id, description, status: id !== spot ? 'planned' : state.tasks[id] ? 'enabled' : 'available', live: state.tasks[id]?.live ?? false })) };
+    case 'task:enable':
+    case 'task:disable':
+      if (!Object.hasOwn(activities, arg ?? '')) throw new Error('Choose an activity from agentpay task list.');
+      if (arg !== spot) throw new Error(`${arg} is planned. The executable adapter is spot-trading.`);
+      return withAgentState(agent, current => {
+        if (current.tradePending) throw new Error('TRADE_RECONCILIATION_REQUIRED');
+        if (command === 'task:enable') current.tasks[arg] = intentsConfig(v);
+        else { delete current.tasks[arg]; if (current.follow) current.follow.mode = 'observe'; }
+        return { activity: arg, enabled: Boolean(current.tasks[arg]), config: current.tasks[arg] ?? null };
+      });
+    case 'task:run':
+      if (arg !== spot) throw new Error('Only spot-trading is executable.');
+      return runSpotTask(agent, spotOrder({ from: v.from, to: v.to, amount: v['amount-raw'] }), v.execute);
+    case 'publish:set':
+      return configurePublish(agent, { ...v, port: provided.includes('port') ? v.port : undefined, recipient: v.recipient ?? (await agentSetupState(agent)).ownerId });
+    case 'publish:start':
+    case 'publish:stop':
+      return withAgentState(agent, current => {
+        if (!current.publish) throw new Error('Configure publish set first.');
+        current.publish.enabled = command === 'publish:start';
+        return { enabled: current.publish.enabled, id: agent.id, origin: current.publish.origin, ...(current.publish.enabled ? { next: 'Run agentpay agent run to serve the listing and gated journal.' } : {}) };
+      });
+    case 'publish:status': return { agentId: agent.id, publication: state.publish ?? null, entries: state.journal?.length ?? 0 };
+    case 'publish:history': return publicationHistory(agent);
+    case 'earnings:show': return earnings(agent, 'show', v);
+    case 'earnings:claim': return earnings(agent, 'claim', v);
+    case 'discover': {
+      if (v.activity && !Object.hasOwn(activities, v.activity)) throw new Error('Unknown activity.');
+      if (Boolean(v.id) !== Boolean(v.url)) throw new Error('Provide --id and --url together to verify and remember a publisher.');
+      if (v.url) {
+        const listing = await getListing(v.id, originOf(v.url));
+        await withAgentState(agent, current => { current.directory[listing.id] = listing.origin; });
+        return { listings: !v.activity || v.activity === listing.activity ? [listing] : [] };
+      }
+      if (v.activity && v.activity !== spot) return { listings: [], unavailable: [] };
+      const results = await Promise.allSettled(Object.entries(state.directory).map(([id, origin]) => getListing(id, origin)));
+      const ids = Object.keys(state.directory);
+      return { listings: results.flatMap(item => item.status === 'fulfilled' ? [item.value] : []), unavailable: results.flatMap((item, i) => item.status === 'rejected' ? [ids[i]] : []) };
+    }
+    case 'copy:preview': return previewCopy(agent, p[1], v.url);
+    case 'copy:start': if (!arg) throw new Error('Supply a publisher agent ID.'); return startCopy(agent, { id: arg, url: v.url, activity: v.activity });
+    case 'copy:resume': return startCopy(agent, { resume: true });
+    case 'copy:pause': return stopCopy(agent, 'paused');
+    case 'copy:stop': return stopCopy(agent, 'stopped');
+    case 'copy:mode': return changeMode(agent, arg);
+    case 'copy:approve': return decideAction(agent, arg, 'approved');
+    case 'copy:reject': return decideAction(agent, arg, 'rejected');
+    case 'copy:status': return { subscription: state.follow ?? null, tradePending: Boolean(state.tradePending) };
+    case 'copy:pending': return { actions: Object.values(state.pending ?? {}).filter(item => item.sessionId === state.follow?.sessionId && item.status === 'pending' && item.action.expiresAt > Date.now()) };
+    case 'copy:history': return { history: state.history };
+    case 'guard:set': return guard(agent, arg, v, provided);
+    case 'guard:show': {
+      const setup = await agentSetupState(agent);
+      return { payment: setup.configured ? await vaultBalance(agent.path).then(x => x.vault.policy) : null, runtime: setup.configured ? (await settings(agent.path)).config.runtimePolicy : null, execution: state.executionPolicy ?? null, feed: state.feedGuard ?? { staleSeconds: 45, failures: 3 } };
+    }
+    case 'status': return { name: agent.name, id: agent.id, setup: await agentSetupState(agent), publicationEnabled: Boolean(state.publish?.enabled), subscription: state.follow ?? null, pendingTrade: Boolean(state.tradePending) };
+    case 'reconcile': {
+      const copy = await reconcileCopy(agent);
+      const payouts = await reconcilePayouts(agent);
+      if (!(await agentSetupState(agent)).configured) return { resolved: copy.resolved && payouts.resolved, copy, payouts };
+      const { gatewayFor } = await import('./config.mjs');
+      const client = await gatewayFor(agent.path);
+      try {
+        const payment = await client.reconcile();
+        const policy = await reconcileLimits(agent.path);
+        return { resolved: copy.resolved && payment.resolved && policy.resolved && payouts.resolved, copy, payment, policy, payouts };
+      } finally { await client.dispose(); }
+    }
+    default: throw new Error('Unknown command. Run agentpay --help.');
+  }
+}

package/src/copy-feed.mjs

@@ -0,0 +1,278 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PublicKey, baseEncode } from 'near-api-js';
+import { NearAgentPayClient, USDC } from '@ola-893/agentpay-core/near';
+import { verifySession } from '@ola-893/agentpay-core/internal-session';
+import { canonical } from '@ola-893/agentpay-core/internal-evidence-audit';
+import { atomicWrite, readOptional } from './files.mjs';
+import { feedKey, fingerprint, readAgentState, withAgentState } from './agents.mjs';
+import { assetId, rawAmount, spot } from './copy-activity.mjs';
+import { credential } from './copy-intents.mjs';
+import { bundledWasm } from './setup.mjs';
+import { usdc } from './settings.mjs';
+
+export const agentIdPattern = /^ap_[a-f0-9]{64}$/;
+export const accountId = value => typeof value === 'string' && /^(?=.{2,64}$)[a-z0-9]+(?:[-_.][a-z0-9]+)*$/.test(value);
+export const quotePath = (vaultId, expiresAt) => `/copy/quote/${vaultId}` + (expiresAt ? `/${expiresAt}` : "");
+export const listingPath = '/.well-known/agentpay.json';
+export const feedPath = '/copy/actions';
+export const healthPath = '/copy/health';
+export const quoteHash = quote => fingerprint(JSON.stringify(quote));
+
+export function originOf(value) {
+  const url = new URL(value);
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === '127.0.0.1'))) throw new Error('Use an HTTPS feed origin or http://127.0.0.1 for a local feed.');
+  return url.origin;
+}
+
+export async function readJsonResponse(response, max = 131072) {
+  const parts = [];
+  let size = 0;
+  for await (const part of response.body ?? []) {
+    size += part.length;
+    if (size > max) throw new Error('FEED_RESPONSE_TOO_LARGE');
+    parts.push(part);
+  }
+  return JSON.parse(Buffer.concat(parts).toString('utf8'));
+}
+
+export async function fetchFeed(origin, path, headers) {
+  const response = await fetch(`${origin}${path}`, { headers, redirect: 'error', signal: AbortSignal.timeout(10000) });
+  if (!response.ok) throw new Error(`FEED_HTTP_${response.status}`);
+  return readJsonResponse(response);
+}
+
+function signed(key, domain, body) {
+  const signature = key.sign(Buffer.from(canonical({ domain, body }))).signature;
+  return { body, signature: Buffer.from(signature).toString('base64') };
+}
+
+function verified(envelope, key, domain) {
+  return envelope?.body && typeof envelope.signature === 'string' && envelope.signature.length === 88 &&
+    PublicKey.fromString(key).verify(Buffer.from(canonical({ domain, body: envelope.body })), Buffer.from(envelope.signature, 'base64'));
+}
+
+export async function configurePublish(agent, flags) {
+  const selected = flags.activities?.split(',') ?? [spot];
+  if (selected.length !== 1 || selected[0] !== spot) throw new Error('The executable publication adapter is spot-trading. See agentpay task list for the catalog.');
+  const origin = originOf(flags.url ?? 'http://127.0.0.1:5380');
+  const port = Number(flags.port ?? (new URL(origin).protocol === 'http:' ? new URL(origin).port || 80 : 5380));
+  const duration = Number(flags.duration ?? 600);
+  const rate = usdc(flags.rate);
+  if (BigInt(rate) < 1n || !accountId(flags.recipient) || !flags.recipient.endsWith('.testnet') || !Number.isInteger(duration) || duration < 30 || duration > 3600 || !Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Provide a positive --rate, .testnet --recipient, --duration 30–3600 seconds and a valid --port.');
+  const nova = flags['nova-group'] ? { group: flags['nova-group'], account: flags['nova-account'], keyEnv: flags['nova-key-env'] ?? 'NOVA_API_KEY', network: flags['nova-network'] ?? 'testnet' } : null;
+  if (nova && (!/^[A-Za-z0-9._-]{1,64}$/.test(nova.group) || !accountId(nova.account) || !/^[A-Z][A-Z0-9_]{0,127}$/.test(nova.keyEnv) || !['testnet', 'mainnet'].includes(nova.network))) throw new Error('Provide a valid --nova-group, --nova-account and --nova-network.');
+  const performance = flags['performance-file'] ? JSON.parse(await readFile(flags['performance-file'], 'utf8')) : null;
+  if (performance && (!Array.isArray(performance) || performance.length > 90 || !performance.every(p => Object.keys(p).length === 2 && /^\d{4}-\d{2}-\d{2}$/.test(p.date) && Number.isFinite(p.pnl)))) throw new Error('Performance file must contain up to 90 { date, pnl } points.');
+  return withAgentState(agent, state => {
+    if (state.publish?.enabled) throw new Error('Stop publication before changing the listing.');
+    state.publish = { enabled: false, origin, port, duration, rate, recipient: flags.recipient, nova, performance };
+    return { origin, rateRawUSDCPerSecond: rate, durationSeconds: duration, recipient: flags.recipient, journal: nova ? 'nova' : 'local-encrypted', enabled: false };
+  });
+}
+
+function listing(agent, state) {
+  const p = state.publish;
+  return {
+    version: 1, id: agent.id, name: agent.name, publicKey: agent.publicKey, origin: p.origin, network: 'testnet',
+    activity: spot, recipient: p.recipient, rate: p.rate, duration: p.duration,
+    journal: p.nova ? 'nova' : 'local-encrypted',
+    ...(p.performance ? { performance: { provenance: 'publisher-reported', points: p.performance, journalHead: state.journal?.at(-1)?.hash ?? null } } : {}),
+  };
+}
+
+export async function getListing(id, origin) {
+  const envelope = await fetchFeed(origin, listingPath);
+  const b = envelope?.body;
+  if (!b || b.version !== 1 || b.id !== id || !agentIdPattern.test(id) || typeof b.publicKey !== 'string' || b.publicKey.length > 70 ||
+      `ap_${fingerprint(b.publicKey)}` !== id || b.origin !== origin || b.network !== 'testnet' || b.activity !== spot ||
+      !accountId(b.recipient) || !b.recipient.endsWith('.testnet') || !rawAmount(b.rate) || !Number.isInteger(b.duration) || b.duration < 30 || b.duration > 3600 ||
+      !verified(envelope, b.publicKey, 'agentpay.listing.v1')) throw new Error('INVALID_SIGNED_LISTING');
+  return b;
+}
+
+function quoteFor(b, vaultId, tokenId, expiresAt) {
+  return {
+    version: 1, vault_id: vaultId, token_id: tokenId, recipient_id: b.recipient, tier: 'basic', rate: b.rate,
+    duration_seconds: b.duration, expires_at: expiresAt, publisher: b.id, origin: b.origin, activity: b.activity,
+  };
+}
+
+export function checkListingQuote(b, vaultId, tokenId, quote) {
+  if (!Number.isSafeInteger(quote?.expires_at) || quote.expires_at <= Date.now() / 1000 || quote.expires_at > Date.now() / 1000 + 300 ||
+      canonical(quote) !== canonical(quoteFor(b, vaultId, tokenId, quote.expires_at))) throw new Error('QUOTE_DOES_NOT_MATCH_SIGNED_LISTING');
+  return quoteHash(quote);
+}
+
+function quoteMatchesStream(b, vault, stream, vaultId) {
+  if (stream?.recipient_id !== b.recipient || stream.rate !== b.rate || stream.duration_seconds !== b.duration) return false;
+  const bucket = Math.floor(Number(stream.started_at) / 60) * 60;
+  // The quote lasts 60–120 seconds. Include the preceding buckets for a transaction crossing a boundary.
+  return [0, 60, 120].some(offset => quoteHash(quoteFor(b, vaultId, vault.token_id, bucket + 120 - offset)) === stream.quote_hash);
+}
+
+function localJournalKey(key) {
+  return createHash('sha256').update('agentpay.local.journal.v1\0').update(key.toString()).digest();
+}
+
+async function novaSdk(nova) {
+  const { NovaSdk } = await import('nova-sdk-js');
+  const settings = nova.network === 'testnet' ? { contractId: 'nova-sdk-7.testnet', rpcUrl: 'https://test.rpc.fastnear.com' } : {};
+  return new NovaSdk(nova.account, { ...settings, apiKey: credential(nova.keyEnv) });
+}
+
+async function storeEntry(agent, key, entry, nova) {
+  const data = Buffer.from(JSON.stringify(entry));
+  const hash = fingerprint(data);
+  if (nova) {
+    const sdk = await novaSdk(nova);
+    const result = await sdk.upload(nova.group, data, `${hash}.json`);
+    if (result.file_hash !== hash || typeof result.cid !== 'string') throw new Error('NOVA_JOURNAL_HASH_MISMATCH');
+    return { nova, ref: result.cid, hash };
+  }
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', localJournalKey(key), iv);
+  const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+  const file = join(agent.path, 'journal', `${hash}.json`);
+  await atomicWrite(file, JSON.stringify({ iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ciphertext: ciphertext.toString('base64') }));
+  return { hash };
+}
+
+async function loadEntry(agent, key, pointer) {
+  let data;
+  if (pointer.nova) {
+    const sdk = await novaSdk(pointer.nova);
+    data = (await sdk.retrieve(pointer.nova.group, pointer.ref)).data;
+  } else {
+    const content = JSON.parse(await readFile(join(agent.path, 'journal', `${pointer.hash}.json`), 'utf8'));
+    const cipher = createDecipheriv('aes-256-gcm', localJournalKey(key), Buffer.from(content.iv, 'base64'));
+    cipher.setAuthTag(Buffer.from(content.tag, 'base64'));
+    data = Buffer.concat([cipher.update(Buffer.from(content.ciphertext, 'base64')), cipher.final()]);
+  }
+  if (fingerprint(data) !== pointer.hash) throw new Error('JOURNAL_HASH_MISMATCH');
+  return JSON.parse(data);
+}
+
+export async function appendFill(agent, state, fill) {
+  if (!state.publish?.enabled) return null;
+  const journal = state.journal ??= [];
+  if (journal.some(item => item.id === fill.id)) return null;
+  const key = await feedKey(agent);
+  const action = { ...fill, sequence: (journal.at(-1)?.sequence ?? 0) + 1, publisher: agent.id, activity: spot };
+  const entry = signed(key, 'agentpay.action.v1', action);
+  const pointer = await storeEntry(agent, key, entry, state.publish.nova);
+  journal.push({ ...pointer, id: action.id, sequence: action.sequence });
+  return { id: action.id, sequence: action.sequence, journalHash: pointer.hash };
+}
+
+export function verifyAction(envelope, listing) {
+  const b = envelope?.body;
+  if (!b || b.publisher !== listing.id || b.activity !== listing.activity || !/^[a-f0-9]{64}$/.test(b.id ?? '') ||
+      !Number.isSafeInteger(b.sequence) || b.sequence < 1 || !Number.isSafeInteger(b.at) || !Number.isSafeInteger(b.expiresAt) || b.expiresAt <= b.at ||
+      !assetId(b.from) || !assetId(b.to) || b.from === b.to || !rawAmount(b.amountIn) || !rawAmount(b.amountOut) ||
+      typeof b.settlementRef !== 'string' || !b.settlementRef.length || b.settlementRef.length > 160 ||
+      !verified(envelope, listing.publicKey, 'agentpay.action.v1')) throw new Error('INVALID_SIGNED_ACTION');
+  return b;
+}
+
+export async function publicationHistory(agent) {
+  const state = await readAgentState(agent);
+  const key = await feedKey(agent);
+  return { actions: await Promise.all((state.journal ?? []).slice(-20).map(p => loadEntry(agent, key, p))) };
+}
+
+export async function subscribers(agent) {
+  const directory = join(agent.path, 'subscribers');
+  let files;
+  try { files = await readdir(directory); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return Promise.all(files.filter(name => /^[a-f0-9]{64}\.json$/.test(name)).map(async name => JSON.parse(await readFile(join(directory, name), 'utf8'))));
+}
+
+export async function serveFeed(agent, { rpcUrl = 'https://test.rpc.fastnear.com', network = 'testnet', token = USDC.testnet, codeFile = bundledWasm, port } = {}) {
+  const { publish } = await readAgentState(agent);
+  if (!publish) throw new Error('Configure publish set first.');
+  const key = await feedKey(agent);
+  const codeHash = baseEncode(createHash('sha256').update(await readFile(codeFile)).digest());
+  const rpc = new NearAgentPayClient({ rpcUrl });
+  if ((await rpc.provider.viewNodeStatus()).chain_id !== network) throw new Error('FEED_RPC_NETWORK_MISMATCH');
+  const server = createServer(async (req, res) => {
+    const send = (status, value) => {
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+      res.end(JSON.stringify(value));
+    };
+    try {
+      if (req.method !== 'GET') return send(405, { error: 'METHOD_NOT_ALLOWED' });
+      const path = new URL(req.url, publish.origin);
+      const state = await readAgentState(agent);
+      if (!state.publish?.enabled || state.publish.origin !== publish.origin || state.publish.port !== publish.port) return send(503, { error: 'PUBLICATION_STOPPED' });
+      const b = listing(agent, state);
+      if (path.pathname === listingPath) return send(200, signed(key, 'agentpay.listing.v1', b));
+      if (path.pathname === healthPath) return send(200, { ok: true, observed_at: Math.floor(Date.now() / 1000) });
+      if (path.pathname.startsWith('/copy/quote/')) {
+        const [vaultId, expiry, ...extra] = path.pathname.slice('/copy/quote/'.length).split('/');
+        const now = Math.floor(Date.now() / 1000);
+        const next = Math.floor(now / 60) * 60 + 120;
+        const expiresAt = expiry === undefined ? next : Number(expiry);
+        if (!accountId(vaultId) || path.searchParams.get('tier') !== 'basic' || extra.length ||
+            ![next, next - 60].includes(expiresAt) || expiresAt <= now) return send(400, { error: 'INVALID_QUOTE_REQUEST' });
+        return send(200, quoteFor(b, vaultId, token, expiresAt));
+      }
+      if (path.pathname !== feedPath) return send(404, { error: 'NOT_FOUND' });
+      const header = req.headers['x-agentpay-session'];
+      if (!header) return send(402, { protocol: 'agentpay-near-v1' });
+      if (typeof header !== 'string' || header.length > 2048) return send(403, { error: 'SESSION_INVALID' });
+      let untrusted;
+      try { untrusted = JSON.parse(Buffer.from(header, 'base64url').toString('utf8')); } catch { return send(403, { error: 'SESSION_INVALID' }); }
+      if (!accountId(untrusted?.vault_id) || !/^[a-zA-Z0-9_-]{1,64}$/.test(untrusted?.session_id ?? '')) return send(403, { error: 'SESSION_INVALID' });
+      const client = new NearAgentPayClient({ rpcUrl, vaultId: untrusted.vault_id });
+      const authenticate = async () => {
+        const [account, vault, stream] = await Promise.all([
+          client.provider.viewAccount({ accountId: untrusted.vault_id, blockQuery: { finality: 'final' } }), client.getVault(), client.getStream(untrusted.session_id),
+        ]);
+        const now = Math.floor(Date.now() / 1000);
+        if (account.code_hash !== codeHash || vault.token_id !== token || Math.abs(now - Number(vault.now)) > 30 || !quoteMatchesStream(b, vault, stream, untrusted.vault_id)) throw new Error('UNTRUSTED_PAYMENT');
+        return { session: verifySession(header, { config: { serviceUrl: b.origin, vaultId: untrusted.vault_id }, vault, stream, now: Math.max(now, Number(vault.now)) }), stream };
+      };
+      let access;
+      try { access = await authenticate(); } catch { return send(403, { error: 'STREAM_ACCESS_DENIED' }); }
+      const after = Number(path.searchParams.get('after') ?? 0);
+      if (!Number.isSafeInteger(after) || after < 0) return send(400, { error: 'INVALID_CURSOR' });
+      const pointers = (state.journal ?? []).filter(p => p.sequence > after).slice(0, 8);
+      const entries = [];
+      for (const pointer of pointers) {
+        const entry = await loadEntry(agent, key, pointer);
+        if (entry.body.at >= Number(access.stream.started_at) * 1000) entries.push(entry);
+      }
+      // A close may finalize while NOVA is retrieving the ciphertext. Check again before releasing entries.
+      if (pointers.length) try { await authenticate(); } catch { return send(403, { error: 'STREAM_ACCESS_DENIED' }); }
+      if (!(await readAgentState(agent)).publish?.enabled) return send(503, { error: 'PUBLICATION_STOPPED' });
+      const sub = { vaultId: untrusted.vault_id, sessionId: access.session.session_id, recipient: b.recipient, rpcUrl };
+      const file = join(agent.path, 'subscribers', `${fingerprint(`${sub.vaultId}:${sub.sessionId}`)}.json`);
+      if (!await readOptional(file)) {
+        await mkdir(join(agent.path, 'subscribers'), { recursive: true, mode: 0o700 });
+        await atomicWrite(file, JSON.stringify(sub));
+      }
+      const cursor = pointers.at(-1)?.sequence ?? after;
+      return send(200, signed(key, 'agentpay.page.v1', { sessionId: access.session.session_id, observedAt: Date.now(), after, cursor, entries }));
+    } catch { return send(503, { error: 'FEED_TEMPORARILY_UNAVAILABLE' }); }
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port ?? publish.port, '127.0.0.1', resolve); });
+  return { port: server.address().port, close: () => new Promise(resolve => { server.close(resolve); server.closeAllConnections(); }) };
+}
+
+export function verifyPage(envelope, listing, sessionId, after, freshness) {
+  const page = envelope?.body;
+  if (!page || page.sessionId !== sessionId || page.after !== after || !Number.isSafeInteger(page.cursor) || page.cursor < after || page.cursor > after + 8 ||
+      !Number.isSafeInteger(page.observedAt) || page.observedAt > Date.now() + 5000 || Date.now() - page.observedAt > freshness * 1000 ||
+      !Array.isArray(page.entries) || page.entries.length > 8 || !verified(envelope, listing.publicKey, 'agentpay.page.v1')) throw new Error('FEED_STALE_OR_INVALID');
+  let previous = after;
+  const actions = page.entries.map(entry => {
+    const action = verifyAction(entry, listing);
+    if (action.sequence <= previous || action.sequence > page.cursor) throw new Error('INVALID_ACTION_ORDER');
+    previous = action.sequence;
+    return action;
+  });
+  return { actions, cursor: page.cursor };
+}

package/src/copy-intents.mjs

@@ -0,0 +1,83 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { rawAmount } from './copy-activity.mjs';
+
+const api = 'https://api.agentsonintents.com';
+const final = new Set(['SUCCESS', 'FAILED', 'REFUNDED']);
+const pending = new Set(['QUEUED', 'PROCESSING']);
+
+export function credential(name) {
+  const value = process.env[name];
+  if (!value || value.length > 8192 || /[^\x21-\x7e]/.test(value)) throw new Error(`Set ${name} in the agent process environment.`);
+  return value;
+}
+
+export function intentsConfig(flags) {
+  if (!/^[a-z0-9_-]{1,128}$/i.test(flags['intents-agent-id'] ?? '')) throw new Error('Provide --intents-agent-id for an owner-provisioned Agent Connect account.');
+  const result = { id: flags['intents-agent-id'], keyEnv: flags['intents-key-env'] ?? 'NEAR_INTENTS_AGENT_API_KEY', grantEnv: flags['intents-grant-env'] ?? 'NEAR_INTENTS_GRANT_TOKEN', live: flags.live === true, confidential: flags.confidential === true };
+  if (![result.keyEnv, result.grantEnv].every(value => /^[A-Z][A-Z0-9_]{0,127}$/.test(value))) throw new Error('Credential options accept environment variable names.');
+  return result;
+}
+
+export function intentsAdapter(config, fetchImpl = fetch) {
+  const basePath = `/v1/agents/${encodeURIComponent(config.id)}`;
+  async function request(path, { body, key, grant = false } = {}) {
+    const headers = { 'X-API-Key': credential(config.keyEnv) };
+    if (grant) headers['X-Grant-Token'] = credential(config.grantEnv);
+    if (key) headers['Idempotency-Key'] = key;
+    if (body) headers['Content-Type'] = 'application/json';
+    const response = await fetchImpl(`${api}${path}`, { headers, redirect: 'error', signal: AbortSignal.timeout(15000), ...(body ? { method: 'POST', body: JSON.stringify(body) } : {}) });
+    const data = await response.json();
+    if (!response.ok) {
+      const code = data.code ?? data.errors?.[0]?.code;
+      throw new Error(`INTENTS_HTTP_${response.status}${/^[a-z0-9_]+$/.test(code ?? '') ? ` ${code}` : ''}`);
+    }
+    return data;
+  }
+
+  return {
+    async quote(order) {
+      const result = await request(`${basePath}/swap`, { key: randomUUID(), body: { ...order, confidential: config.confidential, dry: true } });
+      if (result.dry !== true || result.type !== 'swap') throw new Error('INTENTS_EXPECTED_DRY_QUOTE');
+      const quote = result.quote?.quote ?? result.quote;
+      const amountOut = quote?.amountOut ?? quote?.amount_out;
+      const amountIn = quote?.amountIn ?? quote?.amount_in;
+      if (!rawAmount(amountOut) || !rawAmount(amountIn)) throw new Error('INTENTS_QUOTE_AMOUNTS_MISSING');
+      return { amountIn, amountOut, amountInUsd: result.spend?.amount_usd ?? null, warnings: (result.warnings ?? []).map(item => item.code), ownerApproval: result.owner_approval === true };
+    },
+    async execute(order, key) {
+      if (!config.live) throw new Error('INTENTS_LIVE_DISABLED');
+      return request(`${basePath}/swap`, { key, grant: true, body: { ...order, confidential: config.confidential } });
+    },
+    async status(correlationId) {
+      if (typeof correlationId !== 'string' || !correlationId.length || correlationId.length > 128) throw new Error('INTENTS_CORRELATION_MISSING');
+      return request(`/v1/status?${new URLSearchParams({ correlation_id: correlationId })}`);
+    },
+    async settle(result, order, { attempts = 8 } = {}) {
+      const correlationId = result.correlation_id;
+      const validate = value => {
+        if (!/^[a-z0-9_-]{1,128}$/i.test(correlationId ?? '') || value.correlation_id !== correlationId ||
+            value.agent_id !== config.id || value.type !== 'swap') throw new Error('INTENTS_STATUS_IDENTITY_MISMATCH');
+      };
+      validate(result);
+      for (let i = 0; i < attempts && pending.has(result.status); i++) {
+        await delay(1500);
+        result = await this.status(correlationId);
+        validate(result);
+      }
+      if (result.status === 'SUCCESS') {
+        const details = result.details, requested = details?.request, at = Date.parse(result.updated_at);
+        if (!requested || !['origin_asset', 'destination_asset', 'amount'].every(key => requested[key] === order[key]) ||
+            !rawAmount(details.amount_out) || BigInt(details.amount_out) < BigInt(order.min_amount_out) ||
+            !Number.isSafeInteger(at) || at > Date.now() + 5000) throw new Error('INTENTS_SETTLEMENT_MISMATCH');
+      }
+      return { status: result.status, final: final.has(result.status), correlationId, details: result.details, updatedAt: Date.parse(result.updated_at) };
+    },
+  };
+}
+
+export function minimumOutput(action, order, policy) {
+  const numerator = BigInt(action.amountOut) * BigInt(order.amount) * BigInt(10000 - policy.slippageBps);
+  const denominator = BigInt(action.amountIn) * 10000n;
+  return ((numerator + denominator - 1n) / denominator).toString();
+}