@envarai/envarpay 0.1.0-alpha.3 → 0.2.0-alpha.10

package/dist/commerce/upstream.js

@@ -0,0 +1,103 @@
+import { AgentCard, GetTaskRequest, SendMessageRequest, TaskState } from '@a2a-js/sdk';
+import { ClientFactory, JsonRpcTransportFactory } from '@a2a-js/sdk/client';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CommerceError } from './types.js';
+import { validateUrl } from './config.js';
+export function nativeA2AExecutor(tokens, fetchImpl = fetch, signal, options = {}) {
+    const inputEncoding = Object.freeze({ ...options.inputEncoding });
+    if (Object.values(inputEncoding).some(value => value !== 'data' && value !== 'json-text'))
+        throw new CommerceError('invalid_upstream_encoding', 'Choose an explicit data or json-text input encoding');
+    const parts = (service, input) => inputEncoding[service.id] === 'json-text' ? [{ text: JSON.stringify(input), mediaType: 'application/json' }] : [{ data: input }];
+    const interfaces = new WeakMap();
+    async function prepare(service, remote) {
+        const cardUrl = validateUrl(service.execution.cardUrl, true), token = tokens[`${service.id}:${service.revision}`] ?? tokens[service.id];
+        if (!token || token.length < 16)
+            throw new CommerceError('upstream_credentials', 'Configured runtime authentication is missing');
+        if (remote && remote.origin !== service.execution.cardUrl)
+            throw new CommerceError('upstream_origin', 'Original runtime origin differs from the frozen service');
+        const scopedFetch = async (input, init) => {
+            const request = new Request(input, init);
+            if (new URL(request.url).origin !== cardUrl.origin)
+                throw new CommerceError('upstream_origin', 'Runtime Card cannot redirect credentials to another origin');
+            const headers = new Headers(request.headers);
+            headers.set('Authorization', 'Bearer ' + token);
+            headers.set('A2A-Version', '1.0');
+            const signals = [request.signal, AbortSignal.timeout(120000), ...(signal ? [signal] : [])];
+            const response = await fetchImpl(new Request(request, { headers, redirect: 'error', signal: AbortSignal.any(signals) }));
+            if (Number(response.headers.get('Content-Length') ?? 0) > 4 * 1024 * 1024)
+                throw new CommerceError('upstream_size', 'Runtime response exceeds limit');
+            if (response.body) {
+                const reader = response.body.getReader(), chunks = [];
+                let length = 0;
+                for (;;) {
+                    const next = await reader.read();
+                    if (next.done)
+                        break;
+                    length += next.value.byteLength;
+                    if (length > 4 * 1024 * 1024) {
+                        await reader.cancel();
+                        throw new CommerceError('upstream_size', 'Runtime response exceeds limit');
+                    }
+                    chunks.push(next.value);
+                }
+                return new Response(Buffer.concat(chunks), { status: response.status, statusText: response.statusText, headers: response.headers });
+            }
+            return response;
+        };
+        const response = await scopedFetch(cardUrl);
+        if (!response.ok)
+            throw new CommerceError('upstream_card', 'Unable to read runtime Agent Card');
+        const card = AgentCard.fromJSON(await response.json());
+        const selected = card.supportedInterfaces.find(x => x.protocolVersion === '1.0' && x.protocolBinding === 'JSONRPC');
+        if (!selected)
+            throw new CommerceError('upstream_version', 'Runtime must expose A2A 1.0 JSONRPC');
+        for (const endpoint of card.supportedInterfaces)
+            if (validateUrl(endpoint.url, true).origin !== cardUrl.origin)
+                throw new CommerceError('upstream_origin', 'Runtime interface must share configured Card origin');
+        if (remote?.interfaceUrl && selected.url !== remote.interfaceUrl)
+            throw new CommerceError('upstream_endpoint_changed', 'Original Task interface changed; restore it before recovery');
+        const factory = new ClientFactory({ transports: [new JsonRpcTransportFactory({ fetchImpl: scopedFetch })] });
+        const client = await factory.createFromAgentCard({ ...card, supportedInterfaces: [selected] });
+        return { client, interfaceUrl: selected.url };
+    }
+    function observed(task, interfaceUrl, expectedId) {
+        if (!task || typeof task !== 'object' || !('status' in task) || !('id' in task) || !task.id)
+            throw new CommerceError('upstream_task_required', 'Runtime returned no durable Task handle');
+        const result = task;
+        if (expectedId && result.id !== expectedId)
+            throw new CommerceError('remote_task_conflict', 'Runtime returned a different Task');
+        interfaces.set(result, interfaceUrl);
+        return result;
+    }
+    async function* observe(task, prepared, service) {
+        const deadline = Date.now() + service.contract.targetDurationSeconds * 1000, id = task.id;
+        for (;;) {
+            yield task;
+            if ([TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_FAILED, TaskState.TASK_STATE_CANCELED, TaskState.TASK_STATE_REJECTED, TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED].includes(task.status?.state ?? 0))
+                return;
+            if (Date.now() >= deadline)
+                throw new CommerceError('execution_pending', 'Read the original Task to continue observing execution');
+            await sleep(1000, undefined, { signal });
+            task = observed(await prepared.client.getTask(GetTaskRequest.fromJSON({ id })), prepared.interfaceUrl, id);
+        }
+    }
+    const execute = async function* (order, service) {
+        const prepared = await prepare(service);
+        const request = SendMessageRequest.fromJSON({ message: { messageId: order.messageId, role: 'ROLE_USER', parts: parts(service, order.input) }, configuration: { returnImmediately: true } });
+        const task = observed(await prepared.client.sendMessage(request), prepared.interfaceUrl);
+        yield* observe(task, prepared, service);
+    };
+    execute.continue = async function* (_order, service, continuation, remote) {
+        const prepared = await prepare(service, remote);
+        const request = SendMessageRequest.fromJSON({ message: { messageId: continuation.messageId, taskId: remote.taskId, ...(remote.contextId ? { contextId: remote.contextId } : {}), role: 'ROLE_USER', parts: parts(service, continuation.input) }, configuration: { returnImmediately: true } });
+        const task = observed(await prepared.client.sendMessage(request), prepared.interfaceUrl, remote.taskId);
+        yield* observe(task, prepared, service);
+    };
+    execute.recover = async (_order, service, remote) => {
+        const prepared = await prepare(service, remote);
+        // Recovery never calls SendMessage, creates a new Task, or retries a dispatch.
+        return observed(await prepared.client.getTask(GetTaskRequest.fromJSON({ id: remote.taskId })), prepared.interfaceUrl, remote.taskId);
+    };
+    execute.remoteInterface = task => interfaces.get(task);
+    return execute;
+}

