@envarai/connect 2026.1107.2 → 2026.1110.1

package/README.md

@@ -28,7 +28,7 @@ For the independent seller-side developer path, start with [EnvarPay](https://gi
 ## Install
 
 ```sh
-npm install --global --ignore-scripts @envarai/connect@2026.1107.2
+npm install --global --ignore-scripts @envarai/connect@2026.1110.1
 envar-connect --version
 ```
 
@@ -70,7 +70,7 @@ bundled package with integrity verification; it installs without fetching npm
 dependencies. A mirror returning 404 does not establish that the public package
 is missing.
 
-See [native setup](docs/native-connector.md), [migration](docs/migration.md), [release automation](docs/releasing.md), and [contributing](CONTRIBUTING.md). The non-root container is `ghcr.io/envarai/connect`; it contains the Connector, not a native Agent runtime.
+See [native setup](docs/native-connector.md), [runtime diagnostics](docs/runtime-diagnostics.md), [migration](docs/migration.md), [release automation](docs/releasing.md), and [contributing](CONTRIBUTING.md). The non-root container is `ghcr.io/envarai/connect`; it contains the Connector, not a native Agent runtime.
 GHCR package access is separate from repository visibility. Anonymous image pulls
 are not currently part of the verified public installation path. Use the npm
 package, the official bundled download, or build the checked-out `Dockerfile`

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

@@ -1,3 +1,4 @@
+import type { RelayRuntime } from './types.js';
 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';
@@ -8,6 +9,7 @@ export declare class A2ARuntimeAdapter implements RuntimeAdapter {
     readonly key: string;
     private readonly settings;
     private readonly client;
+    readonly relay: RelayRuntime;
     constructor(key: string, settings: NativeA2ASettings);
     probe(): Promise<RuntimeReadiness>;
     private reference;

package/dist/adapters/a2a-runtime.js

@@ -1,4 +1,5 @@
-import { SendMessageRequest, TaskState, Task } from '@a2a-js/sdk';
+import { AgentCard, SendMessageRequest, TaskState, Task } from '@a2a-js/sdk';
+import { digest } from '../shared/json.js';
 import { NativeRequestNotStarted, NativeA2AClient } from './native-a2a.js';
 import { RuntimeOutcomeUnknown } from './types.js';
 export class RuntimeControlUnsupported extends Error {
@@ -8,15 +9,32 @@ export class A2ARuntimeAdapter {
     key;
     settings;
     client;
+    relay;
     constructor(key, settings) {
         this.key = key;
         this.settings = settings;
         this.client = new NativeA2AClient(settings);
+        const convert = (result) => ({
+            ...(result.task ? { task: result.task } : {}), ...(result.message ? { message: result.message } : {}),
+            ...(result.reference ? { reference: { origin: result.reference.origin, interface: result.reference.interfaceUrl, task_id: result.reference.taskId, context_id: result.reference.contextId } } : {}),
+        });
+        this.relay = {
+            cardDigest: async () => digest(AgentCard.toJSON(await this.client.probe())),
+            send: async (params) => convert(await this.client.sendStandard(params)),
+            prepareSend: async (params) => {
+                const dispatch = await this.client.prepareStandard(params);
+                return async () => convert(await dispatch());
+            },
+            read: async (reference) => Task.toJSON((await this.client.read({ origin: reference.origin, interfaceUrl: reference.interface, taskId: reference.task_id, contextId: reference.context_id })).task),
+        };
     }
     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 } };
+        return { adapter: this.key, runtimeVersion: card.version || 'unknown',
+            capabilities: { recover: true, input: false, cancel: false },
+            recovery: { taskLookupAfterRestart: false, executionKeyLookup: false, resultPersistence: false },
+            maxConcurrency: 1 };
     }
     reference(reference) {
         if (reference.adapter !== this.key || reference.version !== 1 || !reference.value ||

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

@@ -32,5 +32,23 @@ export declare class NativeA2AClient {
         task: Task;
         reference: NativeTaskReference;
     }>;
+    sendStandard(params: Record<string, unknown>): Promise<{
+        task: Record<string, unknown>;
+        reference: NativeTaskReference;
+        message?: undefined;
+    } | {
+        message: Record<string, unknown>;
+        task?: undefined;
+        reference?: undefined;
+    }>;
+    prepareStandard(params: Record<string, unknown>): Promise<() => Promise<{
+        task: Record<string, unknown>;
+        reference: NativeTaskReference;
+        message?: undefined;
+    } | {
+        message: Record<string, unknown>;
+        task?: undefined;
+        reference?: undefined;
+    }>>;
 }
 export {};

package/dist/adapters/native-a2a.js

@@ -1,6 +1,6 @@
 /** 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 { AgentCard, GetTaskRequest, Message, SendMessageRequest, Task } from '@a2a-js/sdk';
 import { TaskNotFoundError, RequestMalformedError } from '@a2a-js/sdk/errors';
 import { ClientFactory, JsonRpcTransportFactory } from '@a2a-js/sdk/client';
 import { validateUrl } from '../shared/json.js';
@@ -107,6 +107,28 @@ export class NativeA2AClient {
     }
     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);
+        const result = this.observed(await prepared.client.getTask(GetTaskRequest.fromJSON({ id: remote.taskId })), prepared.interfaceUrl, remote.taskId);
+        if (remote.contextId && result.reference.contextId !== remote.contextId)
+            throw new CommerceError('remote_context_conflict', 'Native runtime returned another original context');
+        return result;
+    }
+    async sendStandard(params) {
+        return (await this.prepareStandard(params))();
+    }
+    async prepareStandard(params) {
+        const prepared = await this.prepare();
+        const request = SendMessageRequest.fromJSON(params);
+        // Preparation only reads and validates the Card. The caller commits its
+        // dispatch marker immediately before invoking this one-POST closure.
+        return async () => {
+            const response = await prepared.client.sendMessage(request);
+            if (response && 'status' in response) {
+                const result = this.observed(response, prepared.interfaceUrl);
+                return { task: Task.toJSON(result.task), reference: result.reference };
+            }
+            if (!response || !('role' in response))
+                throw new CommerceError('upstream_result', 'Native runtime returned no standard result');
+            return { message: Message.toJSON(response) };
+        };
     }
 }

package/dist/adapters/types.d.ts

@@ -1,5 +1,16 @@
 /** Runtime boundary: the Connector owns delivery; the user/vendor owns execution. */
 import type { Work } from '../connector/contracts.generated.js';
+import type { RelayReference } from '../connector/relay-types.js';
+export interface RelayRuntime {
+    cardDigest(): Promise<string>;
+    prepareSend?(params: Record<string, unknown>): Promise<() => ReturnType<RelayRuntime['send']>>;
+    send(params: Record<string, unknown>): Promise<{
+        task?: Record<string, unknown>;
+        message?: Record<string, unknown>;
+        reference?: RelayReference;
+    }>;
+    read(reference: RelayReference): Promise<Record<string, unknown>>;
+}
 export interface RuntimeReference {
     adapter: string;
     version: 1;
@@ -14,6 +25,13 @@ export interface RuntimeReadiness {
         input: boolean;
         cancel: boolean;
     };
+    /** Separate guarantees; a live Task lookup does not prove restart recovery. */
+    recovery?: {
+        taskLookupAfterRestart: boolean;
+        executionKeyLookup: boolean;
+        resultPersistence: boolean;
+    };
+    maxConcurrency?: number;
 }
 export interface RuntimeObservation {
     reference: RuntimeReference;
@@ -23,6 +41,7 @@ export interface RuntimeObservation {
 }
 export interface RuntimeAdapter {
     readonly key: string;
+    readonly relay?: RelayRuntime;
     probe(): Promise<RuntimeReadiness>;
     /** Called once after durable local preparation and Envar admission. Never retries an unknown POST. */
     start(work: Work, executionKey: string): Promise<RuntimeObservation>;

package/dist/connector/cli.js

@@ -8,6 +8,7 @@ import { privateDirectory, privateJson, writePrivate, writePrivateJson } from '.
 import { ConnectorLoop } from './loop.js';
 import { connectorMcp } from './mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CONNECTOR_VERSION } from './runtime-report.js';
 const usageFor = (command) => `Envar Connector\n${command.join(' ')} connect --agent UUID --framework hermes|openclaw [--home PROFILE] [--native-agent main]\n${command.join(' ')} run --agent UUID\n${command.join(' ')} doctor --agent UUID\n${command.join(' ')} status --agent UUID\n${command.join(' ')} disconnect --agent UUID\nAdvanced: use --directory PATH for an existing private state directory. Keep its journal to recover original tasks.`;
 const output = (value) => console.log(JSON.stringify(value, null, 2));
 export async function runConnectorCli(args, commandPrefix = ['envar-connect']) {
@@ -86,7 +87,9 @@ export async function runConnectorCli(args, commandPrefix = ['envar-connect']) {
     }
     if (command === 'doctor') {
         const connection = await client.status(), runtime = await runtimeAdapter(directory, config).probe();
-        output({ connection_id: connection.id, agent_id: connection.agent_id, runtime,
+        const reporting = await client.reportRuntime(runtime);
+        output({ connection_id: connection.id, agent_id: connection.agent_id, connector_version: CONNECTOR_VERSION, runtime,
+            runtime_version_source: 'agent_card', diagnostic_reporting: reporting,
             readiness: connection.readiness, next: 'Send the free test from the Envar Agent page and inspect its returned result.' });
         return;
     }

package/dist/connector/client.d.ts

@@ -1,4 +1,6 @@
 import type { Claim, ConfirmOrderResult, ExecutionRef, Inbox, Order, Report, ServiceConfirmation, ServiceQuoteRequest, Submit, Work } from './contracts.generated.js';
+import type { RuntimeReadiness } from '../adapters/types.js';
+import { type RelayCommand, type RelayEvent } from './relay-types.js';
 export declare function validate<T>(kind: string, value: unknown): T;
 export declare class WorkApiError extends Error {
     readonly status: number;
@@ -35,7 +37,17 @@ export declare class EnvarWorkClient {
         credential_revoked: boolean;
         connection_revoked: boolean;
     }>;
+    relayHello(cardDigest: string): Promise<boolean>;
+    relayCommands(): Promise<RelayCommand[]>;
+    relayCommand(commandId: string): Promise<RelayCommand>;
+    relayOperation(commandId: string, operation: 'claim' | 'admit' | 'lease' | 'recover', body: unknown): Promise<RelayCommand>;
+    relayEvent(commandId: string, event: RelayEvent): Promise<{
+        result_digest: string;
+        state: string;
+    }>;
+    relayAck(commandId: string, body: unknown): Promise<void>;
     status(): Promise<ConnectionStatus>;
+    reportRuntime(runtime: RuntimeReadiness): Promise<'accepted' | 'unsupported' | 'unavailable'>;
     peers(): Promise<{
         items: {
             agent_id: string;

package/dist/connector/client.js

@@ -3,6 +3,8 @@ import { readFileSync } from 'node:fs';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormatsImport from 'ajv-formats';
 import { digest } from '../shared/json.js';
+import { runtimeReport } from './runtime-report.js';
+import { relayCommand } from './relay-types.js';
 const ajv = new Ajv2020({ allErrors: false, strict: true });
 addFormatsImport(ajv);
 const schema = JSON.parse(readFileSync(new URL('../../contracts/agent-work/v1/schema.json', import.meta.url), 'utf8'));
@@ -45,14 +47,14 @@ export class EnvarWorkClient {
         this.token = token;
         this.fetchImpl = options.fetch ?? fetch;
     }
-    async request(path, body, key, method) {
+    async request(path, body, key, method, maximum = 262144) {
         if (!path.startsWith('/api/v1/'))
             throw new Error('Invalid application route');
         const headers = new Headers({ Authorization: `Bearer ${this.token}`, Accept: 'application/json' });
         if (key)
             headers.set('Idempotency-Key', id(key));
         const encoded = body === undefined ? undefined : JSON.stringify(body);
-        if (encoded && Buffer.byteLength(encoded) > 262144)
+        if (encoded && Buffer.byteLength(encoded) > maximum)
             throw new Error('Work request exceeds the size limit');
         if (encoded)
             headers.set('Content-Type', 'application/json');
@@ -89,12 +91,73 @@ export class EnvarWorkClient {
     async disconnect() {
         return await this.request('/api/v1/agent-connections/current/credential', {}, undefined, 'DELETE');
     }
+    async relayHello(cardDigest) {
+        try {
+            const value = await this.request('/api/v1/connector/a2a-relay/hello', {
+                relay_version: '1', a2a_wire_version: '1.0', runtime_card_digest: cardDigest,
+                capabilities: { get: true, input: false, cancel: false, artifacts: false, streaming: false,
+                    task_lookup_after_restart: false, execution_key_lookup: false }, max_concurrency: 1,
+            });
+            if (value.relay_version !== '1')
+                throw new Error('Unsupported relay handshake');
+            return true;
+        }
+        catch (error) {
+            if (error instanceof WorkApiError && [404, 405, 409].includes(error.status))
+                return false;
+            throw error;
+        }
+    }
+    async relayCommands() {
+        const result = await this.request('/api/v1/connector/a2a-relay/commands?limit=1');
+        if (!Array.isArray(result?.items) || result.items.length > 1)
+            throw new Error('Invalid relay command page');
+        return result.items.map(relayCommand);
+    }
+    async relayCommand(commandId) {
+        const result = relayCommand(await this.request(`/api/v1/connector/a2a-relay/commands/${id(commandId)}`));
+        if (result.command_id !== commandId)
+            throw new Error('Envar returned another original relay command');
+        return result;
+    }
+    async relayOperation(commandId, operation, body) {
+        const result = relayCommand(await this.request(`/api/v1/connector/a2a-relay/commands/${id(commandId)}/${operation}`, body));
+        if (result.command_id !== commandId)
+            throw new Error('Envar returned another original relay command');
+        return result;
+    }
+    async relayEvent(commandId, event) {
+        const result = await this.request(`/api/v1/connector/a2a-relay/commands/${id(commandId)}/events`, event, undefined, undefined, 5243904);
+        if (result.event_id !== event.event_id || result.last_committed_sequence < event.sequence)
+            throw new Error('Relay did not persist the original event');
+        return result;
+    }
+    async relayAck(commandId, body) {
+        const result = await this.request(`/api/v1/connector/a2a-relay/commands/${id(commandId)}/ack`, body);
+        if (result.command_id !== commandId || result.acknowledged !== true)
+            throw new Error('Relay did not acknowledge the original result');
+    }
     async status() {
         const value = await this.request('/api/v1/agent-connections/current');
         if (!value || !uuid.test(value.id) || !uuid.test(value.agent_id) || value.mode !== 'inbox' || value.status !== 'active')
             throw new Error('Reconnect this Agent to an active inbox');
         return value;
     }
+    async reportRuntime(runtime) {
+        const report = runtimeReport(runtime);
+        try {
+            await this.request('/api/v1/agent-connections/current/runtime', report);
+            return 'accepted';
+        }
+        catch (error) {
+            if (error instanceof WorkApiError && [401, 403].includes(error.status))
+                throw error;
+            if (error instanceof WorkApiError && [404, 405].includes(error.status))
+                return 'unsupported';
+            // Optional diagnostics must not block recovery of an already admitted task.
+            return 'unavailable';
+        }
+    }
     async peers() {
         const value = await this.request('/api/v1/agent-connections/peers');
         if (!value || !Array.isArray(value.items) || value.items.length > 100 || value.items.some(item => !uuid.test(item.agent_id) || !uuid.test(item.connection_id) || typeof item.display_name !== 'string'))

package/dist/connector/loop.d.ts

@@ -7,6 +7,7 @@ export declare class ConnectorLoop {
     readonly journal: ConnectorJournal;
     private running;
     private verified;
+    private readonly relay?;
     constructor(client: EnvarWorkClient, runtime: RuntimeAdapter, journal: ConnectorJournal);
     private lease;
     private withHeartbeat;

package/dist/connector/loop.js

@@ -3,6 +3,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { WorkApiError } from './client.js';
 import { NativeRequestNotStarted } from '../adapters/native-a2a.js';
 import { RuntimeControlUnsupported } from '../adapters/a2a-runtime.js';
+import { RelayLoop, relayBlocksDispatch } from './relay-loop.js';
 const terminal = new Set(['completed', 'failed', 'canceled']);
 const claimValue = (record) => ({ id: record.claim.id, fence: record.claim.fence });
 export class ConnectorLoop {
@@ -11,10 +12,13 @@ export class ConnectorLoop {
     journal;
     running = false;
     verified = false;
+    relay;
     constructor(client, runtime, journal) {
         this.client = client;
         this.runtime = runtime;
         this.journal = journal;
+        if (runtime.relay)
+            this.relay = new RelayLoop(client, runtime.relay, journal);
     }
     async lease(record, recover = false) {
         if (!record.claim)
@@ -222,7 +226,8 @@ export class ConnectorLoop {
                 if (status.id !== this.journal.binding.connectionId || status.agent_id !== this.journal.binding.agentId ||
                     this.runtime.key !== this.journal.binding.adapter)
                     throw new Error('Restore the original Agent/runtime binding');
-                await this.runtime.probe();
+                const readiness = await this.runtime.probe();
+                await this.client.reportRuntime(readiness);
                 this.verified = true;
             }
             let after = 0;
@@ -240,7 +245,8 @@ export class ConnectorLoop {
             const active = this.journal.pending().filter(record => record.phase !== 'prepared');
             for (const record of active)
                 await this.advance(record);
-            if (!this.journal.pending().some(record => record.phase !== 'prepared')) {
+            await this.relay?.tick(!this.journal.pending().some(record => record.phase !== 'prepared'));
+            if (!this.journal.pending().some(record => record.phase !== 'prepared') && !this.journal.pendingRelay().some(relayBlocksDispatch)) {
                 const next = this.journal.pending().find(record => record.phase === 'prepared');
                 if (next)
                     await this.advance(next);

package/dist/connector/relay-loop.d.ts

@@ -0,0 +1,25 @@
+import type { RelayRuntime } from '../adapters/types.js';
+import { EnvarWorkClient } from './client.js';
+import type { ConnectorJournal } from './state.js';
+import type { RelayRecord } from './relay-types.js';
+export declare const relayBlocksDispatch: (record: RelayRecord) => boolean;
+/** Uses the existing journal and process lock; unknown sends never get another POST. */
+export declare class RelayLoop {
+    readonly client: EnvarWorkClient;
+    readonly runtime: RelayRuntime;
+    readonly journal: ConnectorJournal;
+    private lastHello;
+    private enabled;
+    constructor(client: EnvarWorkClient, runtime: RelayRuntime, journal: ConnectorJournal);
+    private queue;
+    private lease;
+    private heartbeat;
+    private flush;
+    private acknowledge;
+    private observed;
+    private unknown;
+    private claim;
+    private adoptOriginal;
+    private advance;
+    tick(allowNew: boolean): Promise<void>;
+}

package/dist/connector/relay-loop.js

@@ -0,0 +1,339 @@
+import { randomUUID } from 'node:crypto';
+import { digest } from '../shared/json.js';
+import { WorkApiError } from './client.js';
+const terminal = new Set(['TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED', 'TASK_STATE_REJECTED']);
+const taskState = (task) => String(task.status?.state);
+export const relayBlocksDispatch = (record) => !['received', 'events_acked'].includes(record.phase) &&
+    !(record.phase === 'terminal_saved' && !record.pending.length && record.command.state === 'completed' && Boolean(record.finalDigest));
+/** Uses the existing journal and process lock; unknown sends never get another POST. */
+export class RelayLoop {
+    client;
+    runtime;
+    journal;
+    lastHello = 0;
+    enabled = false;
+    constructor(client, runtime, journal) {
+        this.client = client;
+        this.runtime = runtime;
+        this.journal = journal;
+    }
+    queue(record, kind, payload, observation) {
+        if (!record.command.claim)
+            throw new Error('The original relay claim is required');
+        record.pending.push({ claim: record.command.claim, event_id: randomUUID(), sequence: record.nextEvent++,
+            control_generation: record.command.control_generation, kind, payload, payload_digest: digest(payload),
+            ...(observation === undefined ? {} : { observation_seq: observation }) });
+        this.journal.saveRelay(record);
+    }
+    async lease(record) {
+        const current = await this.client.relayCommand(record.command.command_id);
+        if (current.request_digest !== record.command.request_digest || current.claim?.id !== record.command.claim?.id || current.claim?.fence !== record.command.claim?.fence)
+            throw new Error('The original relay execution fence changed');
+        if (record.reference && current.native_reference && digest(record.reference) !== digest(current.native_reference))
+            throw new Error('The platform returned another original native reference');
+        const command = await this.client.relayOperation(record.command.command_id, 'recover', {
+            claim: record.command.claim, execution_key: record.executionKey, journal_phase: record.phase,
+            last_event_sequence: Math.max(record.nextEvent - 1, current.last_event_sequence),
+        });
+        if (command.request_digest !== record.command.request_digest || command.claim?.id !== record.command.claim?.id || command.claim?.fence !== record.command.claim?.fence)
+            throw new Error('The original relay execution fence changed');
+        record.command = command;
+        record.nextEvent = Math.max(record.nextEvent, command.last_event_sequence + 1);
+        record.nextObservation = Math.max(record.nextObservation, (command.last_observation_sequence ?? 0) + 1);
+        this.journal.saveRelay(record);
+    }
+    async heartbeat(record, operation) {
+        let active;
+        const timer = setInterval(() => {
+            if (!active)
+                active = this.lease(record).catch(() => {
+                    // The native result is still preserved; flush revalidates the original authority.
+                }).finally(() => { active = undefined; });
+        }, 40000);
+        try {
+            return await operation();
+        }
+        finally {
+            clearInterval(timer);
+            await active;
+        }
+    }
+    async flush(record) {
+        if (!record.pending.length)
+            return;
+        await this.lease(record);
+        while (record.pending.length) {
+            const event = record.pending[0];
+            let receipt;
+            try {
+                receipt = await this.client.relayEvent(record.command.command_id, event);
+            }
+            catch (error) {
+                if (!(error instanceof WorkApiError) || ![400, 413].includes(error.status) || event.kind === 'outcome_unknown')
+                    throw error;
+                // A confirmed schema/size rejection did not commit this event. Keep
+                // the rejected payload locally and report a bounded uncertainty at
+                // the same sequence so original Task reads can continue.
+                record.rejectedEvents ??= [];
+                if (!record.rejectedEvents.some(item => item.payload_digest === event.payload_digest))
+                    record.rejectedEvents = [...record.rejectedEvents.slice(-19), event];
+                const payload = { reason: 'receipt_incomplete' };
+                record.pending = [{ claim: event.claim, event_id: randomUUID(), sequence: event.sequence,
+                        control_generation: event.control_generation, kind: 'outcome_unknown', payload, payload_digest: digest(payload) }];
+                record.nextEvent = event.sequence + 1;
+                record.phase = 'outcome_unknown';
+                record.finalReadPending = false;
+                this.journal.saveRelay(record);
+                continue;
+            }
+            record.pending.shift();
+            if (receipt.result_digest)
+                record.finalDigest = receipt.result_digest;
+            if (receipt.state)
+                record.command.state = receipt.state;
+            if (receipt.state === 'unknown' && record.phase === 'terminal_saved')
+                record.phase = 'outcome_unknown';
+            this.journal.saveRelay(record);
+        }
+    }
+    async acknowledge(record) {
+        if (!record.finalDigest || record.pending.length || !['terminal_saved', 'outcome_unknown'].includes(record.phase))
+            return;
+        if (record.finalReadPending && record.reference) {
+            await this.lease(record);
+            const observation = record.nextObservation++;
+            this.journal.saveRelay(record);
+            let original;
+            try {
+                original = await this.heartbeat(record, () => this.runtime.read(record.reference));
+            }
+            catch { /* Retry this original verification read; do not repeat its send. */ }
+            if (original) {
+                // The obligation and its evidence share one durable journal write.
+                record.finalReadPending = false;
+                this.queue(record, 'task_snapshot', original, observation);
+                await this.flush(record);
+            }
+        }
+        const sequence = record.nextEvent - 1;
+        if (record.acknowledgedSequence === sequence)
+            return;
+        await this.client.relayAck(record.command.command_id, { claim: record.command.claim, last_event_sequence: sequence, result_digest: record.finalDigest });
+        record.acknowledgedSequence = sequence;
+        if (record.phase === 'terminal_saved' && !record.finalReadPending)
+            record.phase = 'events_acked';
+        this.journal.saveRelay(record);
+    }
+    async observed(record, result, observation) {
+        if (result.reference) {
+            if (record.reference && digest(record.reference) !== digest(result.reference))
+                throw new Error('Native reference changed');
+            if (!record.reference) {
+                record.reference = result.reference;
+                this.queue(record, 'native_reference', { ...result.reference });
+            }
+        }
+        record.result = result.task ? { task: result.task } : { message: result.message };
+        record.phase = 'native_ref_saved';
+        this.journal.saveRelay(record);
+        if (result.task) {
+            if (!record.reference || result.task.id !== record.reference.task_id || result.task.contextId !== record.reference.context_id)
+                throw new Error('Native response does not belong to the original Task and context');
+            this.queue(record, 'task_snapshot', result.task, observation);
+            record.phase = terminal.has(taskState(result.task)) ? 'terminal_saved' : 'observing';
+        }
+        else if (result.message) {
+            this.queue(record, 'delivery_receipt', { message: result.message }, observation);
+            record.phase = 'terminal_saved';
+        }
+        else
+            throw new Error('Native response contains no original Task or Message');
+        this.journal.saveRelay(record);
+        await this.flush(record);
+    }
+    async unknown(record, reason) {
+        if (record.phase !== 'outcome_unknown') {
+            record.phase = 'outcome_unknown';
+            this.queue(record, 'outcome_unknown', { reason });
+        }
+        await this.flush(record);
+        await this.acknowledge(record);
+    }
+    async claim(record) {
+        try {
+            record.command = await this.client.relayOperation(record.command.command_id, 'claim', { request_id: record.claimRequestId });
+        }
+        catch (error) {
+            if (!(error instanceof WorkApiError) || error.status !== 409)
+                throw error;
+            const current = await this.client.relayCommand(record.command.command_id);
+            if (current.request_digest !== record.command.request_digest)
+                throw new Error('The original relay command changed');
+            if (current.state !== 'canceled')
+                throw error;
+            record.phase = 'events_acked';
+            this.journal.saveRelay(record);
+            return false;
+        }
+        return true;
+    }
+    adoptOriginal(record) {
+        if (record.command.native_reference)
+            record.reference = record.command.native_reference;
+        record.finalDigest = record.command.result_digest || record.finalDigest;
+        record.phase = record.command.state === 'canceled' ? 'events_acked'
+            : record.command.state === 'completed' ? 'terminal_saved'
+                : record.reference ? 'observing' : 'outcome_unknown';
+        // A stale local checkpoint cannot prove that the original lookup evidence
+        // was durably reported. Another GET is safe; another SendMessage is not.
+        if (record.reference && (record.phase === 'terminal_saved' || !record.command.last_observation_sequence))
+            record.finalReadPending = true;
+        this.journal.saveRelay(record);
+    }
+    async advance(record) {
+        let preparedDispatch;
+        if (record.command.kind !== 'send')
+            throw new Error('This Connector cannot execute unverified native controls');
+        if (record.pending.length) {
+            await this.flush(record);
+            await this.acknowledge(record);
+            return;
+        }
+        if (record.phase === 'terminal_saved') {
+            await this.acknowledge(record);
+            return;
+        }
+        if (record.phase === 'outcome_unknown')
+            await this.acknowledge(record);
+        if (record.phase === 'received') {
+            if (!await this.claim(record))
+                return;
+            record.phase = 'intent_persisted';
+            this.journal.saveRelay(record);
+        }
+        if (record.phase === 'intent_persisted') {
+            // Check the native Card before the first financial admission. This GET
+            // is safely repeatable and has not started an Agent task.
+            preparedDispatch = this.runtime.prepareSend ? await this.runtime.prepareSend(record.command.a2a.params) : undefined;
+            try {
+                record.command = await this.client.relayOperation(record.command.command_id, 'admit', { claim: record.command.claim, execution_key: record.executionKey });
+            }
+            catch (error) {
+                if (!(error instanceof WorkApiError) || error.status !== 409)
+                    throw error;
+                // Admission may have succeeded before its response was lost. Recover
+                // that exact execution; a changed key/fence cannot be substituted.
+                try {
+                    await this.lease(record);
+                }
+                catch (recoveryError) {
+                    if (!(recoveryError instanceof WorkApiError) || recoveryError.status !== 409)
+                        throw recoveryError;
+                    // A pre-admission lease may expire. The server permits a new fence
+                    // only while this same command has never crossed admission.
+                    record.claimRequestId = randomUUID();
+                    this.journal.saveRelay(record);
+                    if (!await this.claim(record))
+                        return;
+                    this.journal.saveRelay(record);
+                    return;
+                }
+            }
+            record.phase = 'admitted';
+            this.journal.saveRelay(record);
+        }
+        if (record.phase === 'admitted') {
+            await this.lease(record);
+            // The platform may already know a result beyond this local checkpoint.
+            // Adopt only its original reference/receipt; never replay a known dispatch.
+            // Restored backups may predate the durable dispatch marker. An expired
+            // admission with no native evidence cannot prove that no POST occurred.
+            // Report and acknowledge uncertainty without making another send.
+            if (record.command.state === 'unknown' && !record.command.native_reference && !record.command.result_digest) {
+                await this.unknown(record, 'dispatch_uncertain');
+                return;
+            }
+            if (record.command.native_reference || record.command.state !== 'admitted') {
+                this.adoptOriginal(record);
+                await this.acknowledge(record);
+                return;
+            }
+            const dispatch = preparedDispatch ?? (this.runtime.prepareSend ? await this.heartbeat(record, () => this.runtime.prepareSend(record.command.a2a.params))
+                : () => this.runtime.send(record.command.a2a.params));
+            await this.lease(record);
+            record.phase = 'dispatch_started';
+            const observation = record.nextObservation++;
+            this.journal.saveRelay(record); // FULL synchronous SQLite commit precedes POST.
+            let result;
+            try {
+                result = await this.heartbeat(record, dispatch);
+            }
+            catch {
+                await this.unknown(record, 'dispatch_uncertain');
+                return;
+            }
+            // Even an immediately terminal Task gets one original GetTask readback.
+            // This also supplies the explicit native lookup evidence for enrollment.
+            record.finalReadPending = Boolean(result.task && terminal.has(taskState(result.task)));
+            await this.observed(record, result, observation);
+            await this.acknowledge(record);
+            return;
+        }
+        if (record.phase === 'dispatch_started' && !record.reference && !record.result) {
+            await this.lease(record);
+            if (record.command.native_reference || record.command.result_digest || record.command.state === 'canceled') {
+                this.adoptOriginal(record);
+                await this.acknowledge(record);
+                return;
+            }
+            await this.unknown(record, 'dispatch_uncertain');
+            return;
+        }
+        if (record.phase === 'native_ref_saved' && record.result) {
+            await this.observed(record, { ...record.result, ...(record.reference ? { reference: record.reference } : {}) }, record.nextObservation - 1);
+            return;
+        }
+        if (record.reference) {
+            await this.lease(record);
+            const observation = record.nextObservation++;
+            this.journal.saveRelay(record);
+            let task;
+            try {
+                task = await this.heartbeat(record, () => this.runtime.read(record.reference));
+            }
+            catch {
+                await this.unknown(record, 'native_task_unavailable');
+                return;
+            }
+            await this.observed(record, { task, reference: record.reference }, observation);
+            await this.acknowledge(record);
+        }
+    }
+    async tick(allowNew) {
+        let handshakeError;
+        if (Date.now() - this.lastHello > 20000) {
+            try {
+                this.enabled = await this.client.relayHello(await this.runtime.cardDigest());
+            }
+            catch (error) {
+                if (error instanceof WorkApiError && [401, 403].includes(error.status))
+                    throw error;
+                this.enabled = false;
+                handshakeError = error;
+            }
+            this.lastHello = Date.now();
+        }
+        if (this.enabled)
+            for (const command of await this.client.relayCommands())
+                this.journal.ingestRelay(command);
+        for (const record of this.journal.pendingRelay().filter(value => value.phase !== 'received'))
+            await this.advance(record);
+        if (allowNew && !this.journal.pendingRelay().some(relayBlocksDispatch)) {
+            const next = this.journal.pendingRelay().find(value => value.phase === 'received');
+            if (next && this.enabled)
+                await this.advance(next);
+        }
+        if (handshakeError)
+            throw handshakeError;
+    }
+}

package/dist/connector/relay-types.d.ts

@@ -0,0 +1,62 @@
+export interface RelayClaim {
+    id: string;
+    fence: number;
+}
+export interface RelayReference {
+    origin: string;
+    interface: string;
+    task_id: string;
+    context_id: string;
+}
+export interface RelayCommand {
+    relay_version: '1';
+    command_id: string;
+    connection_id: string;
+    binding_id: string;
+    work_id: string;
+    sequence: number;
+    kind: 'send' | 'input' | 'cancel' | 'get';
+    request_digest: string;
+    control_generation: number;
+    a2a: {
+        method: string;
+        params: Record<string, unknown>;
+    };
+    state: string;
+    last_event_sequence: number;
+    lease_until: string | null;
+    result_digest: string;
+    claim: RelayClaim | null;
+    admission_ref: string | null;
+    native_reference?: RelayReference | null;
+    last_observation_sequence?: number;
+}
+export interface RelayEvent {
+    claim: RelayClaim;
+    event_id: string;
+    sequence: number;
+    control_generation: number;
+    observation_seq?: number;
+    kind: 'native_reference' | 'task_snapshot' | 'delivery_receipt' | 'outcome_unknown';
+    payload: Record<string, unknown>;
+    payload_digest: string;
+}
+export interface RelayRecord {
+    command: RelayCommand;
+    phase: 'received' | 'intent_persisted' | 'admitted' | 'dispatch_started' | 'native_ref_saved' | 'observing' | 'outcome_unknown' | 'terminal_saved' | 'events_acked';
+    claimRequestId: string;
+    executionKey: string;
+    reference?: RelayReference;
+    nextEvent: number;
+    nextObservation: number;
+    pending: RelayEvent[];
+    result?: {
+        task?: Record<string, unknown>;
+        message?: Record<string, unknown>;
+    };
+    finalDigest?: string;
+    acknowledgedSequence?: number;
+    finalReadPending?: boolean;
+    rejectedEvents?: RelayEvent[];
+}
+export declare function relayCommand(value: unknown): RelayCommand;

package/dist/connector/relay-types.js

@@ -0,0 +1,19 @@
+/** The relay envelope carries standard A2A 1.0; it is not another agent protocol. */
+import { digest } from '../shared/json.js';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function relayCommand(value) {
+    const command = value;
+    if (!command || command.relay_version !== '1' ||
+        ![command.command_id, command.connection_id, command.binding_id, command.work_id].every(id => typeof id === 'string' && uuid.test(id)) ||
+        !Number.isSafeInteger(command.sequence) || command.sequence < 1 ||
+        !Number.isSafeInteger(command.control_generation) || command.control_generation < 0 ||
+        !Number.isSafeInteger(command.last_event_sequence) || command.last_event_sequence < 0 ||
+        !['pending', 'claimed', 'admitted', 'observing', 'completed', 'unknown', 'canceled'].includes(command.state) ||
+        !command.a2a || typeof command.a2a.params !== 'object' || command.a2a.params === null ||
+        ({ send: 'SendMessage', input: 'SendMessage', cancel: 'CancelTask', get: 'GetTask' })[command.kind] !== command.a2a.method ||
+        digest({ kind: command.kind, method: command.a2a.method, params: command.a2a.params, binding: command.binding_id }) !== command.request_digest)
+        throw new Error('Invalid original A2A relay command');
+    if (command.claim && (!uuid.test(command.claim.id) || !Number.isSafeInteger(command.claim.fence) || command.claim.fence < 1))
+        throw new Error('Invalid original relay claim');
+    return command;
+}

package/dist/connector/runtime-report.d.ts

@@ -0,0 +1,18 @@
+import type { RuntimeReadiness } from '../adapters/types.js';
+export declare const CONNECTOR_VERSION: string;
+export declare function runtimeReport(runtime: RuntimeReadiness): {
+    schema_version: number;
+    connector_version: string;
+    adapter: string;
+    runtime_version: string;
+    version_source: string;
+    capabilities: {
+        task_lookup: boolean;
+        task_lookup_after_restart: boolean;
+        execution_key_lookup: boolean;
+        result_persistence: boolean;
+        input: boolean;
+        cancel: boolean;
+        max_concurrency: number;
+    };
+};

package/dist/connector/runtime-report.js

@@ -0,0 +1,25 @@
+/** Diagnostics are receiver reports, never a grant or proof of task completion. */
+import { readFileSync } from 'node:fs';
+export const CONNECTOR_VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+const version = (value) => /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$/.test(value) ? value : 'unknown';
+export function runtimeReport(runtime) {
+    const concurrency = runtime.maxConcurrency ?? 1;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 64)
+        throw new Error('Use a bounded runtime concurrency limit');
+    return {
+        schema_version: 1,
+        connector_version: CONNECTOR_VERSION,
+        adapter: runtime.adapter,
+        runtime_version: version(runtime.runtimeVersion),
+        version_source: 'agent_card',
+        capabilities: {
+            task_lookup: runtime.capabilities.recover,
+            task_lookup_after_restart: runtime.recovery?.taskLookupAfterRestart ?? false,
+            execution_key_lookup: runtime.recovery?.executionKeyLookup ?? false,
+            result_persistence: runtime.recovery?.resultPersistence ?? false,
+            input: runtime.capabilities.input,
+            cancel: runtime.capabilities.cancel,
+            max_concurrency: concurrency,
+        },
+    };
+}

package/dist/connector/state.d.ts

@@ -1,5 +1,6 @@
 import type { Claim, Delivery, Report, Work } from './contracts.generated.js';
 import type { RuntimeObservation, RuntimeReference } from '../adapters/types.js';
+import { type RelayCommand, type RelayRecord } from './relay-types.js';
 export type Phase = 'prepared' | 'claimed' | 'admitted' | 'dispatching' | 'running' | 'waiting_input' | 'report_pending' | 'unknown' | 'terminal';
 export interface LocalWork {
     work: Work;
@@ -53,5 +54,9 @@ export declare class ConnectorJournal {
     saveControl(control: LocalControl): void;
     queueReport(record: LocalWork, kind: Report['kind'], text: string, afterReport: Phase, observation?: unknown, eventId?: string): void;
     sameObservation(record: LocalWork, observation: unknown): boolean;
+    ingestRelay(value: RelayCommand): RelayRecord;
+    getRelay(id: string): RelayRecord | undefined;
+    saveRelay(record: RelayRecord): void;
+    pendingRelay(): RelayRecord[];
     close(): void;
 }

package/dist/connector/state.js

@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { DatabaseSync } from 'node:sqlite';
+import { relayCommand } from './relay-types.js';
 const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 function parseStored(value) {
     try {
@@ -42,6 +43,7 @@ export class ConnectorJournal {
       CREATE TABLE IF NOT EXISTS connector_outgoing (id TEXT PRIMARY KEY,request TEXT NOT NULL,work TEXT);
       CREATE TABLE IF NOT EXISTS connector_control (id INTEGER PRIMARY KEY,value TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS connector_order_request (id TEXT PRIMARY KEY,request TEXT NOT NULL,order_id TEXT);
+      CREATE TABLE IF NOT EXISTS connector_relay (id TEXT PRIMARY KEY,phase TEXT NOT NULL,value TEXT NOT NULL,created INTEGER NOT NULL);
       CREATE INDEX IF NOT EXISTS connector_work_phase ON connector_work(phase,created);`);
         const existing = this.db.prepare("SELECT value FROM connector_meta WHERE key='binding'").get();
         if (existing && existing.value !== JSON.stringify(binding)) {
@@ -228,6 +230,35 @@ export class ConnectorJournal {
         this.save(record);
     }
     sameObservation(record, observation) { return record.lastObservation === digest(observation); }
+    ingestRelay(value) {
+        const command = relayCommand(value);
+        if (command.connection_id !== this.binding.connectionId)
+            throw new Error('Relay belongs to another original connection');
+        const prior = this.getRelay(command.command_id);
+        if (prior) {
+            if (prior.command.request_digest !== command.request_digest || prior.command.binding_id !== command.binding_id)
+                throw new Error('The original relay command changed');
+            return prior;
+        }
+        if (command.claim || !['pending', 'canceled'].includes(command.state))
+            throw new Error('Restore the original relay journal before recovering an admitted command');
+        const created = { command, phase: command.state === 'canceled' ? 'events_acked' : 'received', claimRequestId: randomUUID(),
+            executionKey: command.command_id, nextEvent: 1, nextObservation: 1, pending: [] };
+        this.saveRelay(created);
+        return created;
+    }
+    getRelay(id) {
+        const row = this.db.prepare('SELECT value FROM connector_relay WHERE id=?').get(id);
+        return row ? parseStored(String(row.value)) : undefined;
+    }
+    saveRelay(record) {
+        this.db.prepare('INSERT INTO connector_relay VALUES (?,?,?,?) ON CONFLICT(id) DO UPDATE SET phase=excluded.phase,value=excluded.value')
+            .run(record.command.command_id, record.phase, JSON.stringify(record), Date.now());
+    }
+    pendingRelay() {
+        return this.db.prepare("SELECT value FROM connector_relay WHERE phase!='events_acked' ORDER BY created").all()
+            .map(row => parseStored(String(row.value)));
+    }
     close() {
         this.db.close();
         try {

package/docs/a2a-relay.md

@@ -0,0 +1,35 @@
+# Outbound standard A2A relay
+
+A compatible Envar server can negotiate `a2a-relay.v1` alongside Agent Work v1.
+The transport carries standard A2A 1.0 requests and Task/Message responses;
+it is not an arbitrary TCP tunnel and requires no public port on the Agent.
+The receiver validates the original command, persists its execution checkpoint
+before a native send, and preserves ordered receipts and the original Task ID
+in the existing private SQLite journal.
+
+Only one native execution runs at a time. Unknown outcomes block new execution.
+Lost responses are recovered with the original Task reference when available,
+never by creating another Task. Restoring an old journal backup is not proof
+that an admitted task was never dispatched: an expired admission without native
+evidence is reported as unknown and requires original-task recovery or an
+explicit audited resolution. Do not delete the journal or clear unknown records
+to make an upgrade appear successful.
+
+A native Card lookup that fails before admission is retryable. Once a send may
+have occurred, only its durable receipts and original GetTask can advance the
+record. Permanent oversized/schema-rejected snapshots remain in the private
+journal and produce a bounded incomplete-receipt report, rather than silently
+claiming completion. Immediately completed Tasks and recovered reference-only
+Tasks retain the required original lookup evidence for platform enrollment.
+
+The owner selects and tests an explicitly free service before the platform
+advertises it through its public Card. Marketplace orders use the same frozen
+order authorization; the connection itself grants no spending authority.
+Private inventory and legacy paid workflows retain Agent Work v1 until their
+buyer-only artifact contract is separately verified.
+
+This release declares original Task lookup only. Native input, admitted-task
+cancellation, durable lookup after native runtime restart, media artifacts and
+streaming remain unverified and disabled. A package version or Card claim alone
+cannot enable these capabilities. Upgrade through the existing connection
+instructions, preserving credentials, native binding, SQLite journal and lock.

package/docs/compatibility.md

@@ -3,7 +3,7 @@
 Install the release documented by this checkout:
 
 ```sh
-npm install --global --ignore-scripts @envarai/connect@2026.1107.2
+npm install --global --ignore-scripts @envarai/connect@2026.1110.1
 envar-connect --version
 ```
 

package/docs/native-connector.md

@@ -18,7 +18,7 @@ Replace `CONTAINER` with your container name. Run `node --version` there. On a l
 Create a private Envar Agent and copy its connection command. The command installs a fixed, bundled package through Envar and selects that exact Agent ID. The official npm package is also available:
 
 ```sh
-npm install --prefix "$HOME/.envarpay/cli" --ignore-scripts --no-audit --no-fund @envarai/connect@2026.1107.2
+npm install --prefix "$HOME/.envarpay/cli" --ignore-scripts --no-audit --no-fund @envarai/connect@2026.1110.1
 "$HOME/.envarpay/cli/node_modules/.bin/envar-connect" connect --agent AGENT_UUID --framework hermes
 ```
 

package/docs/runtime-diagnostics.md

@@ -0,0 +1,59 @@
+# Runtime diagnostics
+
+`envar-connect doctor` and receiver startup report the installed Connector version,
+the native Agent Card's version and separate recovery capabilities to the original
+Envar connection. They do not invoke a model, create a task or grant permissions.
+`doctor` now writes this bounded diagnostic report to Envar as well as printing it
+locally. A real task/result test is still required to verify delivery.
+
+The authenticated endpoint is `POST /api/v1/agent-connections/current/runtime`.
+It requires the original native inbox connection's `connection:read`,
+`work:receive` and `work:report` scopes. The report contains no native URL,
+credential, local profile path, prompt or result. Envar timestamps it and labels it
+as a receiver report; the report cannot set online/verified state, change a
+spending grant or enable concurrency.
+
+```json
+{
+  "schema_version": 1,
+  "connector_version": "<installed package version>",
+  "adapter": "hermes",
+  "runtime_version": "<version reported by the Agent Card, or unknown>",
+  "version_source": "agent_card",
+  "capabilities": {
+    "task_lookup": true,
+    "task_lookup_after_restart": false,
+    "execution_key_lookup": false,
+    "result_persistence": false,
+    "input": false,
+    "cancel": false,
+    "max_concurrency": 1
+  }
+}
+```
+
+The Card version may describe its A2A implementation rather than the native CLI
+release. Do not present it as a separately verified installation version. Missing
+or invalid version text is reported as `unknown`.
+
+The original `RuntimeReadiness.capabilities.recover` flag means that the adapter
+can query a saved original Task reference. It does not imply that the gateway
+preserves that Task after a restart. Optional `recovery` fields describe the
+additional guarantees independently. Unspecified guarantees are false. The
+current adapters keep these additional guarantees unconfirmed until their exact
+runtime versions and failure windows have been validated; some newer upstream
+implementations already persist terminal results, which is not the same as
+recovering an interrupted in-flight execution.
+
+Older Envar deployments may return 404/405; `doctor` then prints
+`diagnostic_reporting: unsupported`. A temporary diagnostics failure prints
+`unavailable` and does not block existing task recovery. Revoked or forbidden
+credentials still stop the receiver. Reports are sampled at receiver startup or
+an explicit `doctor` run, not treated as a continuously refreshed health signal.
+
+When upgrading, stop the original receiver, preserve its private state directory,
+install the reviewed package and restart against that same directory. Check
+`doctor`, then verify the original pending task/result before starting new work.
+Do not delete the journal, replace the Agent identity or replay an unknown native
+request to make an upgrade appear successful. Roll back only to a version that
+has passed journal/contract compatibility checks for the same state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/connect",
-  "version": "2026.1107.2",
+  "version": "2026.1110.1",
   "description": "Connect your own Agent to Envar: tasks, native adapters and recovery",
   "type": "module",
   "license": "MIT",