@envarai/envarpay 0.2.0-alpha.17 → 0.2.0-alpha.19

package/README.md

@@ -13,6 +13,11 @@ not evidence that its npm/OCI artifact is published.
 
 For Hermes onboarding, see [guided Skill setup](../../docs/hermes-skill-setup.md). The `setup --file ...` command reads the owner's local model configuration and creates a private seller with an empty catalog, ready for the first service to be configured in Envar.
 
+The experimental `external-setup` and `external-serve` commands connect an existing
+external Agent through scoped MCP tasks/events and a free A2A entry. See
+[external Agent acceptance](../../docs/external-agents.md) for OAuth pairing,
+Skill discovery, restart and the required real execution evidence.
+
 Node.js 22.14+ (Node 24 recommended). SQLite is single-instance. Contracts can be
 read without loading the seller or buyer runtime; Bun validation covers the
 contracts entry, not the SQLite server.

package/dist/commerce/card.js

@@ -14,7 +14,7 @@ export function createOfferCard(config, serviceId, offerId, origin) {
     if (!service || !offer)
         throw new CommerceError('offer_not_found', 'Service offer not found');
     const profile = offer.paymentProfile ? config.paymentProfiles[offer.paymentProfile] : null;
-    const payment = profile?.adapter === 'x402' ? { adapter: 'x402', network: profile.network, asset: profile.asset, payTo: profile.payTo } : profile ? { adapter: 'mpp', method: 'stripe', intent: 'charge', currency: profile.currency } : null;
+    const payment = profile?.adapter === 'x402' ? { adapter: 'x402', network: profile.network, asset: profile.asset, payTo: profile.payTo } : profile?.adapter === 'envar_balance' ? { adapter: 'envar_balance', currency: 'usd', accountRef: profile.accountRef } : profile ? { adapter: 'mpp', method: 'stripe', intent: 'charge', currency: profile.currency } : null;
     return AgentCard.fromJSON({
         name: service.name,
         description: `Deliverables: ${service.contract.deliverables.join(', ')}`,

package/dist/commerce/cli.js

@@ -17,6 +17,7 @@ import { EnvarSellerRuntime, PinnedUpstreams, restoreEnvarConfig } from './envar
 import { listenCommerce } from './http.js';
 import { CredentialVault } from './vault.js';
 import { X402Gate } from './x402.js';
+import { EnvarBalanceGate } from './envar-balance.js';
 import { evmReceiptVerifier, evmSettlementRecovery } from './chain.js';
 import { CommerceError } from './types.js';
 import { createNativeSkillExecutor } from './native-skills.js';
@@ -26,6 +27,7 @@ import { setupAgent } from './setup.js';
 import { SkillDiscovery } from './discovery.js';
 import { upgradeDiscovery, configurePayments } from './configure.js';
 import { agentSetup } from './agent-setup.js';
+import { setupExternalAgent, serveExternalAgent } from './external-runtime.js';
 const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         config: { type: 'string' }, service: { type: 'string' }, offer: { type: 'string' }, origin: { type: 'string' },
         version: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, state: { type: 'string' }, credentials: { type: 'string' }, host: { type: 'string' },
@@ -33,7 +35,7 @@ const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         after: { type: 'string' }, limit: { type: 'string' }, 'refund-review': { type: 'boolean' }, alerts: { type: 'boolean' }, 'fail-on-alert': { type: 'boolean' }, 'integration-state': { type: 'string' }, 'no-integration': { type: 'boolean' },
         framework: { type: 'string' }, file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' }, check: { type: 'boolean' },
     } });