package/dist/commerce/vault.d.ts

@@ -0,0 +1,8 @@
+/** Original authorizations are encrypted before any external settlement attempt. */
+export declare class CredentialVault {
+    private directory;
+    private readonly key;
+    constructor(directory: string, key: Buffer);
+    put(value: unknown): string;
+    get(id: string): unknown;
+}

package/dist/commerce/vault.js

@@ -0,0 +1,55 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, chmodSync, openSync, closeSync, fsyncSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { CommerceError } from './types.js';
+/** Original authorizations are encrypted before any external settlement attempt. */
+export class CredentialVault {
+    directory;
+    key;
+    constructor(directory, key) {
+        this.directory = directory;
+        if (key.length !== 32)
+            throw new CommerceError('vault_key', 'A 32-byte vault encryption key is required');
+        this.key = Buffer.from(key);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if (!lstatSync(directory).isDirectory())
+            throw new CommerceError('vault_directory', 'Vault must be a real directory');
+        chmodSync(directory, 0o700);
+    }
+    put(value) {
+        const serialized = JSON.stringify(value);
+        if (!serialized || Buffer.byteLength(serialized) > 65536)
+            throw new CommerceError('vault_size', 'Authorization exceeds vault limit');
+        const id = randomUUID(), nonce = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.key, nonce);
+        cipher.setAAD(Buffer.from(id));
+        const encrypted = Buffer.concat([cipher.update(serialized, 'utf8'), cipher.final()]);
+        writeFileSync(join(this.directory, id), Buffer.concat([nonce, cipher.getAuthTag(), encrypted]), { mode: 0o600, flag: 'wx', flush: true });
+        // Persist the directory entry before returning a reference to the ledger.
+        const directoryFd = openSync(this.directory, 'r');
+        try {
+            fsyncSync(directoryFd);
+        }
+        finally {
+            closeSync(directoryFd);
+        }
+        return id;
+    }
+    get(id) {
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(id))
+            throw new CommerceError('vault_reference', 'Invalid credential reference');
+        const path = join(this.directory, id), stat = lstatSync(path);
+        if (!stat.isFile() || stat.size < 29 || stat.size > 65564 || (stat.mode & 0o077) !== 0)
+            throw new CommerceError('vault_file', 'Invalid private authorization file');
+        const bytes = readFileSync(path);
+        const cipher = createDecipheriv('aes-256-gcm', this.key, bytes.subarray(0, 12));
+        cipher.setAAD(Buffer.from(id));
+        cipher.setAuthTag(bytes.subarray(12, 28));
+        try {
+            return JSON.parse(Buffer.concat([cipher.update(bytes.subarray(28)), cipher.final()]).toString('utf8'));
+        }
+        catch {
+            throw new CommerceError('vault_integrity', 'Original authorization failed integrity verification');
+        }
+    }
+}

