@ola-893/agentpay-cli 0.2.0 → 0.4.0

package/src/copy-runtime.mjs

@@ -0,0 +1,369 @@
+import { open, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { assessQuote } from '@ola-893/agentpay-core';
+import { gatewayFor } from './config.mjs';
+import { settings, setService } from './settings.mjs';
+import { agentSetupState, readAgentState, withAgentState } from './agents.mjs';
+import { checkQuote, operationKey, proposedOrder, rawAmount, spot } from './copy-activity.mjs';
+import { credential, intentsAdapter, minimumOutput } from './copy-intents.mjs';
+import { appendFill, checkListingQuote, fetchFeed, feedPath, getListing, healthPath, originOf, quotePath, readJsonResponse, serveFeed, verifyPage } from './copy-feed.mjs';
+
+const addHistory = (state, item) => {
+  state.history.push({ at: new Date().toISOString(), ...item });
+  if (state.history.length > 500) state.history.shift();
+};
+
+function current(state) {
+  if (!state.follow) throw new Error('No copy subscription. Run agentpay copy start first.');
+  return state.follow;
+}
+
+async function gateway(agent, work) {
+  const client = await gatewayFor(agent.path);
+  try { return await work(client); }
+  finally { await client.dispose(); }
+}
+
+async function offer(agent, state, id, url) {
+  if (id === agent.id) throw new Error('Choose another agent to copy.');
+  const source = url ?? state.directory[id];
+  if (!source) throw new Error('Supply --url with the publisher’s feed origin on first lookup.');
+  return getListing(id, originOf(source));
+}
+
+async function readQuote(listing, config) {
+  const quote = await fetchFeed(listing.origin, `${quotePath(config.vaultId)}?tier=basic`);
+  return { quote, hash: checkListingQuote(listing, config.vaultId, config.tokenId, quote) };
+}
+
+export async function previewCopy(agent, id, url) {
+  const state = await readAgentState(agent);
+  const listing = await offer(agent, state, id, url);
+  const maxEscrowRawUSDC = (BigInt(listing.rate) * BigInt(listing.duration)).toString();
+  let admission = { decision: 'DENY', reason: 'VAULT_SETUP_REQUIRED' };
+  if ((await agentSetupState(agent)).configured) {
+    const { config } = await settings(agent.path);
+    admission = await gateway(agent, async client => {
+      const [{ vault }, { quote }, health] = await Promise.all([client.status(), readQuote(listing, config), fetchFeed(listing.origin, healthPath)]);
+      return assessQuote({ vault: { ...vault, vault_id: config.vaultId }, quote, health });
+    });
+  }
+  return { listing, maxEscrowRawUSDC, admission, signedTransactions: 0, next: 'agentpay copy start ' + id + ' --url ' + listing.origin };
+}
+
+async function openCopy(agent, state, save, listing, mode) {
+  const { profile, config } = await settings(agent.path);
+  if (!profile.paymentsEnabled) throw new Error('PAYMENTS_DISABLED: run agentpay payments --enable after checking the subscription limits.');
+  const { hash, quote } = await readQuote(listing, config);
+  if (!config.runtimePolicy.reuseStream) throw new Error('Enable reuse with agentpay config set --reuse true.');
+  await setService(agent.path, { url: listing.origin, recipient: listing.recipient, healthPath, quotePath: quotePath(config.vaultId, quote.expires_at), requestPath: feedPath, tiers: ['basic'] });
+  return gateway(agent, async client => {
+    const checked = await client.check({ tier: 'basic', expectedQuoteHash: hash });
+    if (checked.decision !== 'OPEN') throw new Error(checked.reason ?? 'COPY_OPEN_DENIED');
+    state.directory[listing.id] = listing.origin;
+    state.follow = { listing, status: 'opening', mode, cursor: state.cursors?.[listing.id] ?? 0, failures: 0, startedAt: Date.now() };
+    await save();
+    const opened = await client.open({ approvalId: checked.approvalId });
+    Object.assign(state.follow, { status: 'active', sessionId: opened.sessionId, openHash: opened.receipt.hash });
+    return { ...state.follow, payment: opened.receipt, explorerUrl: `https://testnet.nearblocks.io/txns/${opened.receipt.hash}` };
+  });
+}
+
+export async function startCopy(agent, { id, url, activity, resume = false }) {
+  return withAgentState(agent, async (state, save) => {
+    const follow = state.follow;
+    if (resume ? follow?.status !== 'paused' : ['active', 'opening', 'closing'].includes(follow?.status)) throw new Error('Resolve or close the current subscription before opening another.');
+    if (activity && activity !== spot) throw new Error('Only spot-trading can be copied in this release.');
+    const listing = await offer(agent, state, resume ? follow.listing.id : id, resume ? follow.listing.origin : url);
+    if (resume && ['recipient', 'rate', 'duration'].some(field => follow.listing[field] !== listing[field])) throw new Error('Offer changed. Preview it and start a new subscription to accept new terms.');
+    return openCopy(agent, state, save, listing, 'observe');
+  });
+}
+
+async function closeCopy(agent, state, save, status, reason, client) {
+  const follow = current(state);
+  if (!['active', 'opening', 'closing'].includes(follow.status)) {
+    follow.status = status;
+    return follow;
+  }
+  follow.status = 'closing';
+  follow.closeTarget = status;
+  follow.reason = reason;
+  await save();
+  const close = async activeClient => {
+    const context = await activeClient.status();
+    if (context.vault.active_session && (!context.reusable || (follow.sessionId && context.vault.active_session !== follow.sessionId))) throw new Error('ACTIVE_SESSION_RECOVERY_REQUIRED');
+    return context.vault.active_session ? activeClient.close({ sessionId: context.vault.active_session }) : { alreadyClosed: true };
+  };
+  const result = client ? await close(client) : await gateway(agent, close);
+  follow.status = status;
+  follow.closeHash = result.receipt?.hash ?? null;
+  for (const item of Object.values(state.pending ?? {})) {
+    if (item.status === 'pending' || item.status === 'approved') item.status = 'cancelled';
+  }
+  addHistory(state, { type: 'subscription', status, reason, sessionId: follow.sessionId, transactionHash: follow.closeHash });
+  return { ...follow, ...(result.receipt ? { receipt: result.receipt, explorerUrl: `https://testnet.nearblocks.io/txns/${result.receipt.hash}` } : {}) };
+}
+
+export async function stopCopy(agent, status, reason = 'OPERATOR_REQUEST') {
+  return withAgentState(agent, (state, save) => closeCopy(agent, state, save, status, reason));
+}
+
+export async function changeMode(agent, mode) {
+  if (!['observe', 'approve', 'auto'].includes(mode)) throw new Error('Choose observe, approve or auto.');
+  return withAgentState(agent, state => {
+    const follow = current(state);
+    if (follow.status !== 'active') throw new Error('Subscription is not active.');
+    if (mode !== 'observe' && (!state.tasks[spot]?.live || !state.executionPolicy)) throw new Error('Enable the live Intents adapter and set an execution policy first.');
+    if (mode !== 'approve') for (const item of Object.values(state.pending ?? {})) {
+      if (item.status === 'pending' || item.status === 'approved') item.status = 'cancelled';
+    }
+    follow.mode = mode;
+    return { mode, sessionId: follow.sessionId };
+  });
+}
+
+export async function decideAction(agent, id, decision) {
+  return withAgentState(agent, state => {
+    const follow = current(state);
+    const item = state.pending?.[id];
+    if (follow.status !== 'active' || !item || item.sessionId !== follow.sessionId || item.status !== 'pending') throw new Error('Action is not pending for the active subscription.');
+    if (decision === 'approved' && follow.mode !== 'approve') throw new Error('Use copy mode approve before approving actions.');
+    if (Date.now() >= item.action.expiresAt) throw new Error('ACTION_EXPIRED');
+    item.status = decision;
+    addHistory(state, { type: 'decision', actionId: id, status: decision });
+    return { actionId: id, status: decision };
+  });
+}
+
+async function executeSwap(agent, state, save, adapter, order, record) {
+  if (state.tradePending) throw new Error('TRADE_RECONCILIATION_REQUIRED');
+  credential(state.tasks[spot].grantEnv);
+  const key = operationKey(agent.id, record.id);
+  state.tradePending = { ...record, order, key, createdAt: Date.now() };
+  await save();
+  const first = await adapter.execute(order, key);
+  if (first.correlation_id) {
+    state.tradePending.correlationId = first.correlation_id;
+    await save();
+  }
+  return finishSwap(agent, state, save, await adapter.settle(first, order));
+}
+
+async function finishSwap(agent, state, save, result) {
+  const trade = state.tradePending;
+  if (!result.final) return { status: result.status, correlationId: result.correlationId, reconciliationRequired: true };
+  if (result.status === 'SUCCESS') {
+    const fill = result.details;
+    if (!rawAmount(fill?.amount_out)) throw new Error('SETTLED_OUTPUT_MISSING: reconcile the recorded trade before another execution.');
+    if (!trade.settled) {
+      const at = result.updatedAt;
+      trade.settled = { id: trade.id, at, expiresAt: at + 60000, from: trade.order.origin_asset, to: trade.order.destination_asset, amountIn: trade.order.amount, amountOut: fill.amount_out,
+        settlementRef: fill.tx_hash ?? fill.destination_tx_hash ?? result.correlationId, ...(trade.source ? { copiedFrom: trade.source } : {}) };
+      await save();
+    }
+    const publication = await appendFill(agent, state, trade.settled);
+    addHistory(state, { type: 'trade', status: result.status, actionId: trade.id, correlationId: result.correlationId, publication });
+  } else addHistory(state, { type: 'trade', status: result.status, actionId: trade.id, correlationId: result.correlationId });
+  if (state.pending?.[trade.id]) state.pending[trade.id].status = result.status.toLowerCase();
+  state.tradePending = null;
+  return { status: result.status, correlationId: result.correlationId, amountOut: result.details?.amount_out ?? null, transactionHash: result.details?.tx_hash ?? null };
+}
+
+export async function runSpotTask(agent, order, execute) {
+  return withAgentState(agent, async (state, save) => {
+    const config = state.tasks[spot];
+    if (!config) throw new Error('Enable spot-trading with an Agent Connect account first.');
+    const adapter = intentsAdapter(config);
+    const quote = await adapter.quote(order);
+    if (!execute) return { mode: 'preview', quote, signedTransactions: 0 };
+    if (!config.live) throw new Error('INTENTS_LIVE_DISABLED');
+    const p = state.executionPolicy;
+    if (!p || order.origin_asset !== p.inputAsset || !p.assets.includes(order.destination_asset) || BigInt(order.amount) > BigInt(p.maxInput)) throw new Error('ORDER_OUTSIDE_EXECUTION_POLICY');
+    const refusal = checkQuote(quote, order, { amountOut: quote.amountOut, amountIn: quote.amountIn }, p);
+    if (refusal || quote.warnings.length) throw new Error(refusal ?? 'INTENTS_QUOTE_WARNING');
+    const min = minimumOutput(quote, order, p);
+    return executeSwap(agent, state, save, adapter, { ...order, min_amount_out: min }, { id: operationKey(agent.id, randomUUID()) });
+  });
+}
+
+export async function reconcileCopy(agent) {
+  return withAgentState(agent, async (state, save) => {
+    const report = {};
+    if (state.tradePending) {
+      const trade = state.tradePending;
+      if (!trade.correlationId) report.trade = { resolved: false, reason: 'CORRELATION_ID_UNKNOWN', idempotencyKey: trade.key };
+      else {
+        const adapter = intentsAdapter(state.tasks[spot]);
+        report.trade = await finishSwap(agent, state, save, await adapter.settle(await adapter.status(trade.correlationId), trade.order, { attempts: 0 }));
+      }
+    }
+    if (['opening', 'closing'].includes(state.follow?.status)) {
+      await gateway(agent, async client => {
+        report.payment = await client.reconcile();
+        if (!report.payment.resolved) return;
+        const { vault, reusable } = await client.status();
+        if (state.follow.status === 'opening' && vault.active_session && reusable) Object.assign(state.follow, { status: 'active', sessionId: vault.active_session });
+        else if (!vault.active_session) state.follow.status = state.follow.closeTarget ?? 'paused';
+        else report.payment = { resolved: false, reason: 'ACTIVE_SESSION_RECOVERY_REQUIRED' };
+      });
+    }
+    return { resolved: !state.tradePending && !['opening', 'closing'].includes(state.follow?.status), ...report };
+  });
+}
+
+async function observeAction(agent, state, save, action, emit, client, approved = false) {
+  const follow = current(state), policy = state.executionPolicy;
+  const result = proposedOrder(action, policy);
+  const record = data => {
+    const item = { type: 'action', actionId: action.id, sequence: action.sequence, publisher: action.publisher, ...data };
+    addHistory(state, item);
+    emit(item);
+  };
+  if (result.reason) {
+    if (approved) state.pending[action.id].status = 'skipped';
+    return record({ status: 'skipped', reason: result.reason, action });
+  }
+  if (action.copiedFrom) {
+    if (approved) state.pending[action.id].status = 'skipped';
+    return record({ status: 'skipped', reason: 'COPIED_ACTION', action });
+  }
+  const config = state.tasks[spot];
+  if (!config) return record({ status: 'observed', reason: 'INTENTS_ADAPTER_REQUIRED', order: result.order, action });
+  const adapter = intentsAdapter(config);
+  const quote = await adapter.quote(result.order);
+  const reason = checkQuote(quote, result.order, action, policy) || (quote.warnings.length ? 'INTENTS_QUOTE_WARNING' : null);
+  if (reason) {
+    if (approved) state.pending[action.id].status = 'skipped';
+    return record({ status: 'skipped', reason, quote, action });
+  }
+  if (follow.mode === 'observe') return record({ status: 'observed', quote, order: result.order, action });
+  if (follow.mode === 'approve' && !approved) {
+    (state.pending ??= {})[action.id] = { status: 'pending', action, quote, sessionId: follow.sessionId };
+    return record({ status: 'pending', quote, order: result.order });
+  }
+  if (!config.live || state.tradePending) return record({ status: 'skipped', reason: state.tradePending ? 'TRADE_RECONCILIATION_REQUIRED' : 'INTENTS_LIVE_DISABLED' });
+  const context = await client.status();
+  if (context.vault.active_session !== follow.sessionId || !context.reusable || !Object.keys(await client.sessionHeaders()).length || proposedOrder(action, policy).reason) {
+    if (approved) state.pending[action.id].status = 'skipped';
+    return record({ status: 'skipped', reason: 'COPY_AUTHORITY_EXPIRED' });
+  }
+  const order = { ...result.order, min_amount_out: minimumOutput(action, result.order, policy) };
+  if (approved) state.pending[action.id].status = 'executing';
+  emit({ type: 'execution', actionId: action.id, ...await executeSwap(agent, state, save, adapter, order, { id: action.id, source: follow.listing.id }) });
+}
+
+export async function copyTick(agent, emit = () => {}) {
+  return withAgentState(agent, async (state, save) => {
+    if (state.follow?.status !== 'active') return;
+    const follow = state.follow;
+    const guard = state.feedGuard ?? { staleSeconds: 45, failures: 3 };
+    return gateway(agent, async client => {
+      const { vault } = await client.status();
+      if (vault.active_session !== follow.sessionId) return closeCopy(agent, state, save, 'paused', 'STREAM_ENDED', client);
+      const checked = await client.check({ tier: 'basic' });
+      if (checked.decision === 'CLOSE') return closeCopy(agent, state, save, 'paused', checked.reason, client);
+      if (checked.decision !== 'CONTINUE') throw new Error(checked.reason ?? 'COPY_PAYMENT_UNAVAILABLE');
+      const headers = await client.sessionHeaders();
+      if (!Object.keys(headers).length) return closeCopy(agent, state, save, 'paused', 'LEASE_EXPIRED', client);
+      let page;
+      try {
+        const response = await fetch(`${follow.listing.origin}${feedPath}?after=${follow.cursor}`, { headers, redirect: 'error', signal: AbortSignal.timeout(10000) }).catch(async () => {
+          const transport = await client.observeResult({ kind: 'transport' });
+          if (transport.decision === 'CLOSE') return transport;
+          throw new Error('FEED_TRANSPORT_ERROR');
+        });
+        if (response.decision === 'CLOSE') return closeCopy(agent, state, save, 'paused', response.reason, client);
+        const observed = await client.observeResult({ kind: 'response', status: response.status });
+        if (observed.decision === 'CLOSE') return closeCopy(agent, state, save, 'paused', observed.reason, client);
+        if (!response.ok) throw new Error(`FEED_HTTP_${response.status}`);
+        page = verifyPage(await readJsonResponse(response), follow.listing, follow.sessionId, follow.cursor, guard.staleSeconds);
+      } catch (error) {
+        follow.failures++;
+        const stale = Date.now() - (follow.lastFeedAt ?? follow.startedAt) >= guard.staleSeconds * 1000;
+        if (stale || follow.failures >= guard.failures) return closeCopy(agent, state, save, 'paused', stale ? 'FEED_STALE' : 'FEED_FAILURE_LIMIT', client);
+        emit({ type: 'feed-error', reason: error.message, failures: follow.failures });
+        return;
+      }
+      follow.lastFeedAt = Date.now();
+      follow.failures = 0;
+      for (const action of page.actions) {
+        // Persist the cursor before any external execution. A lost reply cannot replay the order.
+        follow.cursor = action.sequence;
+        (state.cursors ??= {})[follow.listing.id] = action.sequence;
+        const seen = state.seen ??= {};
+        if (seen[action.id]) continue;
+        seen[action.id] = true;
+        await save();
+        try { await observeAction(agent, state, save, action, emit, client); }
+        catch (error) { addHistory(state, { type: 'action', actionId: action.id, status: 'error', reason: error.message }); emit({ type: 'action-error', actionId: action.id, reason: error.message }); }
+      }
+      follow.cursor = page.cursor;
+      (state.cursors ??= {})[follow.listing.id] = page.cursor;
+      if (follow.mode === 'approve') for (const item of Object.values(state.pending ?? {})) {
+        if (item.status === 'approved' && item.sessionId === follow.sessionId) await observeAction(agent, state, save, item.action, emit, client, true);
+      }
+      return { cursor: page.cursor, received: page.actions.length };
+    });
+  });
+}
+
+export async function runCopyAgent(agent, { once, rpc, emit }) {
+  if (once) {
+    const events = [];
+    const result = (await copyTick(agent, item => events.push(item))) ?? { received: 0, status: 'idle' };
+    return { ...result, ...(events.length ? { events } : {}) };
+  }
+  const lockPath = join(agent.path, 'runner.lock');
+  const lock = await open(lockPath, 'wx', 0o600).catch(error => {
+    if (error.code === 'EEXIST') throw new Error(`AGENT_RUNNER_BUSY: inspect ${lockPath} for its PID.`);
+    throw error;
+  });
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  let server, listening;
+  try {
+    await lock.writeFile(`${process.pid}\n`);
+    emit({ running: true, agentId: agent.id });
+    do {
+      try {
+        const state = await readAgentState(agent);
+        const target = state.publish?.enabled ? `${state.publish.origin}|${state.publish.port}` : null;
+        if (target !== listening) {
+          await server?.close();
+          server = undefined;
+          listening = null;
+          if (target) {
+            server = await serveFeed(agent, { rpcUrl: rpc });
+            listening = target;
+            emit({ publisher: state.publish.origin, port: server.port });
+          }
+        }
+      } catch (error) { emit({ type: 'publisher-error', reason: error.message }); }
+      try {
+        const result = await copyTick(agent, emit);
+        if (result?.status === 'paused') emit({ type: 'subscription', ...result });
+      } catch (error) {
+        emit({ type: 'runner-error', reason: error.message });
+      }
+      const state = await readAgentState(agent);
+      const seconds = state.follow?.status === 'active' ? (await settings(agent.path)).config.runtimePolicy.healthPollSeconds : 2;
+      await sleep(seconds * 1000, undefined, { signal: controller.signal }).catch(error => { if (error.name !== 'AbortError') throw error; });
+    } while (!controller.signal.aborted);
+  } finally {
+    process.removeListener('SIGINT', stop);
+    process.removeListener('SIGTERM', stop);
+    try {
+      await server?.close();
+      if ((await readAgentState(agent)).follow?.status === 'active') {
+        const { config } = await settings(agent.path);
+        if (config.runtimePolicy.closeOnExit) emit(await stopCopy(agent, 'paused', 'RUNNER_EXIT'));
+      }
+    } catch (error) { emit({ type: 'closure-unconfirmed', reason: error.message }); process.exitCode = 1; }
+    finally { await lock.close(); await unlink(lockPath); }
+  }
+}

package/src/inference.mjs

@@ -0,0 +1,69 @@
+export const NEAR_AI_BASE_URL = 'https://cloud-api.near.ai/v1';
+export const NEAR_AI_CATALOG_URL = `${NEAR_AI_BASE_URL}/model/list`;
+
+export function inferenceConfig(input) {
+  if (!input || typeof input.model !== 'string' || !input.model.trim() || input.model.length > 256) throw new Error('Provide --model.');
+  const provider = input.provider ?? 'openai-compatible';
+  if (!['openai-compatible', 'near-ai'].includes(provider)) throw new Error('Choose --provider near-ai or openai-compatible.');
+  const url = new URL(input.baseUrl ?? (provider === 'near-ai' ? NEAR_AI_BASE_URL : undefined));
+  if (url.username || url.password || url.search || url.hash || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)))) throw new Error('Inference URL must use HTTPS or loopback without embedded credentials.');
+  const baseUrl = url.href.replace(/\/$/, '');
+  if (provider === 'near-ai' && baseUrl !== NEAR_AI_BASE_URL) throw new Error('The near-ai provider uses https://cloud-api.near.ai/v1. Use openai-compatible for a custom endpoint.');
+  const apiKeyEnv = input.apiKeyEnv ?? (provider === 'near-ai' ? 'NEAR_AI_API_KEY' : undefined);
+  if (apiKeyEnv !== undefined && !/^[A-Z][A-Z0-9_]{0,127}$/.test(apiKeyEnv)) throw new Error('Provide an environment variable NAME via --api-key-env, never the key itself.');
+  const maxSteps = input.maxSteps ?? 12;
+  const timeoutSeconds = input.timeoutSeconds ?? 120;
+  if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 10 || timeoutSeconds > 600) throw new Error('timeoutSeconds must be between 10 and 600.');
+  if (!Number.isInteger(maxSteps) || maxSteps < 1 || maxSteps > 100) throw new Error('maxSteps must be between 1 and 100.');
+  if (input.thinking !== undefined && typeof input.thinking !== 'boolean') throw new Error('thinking must be true or false.');
+  if (provider === 'near-ai' && input.thinking !== undefined && /^openai\/gpt-oss-/i.test(input.model)) throw new Error('GPT-OSS reasoning is always on; omit --thinking and use --reasoning-effort.');
+  if (input.reasoningEffort !== undefined && !['low', 'medium', 'high'].includes(input.reasoningEffort)) throw new Error('reasoningEffort must be low, medium or high.');
+  const maxOutputTokens = input.maxOutputTokens ?? (provider === 'near-ai' ? 2048 : undefined);
+  if (maxOutputTokens !== undefined && (!Number.isInteger(maxOutputTokens) || maxOutputTokens < 1 || maxOutputTokens > 131072)) throw new Error('maxOutputTokens must be between 1 and 131072.');
+  return { provider, protocol: 'openai-chat', baseUrl, model: input.model, ...(apiKeyEnv ? { apiKeyEnv } : {}),
+    ...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
+    ...(input.reasoningEffort !== undefined ? { reasoningEffort: input.reasoningEffort } : {}),
+    ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}), timeoutSeconds, maxSteps };
+}
+
+export function completionBody(config, messages, tools) {
+  const thinking = config.thinking === undefined ? {} : config.provider === 'near-ai'
+    ? { chat_template_kwargs: { [/^moonshotai\/kimi-/i.test(config.model) ? 'thinking' : 'enable_thinking']: config.thinking } }
+    : { enable_thinking: config.thinking };
+  return { model: config.model, messages, tools, tool_choice: 'auto', stream: false, ...thinking,
+    ...(config.reasoningEffort !== undefined ? { reasoning_effort: config.reasoningEffort } : {}),
+    ...(config.maxOutputTokens !== undefined ? { max_tokens: config.maxOutputTokens } : {}) };
+}
+
+export async function listInferenceModels({ provider = 'near-ai', fetchImpl = fetch } = {}) {
+  if (provider !== 'near-ai') throw new Error('Model discovery currently supports --provider near-ai.');
+  const models = [], seen = new Set();
+  let offset = 0, total;
+  do {
+    const url = new URL(NEAR_AI_CATALOG_URL);
+    if (offset) { url.searchParams.set('offset', String(offset)); url.searchParams.set('limit', '100'); }
+    // The public catalog does not need a key. Never forward a configured model key here.
+    const response = await fetchImpl(url.href, { redirect: 'error', signal: AbortSignal.timeout(20000) });
+    if (!response.ok) throw new Error(`NEAR_AI_CATALOG_HTTP_${response.status}`);
+    const page = await response.json();
+    if (!Array.isArray(page.models) || !Number.isSafeInteger(page.total) || page.total < 0 || page.total > 10000 || page.offset !== offset || (total !== undefined && page.total !== total)) throw new Error('INVALID_NEAR_AI_CATALOG');
+    total = page.total;
+    if ((!page.models.length && offset < total) || offset + page.models.length > total) throw new Error('INVALID_NEAR_AI_CATALOG');
+    for (const entry of page.models) {
+      if (typeof entry.modelId !== 'string' || !entry.modelId || seen.has(entry.modelId)) throw new Error('INVALID_NEAR_AI_CATALOG');
+      seen.add(entry.modelId);
+      const m = entry.metadata ?? {};
+      const features = Array.isArray(m.supportedFeatures) ? m.supportedFeatures.filter(s => typeof s === 'string') : [];
+      const textOutput = m.architecture?.outputModalities?.includes('text') === true;
+      models.push({ id: entry.modelId, name: m.modelDisplayName ?? entry.modelId,
+        agentCompatible: features.includes('tools') && textOutput, supportedFeatures: features,
+        providerReportedVerifiable: m.verifiable === true, attestationSupported: m.attestationSupported === true,
+        providerType: typeof m.providerType === 'string' ? m.providerType : null,
+        maxOutputTokens: Number.isSafeInteger(m.maxOutputLength) ? m.maxOutputLength : null });
+    }
+    offset += page.models.length;
+  } while (offset < total);
+  return { provider: 'near-ai', baseUrl: NEAR_AI_BASE_URL, catalogUrl: NEAR_AI_CATALOG_URL,
+    fetchedAt: new Date().toISOString(), total, models, metadataSource: 'provider public catalog',
+    attestationVerified: false, policySignerLocation: 'local host' };
+}

