@envarai/envarpay 2026.1025.1 → 2026.1027.1

package/README.md

@@ -2,17 +2,32 @@
 
 This package runs an A2A seller gate for free services and Envar account-balance purchases. Buyers use their Envar Wallet; this package does not sign buyer payments.
 
-## Recommended setup
+## Native Agent connection
 
-Use the Agent-specific setup file downloaded from Envar:
+Copy the Agent-specific command from Envar's setup page. Run it as the same user as the existing Hermes/OpenClaw process, then approve the printed short code in the browser:
 
 ```sh
-envarpay setup --file /private/path/envar-setup.json
+envarpay connector connect --agent AGENT_UUID --framework hermes
+envarpay connector run --agent AGENT_UUID
 ```
 
-Follow the terminal prompts to select a Hermes or OpenClaw runtime and its text Skills. Setup creates an owner-only directory containing `seller.json`, `credentials.json`, `envar.json`, `envar.token`, `vault.key`, `connection.json`, and `start.mjs`. Run the printed `node .../start.mjs` command, import `connection.json` in Envar, and select **Check connection**. The public [Agent guide](https://envar.ai/guide/agents) gives the platform-specific steps and the test message to send.
+Choose `--framework openclaw` for OpenClaw. When the native profile has multiple Agents, add `--native-agent ID`. Use `--home PATH` for a specific profile. Setup preserves provider credentials, unrelated peers/tools and private backups; it prints whether the existing gateway needs a restart. Normal receiving needs only outbound HTTPS.
 
-The generated seller starts with free services and a local balance receiving reference of `envar`. A paid service becomes available only after Envar approves this seller account and the service editor verifies the actual unpaid USD quote. In Envar, choose a Skill, enter its USD price, select **Test service**, then **Publish**. There is no separate payment setup command.
+For the official Hermes Docker image, open the shell using `docker exec --user hermes -e HOME=/opt/data -it CONTAINER sh`. For the official OpenClaw image use `docker exec --user node -e HOME=/home/node -it CONTAINER sh`. Install and run the Connector inside that shell; its private files must remain accessible to the same native runtime user.
+
+```sh
+envarpay connector doctor --agent AGENT_UUID
+envarpay connector status --agent AGENT_UUID
+envarpay connector disconnect --agent AGENT_UUID
+```
+
+The installed native MCP tools send free tasks to explicitly permitted recipients and retrieve original results. They grant no wallet access. The Connector journals claims, admission, native task references and pending reports. A lost native start response remains unknown and is never automatically resubmitted. Preserve the original private directory when recovering.
+
+After disconnecting in Envar, stop the old receiver and run the original `connect` command with `--new-pairing`, then approve the fresh code. Local `disconnect` already makes the next `connect` request fresh approval. Old journals remain intact. This is a new connection, not recovery of previously admitted work.
+
+## Existing public A2A seller
+
+Advanced setup continues to accept `envarpay setup --file /private/path/envar-setup.json`. It creates the original seller gate and `connection.json` for a public A2A endpoint. Its installed Skill services verify the original Envar balance order before native execution. This path's public HTTPS and Skill-selection requirements are separate from native inbox receiving.
 
 ## Manual seller commands
 

package/dist/adapters/a2a-runtime.d.ts

@@ -0,0 +1,20 @@
+import type { Work } from '../connector/contracts.generated.js';
+import { type NativeA2ASettings } from './native-a2a.js';
+import { type RuntimeAdapter, type RuntimeObservation, type RuntimeReadiness, type RuntimeReference } from './types.js';
+export declare class RuntimeControlUnsupported extends Error {
+    constructor();
+}
+export declare class A2ARuntimeAdapter implements RuntimeAdapter {
+    readonly key: string;
+    private readonly settings;
+    private readonly client;
+    constructor(key: string, settings: NativeA2ASettings);
+    probe(): Promise<RuntimeReadiness>;
+    private reference;
+    private observed;
+    start(work: Work, executionKey: string): Promise<RuntimeObservation>;
+    observe(reference: RuntimeReference): Promise<RuntimeObservation>;
+    provideInput(_reference: RuntimeReference, _operationId: string, _text: string): Promise<RuntimeObservation>;
+    cancel(_reference: RuntimeReference, _operationId: string): Promise<RuntimeObservation>;
+    close(): Promise<void>;
+}

package/dist/adapters/a2a-runtime.js

@@ -0,0 +1,82 @@
+import { SendMessageRequest, TaskState, Task } from '@a2a-js/sdk';
+import { NativeRequestNotStarted, NativeA2AClient } from './native-a2a.js';
+import { RuntimeOutcomeUnknown } from './types.js';
+export class RuntimeControlUnsupported extends Error {
+    constructor() { super('The native runtime cannot confirm this control operation. Keep observing the original task.'); }
+}
+export class A2ARuntimeAdapter {
+    key;
+    settings;
+    client;
+    constructor(key, settings) {
+        this.key = key;
+        this.settings = settings;
+        this.client = new NativeA2AClient(settings);
+    }
+    async probe() {
+        const card = await this.client.probe();
+        // The currently supported native plugins retain tasks in memory. Their restart loses those handles.
+        return { adapter: this.key, runtimeVersion: card.version || 'unknown', capabilities: { recover: true, input: false, cancel: false } };
+    }
+    reference(reference) {
+        if (reference.adapter !== this.key || reference.version !== 1 || !reference.value ||
+            Object.keys(reference.value).sort().join(',') !== 'contextId,interfaceUrl,origin,taskId')
+            throw new RuntimeOutcomeUnknown('native_reference_mismatch');
+        const value = reference.value;
+        if (Object.values(value).some(item => typeof item !== 'string' || item.length > 2048) || value.origin !== this.settings.cardUrl)
+            throw new RuntimeOutcomeUnknown('native_reference_mismatch');
+        return value;
+    }
+    observed(task, reference) {
+        const wire = Task.toJSON(task);
+        const textParts = (parts) => Array.isArray(parts)
+            ? parts.flatMap(part => part && typeof part === 'object' && typeof part.text === 'string' ? [part.text] : []) : [];
+        const artifacts = (wire.artifacts ?? []).flatMap(artifact => textParts(artifact.parts));
+        const text = (artifacts.length ? artifacts : textParts(wire.status?.message?.parts)).join('\n');
+        const state = {
+            [TaskState.TASK_STATE_COMPLETED]: 'completed', [TaskState.TASK_STATE_FAILED]: 'failed',
+            [TaskState.TASK_STATE_REJECTED]: 'failed', [TaskState.TASK_STATE_CANCELED]: 'canceled',
+            [TaskState.TASK_STATE_INPUT_REQUIRED]: 'input_required', [TaskState.TASK_STATE_AUTH_REQUIRED]: 'input_required',
+        }[task.status?.state ?? 0] ?? 'working';
+        const result = { reference: { adapter: this.key, version: 1, value: { ...reference } }, state };
+        if (Buffer.byteLength(text) > 32000)
+            return { ...result, state: 'failed', errorCode: 'result_too_large', text: 'The original native result exceeds this text service limit. Inspect the original Task; do not repeat it.' };
+        if (state === 'completed' && !text.trim())
+            return { ...result, state: 'failed', errorCode: 'empty_native_result', text: 'The native Task completed without a text result.' };
+        return { ...result, ...(text ? { text } : {}) };
+    }
+    async start(work, executionKey) {
+        if (executionKey !== work.id)
+            throw new Error('Use the original Envar work ID as execution key');
+        try {
+            const result = await this.client.send(SendMessageRequest.fromJSON({
+                message: { messageId: work.id, contextId: 'envar-' + work.context_id, role: 'ROLE_USER', parts: [{ text: work.request.message }] },
+                configuration: { returnImmediately: true },
+            }));
+            return this.observed(result.task, result.reference);
+        }
+        catch (error) {
+            if (error instanceof NativeRequestNotStarted)
+                throw error;
+            throw new RuntimeOutcomeUnknown('native_dispatch_unknown');
+        }
+    }
+    async observe(reference) {
+        const remote = this.reference(reference);
+        try {
+            const result = await this.client.read(remote);
+            return this.observed(result.task, result.reference);
+        }
+        catch {
+            throw new RuntimeOutcomeUnknown('native_task_unavailable');
+        }
+    }
+    async provideInput(_reference, _operationId, _text) {
+        throw new RuntimeControlUnsupported();
+    }
+    async cancel(_reference, _operationId) {
+        // OpenClaw explicitly refuses CancelTask. Hermes does not expose proven native-run abort evidence.
+        throw new RuntimeControlUnsupported();
+    }
+    async close() { }
+}

package/dist/adapters/configure-native.d.ts

@@ -0,0 +1,17 @@
+import type { ConnectorConfig } from '../connector/config.js';
+export interface NativeInspection {
+    home: string;
+    configFile: string;
+    port: number;
+    agentId: string;
+    cardUrl: string;
+    binary: string[];
+    runtimeVersion: string;
+}
+export declare function inspectNative(framework: 'hermes' | 'openclaw', options?: {
+    home?: string;
+    nativeAgent?: string;
+    cardUrl?: string;
+    versionProbe?: (binary: string[], env: NodeJS.ProcessEnv) => string;
+}): NativeInspection;
+export declare function configureNative(directory: string, config: ConnectorConfig): boolean;

package/dist/adapters/configure-native.js

@@ -0,0 +1,206 @@
+/** Targeted local configuration for each supported native platform. Never exports model credentials. */
+import { existsSync, lstatSync, readFileSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, dirname, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import JSON5 from 'json5';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { digest, validateUrl } from '../commerce/config.js';
+import { privateJson, privateText, writePrivate, writePrivateJson } from '../connector/files.js';
+function object(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Native configuration has an unexpected shape');
+    return value;
+}
+function readProfile(path) {
+    if (!existsSync(path))
+        return '';
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new Error('Use a bounded regular native configuration file');
+    return readFileSync(path, 'utf8');
+}
+function readConfig(path, yaml) {
+    try {
+        const text = readProfile(path);
+        return object(text.trim() ? (yaml ? parseYaml(text) : JSON5.parse(text)) : {});
+    }
+    catch {
+        throw new Error('Native configuration could not be parsed. Preserve it and correct the native profile first.');
+    }
+}
+function hermesEnvironment(home) {
+    return home === resolve(process.env.HERMES_HOME ?? join(homedir(), '.hermes')) ? process.env : {};
+}
+function envValues(text) {
+    const result = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?(A2A_[A-Z0-9_]+|ENVAR_A2A_[A-Z0-9_]+)\s*=\s*(.*?)\s*$/.exec(line);
+        if (!match)
+            continue;
+        let value = match[2];
+        if (value.startsWith('"')) {
+            try {
+                value = JSON.parse(value);
+            }
+            catch {
+                throw new Error('Invalid A2A environment value');
+            }
+        }
+        else if (value.startsWith("'") && value.endsWith("'"))
+            value = value.slice(1, -1);
+        result[match[1]] = value;
+    }
+    return result;
+}
+function changeEnv(text, changes) {
+    let result = text;
+    for (const [key, value] of Object.entries(changes)) {
+        const line = key + '=' + JSON.stringify(value);
+        const pattern = new RegExp('^\\s*(?:export\\s+)?' + key + '\\s*=.*$', 'gm');
+        result = pattern.test(result) ? result.replace(pattern, () => line) : result.trimEnd() + '\n' + line + '\n';
+    }
+    return result;
+}
+function writeProfile(path, text, backupRoot) {
+    const before = readProfile(path);
+    if (before === text)
+        return false;
+    if (existsSync(path))
+        writePrivate(join(backupRoot, randomUUID() + '-' + basename(path)), before);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    if (lstatSync(dirname(path)).isSymbolicLink())
+        throw new Error('Native profile directory must not be a symlink');
+    const temp = join(dirname(path), '.envar-write-' + randomUUID());
+    writeFileSync(temp, text, { mode: 0o600, flag: 'wx', flush: true });
+    renameSync(temp, path);
+    return true;
+}
+export function inspectNative(framework, options = {}) {
+    const overrideFile = framework === 'openclaw' && !options.home ? process.env.OPENCLAW_CONFIG_PATH : undefined;
+    const home = resolve(options.home ?? (overrideFile ? dirname(resolve(overrideFile)) : undefined) ?? (framework === 'hermes' ? process.env.HERMES_HOME ?? join(homedir(), '.hermes')
+        : process.env.OPENCLAW_STATE_DIR ?? join(homedir(), '.openclaw')));
+    const file = overrideFile ? resolve(overrideFile) : join(home, framework === 'hermes' ? 'config.yaml' : 'openclaw.json');
+    if (process.getuid?.() === 0 && existsSync(home) && lstatSync(home).uid !== 0)
+        throw new Error('Run the Connector as the same user as the native Agent. For the official Hermes Docker image, open a shell with docker exec --user hermes -e HOME=/opt/data -it CONTAINER sh, then run the setup command there.');
+    const config = readConfig(file, framework === 'hermes');
+    const env = envValues(readProfile(join(home, '.env')));
+    let nativeAgent = options.nativeAgent ?? 'main', port = 9900, origin = '';
+    if (framework === 'hermes') {
+        if (options.nativeAgent && options.nativeAgent !== 'main')
+            throw new Error('Select the Hermes profile with --home; its local A2A gateway uses that profile');
+        const active = hermesEnvironment(home);
+        port = Number(active.A2A_PORT ?? env.A2A_PORT ?? config.platforms?.a2a?.extra?.port ?? config.gateway?.platforms?.a2a?.extra?.port ?? 9900);
+        origin = active.A2A_PUBLIC_URL ?? env.A2A_PUBLIC_URL ?? '';
+    }
+    else {
+        const entries = object(config.agents?.entries);
+        const legacy = config.agents?.list;
+        const ids = Object.keys(entries).length ? Object.keys(entries) : Array.isArray(legacy) ? legacy.map((agent) => agent.id) : [];
+        const selected = Array.isArray(legacy) ? legacy.find((agent) => agent.default)?.id : undefined;
+        if (!options.nativeAgent && ids.length > 1 && !selected)
+            throw new Error('This OpenClaw has multiple Agents. Choose the intended one with --native-agent ID.');
+        nativeAgent = options.nativeAgent ?? selected ?? ids[0] ?? 'main';
+        if (ids.length && !ids.includes(nativeAgent))
+            throw new Error('Choose an existing OpenClaw agent ID');
+        port = Number(config.gateway?.port ?? 18789);
+        origin = config.channels?.a2a?.advertisedUrl ?? '';
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535 || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(nativeAgent))
+        throw new Error('Invalid native Agent or A2A port');
+    const cardUrl = options.cardUrl ?? new URL('.well-known/agent-card.json', (origin || `http://127.0.0.1:${port}`).replace(/\/$/, '') + '/').href;
+    validateUrl(cardUrl, true);
+    const binary = framework === 'hermes' ? [existsSync('/opt/hermes/bin/hermes') ? '/opt/hermes/bin/hermes' : 'hermes']
+        : existsSync('/app/openclaw.mjs') ? [process.execPath, '/app/openclaw.mjs'] : ['openclaw'];
+    const runtimeEnv = { ...process.env, ...(framework === 'hermes' ? { HERMES_HOME: home } : { OPENCLAW_STATE_DIR: home }) };
+    let output;
+    try {
+        output = options.versionProbe ? options.versionProbe(binary, runtimeEnv)
+            : execFileSync(binary[0], [...binary.slice(1), '--version'], { encoding: 'utf8', env: runtimeEnv, stdio: 'pipe', timeout: 30000, maxBuffer: 65536 });
+    }
+    catch {
+        throw new Error('Cannot inspect the native CLI. Confirm the Agent installation and profile before connecting.');
+    }
+    const runtimeVersion = output.replace(/\x1b\[[0-9;]*m/g, '').match(/\b\d{1,4}\.\d+(?:\.[0-9A-Za-z.+-]+)?/)?.[0] ?? 'unknown';
+    return { home, configFile: file, port, agentId: nativeAgent, cardUrl, binary, runtimeVersion };
+}
+export function configureNative(directory, config) {
+    const home = config.runtime.home, yaml = config.framework === 'hermes';
+    const path = config.runtime.configFile ?? join(home, yaml ? 'config.yaml' : 'openclaw.json');
+    const value = readConfig(path, yaml), envPath = join(home, '.env'), envText = readProfile(envPath), env = envValues(envText);
+    const nativeTokenFile = join(directory, 'native.token');
+    const token = existsSync(nativeTokenFile) ? privateText(nativeTokenFile).trim() : randomBytes(32).toString('base64url');
+    if (!/^[A-Za-z0-9_-]{32,128}$/.test(token))
+        throw new Error('Restore the original private native peer credential');
+    if (!existsSync(nativeTokenFile))
+        writePrivate(nativeTokenFile, token + '\n');
+    const markerFile = join(directory, 'native-binding.json');
+    const previous = existsSync(markerFile) ? privateJson(markerFile) : undefined;
+    if (previous && (previous.agentId !== config.agentId || previous.home !== home))
+        throw new Error('Native binding belongs to another Agent or profile');
+    const cli = fileURLToPath(new URL('../cli.js', import.meta.url));
+    const mcp = { command: process.execPath, args: [cli, 'connector', 'mcp', '--directory', directory, '--connection', config.connectionId],
+        ...(yaml ? { timeout: 70 } : { enabled: true, requestTimeoutMs: 70000 }) };
+    const servers = yaml ? object(value.mcp_servers) : object(object(value.mcp).servers);
+    const existing = servers[config.runtime.mcpName];
+    if (existing && digest(existing) !== digest(mcp) && (!previous || digest(existing) !== previous.mcpDigest))
+        throw new Error('The existing Envar MCP entry was edited. Preserve it and review its configuration before replacing it.');
+    servers[config.runtime.mcpName] = mcp;
+    const changes = {};
+    const origin = config.runtime.cardUrl.replace(/\/\.well-known\/agent-card\.json$/, '');
+    if (yaml) {
+        value.mcp_servers = servers;
+        const platforms = object(value.platforms), legacy = object(object(value.gateway).platforms);
+        const a2a = object(platforms.a2a ?? legacy.a2a);
+        platforms.a2a = { ...a2a, enabled: true, extra: { ...object(a2a.extra), port: config.runtime.port ?? a2a.extra?.port ?? 9900 } };
+        value.platforms = platforms;
+        const active = hermesEnvironment(home);
+        const peers = active.A2A_PEER_TOKENS ?? env.A2A_PEER_TOKENS ?? '';
+        const own = peers.split(',').find(item => item.trim().startsWith(config.runtime.peerName + ':'))?.trim();
+        if (own && own.slice(config.runtime.peerName.length + 1) !== token)
+            throw new Error('Existing native peer credential differs; restore the original Connector directory');
+        changes.A2A_PEER_TOKENS = own ? peers : [peers, config.runtime.peerName + ':' + token].filter(Boolean).join(',');
+        const trusted = (active.A2A_TRUSTED_PEERS ?? env.A2A_TRUSTED_PEERS ?? '').split(',').map(v => v.trim()).filter(Boolean);
+        changes.A2A_TRUSTED_PEERS = [...new Set([...trusted, config.runtime.peerName])].join(',');
+        if (!active.A2A_PUBLIC_URL && !env.A2A_PUBLIC_URL)
+            changes.A2A_PUBLIC_URL = origin;
+        // Environment overrides cannot be silently changed by writing a profile file.
+        for (const key of ['A2A_PEER_TOKENS', 'A2A_TRUSTED_PEERS']) {
+            if (active[key] && active[key] !== changes[key])
+                throw new Error('A2A peer settings are supplied by the deployment environment. Add this Connector through that environment before continuing.');
+        }
+    }
+    else {
+        value.mcp = { ...object(value.mcp), servers };
+        const channels = object(value.channels), a2a = object(channels.a2a), peers = object(a2a.peers);
+        const key = 'ENVAR_A2A_' + config.agentId.replaceAll('-', '').toUpperCase();
+        if ((process.env[key] ?? env[key]) && (process.env[key] ?? env[key]) !== token)
+            throw new Error('The managed native peer environment key already has another value');
+        const reference = '${' + key + '}';
+        if (peers[config.runtime.peerName]?.token && peers[config.runtime.peerName].token !== reference)
+            throw new Error('Existing native peer credential differs; preserve its configuration');
+        peers[config.runtime.peerName] = { ...object(peers[config.runtime.peerName]), token: reference };
+        channels.a2a = { ...a2a, enabled: true, peers, advertisedUrl: a2a.advertisedUrl || origin,
+            ...(!a2a.enabled && a2a.exposeAgents === undefined ? { exposeAgents: [config.runtime.agentId] } : {}) };
+        value.channels = channels;
+        changes[key] = token;
+        const bindings = value.bindings ?? [];
+        if (!Array.isArray(bindings))
+            throw new Error('Native bindings must remain an array');
+        const prior = bindings.find((b) => b.match?.channel === 'a2a' && b.match?.peer?.id === config.runtime.peerName);
+        if (prior && prior.agentId !== config.runtime.agentId)
+            throw new Error('This peer is already routed to another native Agent');
+        if (!prior)
+            bindings.push({ agentId: config.runtime.agentId, match: { channel: 'a2a', peer: { kind: 'direct', id: config.runtime.peerName } } });
+        value.bindings = bindings;
+    }
+    const backupRoot = join(directory, 'native-backups');
+    const envChanged = writeProfile(envPath, changeEnv(envText, changes), backupRoot);
+    const configChanged = writeProfile(path, yaml ? stringifyYaml(value) : JSON.stringify(value, null, 2) + '\n', backupRoot);
+    writePrivateJson(markerFile, { agentId: config.agentId, home, mcpDigest: digest(mcp) });
+    return envChanged || configChanged;
+}

package/dist/adapters/hermes.d.ts

@@ -0,0 +1,6 @@
+import { A2ARuntimeAdapter } from './a2a-runtime.js';
+import type { NativeA2ASettings } from './native-a2a.js';
+/** Hermes' native A2A platform injects work into its real gateway session. */
+export declare class HermesRuntimeAdapter extends A2ARuntimeAdapter {
+    constructor(settings: NativeA2ASettings);
+}

package/dist/adapters/hermes.js

@@ -0,0 +1,5 @@
+import { A2ARuntimeAdapter } from './a2a-runtime.js';
+/** Hermes' native A2A platform injects work into its real gateway session. */
+export class HermesRuntimeAdapter extends A2ARuntimeAdapter {
+    constructor(settings) { super('hermes', settings); }
+}

package/dist/adapters/native-a2a.d.ts

@@ -0,0 +1,36 @@
+import { AgentCard, SendMessageRequest, Task } from '@a2a-js/sdk';
+export declare class NativeRequestNotStarted extends Error {
+    constructor();
+}
+export interface NativeTaskReference {
+    origin: string;
+    interfaceUrl: string;
+    taskId: string;
+    contextId: string;
+}
+type RecoverableReference = Omit<NativeTaskReference, "interfaceUrl"> & {
+    interfaceUrl?: string;
+};
+export interface NativeA2ASettings {
+    cardUrl: string;
+    token: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}
+export declare class NativeA2AClient {
+    private readonly settings;
+    private readonly cardUrl;
+    constructor(settings: NativeA2ASettings);
+    private prepare;
+    probe(): Promise<AgentCard>;
+    private observed;
+    send(request: SendMessageRequest, remote?: RecoverableReference): Promise<{
+        task: Task;
+        reference: NativeTaskReference;
+    }>;
+    read(remote: RecoverableReference): Promise<{
+        task: Task;
+        reference: NativeTaskReference;
+    }>;
+}
+export {};

package/dist/adapters/native-a2a.js

@@ -0,0 +1,112 @@
+/** Shared official A2A transport for local runtime adapters and the legacy seller gate. */
+import { randomUUID } from 'node:crypto';
+import { AgentCard, GetTaskRequest } from '@a2a-js/sdk';
+import { TaskNotFoundError, RequestMalformedError } from '@a2a-js/sdk/errors';
+import { ClientFactory, JsonRpcTransportFactory } from '@a2a-js/sdk/client';
+import { validateUrl } from '../commerce/config.js';
+import { CommerceError } from '../commerce/types.js';
+export class NativeRequestNotStarted extends Error {
+    constructor() { super('Native A2A rejected the request before starting a task. Check the peer configuration, gateway address and protocol version.'); }
+}
+export class NativeA2AClient {
+    settings;
+    cardUrl;
+    constructor(settings) {
+        this.settings = settings;
+        this.cardUrl = validateUrl(settings.cardUrl, true);
+        if (!settings.token || settings.token.length < 16 || /[\r\n]/.test(settings.token))
+            throw new CommerceError('upstream_credentials', 'Configure a private native peer credential');
+    }
+    async prepare(remote) {
+        if (remote && (remote.origin !== this.settings.cardUrl || !remote.taskId))
+            throw new CommerceError('upstream_origin', 'Recover only the original configured runtime');
+        const scopedFetch = async (input, init) => {
+            const request = new Request(input, init);
+            if (new URL(request.url).origin !== this.cardUrl.origin)
+                throw new CommerceError('upstream_origin', 'Native interfaces must share the configured Card origin');
+            const headers = new Headers(request.headers);
+            headers.set('Authorization', 'Bearer ' + this.settings.token);
+            headers.set('A2A-Version', '1.0');
+            const signals = [request.signal, AbortSignal.timeout(120000), ...(this.settings.signal ? [this.settings.signal] : [])];
+            const response = await (this.settings.fetch ?? fetch)(new Request(request, {
+                headers, redirect: 'error', signal: AbortSignal.any(signals),
+            }));
+            if ([400, 401, 403, 404, 405, 415].includes(response.status))
+                throw new NativeRequestNotStarted();
+            if (Number(response.headers.get('Content-Length') ?? 0) > 4 * 1024 * 1024)
+                throw new CommerceError('upstream_size', 'Native response exceeds the limit');
+            if (!response.body)
+                return response;
+            const reader = response.body.getReader(), chunks = [];
+            let size = 0;
+            for (;;) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                size += next.value.byteLength;
+                if (size > 4 * 1024 * 1024) {
+                    await reader.cancel();
+                    throw new CommerceError('upstream_size', 'Native response exceeds the limit');
+                }
+                chunks.push(next.value);
+            }
+            return new Response(Buffer.concat(chunks), { status: response.status, statusText: response.statusText, headers: response.headers });
+        };
+        const response = await scopedFetch(this.cardUrl);
+        if (!response.ok)
+            throw new CommerceError('upstream_card', 'Unable to read the native Agent Card');
+        const card = AgentCard.fromJSON(await response.json());
+        const selected = card.supportedInterfaces.find(item => item.protocolVersion === '1.0' && item.protocolBinding === 'JSONRPC');
+        if (!selected)
+            throw new CommerceError('upstream_version', 'Native runtime must expose A2A 1.0 JSONRPC');
+        if (card.supportedInterfaces.some(item => validateUrl(item.url, true).origin !== this.cardUrl.origin))
+            throw new CommerceError('upstream_origin', 'Native interfaces must share the configured Card origin');
+        if (remote?.interfaceUrl && remote.interfaceUrl !== selected.url)
+            throw new CommerceError('upstream_endpoint_changed', 'Original Task interface changed; restore it before recovery');
+        const client = await new ClientFactory({ transports: [new JsonRpcTransportFactory({ fetchImpl: scopedFetch })] })
+            .createFromAgentCard({ ...card, supportedInterfaces: [selected] });
+        return { card, client, interfaceUrl: selected.url };
+    }
+    async probe() {
+        const prepared = await this.prepare();
+        try {
+            await prepared.client.getTask(GetTaskRequest.fromJSON({ id: 'envar-connection-probe-' + randomUUID() }));
+        }
+        catch (error) {
+            if (error instanceof TaskNotFoundError)
+                return prepared.card;
+            throw new CommerceError('upstream_probe', 'Native A2A check failed. Check the gateway address, dedicated peer authorization and restart status.');
+        }
+        throw new CommerceError('upstream_probe', 'Native runtime returned an unexpected probe Task');
+    }
+    observed(value, interfaceUrl, expected) {
+        if (!value || typeof value !== 'object' || !('status' in value) || !('id' in value) || typeof value.id !== 'string' || !value.id)
+            throw new CommerceError('upstream_task_required', 'Native runtime returned no original Task handle');
+        const task = value;
+        if (expected && task.id !== expected)
+            throw new CommerceError('remote_task_conflict', 'Native runtime returned another Task');
+        return { task, reference: { origin: this.settings.cardUrl, interfaceUrl, taskId: task.id, contextId: task.contextId ?? '' } };
+    }
+    async send(request, remote) {
+        let prepared;
+        try {
+            prepared = await this.prepare(remote);
+        }
+        catch {
+            throw new NativeRequestNotStarted();
+        }
+        // Exactly one native POST. A lost response must not cause a replacement task.
+        try {
+            return this.observed(await prepared.client.sendMessage(request), prepared.interfaceUrl, remote?.taskId);
+        }
+        catch (error) {
+            if (error instanceof RequestMalformedError)
+                throw new NativeRequestNotStarted();
+            throw error;
+        }
+    }
+    async read(remote) {
+        const prepared = await this.prepare(remote);
+        return this.observed(await prepared.client.getTask(GetTaskRequest.fromJSON({ id: remote.taskId })), prepared.interfaceUrl, remote.taskId);
+    }
+}

package/dist/adapters/openclaw.d.ts

@@ -0,0 +1,6 @@
+import { A2ARuntimeAdapter } from './a2a-runtime.js';
+import type { NativeA2ASettings } from './native-a2a.js';
+/** OpenClaw's bundled A2A channel preserves peer/context isolation and native tool policy. */
+export declare class OpenClawRuntimeAdapter extends A2ARuntimeAdapter {
+    constructor(settings: NativeA2ASettings);
+}

package/dist/adapters/openclaw.js

@@ -0,0 +1,5 @@
+import { A2ARuntimeAdapter } from './a2a-runtime.js';
+/** OpenClaw's bundled A2A channel preserves peer/context isolation and native tool policy. */
+export class OpenClawRuntimeAdapter extends A2ARuntimeAdapter {
+    constructor(settings) { super('openclaw', settings); }
+}

package/dist/adapters/types.d.ts

@@ -0,0 +1,38 @@
+/** Runtime boundary: the Connector owns delivery; the user/vendor owns execution. */
+import type { Work } from '../connector/contracts.generated.js';
+export interface RuntimeReference {
+    adapter: string;
+    version: 1;
+    /** Adapter-owned, validated original task/session handle. No credentials. */
+    value: Record<string, unknown>;
+}
+export interface RuntimeReadiness {
+    adapter: string;
+    runtimeVersion: string;
+    capabilities: {
+        recover: boolean;
+        input: boolean;
+        cancel: boolean;
+    };
+}
+export interface RuntimeObservation {
+    reference: RuntimeReference;
+    state: 'working' | 'input_required' | 'completed' | 'failed' | 'canceled' | 'unknown';
+    text?: string;
+    errorCode?: string;
+}
+export interface RuntimeAdapter {
+    readonly key: string;
+    probe(): Promise<RuntimeReadiness>;
+    /** Called once after durable local preparation and Envar admission. Never retries an unknown POST. */
+    start(work: Work, executionKey: string): Promise<RuntimeObservation>;
+    /** Observes only the original validated reference, without creating another execution. */
+    observe(reference: RuntimeReference): Promise<RuntimeObservation>;
+    provideInput(reference: RuntimeReference, operationId: string, text: string): Promise<RuntimeObservation>;
+    cancel(reference: RuntimeReference, operationId: string): Promise<RuntimeObservation>;
+    close(): Promise<void>;
+}
+export declare class RuntimeOutcomeUnknown extends Error {
+    readonly code: string;
+    constructor(code?: string);
+}

package/dist/adapters/types.js

@@ -0,0 +1,7 @@
+export class RuntimeOutcomeUnknown extends Error {
+    code;
+    constructor(code = 'runtime_outcome_unknown') {
+        super('Original runtime outcome is unknown. Preserve its execution reference; do not resubmit.');
+        this.code = code;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+if (process.argv[2] === 'connector') {
+    try {
+        await (await import('./connector/cli.js')).runConnectorCli(process.argv.slice(3));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : 'Connector operation failed');
+        process.exitCode = 1;
+    }
+}
+else {
+    await import('./commerce/cli.js');
+}
+export {};

package/dist/commerce/external-agent.d.ts

@@ -11,16 +11,16 @@ export declare class ExternalAgentExecutor {
         taskId: string;
         serviceId: string;
         claimId: string;
-        state: "unknown" | "not_started" | "queued" | "dispatching" | "working" | "input_required" | "auth_required" | "completed" | "failed";
+        state: "input_required" | "completed" | "failed" | "queued" | "dispatching" | "working" | "unknown" | "not_started" | "auth_required";
         input: import("./types.js").Input;
-        paymentState: "not_required" | "quoted" | "settling" | "confirmed" | "rejected" | "unknown";
+        paymentState: "unknown" | "not_required" | "quoted" | "settling" | "confirmed" | "rejected";
     }[];
     claim(taskId: string): Promise<{
         taskId: string;
         claimId: string;
         input: import("./types.js").Input;
-        paymentState: "not_required" | "quoted" | "settling" | "confirmed" | "rejected" | "unknown";
-        state: "unknown" | "not_started" | "queued" | "dispatching" | "working" | "input_required" | "auth_required" | "completed" | "failed";
+        paymentState: "unknown" | "not_required" | "quoted" | "settling" | "confirmed" | "rejected";
+        state: "input_required" | "completed" | "failed" | "queued" | "dispatching" | "working" | "unknown" | "not_started" | "auth_required";
     }>;
     complete(taskId: string, claimId: string, text: string, failed?: boolean): Promise<unknown>;
 }