-const usage = 'envarpay onboard --file invitation.json [--framework hermes|openclaw] [--check] [--python PATH] [--docker-container NAME] [--hermes-home PATH] [--origin HTTPS_ORIGIN]\nenvarpay upgrade --directory DIR [--hermes-home PATH] | payments --directory DIR --file receiving.json\nenvarpay setup --file envar-setup.json [--docker-container NAME | --python PATH] [--hermes-home PATH] [--directory DIR]\ninit --directory DIR | inspect --state DB [--after ROW --limit 100 --refund-review] [--alerts --config buyer-policy.json --integration-state DB/--no-integration --fail-on-alert] | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
+const usage = 'envarpay external-setup --directory DIR --origin HTTPS_ORIGIN | external-serve --config FILE --credentials FILE --state DB --origin HTTPS_ORIGIN\nenvarpay onboard --file invitation.json [--framework hermes|openclaw] [--check] [--python PATH] [--docker-container NAME] [--hermes-home PATH] [--origin HTTPS_ORIGIN]\nenvarpay upgrade --directory DIR [--hermes-home PATH] | payments --directory DIR --file receiving.json\nenvarpay setup --file envar-setup.json [--docker-container NAME | --python PATH] [--hermes-home PATH] [--directory DIR]\ninit --directory DIR | inspect --state DB [--after ROW --limit 100 --refund-review] [--alerts --config buyer-policy.json --integration-state DB/--no-integration --fail-on-alert] | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
 const closers = [];
 function privateFile(path) {
     const stat = lstatSync(path);
@@ -93,6 +95,22 @@ async function run() {
         return;
     }
     const command = positionals[0];
+    if (command === 'external-setup') {
+        if (!values.directory || !values.origin)
+            throw new CommerceError('external_setup', 'Provide directory and public HTTPS origin');
+        console.log(JSON.stringify(setupExternalAgent(values.directory, values.origin)));
+        return;
+    }
+    if (command === 'external-serve') {
+        if (!values.config || !values.credentials || !values.state || !values.origin)
+            throw new CommerceError('external_serve', 'Provide config, credentials, state and origin');
+        const runtime = serveExternalAgent({ configFile: values.config, credentialsFile: values.credentials, stateFile: values.state, origin: values.origin, host: values.host ?? '127.0.0.1', port: port(4020) });
+        closers.push(() => runtime.close());
+        await once(runtime.http, 'listening');
+        signals();
+        console.log(JSON.stringify({ listening: port(4020), role: 'external-agent', paymentsEnabled: false }));
+        return;
+    }
     if (values.framework && !['hermes', 'openclaw'].includes(values.framework))
         throw new CommerceError('setup_runtime', 'Use hermes or openclaw');
     if (command === 'managed-serve') {
@@ -294,6 +312,11 @@ async function run() {
         gates.mpp = gate;
         stripeRecipientFor = ref => gate.merchantRecipient(ref);
     }
+    if (protocols.has('envar_balance')) {
+        if (!integration)
+            throw new CommerceError('balance_configuration', 'Envar balance requires an authenticated Envar seller integration');
+        gates.envar_balance = new EnvarBalanceGate({ store, vault: vault, claim: args => integration.claimBalancePayment(args) });
+    }
     const nativeSkills = secrets.skills ? createNativeSkillExecutor(secrets.skills, values.origin, config.agent.name) : undefined;
     const discovery = secrets.skills?.discovery?.enabledFromWeb ? new SkillDiscovery(secrets.skills, secrets.skills.discovery, values.origin) : undefined;
     if (nativeSkills)
@@ -308,6 +331,8 @@ async function run() {
                 throw new CommerceError('x402_configuration', 'Configure the required network RPC locally');
             if (profile.adapter === 'mpp' && !stripeRecipientFor?.(profile.accountRef))
                 throw new CommerceError('mpp_configuration', 'Configure and verify the merchant account locally');
+            if (profile.adapter === 'envar_balance' && !syncSettings?.policy.allowedBalanceAccounts?.includes(profile.accountRef))
+                throw new CommerceError('balance_configuration', 'Allow this balance receiving account locally');
         }
     };
     validateAdapters(config);

package/dist/commerce/config.js

@@ -135,6 +135,8 @@ export function loadCommerceConfig(value) {
                 throw new CommerceError('invalid_amount', 'Maximum total exceeds supported integer range');
             if (profile.adapter === 'mpp' && low < 50n)
                 throw new CommerceError('card_minimum', 'USD card orders must be at least 50 cents');
+            if (profile.adapter === 'envar_balance' && high > 2n ** 63n - 1n)
+                throw new CommerceError('balance_amount', 'Envar balance prices must fit signed micro-USD');
         }
     }
     return config;

package/dist/commerce/envar-balance.d.ts

@@ -0,0 +1,25 @@
+import { type PriceQuote } from './types.js';
+import { CommerceStore, type OrderRecord } from './store.js';
+import { CredentialVault } from './vault.js';
+export interface BalanceClaimArgs {
+    platformOrderId: string;
+    claimToken: string;
+    taskId: string;
+    quote: PriceQuote;
+}
+export interface EnvarBalanceGateOptions {
+    store: CommerceStore;
+    vault: CredentialVault;
+    claim: (args: BalanceClaimArgs) => Promise<Record<string, unknown>>;
+}
+export declare class EnvarBalanceGate {
+    private readonly options;
+    constructor(options: EnvarBalanceGateOptions);
+    private assertReceipt;
+    private settle;
+    handle(request: Request, order: OrderRecord): Promise<{
+        response: Response;
+    } | {
+        headers: Record<string, string>;
+    }>;
+}