package/dist/commerce/x402.d.ts

@@ -0,0 +1,38 @@
+import { type FacilitatorClient } from '@x402/core/server';
+import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import { type PaymentProfile } from './types.js';
+import { CommerceStore, type OrderRecord } from './store.js';
+import { CredentialVault } from './vault.js';
+type X402Profile = Extract<PaymentProfile, {
+    adapter: 'x402';
+}>;
+export interface X402GateOptions {
+    store: CommerceStore;
+    vault: CredentialVault;
+    payerFor: (caller: string) => string | undefined;
+    facilitator?: (profile: X402Profile) => FacilitatorClient;
+    verifyReceipt: (receipt: SettleResponse, payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+    /** Read chain before broadcast, so a lost facilitator response remains recoverable. */
+    checkpoint?: (requirements: PaymentRequirements) => Promise<string>;
+    findOriginalReceipt?: (payload: PaymentPayload, requirements: PaymentRequirements, fromBlock: string) => Promise<SettleResponse | undefined>;
+    proveExpiredUnused?: (payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+}
+export type GateResult = {
+    response: Response;
+} | {
+    headers: Record<string, string>;
+};
+/** Official x402 v2 exact settlement, with independent chain evidence before work. */
+export declare class X402Gate {
+    private options;
+    private servers;
+    constructor(options: X402GateOptions);
+    check(profiles: readonly X402Profile[]): Promise<void>;
+    recover(orderId: string, caller: string): Promise<{
+        state: string;
+        taskId: string;
+    }>;
+    private resource;
+    handle(request: Request, order: OrderRecord): Promise<GateResult>;
+}
+export {};

package/dist/commerce/x402.js

@@ -0,0 +1,181 @@
+import { findDefaultAsset } from '@x402/evm';
+import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server';
+import { decodePaymentSignatureHeader, encodePaymentRequiredHeader, encodePaymentResponseHeader } from '@x402/core/http';
+import { ExactEvmScheme } from '@x402/evm/exact/server';
+import { PAYMENT_IDENTIFIER, declarePaymentIdentifierExtension, extractPaymentIdentifier, validatePaymentIdentifier, paymentIdentifierResourceServerExtension, } from '@x402/extensions/payment-identifier';
+import { CommerceError } from './types.js';
+import { digest } from './config.js';
+/** Official x402 v2 exact settlement, with independent chain evidence before work. */
+export class X402Gate {
+    options;
+    servers = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async check(profiles) {
+        for (const profile of profiles) {
+            const { facilitator } = await this.resource(profile);
+            const supported = await facilitator.getSupported();
+            if (!supported.kinds.some(k => k.x402Version === 2 && k.scheme === 'exact' && k.network === profile.network))
+                throw new CommerceError('facilitator_network', 'Configured facilitator does not support exact payments on this network');
+            if (this.options.checkpoint)
+                await this.options.checkpoint({ scheme: 'exact', network: profile.network, asset: profile.asset, payTo: profile.payTo, amount: '1', maxTimeoutSeconds: 300, extra: {} });
+        }
+    }
+    async recover(orderId, caller) {
+        const order = this.options.store.getOrder(orderId, caller);
+        if (!order)
+            throw new CommerceError('order_not_found', 'Order not found for this buyer');
+        const attempt = this.options.store.paymentForOrder(order.id);
+        if (!attempt)
+            throw new CommerceError('attempt_not_found', 'No original payment to recover');
+        if (attempt.state === 'confirmed')
+            return { state: 'confirmed', taskId: order.taskId };
+        if (attempt.state === 'rejected')
+            return { state: 'rejected', taskId: order.taskId };
+        const saved = this.options.vault.get(attempt.credentialRef);
+        const required = this.options.store.paymentChallenge(order.id);
+        if (saved.quoteId !== order.quote.quoteId || !required?.accepts.some(r => digest(r) === digest(saved.requirements))) {
+            throw new CommerceError('recovery_conflict', 'Stored authorization differs from the frozen challenge');
+        }
+        let receipt = attempt.receipt;
+        if (!receipt?.transaction && saved.fromBlock && this.options.findOriginalReceipt) {
+            receipt = await this.options.findOriginalReceipt(saved.payload, saved.requirements, saved.fromBlock) ?? null;
+        }
+        if (!receipt?.transaction) {
+            if (await this.options.proveExpiredUnused?.(saved.payload, saved.requirements)) {
+                this.options.store.recordSettlement(attempt.id, 'rejected', { errorReason: 'authorization_expired_unused' });
+                return { state: 'rejected', taskId: order.taskId };
+            }
+            return { state: 'unknown', taskId: order.taskId };
+        }
+        let proven = false;
+        try {
+            proven = await this.options.verifyReceipt(receipt, saved.payload, saved.requirements);
+        }
+        catch { }
+        // Persist the discovered transaction even if confirmations are still pending.
+        this.options.store.recordSettlement(attempt.id, proven ? 'confirmed' : 'unknown', receipt);
+        return { state: proven ? 'confirmed' : 'unknown', taskId: order.taskId };
+    }
+    async resource(profile) {
+        const key = digest(profile);
+        let promise = this.servers.get(key);
+        if (!promise) {
+            promise = (async () => {
+                const facilitator = this.options.facilitator?.(profile) ?? new HTTPFacilitatorClient({ url: profile.facilitatorUrl });
+                const server = new x402ResourceServer(facilitator)
+                    .register(profile.network, new ExactEvmScheme())
+                    .registerExtension(paymentIdentifierResourceServerExtension);
+                await server.initialize();
+                return { server, facilitator };
+            })();
+            this.servers.set(key, promise);
+            void promise.catch(() => this.servers.delete(key));
+        }
+        return promise;
+    }
+    async handle(request, order) {
+        const profile = order.quote.paymentProfile;
+        if (profile?.adapter !== 'x402')
+            throw new CommerceError('payment_method_unavailable', 'This offer requires another installed payment adapter');
+        const previous = this.options.store.paymentForOrder(order.id);
+        if (order.paymentState === 'confirmed' && previous?.receipt) {
+            return { headers: { 'PAYMENT-RESPONSE': encodePaymentResponseHeader(previous.receipt) } };
+        }
+        if (['settling', 'unknown'].includes(order.paymentState)) {
+            const recovered = await this.recover(order.id, order.caller);
+            if (recovered.state === 'confirmed') {
+                const receipt = this.options.store.paymentForOrder(order.id).receipt;
+                return { headers: { 'PAYMENT-RESPONSE': encodePaymentResponseHeader(receipt) } };
+            }
+            if (recovered.state === 'rejected')
+                return { response: Response.json({ error: 'authorization_expired_unused', taskId: order.taskId }, { status: 409, headers: { 'Cache-Control': 'no-store' } }) };
+            return { response: Response.json({ error: 'payment_reconciliation_required', taskId: order.taskId }, { status: 503, headers: { 'Cache-Control': 'no-store' } }) };
+        }
+        if (Date.now() >= Date.parse(order.quote.expiresAt))
+            return { response: Response.json({ error: 'quote_expired' }, { status: 409 }) };
+        const { server, facilitator } = await this.resource(profile);
+        let required = this.options.store.paymentChallenge(order.id);
+        if (!required) {
+            const token = findDefaultAsset(profile.asset, profile.network);
+            if (!token)
+                throw new CommerceError('unsupported_asset', 'Official token signing domain is unavailable');
+            const requirements = await server.buildPaymentRequirements({
+                scheme: 'exact', network: profile.network, payTo: profile.payTo,
+                price: { asset: profile.asset, amount: order.quote.amount, extra: { name: token.name, version: token.version } },
+                maxTimeoutSeconds: 300, extra: { paymentFlow: 'upfront', assetTransferMethod: 'eip3009' },
+            });
+            const resource = new URL(request.url);
+            resource.search = '';
+            resource.searchParams.set('quote', order.quote.quoteId);
+            required = this.options.store.freezePaymentChallenge(order.id, await server.createPaymentRequiredResponse(requirements, { url: resource.href, description: order.quote.serviceId, mimeType: 'application/json' }, undefined, { [PAYMENT_IDENTIFIER]: declarePaymentIdentifierExtension(false), 'urn:envarpay:quote:1': { info: { quoteId: order.quote.quoteId, messageId: order.messageId, serviceId: order.quote.serviceId, serviceRevision: order.quote.serviceRevision, offerId: order.offerId, inputDigest: order.inputDigest, termsDigest: order.quote.termsDigest, expiresAt: order.quote.expiresAt, amount: order.quote.amount, currency: order.quote.currency, recipient: order.quote.recipient } } }));
+        }
+        // Identifier is optional for unextended standard clients; nonce dedup is mandatory.
+        const challenge = () => ({ response: new Response('{}', {
+                status: 402, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'PAYMENT-REQUIRED': encodePaymentRequiredHeader(required) },
+            }) });
+        const header = request.headers.get('PAYMENT-SIGNATURE');
+        if (!header)
+            return challenge();
+        if (header.length > 32768)
+            throw new CommerceError('payment_payload_size', 'Payment credential exceeds limit');
+        let payload;
+        try {
+            payload = decodePaymentSignatureHeader(header);
+        }
+        catch {
+            throw new CommerceError('invalid_payment', 'Malformed payment credential');
+        }
+        const matched = server.findMatchingRequirements(required.accepts, payload);
+        if (!matched || payload.x402Version !== 2 || payload.resource?.url !== required.resource.url || digest(payload.accepted) !== digest(matched)) {
+            throw new CommerceError('quote_mismatch', 'Payment does not match the frozen quote');
+        }
+        const extension = payload.extensions?.[PAYMENT_IDENTIFIER];
+        // Validate against our schema; never compile a schema supplied by the buyer.
+        if (extension !== undefined && !validatePaymentIdentifier({ info: extension?.info, schema: declarePaymentIdentifierExtension(false).schema }).valid) {
+            throw new CommerceError('invalid_payment_identifier', 'Invalid standard payment identifier');
+        }
+        const identifier = extractPaymentIdentifier(payload, false);
+        const native = payload.payload;
+        const auth = native.authorization;
+        const payer = this.options.payerFor(order.caller);
+        if (!payer || !auth?.from || auth.from.toLowerCase() !== payer.toLowerCase() || auth.to?.toLowerCase() !== profile.payTo.toLowerCase() || auth.value !== order.quote.amount || !/^0x[0-9a-fA-F]{64}$/.test(auth.nonce ?? '') || !native.signature) {
+            throw new CommerceError('payment_identity', 'Signed payer, recipient, amount and nonce must match authorized buyer and quote');
+        }
+        // Quote UI metadata is locally checked above. It is not a facilitator
+        // settlement extension; do not require third-party facilitators to implement it.
+        const settlementPayload = { ...payload, extensions: Object.fromEntries(Object.entries(payload.extensions ?? {}).filter(([key]) => key !== 'urn:envarpay:quote:1')) };
+        // Upfront SDK verification may skip /verify; explicitly perform it before reserve.
+        const verified = await facilitator.verify(settlementPayload, matched);
+        if (!verified.isValid)
+            return challenge();
+        if (verified.payer && verified.payer.toLowerCase() !== payer.toLowerCase())
+            throw new CommerceError('payment_identity', 'Verified payer differs from authorized buyer');
+        const economicKey = digest({ network: profile.network, asset: profile.asset.toLowerCase(), payer: payer.toLowerCase(), nonce: auth.nonce.toLowerCase() });
+        const fromBlock = await this.options.checkpoint?.(matched);
+        const saved = { payload, requirements: matched, quoteId: order.quote.quoteId, ...(fromBlock !== undefined ? { fromBlock } : {}) };
+        const credentialRef = this.options.vault.put(saved);
+        const attempt = this.options.store.reservePayment(order.id, order.caller, economicKey, credentialRef, identifier ?? undefined);
+        let result;
+        try {
+            result = await server.settlePayment(settlementPayload, matched, undefined, undefined, undefined, 'before-handler');
+        }
+        catch {
+            this.options.store.recordSettlement(attempt, 'unknown', {});
+            return { response: Response.json({ error: 'payment_outcome_unknown' }, { status: 503 }) };
+        }
+        // A failure can follow broadcast. Never create a second economic authorization.
+        let proven = false;
+        if (result.success) {
+            try {
+                proven = await this.options.verifyReceipt(result, payload, matched);
+            }
+            catch { }
+        }
+        this.options.store.recordSettlement(attempt, proven ? 'confirmed' : 'unknown', result);
+        if (!proven)
+            return { response: Response.json({ error: result.success ? 'receipt_verification_pending' : 'payment_outcome_unknown' }, { status: 503 }) };
+        return { headers: { 'PAYMENT-RESPONSE': encodePaymentResponseHeader(result) } };
+    }
+}

package/examples/buyer-policy.json

@@ -0,0 +1,18 @@
+{
+  "policyVersion":1,
+  "paymentsEnabled":false,
+  "approval":"per_purchase",
+  "peers":[{
+    "id":"research-seller",
+    "cardUrl":"https://seller.example/services/research/v1/offers/usdc-once/agent-card.json",
+    "protocol":"x402",
+    "currency":"eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "recipient":"0x2222222222222222222222222222222222222222",
+    "maxPerPurchase":"3000000"
+  }],
+  "budgets":[{
+    "currency":"eip155:84532/erc20:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    "maxTotal":"10000000",
+    "period":"cumulative"
+  }]
+}

package/examples/envar-integration-policy.json

@@ -0,0 +1,18 @@
+{
+  "enabled": true,
+  "platformOrigin": "https://envar.ai",
+  "agentId": "54fe760a-4580-4258-9002-80f34c0d757a",
+  "runtimeAgentId": "hermes-researcher",
+  "acceptUpdates": true,
+  "allowedServices": ["research"],
+  "allowedUpstreamOrigins": ["http://hermes:9000"],
+  "allowedX402": [
+    {
+      "network": "eip155:84532",
+      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+      "payTo": "0x2222222222222222222222222222222222222222",
+      "facilitatorOrigin": "https://facilitator.example"
+    }
+  ],
+  "allowedMppAccounts": ["seller-stripe"]
+}

package/examples/hermes-setup-probe.py

@@ -0,0 +1,105 @@
+"""Read owner-local Hermes settings through a private pipe; never calls a model."""
+
+import json
+import os
+import shlex
+import sys
+from pathlib import Path
+
+try:
+    import hermes_yaml as yaml
+except ImportError:
+    import yaml
+
+
+def inspect(home):
+    home = Path(home or os.environ.get("HERMES_HOME", "~/.hermes")).expanduser().resolve()
+    config = yaml.safe_load((home / "config.yaml").read_text()) or {}
+    model = config.get("model", {})
+    if isinstance(model, str):
+        model = {"default": model}
+    provider = config.get("providers", {}).get(model.get("provider"), {})
+    dotenv = {}
+    if (home / ".env").exists():
+        for line in (home / ".env").read_text().splitlines():
+            key, sep, value = line.partition("=")
+            if sep and not key.strip().startswith("#"):
+                dotenv[key.strip()] = value.strip().strip("\"'")
+    key_file = None
+    command = shlex.split(provider.get("key_cmd", ""))
+    if len(command) == 2 and command[0] == "cat":
+        key_file = str(Path(command[1]).expanduser().resolve())
+    key = (
+        provider.get("api_key")
+        or provider.get("key")
+        or dotenv.get("OPENAI_API_KEY")
+        or os.environ.get("OPENAI_API_KEY")
+    )
+    base = (
+        provider.get("api")
+        or provider.get("base_url")
+        or model.get("base_url")
+        or dotenv.get("OPENAI_BASE_URL")
+        or os.environ.get("OPENAI_BASE_URL")
+    )
+    if not model.get("default") or not base or not (key_file or key):
+        raise ValueError("Model configuration unavailable")
+    if key_file and (not Path(key_file).is_file() or not Path(key_file).read_text().strip()):
+        raise ValueError("Model key unavailable")
+    roots = [home / "skills"]
+    roots.extend(
+        Path(os.path.expandvars(str(p))).expanduser().resolve()
+        for p in config.get("skills", {}).get("external_dirs", [])
+    )
+    skills = []
+    seen = set()
+    for root in roots:
+        for entry in sorted(root.rglob("SKILL.md")) if root.is_dir() else []:
+            if entry.is_symlink():
+                continue
+            raw = entry.read_text()
+            front = raw.split("---", 2)
+            meta = yaml.safe_load(front[1]) if raw.startswith("---\n") and len(front) == 3 else {}
+            name = (meta or {}).get("name")
+            if not isinstance(name, str) or name in seen:
+                continue
+            seen.add(name)
+            files = []
+            unsupported = False
+            for file in entry.parent.rglob("*"):
+                if file.is_symlink():
+                    unsupported = True
+                elif file.is_file():
+                    if file.suffix.lower() not in {".md", ".txt"} and file.name != "LICENSE":
+                        unsupported = True
+                    files.append(str(file.relative_to(entry.parent)))
+            skills.append(
+                {
+                    "name": name,
+                    "path": str(entry.parent),
+                    "description": str((meta or {}).get("description", ""))[:500],
+                    "textPackage": not unsupported,
+                    "files": len(files),
+                }
+            )
+    return {
+        "home": str(home),
+        "python": sys.executable,
+        "model": model["default"],
+        "baseUrl": base,
+        "apiKeyFile": key_file,
+        "apiKey": None if key_file else key,
+        "skills": skills,
+    }
+
+
+if __name__ == "__main__":
+    try:
+        print(json.dumps(inspect(sys.argv[1] if len(sys.argv) > 1 else None)))
+    except Exception:
+        print(
+            "Cannot read this Hermes model configuration. "
+            "Configure an OpenAI-compatible model with a base URL and a local API key first.",
+            file=sys.stderr,
+        )
+        sys.exit(1)