package/src/install.mjs

@@ -1,5 +1,5 @@
 import { parse, stringify } from 'smol-toml';
-import { relative } from 'node:path';
+import { relative, resolve } from 'node:path';
 import { realpath } from 'node:fs/promises';
 import { atomicWrite, readOptional, safeTarget } from './files.mjs';
 
@@ -16,10 +16,14 @@ function managed(text, start, end, block) {
   return a < 0 ? `${text}${text && !text.endsWith('\n') ? '\n' : ''}\n${start}\n${block}\n${end}\n` : text.slice(0, a) + `${start}\n${block}\n${end}` + text.slice(b + end.length);
 }
 
-export async function installAgent(target, project, binPath, { dryRun = false } = {}) {
+export function mcpServer(project, binPath, { home = process.env.AGENTPAY_HOME, agent } = {}) {
+  return { command: process.execPath, args: [binPath, 'mcp', '--project', project, ...(agent ? ['--agent', agent] : [])], ...(home ? { env: { AGENTPAY_HOME: resolve(home) } } : {}) };
+}
+
+export async function installAgent(target, project, binPath, { dryRun = false, home = process.env.AGENTPAY_HOME, agent } = {}) {
   project = await realpath(project);
   if (!['cursor', 'codex'].includes(target)) throw new Error('Choose cursor or codex.');
-  const server = { command: process.execPath, args: [binPath, 'mcp', '--project', project] };
+  const server = mcpServer(project, binPath, { home, agent });
   const writes = [];
   const stage = async (file, transform) => {
     const path = await safeTarget(project, file);

package/src/repository-analysis.mjs

@@ -0,0 +1,150 @@
+import { opendir, open, realpath } from 'node:fs/promises';
+import { resolve, relative, extname, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import ts from 'typescript';
+
+const excluded = new Set(['.git', '.local', '.agentpay', '.aws', '.ssh', '.codex', '.agents', 'node_modules', 'target', 'dist', 'build', 'coverage', 'vendor', 'artifacts', 'cache']);
+const extensions = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.rs', '.sol', '.py']);
+const rules = [
+  { id: 'dynamic-eval', severity: 'high', pattern: /\beval\s*\(/, title: 'Dynamic evaluation', recommendation: 'Replace eval with a parser or an explicit operation allowlist; check whether external input reaches this call.' },
+  { id: 'tls-verification-disabled', severity: 'high', pattern: /rejectUnauthorized\s*:\s*false|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*['"]?0/, title: 'TLS certificate verification disabled', recommendation: 'Enable certificate verification and configure the required CA instead.' },
+  { id: 'shell-execution', severity: 'medium', pattern: /\b(?:exec|execSync)\s*\(/, title: 'Shell execution needs input review', recommendation: 'Prefer execFile with a fixed executable and separate arguments; inspect any user-controlled command interpolation.' },
+  { id: 'raw-html', severity: 'medium', pattern: /dangerouslySetInnerHTML|\.innerHTML\s*=/, title: 'Raw HTML insertion', recommendation: 'Use text rendering or a maintained sanitizer before inserting untrusted content.' },
+  { id: 'fetch-deadline', severity: 'medium', title: 'Fetch deadline needs review', recommendation: 'No explicit AbortSignal is present at this call. Check whether the Request already carries a deadline; otherwise add AbortSignal.timeout or an owner-controlled cancellation signal so a stalled service cannot hold the operation indefinitely.' },
+  { id: 'wildcard-cors', severity: 'medium', pattern: /['"]access-control-allow-origin['"]\s*[:,]\s*['"]\*['"]/i, title: 'Wildcard cross-origin access', recommendation: 'Check whether this endpoint should expose data to every origin; use an origin allowlist when required.' },
+  { id: 'unfinished-work', severity: 'info', pattern: /\b(?:TODO|FIXME)\b/, title: 'Unfinished work marker', recommendation: 'Review this marker and track required work before release.' },
+];
+const hash = text => createHash('sha256').update(text).digest('hex');
+
+function sourceFindings(text, file) {
+  if (!['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'].includes(extname(file))) return [];
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('.tsx') ? ts.ScriptKind.TSX : file.endsWith('.jsx') ? ts.ScriptKind.JSX : file.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+  const shellNames = new Set(), shellNamespaces = new Set(), found = [];
+  const isChildProcess = value => ts.isStringLiteral(value) && ['child_process', 'node:child_process'].includes(value.text);
+  const propertyName = node => node && (ts.isIdentifier(node) || ts.isStringLiteral(node)) ? node.text : '';
+  function bindings(node) {
+    if (ts.isImportDeclaration(node) && isChildProcess(node.moduleSpecifier)) {
+      const imports = node.importClause;
+      if (imports?.name) shellNamespaces.add(imports.name.text);
+      if (imports?.namedBindings && ts.isNamespaceImport(imports.namedBindings)) shellNamespaces.add(imports.namedBindings.name.text);
+      if (imports?.namedBindings && ts.isNamedImports(imports.namedBindings)) for (const item of imports.namedBindings.elements) if (['exec', 'execSync'].includes((item.propertyName || item.name).text)) shellNames.add(item.name.text);
+    }
+    if (ts.isVariableDeclaration(node) && node.initializer && ts.isCallExpression(node.initializer) && node.initializer.expression.getText(source) === 'require' && node.initializer.arguments[0] && isChildProcess(node.initializer.arguments[0])) {
+      if (ts.isIdentifier(node.name)) shellNamespaces.add(node.name.text);
+      if (ts.isObjectBindingPattern(node.name)) for (const item of node.name.elements) if (['exec', 'execSync'].includes((item.propertyName || item.name).getText(source))) shellNames.add(item.name.getText(source));
+    }
+    ts.forEachChild(node, bindings);
+  }
+  bindings(source);
+  const add = (id, node) => {
+    const rule = rules.find(rule => rule.id === id), line = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+    if (!found.some(item => item.rule === id && item.line === line)) found.push({ id: hash(`${file}:${line}:${id}`).slice(0, 16), rule: id, severity: rule.severity, file, line, title: rule.title, recommendation: rule.recommendation });
+  };
+  function visit(node) {
+    if (ts.isCallExpression(node)) {
+      const expression = node.expression;
+      if (ts.isIdentifier(expression) && expression.text === 'eval') add('dynamic-eval', node);
+      if (ts.isIdentifier(expression) && expression.text === 'fetch' && node.arguments.length && !(ts.isNewExpression(node.arguments[0]) && node.arguments[0].expression.getText(source) === 'Request')) {
+        const options = node.arguments[1];
+        if (!options || (ts.isObjectLiteralExpression(options) && !options.properties.some(property => ts.isSpreadAssignment(property) || propertyName(property.name) === 'signal'))) add('fetch-deadline', node);
+      }
+      if ((ts.isIdentifier(expression) && shellNames.has(expression.text)) || (ts.isPropertyAccessExpression(expression) && shellNamespaces.has(expression.expression.getText(source)) && ['exec', 'execSync'].includes(expression.name.text))) add('shell-execution', node);
+      if (ts.isPropertyAccessExpression(expression) && ['setHeader', 'header', 'set'].includes(expression.name.text) && node.arguments.length >= 2 && ts.isStringLiteral(node.arguments[0]) && node.arguments[0].text.toLowerCase() === 'access-control-allow-origin' && ts.isStringLiteral(node.arguments[1]) && node.arguments[1].text === '*') add('wildcard-cors', node);
+    }
+    if (ts.isPropertyAssignment(node)) {
+      const name = propertyName(node.name);
+      if (name === 'rejectUnauthorized' && node.initializer.kind === ts.SyntaxKind.FalseKeyword) add('tls-verification-disabled', node);
+      if (name.toLowerCase() === 'access-control-allow-origin' && ts.isStringLiteral(node.initializer) && node.initializer.text === '*') add('wildcard-cors', node);
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+      if (ts.isPropertyAccessExpression(node.left) && node.left.name.text === 'innerHTML') add('raw-html', node);
+      if (node.left.getText(source) === 'process.env.NODE_TLS_REJECT_UNAUTHORIZED' && (ts.isStringLiteral(node.right) && node.right.text === '0')) add('tls-verification-disabled', node);
+    }
+    if (ts.isJsxAttribute(node) && propertyName(node.name) === 'dangerouslySetInnerHTML') add('raw-html', node);
+    ts.forEachChild(node, visit);
+  }
+  visit(source);
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, text);
+  for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) if ([ts.SyntaxKind.SingleLineCommentTrivia, ts.SyntaxKind.MultiLineCommentTrivia].includes(token) && /\b(?:TODO|FIXME)\b/.test(scanner.getTokenText())) {
+    const line = source.getLineAndCharacterOfPosition(scanner.getTokenPos()).line + 1, rule = rules.find(r => r.id === 'unfinished-work');
+    found.push({ id: hash(`${file}:${line}:${rule.id}`).slice(0, 16), rule: rule.id, severity: rule.severity, file, line, title: rule.title, recommendation: rule.recommendation });
+  }
+  return found.sort((a, b) => a.line - b.line);
+}
+
+// Read only operator-selected regular files. Never execute repository code or follow symlinks.
+export async function analyzeRepository(repository, { maxFiles = 500, maxBytes = 3000000, maxFileBytes = 200000, maxEntries = 10000 } = {}) {
+  const root = await realpath(resolve(repository));
+  const files = [], findings = [], dependencies = [];
+  const languages = {};
+  let bytes = 0, lines = 0, skipped = 0, entriesVisited = 0, limited = false;
+  async function walk(directory) {
+    const entries = [];
+    for await (const entry of await opendir(directory)) {
+      if (++entriesVisited > maxEntries) { limited = true; break; }
+      entries.push(entry);
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name.startsWith('.') || excluded.has(entry.name)) continue;
+      const path = resolve(directory, entry.name);
+      const name = relative(root, path).split(sep).join('/');
+      if (entry.isDirectory()) { if (!limited) await walk(path); continue; }
+      if (!entry.isFile() || (!extensions.has(extname(entry.name)) && entry.name !== 'package.json')) continue;
+      if (files.length >= maxFiles || bytes >= maxBytes) { limited = true; continue; }
+      // O_NOFOLLOW closes the symlink-swap window for the final file; verify canonical ancestry too.
+      const canonical = await realpath(path);
+      if (!canonical.startsWith(root + sep)) { skipped++; continue; }
+      const { constants } = await import('node:fs');
+      let handle;
+      try { handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); }
+      catch (error) { if (['ELOOP', 'ENOENT'].includes(error.code)) { skipped++; continue; } throw error; }
+      let text;
+      try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxFileBytes || bytes + info.size > maxBytes) { skipped++; limited ||= bytes + info.size > maxBytes; continue; }
+        const buffer = Buffer.alloc(Math.min(maxFileBytes, maxBytes - bytes) + 1);
+        const read = await handle.read(buffer, 0, buffer.length, 0);
+        if (read.bytesRead > maxFileBytes || bytes + read.bytesRead > maxBytes) { skipped++; limited = true; continue; }
+        text = buffer.subarray(0, read.bytesRead).toString('utf8');
+        bytes += read.bytesRead;
+      } finally { await handle.close(); }
+      if (text.includes('\0')) { skipped++; continue; }
+      const fileLines = text.split(/\r?\n/);
+      files.push({ path: name, lines: fileLines.length, sha256: hash(text) });
+      lines += fileLines.length;
+      const extension = extname(entry.name) || 'json';
+      languages[extension] = (languages[extension] || 0) + 1;
+      if (entry.name === 'package.json') {
+        try {
+          const pkg = JSON.parse(text);
+          for (const [scope, values] of Object.entries({ dependencies: pkg.dependencies, devDependencies: pkg.devDependencies })) {
+            if (!values || typeof values !== 'object' || Array.isArray(values)) continue;
+            // Do not return dependency values: URLs can carry registry credentials.
+            for (const dependency of Object.keys(values)) if (/^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i.test(dependency)) dependencies.push({ manifest: name, name: dependency, scope });
+          }
+        } catch { findings.push({ id: hash(name + ':invalid-manifest').slice(0, 16), rule: 'invalid-manifest', severity: 'medium', file: name, line: 1, title: 'Invalid package manifest', recommendation: 'Correct package.json syntax so dependency tooling can read it.' }); }
+        continue;
+      }
+      findings.push(...sourceFindings(text, name).slice(0, Math.max(0, 300 - findings.length)));
+    }
+  }
+  await walk(root);
+  return { schemaVersion: 1, source: 'AgentPay repository analysis', generatedAt: new Date().toISOString(), fingerprint: hash(JSON.stringify(files)), scope: 'Bounded syntax-based JS/TS heuristics, not a security audit or dataflow analysis. Other source languages contribute inventory only. No source code is executed. Findings need human review; absence of findings does not establish safety.', coverage: { files: files.length, lines, bytes, skipped, limited, maxFiles, maxBytes, maxFileBytes, entriesVisited, maxEntries, maxFindings: 300, findingLimitReached: findings.length === 300 }, languages, files, findings, dependencies };
+}
+
+export function repositoryResponse(snapshot, params) {
+  if ([...params.keys()].some(key => !['view', 'severity', 'file', 'limit', 'offset'].includes(key)) || [...params.keys()].some(key => params.getAll(key).length !== 1)) return { status: 400, body: { error: 'Use view=overview, findings or dependencies; optional severity, exact relative file, limit (1-30) and offset.' } };
+  const limit = Number(params.get('limit') || 5), offset = Number(params.get('offset') || 0);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 30 || !Number.isSafeInteger(offset) || offset < 0 || offset > 10000) return { status: 400, body: { error: 'INVALID_ANALYSIS_PAGINATION' } };
+  const view = params.get('view') || 'overview', severity = params.get('severity'), file = params.get('file');
+  if (!['overview', 'findings', 'dependencies'].includes(view) || (severity && !['high', 'medium', 'info'].includes(severity)) || (file && (file.startsWith('/') || file.includes('\\') || file.split('/').some(part => part === '..' || part.startsWith('.'))))) return { status: 400, body: { error: 'INVALID_ANALYSIS_QUERY' } };
+  const { source, generatedAt, fingerprint, scope, coverage, languages } = snapshot;
+  const body = { source, generatedAt, fingerprint, scope, coverage, view };
+  if (view === 'overview') Object.assign(body, { languages, findingCounts: Object.fromEntries(['high', 'medium', 'info'].map(s => [s, snapshot.findings.filter(f => f.severity === s).length])), dependencyCount: snapshot.dependencies.length });
+  if (view === 'findings') {
+    const matching = snapshot.findings.filter(f => (!severity || f.severity === severity) && (!file || f.file === file));
+    Object.assign(body, { findings: matching.slice(offset, offset + limit), matching: matching.length, offset, limit, truncated: matching.length > offset + limit });
+  }
+  if (view === 'dependencies') Object.assign(body, { dependencies: snapshot.dependencies.slice(0, 80), total: snapshot.dependencies.length, truncated: snapshot.dependencies.length > 80, vulnerabilityDatabaseChecked: false });
+  return { status: 200, body };
+}

package/src/repository-service.mjs

@@ -0,0 +1,17 @@
+import { startProvider } from '@ola-893/agentpay-core/internal-provider';
+import { analyzeRepository, repositoryResponse } from './repository-analysis.mjs';
+
+export async function startRepositoryService(config, { repository, port = 5380, rates, durationSeconds } = {}) {
+  if (!repository) throw new Error('Specify --repository with the operator-selected repository directory.');
+  let cached = await analyzeRepository(repository), refresh;
+  const providerConfig = { ...config };
+  const service = await startProvider(providerConfig, { port, rates, durationSeconds, handleRequest: async params => {
+    if (Date.now() - new Date(cached.generatedAt).getTime() > 5000) {
+      refresh ??= analyzeRepository(repository).then(next => { cached = next; }).finally(() => { refresh = undefined; });
+      await refresh;
+    }
+    return repositoryResponse(cached, params);
+  } });
+  providerConfig.serviceUrl = service.origin;
+  return { ...service, summary: { source: cached.source, fingerprint: cached.fingerprint, coverage: cached.coverage, pricing: { rates: rates || { basic: '10', premium: '200' }, durationSeconds: durationSeconds || 1000, units: 'raw USDC per second; 1000000 raw = 1 USDC', settlement: 'Time-based access, not per-request billing. Accrual continues until closure or lease expiry, including idle time and time before a failure threshold closes the stream.' }, protocol: 'agentpay-near-v1', path: config.service?.requestPath || '/research', views: ['overview', 'findings', 'dependencies'], privateKeysRequired: false } };
+}