package/dist/commerce/envar-balance.js

@@ -0,0 +1,65 @@
+/** Opt-in seller gate for a captured Envar account-balance claim. No x402 or MPP impersonation. */
+import { digest } from './config.js';
+import { CommerceError } from './types.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export class EnvarBalanceGate {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    assertReceipt(order, platformOrderId, receipt) {
+        const quote = order.quote, profile = quote.paymentProfile;
+        if (profile?.adapter !== 'envar_balance')
+            throw new CommerceError('balance_profile', 'Original quote is not an Envar balance offer');
+        if (receipt.state !== 'captured' || receipt.order_id !== platformOrderId ||
+            receipt.amount !== quote.amount || receipt.currency !== 'usd' || receipt.recipient !== profile?.accountRef ||
+            receipt.quote_id !== quote.quoteId || receipt.message_id !== quote.messageId ||
+            receipt.task_id !== order.taskId ||
+            receipt.service_id !== quote.serviceId || receipt.service_revision !== quote.serviceRevision ||
+            receipt.offer_id !== quote.offerId || receipt.input_digest !== quote.inputDigest ||
+            receipt.terms_digest !== quote.termsDigest ||
+            typeof receipt.economic_id !== 'string' || !/^ledger:[0-9a-f-]{36}$/i.test(receipt.economic_id))
+            throw new CommerceError('balance_receipt_mismatch', 'Platform capture differs from the frozen service order');
+    }
+    async settle(order, attemptId, saved) {
+        if (saved.quoteId !== order.quote.quoteId)
+            throw new CommerceError('balance_recovery_conflict', 'Original balance claim belongs to another quote');
+        let receipt;
+        try {
+            receipt = await this.options.claim({ platformOrderId: saved.platformOrderId, claimToken: saved.claimToken, taskId: order.taskId, quote: order.quote });
+            this.assertReceipt(order, saved.platformOrderId, receipt);
+        }
+        catch {
+            this.options.store.recordSettlement(attemptId, 'unknown', {});
+            return { response: Response.json({ error: 'balance_claim_unknown', taskId: order.taskId }, { status: 503, headers: { 'Cache-Control': 'no-store' } }) };
+        }
+        this.options.store.recordSettlement(attemptId, 'confirmed', receipt);
+        return { headers: { 'ENVAR-BALANCE-RECEIPT': String(receipt.economic_id) } };
+    }
+    async handle(request, order) {
+        const quote = order.quote, profile = quote.paymentProfile;
+        if (profile?.adapter !== 'envar_balance' || quote.currency !== 'usd' || quote.recipient !== profile.accountRef)
+            throw new CommerceError('balance_profile', 'This offer does not accept Envar account balance');
+        const prior = this.options.store.paymentForOrder(order.id);
+        if (order.paymentState === 'confirmed' && prior?.receipt)
+            return { headers: { 'ENVAR-BALANCE-RECEIPT': String(prior.receipt.economic_id) } };
+        if (['settling', 'unknown'].includes(order.paymentState)) {
+            if (!prior)
+                throw new CommerceError('balance_recovery_conflict', 'Original balance attempt is missing');
+            const saved = this.options.vault.get(prior.credentialRef);
+            return this.settle(order, prior.id, saved);
+        }
+        if (Date.now() >= Date.parse(quote.expiresAt))
+            return { response: Response.json({ error: 'quote_expired' }, { status: 409, headers: { 'Cache-Control': 'no-store' } }) };
+        const platformOrderId = request.headers.get('Envar-Balance-Order') ?? '';
+        const claimToken = request.headers.get('Envar-Balance-Claim') ?? '';
+        if (!platformOrderId && !claimToken)
+            return { response: Response.json({ error: 'envar_balance_required', taskId: order.taskId, quote: { quoteId: quote.quoteId, messageId: quote.messageId, serviceId: quote.serviceId, serviceRevision: quote.serviceRevision, offerId: quote.offerId, inputDigest: quote.inputDigest, termsDigest: quote.termsDigest, amount: quote.amount, currency: quote.currency, recipient: quote.recipient, expiresAt: quote.expiresAt } }, { status: 402, headers: { 'Cache-Control': 'no-store' } }) };
+        if (!UUID.test(platformOrderId) || claimToken.length < 32 || claimToken.length > 4096 || /\s/.test(claimToken))
+            throw new CommerceError('balance_claim', 'Use the original bounded platform balance claim');
+        const credentialRef = this.options.vault.put({ platformOrderId, claimToken, quoteId: quote.quoteId });
+        const economicKey = digest({ adapter: 'envar_balance', platformOrderId });
+        const attempt = this.options.store.reservePayment(order.id, order.caller, economicKey, credentialRef);
+        return this.settle(order, attempt, { platformOrderId, claimToken, quoteId: quote.quoteId });
+    }
+}

