@envarai/envarpay 0.2.0-alpha.8 → 2026.1025.1

package/dist/commerce/discovery.js

@@ -0,0 +1,162 @@
+import { readSkillInventory } from "./native-inventory.js";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, mkdirSync, renameSync, rmSync, readdirSync, lstatSync, } from "node:fs";
+import { createHash } from 'node:crypto';
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { prepareTextSkill } from "./setup.js";
+import { readInstalledSkills } from "./native-skills.js";
+const exec = promisify(execFile);
+function packageDigest(root) {
+    const files = [];
+    let size = 0;
+    function walk(folder, prefix = '') {
+        if (prefix.split('/').length > 12)
+            throw Error('skill_size');
+        for (const name of readdirSync(folder).sort()) {
+            const path = join(folder, name), stat = lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw Error('skill_symlink');
+            if (stat.isDirectory()) {
+                walk(path, prefix + name + '/');
+                continue;
+            }
+            if (!stat.isFile() || stat.size > 512 * 1024 || (size += stat.size) > 1024 * 1024 || files.length >= 128)
+                throw Error('skill_size');
+            files.push([prefix + name, createHash('sha256').update(readFileSync(path)).digest('hex')]);
+        }
+    }
+    walk(root);
+    files.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const json = JSON.stringify(files).replace(/[\u007f-\uffff]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+    return createHash('sha256').update(json).digest('hex');
+}
+export class SkillDiscovery {
+    settings;
+    discovery;
+    origin;
+    enabled;
+    cached = [];
+    nextScan = 0;
+    state = "ready";
+    path;
+    constructor(settings, discovery, origin) {
+        this.settings = settings;
+        this.discovery = discovery;
+        this.origin = origin;
+        this.path = join(settings.skillsDirectory, ".source-digests.json");
+        this.enabled = existsSync(this.path)
+            ? JSON.parse(readFileSync(this.path, "utf8"))
+            : {};
+    }
+    async scan() {
+        if (this.discovery.roots && !this.settings.dockerContainer)
+            return readSkillInventory(this.discovery.roots);
+        const code = readFileSync(new URL("../../runtime/hermes-skill-inventory.py", import.meta.url), "utf8");
+        const args = ["-c", code, this.discovery.hermesHome];
+        const { stdout } = this.settings.dockerContainer
+            ? await exec("docker", [
+                "exec",
+                this.settings.dockerContainer,
+                this.settings.python,
+                ...args,
+            ], { timeout: 30000, maxBuffer: 1024 * 1024 })
+            : await exec(this.settings.python, args, {
+                timeout: 30000,
+                maxBuffer: 1024 * 1024,
+            });
+        const list = JSON.parse(stdout);
+        if (!Array.isArray(list) ||
+            list.length > 128 ||
+            list.some((s) => !/^[a-z][a-z0-9-]{0,63}$/.test(s.name) ||
+                !/^[0-9a-f]{64}$/.test(s.digest) ||
+                typeof s.path !== "string"))
+            throw Error("inventory");
+        return list;
+    }
+    async sync(integration) {
+        if (Date.now() >= this.nextScan) {
+            this.nextScan = Date.now() + 15000;
+            try {
+                this.cached = await this.scan();
+                this.state = "ready";
+            }
+            catch {
+                this.state = this.settings.dockerContainer
+                    ? "agent_unavailable"
+                    : "scan_failed";
+            }
+        }
+        const active = new Set(readdirSync(this.settings.skillsDirectory, { withFileTypes: true })
+            .filter((x) => x.isDirectory() && !x.name.startsWith("."))
+            .map((x) => x.name));
+        for (const skill of this.cached)
+            if (active.has(skill.name) && !this.enabled[skill.name])
+                this.enabled[skill.name] = skill.digest;
+        if (this.state === "ready")
+            writeFileSync(this.path, JSON.stringify(this.enabled), { mode: 0o600 });
+        const skills = this.cached.map((s) => ({
+            name: s.name,
+            digest: s.digest,
+            description: s.description,
+            status: !s.supported
+                ? "requires_adapter"
+                : active.has(s.name)
+                    ? this.enabled[s.name] && this.enabled[s.name] !== s.digest
+                        ? "updated"
+                        : "enabled"
+                    : "available",
+        }));
+        for (const name of active)
+            if (!skills.some((s) => s.name === name))
+                skills.push({
+                    name,
+                    digest: this.enabled[name] ?? "0".repeat(64),
+                    description: "",
+                    status: "removed",
+                });
+        const result = await integration.reportRuntime({
+            version: createRequire(import.meta.url)("../../package.json").version,
+            card_url: this.origin + "/.well-known/agent-card.json",
+            state: this.state,
+            skills: skills.slice(0, 128),
+        });
+        for (const request of result) {
+            const skill = this.cached.find((s) => s.name === request.name && s.digest === request.digest && s.supported);
+            if (!skill || active.has(skill.name) || this.state !== "ready")
+                continue;
+            // Check source again after the owner's request. Never overwrite a live package.
+            const current = (await this.scan()).find((s) => s.name === skill.name && s.digest === skill.digest && s.supported);
+            if (!current)
+                continue;
+            const stage = mkdtempSync(join(this.settings.skillsDirectory, ".prepare-"));
+            try {
+                let source = skill.path;
+                if (this.settings.dockerContainer) {
+                    source = join(stage, "source");
+                    await exec("docker", ["cp", `${this.settings.dockerContainer}:${skill.path}`, source], { timeout: 30000, maxBuffer: 1024 * 1024 });
+                }
+                if (packageDigest(source) !== skill.digest)
+                    continue;
+                const prepared = join(stage, "prepared");
+                mkdirSync(prepared);
+                prepareTextSkill(source, join(prepared, skill.name), skill.name);
+                readInstalledSkills(prepared, [], this.origin + "/.well-known/agent-card.json");
+                const after = (await this.scan()).find((s) => s.name === skill.name);
+                if (after?.digest !== skill.digest)
+                    continue;
+                renameSync(join(prepared, skill.name), join(this.settings.skillsDirectory, skill.name));
+                this.enabled[skill.name] = skill.digest;
+                writeFileSync(this.path, JSON.stringify(this.enabled), { mode: 0o600 });
+                // This grant includes only the exact installed package explicitly selected in the owner UI.
+                integration.allowInstalledService(skill.name);
+            }
+            finally {
+                rmSync(stage, { recursive: true, force: true });
+            }
+        }
+        for (const name of active)
+            integration.allowInstalledService(name);
+    }
+}

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 @@
+/** Seller gate for one captured Envar account-balance claim. */
+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-runtime.d.ts

@@ -31,6 +31,7 @@ export interface EnvarSellerRuntimeOptions {
     /** Local payment adapters/merchant credentials must already exist; config sync cannot create them. */
     validateConfig?: (config: CommerceConfig) => void;
     onError?: (code: string) => void;
+    beforeSync?: () => Promise<void>;
 }
 export declare class EnvarSellerRuntime {
     private readonly options;

package/dist/commerce/envar-runtime.js

@@ -231,6 +231,13 @@ export class EnvarSellerRuntime {
             return this.running;
         this.running = (async () => {
             try {
+                try {
+                    await this.options.beforeSync?.();
+                }
+                catch {
+                    // A discovery failure must not stall existing service updates or delivery reports.
+                    this.options.onError?.("skill_discovery");
+                }
                 for (const candidate of await this.options.integration.pullCandidates())
                     await this.options.integration.applyCandidate(candidate, (c) => this.apply(c));
             }

package/dist/commerce/envar.d.ts

@@ -9,13 +9,8 @@ export interface EnvarPolicy {
     acceptUpdates: boolean;
     allowedServices: string[];
     allowedUpstreamOrigins: string[];
-    allowedX402: {
-        network: string;
-        asset: string;
-        payTo: string;
-        facilitatorOrigin: string;
-    }[];
-    allowedMppAccounts: string[];
+    /** Explicit seller account references allowed to accept platform balance. */
+    allowedBalanceAccounts: string[];
 }
 export interface EnvarCandidate {
     id: string;
@@ -47,20 +42,6 @@ export interface EnvarIntegrationOptions {
     responseLimitBytes?: number;
     now?: () => number;
 }
-export interface EnvarX402Evidence {
-    network: string;
-    asset: string;
-    payer: string;
-    recipient: string;
-    amount: string;
-    nonce: string;
-    transaction: string;
-}
-export interface EnvarMppEvidence {
-    reference: string;
-    amount: string;
-    currency: string;
-}
 /** Same frozen fingerprint as CommerceStore.registerCatalog; callers must read actual persisted state. */
 export declare function envarServiceProofs(config: CommerceConfig): EnvarApplicationProof["services"];
 export declare class EnvarIntegration {
@@ -81,6 +62,17 @@ 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;
+        digest: string;
+    }[]>;
     private candidate;
     /** Latest locally acknowledged revisions; startup recovery never requires platform connectivity. */
     appliedCandidates(): EnvarCandidate[];
@@ -97,16 +89,6 @@ export declare class EnvarIntegration {
         orderId: string;
         kind: EnvarStatusKind;
     }): string;
-    enqueueX402Payment(dedupeKey: string, report: {
-        orderId: string;
-        quote: PriceQuote;
-        payment: EnvarX402Evidence;
-    }): string;
-    enqueueMppPayment(dedupeKey: string, report: {
-        orderId: string;
-        quote: PriceQuote;
-        payment: EnvarMppEvidence;
-    }): string;
     queueStatus(): {
         pending: number;
         sent: number;

package/dist/commerce/envar.js

@@ -3,9 +3,9 @@ import { randomUUID } from "node:crypto";
 import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { atomic, currencyOf, digest, loadCommerceConfig } from "./config.js";
+import { digest, loadCommerceConfig } 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, HASH = /^0x[0-9a-f]{64}$/i, ADDRESS = /^0x[0-9a-f]{40}$/i, ID = /^[a-z][a-z0-9-]{0,63}$/;
+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, ID = /^[a-z][a-z0-9-]{0,63}$/;
 const STATUS_KINDS = [
     "seller_started",
     "seller_completed",
@@ -122,20 +122,9 @@ export class EnvarIntegration {
             this.policy.allowedServices.some((id) => !ID.test(id)))
             fail("envar_policy", "Configure valid local Agent and service IDs");
         this.policy.allowedUpstreamOrigins = this.policy.allowedUpstreamOrigins.map((url) => origin(url, true));
-        this.policy.allowedX402 = this.policy.allowedX402.map((entry) => {
-            if (!/^eip155:[1-9][0-9]*$/.test(entry.network) ||
-                !ADDRESS.test(entry.asset) ||
-                !ADDRESS.test(entry.payTo))
-                fail("envar_policy", "Configure explicit receiving identities");
-            return {
-                ...entry,
-                asset: entry.asset.toLowerCase(),
-                payTo: entry.payTo.toLowerCase(),
-                facilitatorOrigin: origin(entry.facilitatorOrigin),
-            };
-        });
-        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,11 +203,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",
-        ].includes(path))
+            "/api/v1/agent-config/runtime",
+        ].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" ||
@@ -297,6 +287,31 @@ 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');
+        if (!this.policy.allowedServices.includes(name))
+            this.policy.allowedServices.push(name);
+    }
+    async reportRuntime(value) {
+        const response = await this.request('/api/v1/agent-config/runtime', value, randomUUID());
+        if (response.agent_id !== this.policy.agentId || !Array.isArray(response.enable) || response.enable.length > 128)
+            fail('envar_inventory', 'Invalid runtime acknowledgment');
+        return response.enable.filter((x) => x && ID.test(x.name) && /^[0-9a-f]{64}$/.test(x.digest));
+    }
     candidate(value) {
         if (!this.policy.acceptUpdates)
             fail("envar_updates_disabled", "Local owner has not enabled platform configuration updates");
@@ -328,15 +343,8 @@ export class EnvarIntegration {
         if (!this.policy.allowedUpstreamOrigins.includes(new URL(service.execution.cardUrl).origin))
             fail("envar_upstream_denied", "Upstream origin is outside the local update grant");
         for (const profile of Object.values(config.paymentProfiles)) {
-            if (profile.adapter === "x402") {
-                if (!this.policy.allowedX402.some((a) => a.network === profile.network &&
-                    a.asset === profile.asset.toLowerCase() &&
-                    a.payTo === profile.payTo.toLowerCase() &&
-                    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))
-                fail("envar_merchant_denied", "Merchant account is outside the local update grant");
+            if (!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=?)")
@@ -526,62 +534,6 @@ export class EnvarIntegration {
             payload: {},
         });
     }
-    enqueueX402Payment(dedupeKey, report) {
-        uuid(report.orderId);
-        const { quote, payment: p } = report, profile = quote.paymentProfile;
-        if (!profile ||
-            profile.adapter !== "x402" ||
-            p.network !== profile.network ||
-            p.asset.toLowerCase() !== profile.asset.toLowerCase() ||
-            p.recipient.toLowerCase() !== profile.payTo.toLowerCase() ||
-            p.amount !== quote.amount ||
-            quote.currency !== currencyOf(profile) ||
-            quote.recipient?.toLowerCase() !== profile.payTo.toLowerCase() ||
-            !ADDRESS.test(p.payer) ||
-            !HASH.test(p.nonce) ||
-            !HASH.test(p.transaction))
-            fail("envar_payment_binding", "Report the original x402 transaction matching the frozen quote");
-        atomic(p.amount);
-        return this.enqueue(`report:${dedupeKey}`, "report", {
-            order_id: report.orderId,
-            kind: "payment_observed",
-            payload: {
-                protocol: "x402",
-                payment: {
-                    network: p.network,
-                    asset: p.asset.toLowerCase(),
-                    payer: p.payer.toLowerCase(),
-                    recipient: p.recipient.toLowerCase(),
-                    amount: p.amount,
-                    nonce: p.nonce.toLowerCase(),
-                    transaction: p.transaction.toLowerCase(),
-                },
-            },
-        });
-    }
-    enqueueMppPayment(dedupeKey, report) {
-        uuid(report.orderId);
-        const { quote, payment: p } = report;
-        if (quote.paymentProfile?.adapter !== "mpp" ||
-            p.amount !== quote.amount ||
-            p.currency !== quote.currency ||
-            p.currency !== "usd" ||
-            !/^pi_[A-Za-z0-9]{1,240}$/.test(p.reference))
-            fail("envar_payment_binding", "Report the original Stripe PaymentIntent matching the frozen quote");
-        atomic(p.amount);
-        return this.enqueue(`report:${dedupeKey}`, "report", {
-            order_id: report.orderId,
-            kind: "payment_observed",
-            payload: {
-                protocol: "mpp",
-                payment: {
-                    reference: p.reference,
-                    amount: p.amount,
-                    currency: p.currency,
-                },
-            },
-        });
-    }
     queueStatus() {
         this.open();
         const count = (state) => Number(this.db

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: "unknown" | "not_started" | "queued" | "dispatching" | "working" | "input_required" | "auth_required" | "completed" | "failed";
+        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: "unknown" | "not_started" | "queued" | "dispatching" | "working" | "input_required" | "auth_required" | "completed" | "failed";
+    }>;
+    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);
+    }
+}