package/dist/commerce/envar.d.ts

@@ -16,6 +16,8 @@ export interface EnvarPolicy {
         facilitatorOrigin: string;
     }[];
     allowedMppAccounts: string[];
+    /** Explicit seller account references allowed to accept platform balance. */
+    allowedBalanceAccounts?: string[];
 }
 export interface EnvarCandidate {
     id: string;
@@ -81,6 +83,12 @@ export declare class EnvarIntegration {
     close(): void;
     private open;
     private request;
+    claimBalancePayment(args: {
+        platformOrderId: string;
+        claimToken: string;
+        taskId: string;
+        quote: PriceQuote;
+    }): Promise<Record<string, unknown>>;
     allowInstalledService(name: string): void;
     reportRuntime(value: unknown): Promise<{
         name: string;

package/dist/commerce/envar.js

@@ -136,6 +136,9 @@ export class EnvarIntegration {
         });
         if (this.policy.allowedMppAccounts.some((id) => !ID.test(id)))
             fail("envar_policy", "Configure explicit merchant account references");
+        this.policy.allowedBalanceAccounts ??= [];
+        if (this.policy.allowedBalanceAccounts.some((id) => !ID.test(id)))
+            fail("envar_policy", "Configure explicit balance account references");
         this.timeoutMs = options.timeoutMs ?? 10000;
         this.limitBytes = options.responseLimitBytes ?? 1048576;
         if (!Number.isInteger(this.timeoutMs) ||
@@ -214,12 +217,12 @@ export class EnvarIntegration {
     }
     async request(path, payload, eventId) {
         this.open();
-        if (![
+        if (!([
             "/api/v1/agent-config/candidates",
             "/api/v1/agent-config/acknowledgments",
             "/api/v1/commerce-reports",
             "/api/v1/agent-config/runtime",
-        ].includes(path))
+        ].includes(path) || /^\/api\/v1\/commerce\/payment-claims\/[0-9a-f-]{36}\/claim$/i.test(path)))
             fail("envar_path", "Unsupported platform integration operation");
         const token = await this.options.token();
         if (typeof token !== "string" ||
@@ -298,6 +301,19 @@ export class EnvarIntegration {
             fail("envar_response_json", "Platform response must be an object");
         return value;
     }
+    async claimBalancePayment(args) {
+        uuid(args.platformOrderId);
+        if (typeof args.claimToken !== 'string' || args.claimToken.length < 32 || args.claimToken.length > 4096 || /\s/.test(args.claimToken))
+            fail('envar_balance_claim', 'Use the original bounded platform claim');
+        return this.request(`/api/v1/commerce/payment-claims/${args.platformOrderId}/claim`, {
+            claim_token: args.claimToken, task_id: args.taskId,
+            quote_id: args.quote.quoteId, message_id: args.quote.messageId,
+            service_id: args.quote.serviceId, service_revision: args.quote.serviceRevision,
+            offer_id: args.quote.offerId, input_digest: args.quote.inputDigest,
+            terms_digest: args.quote.termsDigest, amount: args.quote.amount,
+            currency: args.quote.currency, recipient: args.quote.recipient,
+        }, args.platformOrderId);
+    }
     allowInstalledService(name) {
         if (!ID.test(name))
             fail('envar_policy', 'Invalid installed Skill name');
@@ -348,8 +364,10 @@ export class EnvarIntegration {
                     a.facilitatorOrigin === new URL(profile.facilitatorUrl).origin))
                     fail("envar_recipient_denied", "Receiving identity or facilitator is outside the local update grant");
             }
-            else if (!this.policy.allowedMppAccounts.includes(profile.accountRef))
+            else if (profile.adapter === "mpp" && !this.policy.allowedMppAccounts.includes(profile.accountRef))
                 fail("envar_merchant_denied", "Merchant account is outside the local update grant");
+            else if (profile.adapter === "envar_balance" && !this.policy.allowedBalanceAccounts.includes(profile.accountRef))
+                fail("envar_balance_denied", "Balance receiving account is outside the local update grant");
         }
         const prior = this.db
             .prepare("SELECT * FROM revisions WHERE id=? OR (local_service=? AND revision=?)")

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

@@ -0,0 +1,26 @@
+import { CommerceStore } from "./store.js";
+import type { ExecuteOrder } from "./server.js";
+export declare class ExternalAgentExecutor {
+    readonly store: CommerceStore;
+    readonly principal: string;
+    readonly services: readonly string[];
+    readonly execute: ExecuteOrder;
+    constructor(store: CommerceStore, principal: string, services: readonly string[]);
+    private context;
+    list(): {
+        taskId: string;
+        serviceId: string;
+        claimId: string;
+        state: "working" | "input_required" | "completed" | "failed" | "unknown" | "not_started" | "queued" | "dispatching" | "auth_required";
+        input: import("./types.js").Input;
+        paymentState: "not_required" | "quoted" | "settling" | "confirmed" | "rejected" | "unknown";
+    }[];
+    claim(taskId: string): Promise<{
+        taskId: string;
+        claimId: string;
+        input: import("./types.js").Input;
+        paymentState: "not_required" | "quoted" | "settling" | "confirmed" | "rejected" | "unknown";
+        state: "working" | "input_required" | "completed" | "failed" | "unknown" | "not_started" | "queued" | "dispatching" | "auth_required";
+    }>;
+    complete(taskId: string, claimId: string, text: string, failed?: boolean): Promise<unknown>;
+}

package/dist/commerce/external-agent.js

@@ -0,0 +1,129 @@
+/** User-operated external agents claim and complete the original, payment-gated commerce Task. */
+import { randomUUID } from "node:crypto";
+import { Task, TaskState } from "@a2a-js/sdk";
+import { ServerCallContext } from "@a2a-js/sdk/server";
+import { CommerceError } from "./types.js";
+export class ExternalAgentExecutor {
+    store;
+    principal;
+    services;
+    execute;
+    constructor(store, principal, services) {
+        this.store = store;
+        this.principal = principal;
+        this.services = services;
+        if (!principal ||
+            !services.length ||
+            services.some((s) => !/^[a-z][a-z0-9-]{0,63}$/.test(s)))
+            throw new CommerceError("external_scope", "Configure one agent principal and explicit services");
+        const self = this;
+        this.execute = async function* (order, service) {
+            if (!self.services.includes(service.id) ||
+                service.execution.type !== "a2a")
+                throw new CommerceError("external_scope", "This external agent cannot execute that service");
+            self.store.prepareExternalTask(order.id, self.principal);
+            const original = await self.store.load(order.taskId, self.context(order));
+            if (!original)
+                throw new CommerceError("external_task", "Original commerce Task missing");
+            yield Task.fromJSON({
+                ...Task.toJSON(original),
+                status: {
+                    state: "TASK_STATE_INPUT_REQUIRED",
+                    message: {
+                        messageId: randomUUID(),
+                        role: "ROLE_AGENT",
+                        parts: [
+                            {
+                                text: "Waiting for the connected external agent to claim this original Task.",
+                            },
+                        ],
+                    },
+                },
+                metadata: { externalAgent: self.principal },
+            });
+        };
+        this.execute.recover = async (order) => {
+            const task = await self.store.load(order.taskId, self.context(order));
+            if (!task)
+                throw new CommerceError("external_task", "Original commerce Task missing");
+            return task;
+        };
+    }
+    context(order) {
+        return new ServerCallContext({
+            user: { isAuthenticated: true, userName: order.caller },
+            tenant: order.serviceRevision,
+            requestedVersion: "1.0",
+        });
+    }
+    list() {
+        return this.store.externalTasks(this.principal, this.services).map((v) => ({
+            taskId: v.order.taskId,
+            serviceId: v.order.serviceRevision.split(":")[0],
+            claimId: v.claimId,
+            state: v.order.executionState,
+            input: v.order.input,
+            paymentState: v.order.paymentState,
+        }));
+    }
+    async claim(taskId) {
+        const value = this.store.claimExternalTask(taskId, this.principal, this.services);
+        const order = value.order;
+        const original = await this.store.load(taskId, this.context(order));
+        if (!original)
+            throw new CommerceError("external_task", "Original Task missing");
+        if (![TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_FAILED].includes(original.status?.state ?? 0))
+            await this.store.save(Task.fromJSON({
+                ...Task.toJSON(original),
+                status: { state: "TASK_STATE_WORKING" },
+                metadata: { ...original.metadata, externalAgent: this.principal },
+            }), this.context(order));
+        return {
+            taskId,
+            claimId: value.claimId,
+            input: order.input,
+            paymentState: order.paymentState,
+            state: order.executionState,
+        };
+    }
+    async complete(taskId, claimId, text, failed = false) {
+        if (typeof text !== "string" ||
+            !text.trim() ||
+            Buffer.byteLength(text) > 32000)
+            throw new CommerceError("external_result", "Return one bounded nonempty result");
+        const order = this.store.externalClaim(taskId, this.principal, claimId, this.services);
+        const original = await this.store.load(taskId, this.context(order));
+        if (!original)
+            throw new CommerceError("external_task", "Original Task missing");
+        const state = failed
+            ? TaskState.TASK_STATE_FAILED
+            : TaskState.TASK_STATE_COMPLETED;
+        if ([TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_FAILED].includes(original.status?.state ?? 0)) {
+            const previous = original.artifacts
+                .flatMap((a) => a.parts)
+                .map((p) => (p.content?.$case === "text" ? p.content.value : ""))
+                .join("\n");
+            if (original.status?.state !== state || previous !== text)
+                throw new CommerceError("external_result_conflict", "A completed original result cannot be replaced");
+            return Task.toJSON(original);
+        }
+        const result = Task.fromJSON({
+            ...Task.toJSON(original),
+            status: { state: failed ? "TASK_STATE_FAILED" : "TASK_STATE_COMPLETED" },
+            artifacts: [
+                {
+                    artifactId: "external-result",
+                    name: "external-agent-result.txt",
+                    parts: [{ text, mediaType: "text/plain" }],
+                },
+            ],
+            metadata: {
+                ...original.metadata,
+                externalAgent: this.principal,
+                claimId,
+            },
+        });
+        await this.store.save(result, this.context(order), original);
+        return Task.toJSON(result);
+    }
+}

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

@@ -0,0 +1,76 @@
+import { CredentialVault } from "./vault.js";
+import { ExternalAgentExecutor } from "./external-agent.js";
+import type { LookupFunction } from "node:net";
+export type CallbackLookup = (hostname: string) => Promise<readonly {
+    address: string;
+    family: number;
+}[]>;
+export declare const pinnedCallbackLookup: (address: {
+    address: string;
+    family: number;
+}) => LookupFunction;
+export declare function publicWebhook(url: string, body: string, headers: Record<string, string>, resolve?: CallbackLookup): Promise<{
+    status: number;
+    body: string;
+}>;
+export declare class ExternalAgentEvents {
+    private readonly agent;
+    private readonly vault;
+    private readonly webhook;
+    private readonly db;
+    private timer?;
+    private running;
+    constructor(path: string, agent: ExternalAgentExecutor, vault: CredentialVault, webhook?: typeof publicWebhook);
+    definition(): {
+        events: {
+            name: string;
+            description: string;
+            delivery: string[];
+            inputSchema: {
+                type: string;
+                properties: {
+                    agent_id: {
+                        type: string;
+                        const: string;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            payloadSchema: {
+                type: string;
+                properties: {
+                    agent_id: {
+                        type: string;
+                    };
+                    task_id: {
+                        type: string;
+                    };
+                    service_id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+        }[];
+    };
+    private identity;
+    private send;
+    subscribe(params: Record<string, any>, principal: string): Promise<{
+        id: string;
+        refreshBefore: string;
+        cursor: null;
+        truncated: boolean;
+    }>;
+    unsubscribe(params: Record<string, any>, principal: string): {};
+    start(): void;
+    tick(): Promise<void>;
+    inspect(): {
+        subscriptions: {
+            active: boolean;
+        }[];
+        deliveries: Record<string, import("node:sqlite").SQLOutputValue>[];
+    };
+    close(): Promise<void>;
+}