@envarai/envarpay 0.2.0-alpha.2 → 0.2.0-alpha.20

package/dist/commerce/setup.js

@@ -0,0 +1,379 @@
+/** Guided local installation. Platform input is data, never a shell command or wallet policy. */
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, cpSync, mkdtempSync, renameSync, rmSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { probeOpenClaw } from "./openclaw-setup.js";
+import { readInstalledSkills } from "./native-skills.js";
+import { loadCommerceConfig, validateUrl } from "./config.js";
+import { CommerceError } from "./types.js";
+import { isSkillInstallerMetadata } from './native-inventory.js';
+const ID = /^[a-z][a-z0-9-]{0,63}$/, CONTAINER = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+export function parseSetupBundle(raw) {
+    const v = raw;
+    if (!v ||
+        v.version !== 1 ||
+        !/^[0-9a-f-]{36}$/.test(v.agentId) ||
+        !ID.test(v.runtimeAgentId) ||
+        typeof v.agentName !== "string" ||
+        v.agentName.length > 120 ||
+        !/^envar_agent_[A-Za-z0-9_-]{32,100}$/.test(v.token) ||
+        !Number.isFinite(Date.parse(v.expiresAt)) ||
+        Date.parse(v.expiresAt) <= Date.now())
+        throw new CommerceError("setup_file", "Download a fresh Agent setup file from Envar");
+    const origin = validateUrl(v.platformOrigin);
+    if (origin.origin !== v.platformOrigin)
+        throw new CommerceError("setup_origin", "Use the platform HTTPS origin");
+    return v;
+}
+export function prepareTextSkill(source, destination, name) {
+    if (!ID.test(name) || existsSync(destination))
+        throw new CommerceError("setup_skill", "Choose a new exact skill name");
+    const stat = lstatSync(source);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new CommerceError("setup_skill", "Choose a real skill directory");
+    cpSync(source, destination, {
+        recursive: true,
+        filter: (path) => {
+            const item = lstatSync(path);
+            if (item.isSymbolicLink())
+                throw new CommerceError("setup_skill", "Skill symlinks are unsupported");
+            if (item.isFile() && isSkillInstallerMetadata(relative(source, path).split(sep).join('/')))
+                return false;
+            if (item.isFile() &&
+                !/\.(md|txt)$/i.test(path) &&
+                !path.endsWith("/LICENSE"))
+                throw new CommerceError("setup_skill", "Choose a text-only package without scripts or binaries");
+            return true;
+        },
+    });
+    const file = join(destination, "SKILL.md"), original = readFileSync(file, "utf8");
+    if (!original.startsWith("---\n") && !original.startsWith("---\r\n"))
+        throw new CommerceError("setup_skill", "Skill needs YAML frontmatter");
+    const adapted = original.replace(/^(---\r?\n)([\s\S]*?)(\r?\n---)/, (_all, open, front, close) => open +
+        front.replace(/^envar-runtime:.*\r?\n?/gm, "") +
+        "\nenvar-runtime: instruction-only" +
+        close);
+    writeFileSync(file, adapted +
+        "\n\n## Service execution\nUse the supplied buyer input as the complete product context. Bundled Markdown references are included in the task context. Return text in the A2A result. Do not browse, access files, run scripts, or invoke other skills. If information is missing, state what is missing; do not invent it.\n", { mode: 0o600 });
+}
+function privateJson(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", {
+        mode: 0o600,
+        flag: "wx",
+    });
+}
+export async function setupAgent(options) {
+    const file = resolve(options.file), info = lstatSync(file);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 16384)
+        throw new CommerceError("setup_file", "Use the downloaded setup JSON file");
+    const bundle = parseSetupBundle(JSON.parse(readFileSync(file, "utf8")));
+    if (options.container && !CONTAINER.test(options.container))
+        throw new CommerceError("setup_container", "Use a Docker container name");
+    if (!process.stdin.isTTY && !options.automatic)
+        throw new CommerceError("setup_terminal", "Run setup in an interactive terminal to select skills");
+    chmodSync(file, 0o600);
+    const prompt = options.automatic ? undefined : createInterface({ input: process.stdin, output: process.stdout });
+    const output = options.automatic ? (..._args) => { } : console.log;
+    const ask = async (label, fallback = "") => (await prompt.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim() || fallback;
+    let staging;
+    try {
+        output(`\nConnect ${bundle.agentName} to ${bundle.platformOrigin}\nModel credentials and tasks remain on this machine. Start with free services; no wallet is created.\n`);
+        if (!options.automatic && (await ask("Continue? (yes/no)", "no")).toLowerCase() !== "yes")
+            return;
+        const directory = resolve(options.directory ?? join(homedir(), ".envarpay", bundle.agentId));
+        if (existsSync(directory))
+            throw new CommerceError("setup_exists", "This Agent already has a local directory. Use its start script; never reset its ledger.");
+        const configuredFramework = process.env.ENVARPAY_FRAMEWORK;
+        const framework = options.framework ?? (configuredFramework === "hermes" || configuredFramework === "openclaw" ? configuredFramework : process.env.OPENCLAW_STATE_DIR ? "openclaw" : "hermes");
+        let python = options.python;
+        let probe;
+        if (framework === "openclaw") {
+            if (options.container)
+                throw new CommerceError("setup_runtime", "Run OpenClaw setup inside its own runtime");
+            python ??= "python3";
+            probe = probeOpenClaw(options.home, python);
+        }
+        else {
+            const compatibility = 'import inspect;from run_agent import AIAgent;assert all(k in inspect.signature(AIAgent).parameters for k in ["skip_context_files","skip_memory","skip_background_review","ephemeral_system_prompt","enabled_toolsets"])';
+            if (!python && options.container) {
+                for (const candidate of [
+                    "/opt/hermes-latest/bin/python",
+                    "/opt/hermes/.venv/bin/python",
+                    "python3",
+                ]) {
+                    try {
+                        execFileSync("docker", ["exec", options.container, candidate, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
+                        python = candidate;
+                        break;
+                    }
+                    catch {
+                        /* try the next compatible installed interpreter */
+                    }
+                }
+                if (!python)
+                    throw new CommerceError("setup_runtime", "No compatible Hermes interpreter found in this container. Update Hermes or pass --python PATH.");
+            }
+            if (!python && options.automatic) {
+                for (const candidate of [process.env.VIRTUAL_ENV && join(process.env.VIRTUAL_ENV, "bin/python"), "/opt/hermes-latest/bin/python", "/opt/hermes/.venv/bin/python", join(homedir(), "hermes-agent/.venv/bin/python"), "python3"].filter(Boolean)) {
+                    try {
+                        execFileSync(candidate, ["-c", compatibility], { stdio: "pipe", timeout: 30000 });
+                        python = candidate;
+                        break;
+                    }
+                    catch { }
+                }
+                if (!python)
+                    throw new CommerceError("setup_runtime", "No compatible Hermes Python found. Pass its executable using --python.");
+            }
+            python ??= await ask("Hermes Python executable", join(homedir(), "hermes-agent", ".venv", "bin", "python"));
+            const probeSource = readFileSync(new URL("../../examples/hermes-setup-probe.py", import.meta.url), "utf8");
+            try {
+                if (options.container)
+                    execFileSync("docker", ["exec", options.container, python, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
+                else
+                    execFileSync(python, ["-c", compatibility], {
+                        stdio: "pipe",
+                        timeout: 60000,
+                    });
+                const args = ["-c", probeSource, ...(options.home ? [options.home] : [])];
+                const data = options.container
+                    ? execFileSync("docker", ["exec", options.container, python, ...args], {
+                        stdio: "pipe",
+                        timeout: 30000,
+                        maxBuffer: 2 * 1024 * 1024,
+                    })
+                    : execFileSync(python, args, {
+                        stdio: "pipe",
+                        timeout: 30000,
+                        maxBuffer: 2 * 1024 * 1024,
+                    });
+                probe = JSON.parse(data.toString());
+            }
+            catch {
+                throw new CommerceError("setup_model", "Could not read Hermes. Check the container/Python path and configure an OpenAI-compatible model in Hermes first.");
+            }
+        }
+        const candidates = probe.skills.filter((s) => s.textPackage && ID.test(s.name));
+        output(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
+        candidates.forEach((skill, i) => output(`${i + 1}. ${skill.name} — ${skill.description.replace(/[\r\n\x1b]/g, " ").slice(0, 160)}`));
+        output('Newly installed Skills will be discovered privately. Enable each one from the Envar service page after reviewing text-only compatibility.');
+        const selected = (options.automatic ? "" : await ask("Optional: enable existing text Skills now (comma separated, Enter to skip)"))
+            .split(",")
+            .map((s) => s.trim()).filter(Boolean);
+        if (selected.length > 32 ||
+            new Set(selected).size !== selected.length ||
+            selected.some((name) => !candidates.some((s) => s.name === name)))
+            throw new CommerceError("setup_skills", "Choose installed skill names from the list");
+        output("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Agent skills are preserved; a service copy is created.");
+        if (selected.length &&
+            (await ask("Do these selected skills work with text input and text output only? (yes/no)", "no")).toLowerCase() !== "yes")
+            return;
+        const port = options.automatic?.port ?? Number(await ask("Local service port", "4020"));
+        if (!Number.isInteger(port) || port < 1024 || port > 65535)
+            throw new CommerceError("setup_port", "Choose a local port from 1024 to 65535");
+        let origin;
+        const tunnelMode = options.automatic ? "url" : await ask("Public HTTPS: use an existing ngrok session or your own reverse proxy? (ngrok/url)", "ngrok");
+        if (tunnelMode === "ngrok") {
+            const api = new URL(await ask("Local ngrok API", "http://127.0.0.1:4040"));
+            if (api.protocol !== "http:" ||
+                api.hostname !== "127.0.0.1" ||
+                api.username ||
+                api.password ||
+                api.pathname !== "/")
+                throw new CommerceError("setup_tunnel", "Use the local ngrok API on 127.0.0.1");
+            const name = `envarpay-${bundle.agentId}`, addr = `http://127.0.0.1:${port}`;
+            const inventory = await fetch(new URL("/api/tunnels", api), {
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!inventory.ok)
+                throw new CommerceError("setup_tunnel", "Start ngrok first, or choose your own HTTPS URL");
+            const existing = (await inventory.json()).tunnels.find((t) => t.name === name);
+            if (existing) {
+                if (existing.config.addr !== addr)
+                    throw new CommerceError("setup_tunnel", "The existing Agent tunnel uses another local port. Keep its original port.");
+                origin = existing.public_url;
+            }
+            else {
+                const response = await fetch(new URL("/api/tunnels", api), {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        name,
+                        proto: "http",
+                        addr,
+                        schemes: ["https"],
+                        inspect: false,
+                    }),
+                    signal: AbortSignal.timeout(15000),
+                });
+                if (!response.ok)
+                    throw new CommerceError("setup_tunnel", "Could not create a dedicated tunnel. Check ngrok or choose your own HTTPS URL. Existing tunnels were preserved.");
+                origin = (await response.json()).public_url;
+            }
+        }
+        else if (tunnelMode === "url") {
+            origin = options.automatic?.origin ?? await ask(`Public HTTPS origin (forward to http://127.0.0.1:${port})`);
+        }
+        else
+            throw new CommerceError("setup_tunnel", "Choose ngrok or url");
+        const publicUrl = validateUrl(origin);
+        if (publicUrl.origin !== origin ||
+            (publicUrl.port && publicUrl.port !== "443"))
+            throw new CommerceError("setup_origin", "Use an HTTPS origin on port443");
+        // Only publish a complete new setup directory. An interrupted setup cannot strand
+        // the owner behind setup_exists or overwrite a prior ledger.
+        mkdirSync(resolve(directory, ".."), { recursive: true, mode: 0o700 });
+        staging = mkdtempSync(directory + ".setup-");
+        chmodSync(staging, 0o700);
+        const skillsDirectory = join(staging, "skills");
+        mkdirSync(skillsDirectory, { mode: 0o700 });
+        for (const name of selected) {
+            const skill = candidates.find((s) => s.name === name);
+            if (options.container) {
+                const incoming = join(staging, `incoming-${name}`);
+                execFileSync("docker", ["cp", `${options.container}:${skill.path}`, incoming], { stdio: "pipe", timeout: 30000 });
+                prepareTextSkill(incoming, join(skillsDirectory, name), name);
+                rmSync(incoming, { recursive: true });
+            }
+            else
+                prepareTextSkill(skill.path, join(skillsDirectory, name), name);
+        }
+        readInstalledSkills(skillsDirectory, [], origin + "/.well-known/agent-card.json");
+        const access = randomBytes(36).toString("base64url");
+        let apiKeyFile = probe.apiKeyFile;
+        if (options.managed && apiKeyFile) {
+            const stat = lstatSync(apiKeyFile);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384)
+                throw new CommerceError("setup_model", "Invalid local model key file");
+            probe.apiKey = readFileSync(apiKeyFile, "utf8");
+            apiKeyFile = null;
+        }
+        if (!apiKeyFile) {
+            if (options.container) {
+                apiKeyFile = join(probe.home, "envarpay-secrets", bundle.agentId, "model.key");
+                // Key bytes travel through stdin, never process arguments or console output.
+                const writeKey = "import sys,os;from pathlib import Path;p=Path(sys.argv[1]);p.parent.mkdir(parents=True,exist_ok=True,mode=0o700);fd=os.open(p,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600);os.write(fd,sys.stdin.buffer.read());os.close(fd)";
+                try {
+                    execFileSync("docker", [
+                        "exec",
+                        "-i",
+                        options.container,
+                        python,
+                        "-c",
+                        writeKey,
+                        apiKeyFile,
+                    ], {
+                        input: probe.apiKey,
+                        stdio: ["pipe", "pipe", "pipe"],
+                        timeout: 15000,
+                    });
+                }
+                catch {
+                    throw new CommerceError("setup_model", "Could not save the local model credential. Inspect the Agent-specific envarpay-secrets directory before retrying.");
+                }
+            }
+            else {
+                apiKeyFile = join(directory, "model.key");
+                writeFileSync(join(staging, "model.key"), probe.apiKey, {
+                    mode: 0o600,
+                    flag: "wx",
+                });
+            }
+        }
+        const stateDirectory = join(directory, "tasks");
+        mkdirSync(join(staging, "tasks"), { mode: 0o700 });
+        const dockerStateDirectory = options.container
+            ? join(probe.home, "envarpay-tasks", bundle.agentId)
+            : undefined;
+        const config = loadCommerceConfig({
+            configVersion: 2,
+            agent: { id: bundle.runtimeAgentId, name: bundle.agentName },
+            paymentProfiles: {},
+            services: [],
+        });
+        privateJson(join(staging, "seller.json"), config);
+        writeFileSync(join(staging, "vault.key"), randomBytes(32), { mode: 0o600, flag: "wx" });
+        privateJson(join(staging, "credentials.json"), {
+            callers: { [access]: "owner" },
+            upstreams: {},
+            vaultKeyFile: join(directory, "vault.key"),
+            skills: {
+                framework,
+                ...(probe.command ? { command: probe.command } : {}),
+                discovery: { hermesHome: probe.home, enabledFromWeb: true, ...(probe.skillRoots ? { roots: probe.skillRoots } : {}) },
+                skillsDirectory: join(directory, "skills"),
+                freeSkills: [],
+                stateDirectory,
+                python,
+                model: probe.model,
+                baseUrl: probe.baseUrl,
+                apiKeyFile,
+                ...(options.container
+                    ? { dockerContainer: options.container, dockerStateDirectory }
+                    : {}),
+            },
+        });
+        writeFileSync(join(staging, "envar.token"), bundle.token, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        privateJson(join(staging, "envar.json"), {
+            policy: {
+                enabled: true,
+                platformOrigin: bundle.platformOrigin,
+                agentId: bundle.agentId,
+                runtimeAgentId: bundle.runtimeAgentId,
+                acceptUpdates: true,
+                allowedServices: selected,
+                allowedUpstreamOrigins: [origin],
+                allowedBalanceAccounts: ["envar"],
+            },
+            stateDirectory: join(directory, "envar-state"),
+            configDirectory: join(directory, "envar-configs"),
+        });
+        privateJson(join(staging, "connection.json"), {
+            version: 1,
+            agentId: bundle.agentId,
+            url: origin + "/.well-known/agent-card.json",
+            authToken: access,
+        });
+        const cli = fileURLToPath(new URL("./cli.js", import.meta.url));
+        const args = [
+            cli,
+            "serve",
+            "--config",
+            join(directory, "seller.json"),
+            "--credentials",
+            join(directory, "credentials.json"),
+            "--state",
+            join(directory, "seller.sqlite3"),
+            "--origin",
+            origin,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            "--envar-config",
+            join(directory, "envar.json"),
+            "--envar-credentials",
+            join(directory, "envar.token"),
+        ];
+        const start = join(directory, "start.mjs");
+        writeFileSync(join(staging, "start.mjs"), `import {spawn} from 'node:child_process';\nconst child=spawn(${JSON.stringify(process.execPath)},${JSON.stringify(args)},{stdio:'inherit'});\nfor(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>child.kill(signal));\nchild.on('exit',code=>process.exit(code??1));\n`, { mode: 0o700, flag: "wx" });
+        writeFileSync(join(staging, "README.md"), `# ${bundle.agentName}\n\n1. Start: node ${JSON.stringify(start)}\n2. Keep this process, your Agent and the HTTPS tunnel running.\n3. In Envar, import connection.json and select Check connection.\n4. Choose a Skill. You can publish it free immediately.\n5. For a paid Skill, request Envar balance receiving approval in Envar, then enter the USD price. This setup already allows the local receiving reference \"envar\"; there is no chain wallet or payment protocol to configure.\n6. Select Test service, then Publish after Envar confirms the live unpaid quote.\n\nThe Envar Agent token expires ${bundle.expiresAt}. Keep the original files and ledger when restarting. Never share credentials.json, envar.token or vault.key.\n`, { mode: 0o600, flag: "wx" });
+        renameSync(staging, directory);
+        staging = undefined;
+        output(`\nReady. Start the local service:\n${process.execPath} ${JSON.stringify(start)}\n\nThen import this connection file in Envar:\n${join(directory, "connection.json")}\n\nKeep the service and HTTPS tunnel online. No task or payment was performed.`);
+    }
+    finally {
+        prompt?.close();
+        if (staging)
+            rmSync(staging, { recursive: true, force: true });
+    }
+}
+// Preserve the existing SDK helper name for callers using Hermes explicitly.
+export const setupHermes = (options) => setupAgent({ ...options, framework: "hermes" });

package/dist/commerce/skill-gate.d.ts

@@ -0,0 +1,54 @@
+import { AgentCard, Task } from '@a2a-js/sdk';
+import { type Input } from './types.js';
+import type { ExecuteOrder } from './server.js';
+import type { OrderRecord } from './store.js';
+/** The name is the service ID. The digest pins the installed skill version. */
+export interface SkillDescriptor {
+    name: string;
+    digest: string;
+    cardUrl: string;
+    access: 'free' | 'paid';
+    description?: string;
+}
+/** The Agent-owned adapter may expose one private, authenticated A2A Card per skill. */
+export declare function createSkillCard(descriptor: SkillDescriptor, interfaceUrl: string): AgentCard;
+/** In-process authority passed only after the seller has confirmed payment or a free offer. */
+export declare class SkillGrant {
+    #private;
+    readonly skillName: string;
+    readonly skillDigest: string;
+    readonly orderId: string;
+    readonly caller: string;
+    readonly messageId: string;
+    readonly inputDigest: string;
+    constructor(order: OrderRecord, descriptor: SkillDescriptor, freeSkills: ReadonlySet<string>, messageId?: string);
+    /** A purchased task may use its own skill and declared free skills, never another paid skill. */
+    require(skillName: string): void;
+}
+export interface SkillInvocation {
+    orderId: string;
+    messageId: string;
+    taskId?: string;
+    contextId?: string;
+    grant: SkillGrant;
+}
+/**
+ * An Agent-owned adapter. It must route by the passed exact skill name and use
+ * grant.require() for every nested skill invocation. Raw paid skills stay private.
+ */
+export interface SkillRuntime {
+    list(): readonly SkillDescriptor[];
+    send(skillName: string, input: Input, invocation: SkillInvocation): Promise<Task>;
+    getTask(skillName: string, taskId: string, invocation: SkillInvocation): Promise<Task>;
+}
+export interface SkillHandler {
+    descriptor: SkillDescriptor;
+    send(input: Input, invocation: SkillInvocation & {
+        callSkill(name: string, input: Input): Promise<Task>;
+    }): Promise<Task>;
+    getTask(taskId: string, invocation: SkillInvocation): Promise<Task>;
+}
+/** Reference in-process adapter: every nested skill call passes the same purchase gate. */
+export declare function createSkillRegistry(handlers: readonly SkillHandler[]): SkillRuntime;
+/** External buyer/seller communication remains ordinary A2A; only local skill dispatch changes. */
+export declare function skillScopedExecutor(runtime: SkillRuntime, signal?: AbortSignal): ExecuteOrder;

package/dist/commerce/skill-gate.js

@@ -0,0 +1,153 @@
+import { AgentCard, TaskState } from '@a2a-js/sdk';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CommerceError } from './types.js';
+import { validateUrl } from './config.js';
+/** The Agent-owned adapter may expose one private, authenticated A2A Card per skill. */
+export function createSkillCard(descriptor, interfaceUrl) {
+    const card = validateUrl(descriptor.cardUrl, true), endpoint = validateUrl(interfaceUrl, true);
+    if (card.origin !== endpoint.origin || !/^[a-z][a-z0-9-]{0,63}$/.test(descriptor.name) ||
+        !/^[0-9a-f]{64}$/.test(descriptor.digest))
+        throw new CommerceError('invalid_skill_card', 'Skill Card needs one exact named skill, pinned digest and same-origin A2A interface');
+    return AgentCard.fromJSON({
+        name: descriptor.name, description: `Agent Skill: ${descriptor.name}`, version: descriptor.digest,
+        supportedInterfaces: [{ url: endpoint.href, protocolBinding: 'JSONRPC', protocolVersion: '1.0' }],
+        capabilities: { streaming: false, pushNotifications: false, extensions: [{
+                    uri: 'urn:envarpay:skill-gate:1', required: false,
+                    description: 'The owner-operated adapter invokes this exact installed skill and gates other paid skills',
+                    params: { skillName: descriptor.name, skillDigest: descriptor.digest, access: descriptor.access },
+                }] },
+        defaultInputModes: ['application/json'], defaultOutputModes: ['application/json', 'text/plain'],
+        skills: [{ id: descriptor.name, name: descriptor.name, description: `Invoke ${descriptor.name}`, tags: [descriptor.name] }],
+        securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: 'bearer' } } },
+        securityRequirements: [{ schemes: { bearer: { list: [] } } }],
+    });
+}
+/** In-process authority passed only after the seller has confirmed payment or a free offer. */
+export class SkillGrant {
+    skillName;
+    skillDigest;
+    orderId;
+    caller;
+    messageId;
+    inputDigest;
+    #freeSkills;
+    constructor(order, descriptor, freeSkills, messageId = order.messageId) {
+        if (!['confirmed', 'not_required'].includes(order.paymentState))
+            throw new CommerceError('payment_required', 'An unpaid order cannot authorize a skill');
+        this.skillName = descriptor.name;
+        this.skillDigest = descriptor.digest;
+        this.orderId = order.id;
+        this.caller = order.caller;
+        this.messageId = messageId;
+        this.inputDigest = order.inputDigest;
+        this.#freeSkills = new Set(freeSkills);
+        Object.freeze(this);
+    }
+    /** A purchased task may use its own skill and declared free skills, never another paid skill. */
+    require(skillName) {
+        if (skillName !== this.skillName && !this.#freeSkills.has(skillName))
+            throw new CommerceError('skill_payment_required', 'Purchase the other paid skill as a separate service');
+    }
+}
+/** Reference in-process adapter: every nested skill call passes the same purchase gate. */
+export function createSkillRegistry(handlers) {
+    const byName = new Map();
+    for (const handler of handlers) {
+        const { name, digest, cardUrl } = handler.descriptor;
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) || !/^[0-9a-f]{64}$/.test(digest) || !cardUrl || byName.has(name))
+            throw new CommerceError('invalid_skill_registry', 'Skill names and pinned versions must be unique');
+        byName.set(name, { ...handler, descriptor: Object.freeze({ ...handler.descriptor }) });
+    }
+    const select = (name, grant) => {
+        grant.require(name);
+        const handler = byName.get(name);
+        if (!handler)
+            throw new CommerceError('skill_unavailable', 'The requested skill is not installed');
+        return handler;
+    };
+    const dispatch = (name, input, invocation, depth) => {
+        if (depth > 8)
+            throw new CommerceError('skill_depth', 'Nested skill calls exceeded the supported limit');
+        const handler = select(name, invocation.grant);
+        return handler.send(input, { ...invocation, callSkill: async (child, childInput) => dispatch(child, childInput, invocation, depth + 1) });
+    };
+    return {
+        list: () => [...byName.values()].map(h => ({ ...h.descriptor })),
+        send: (name, input, invocation) => dispatch(name, input, invocation, 0),
+        getTask: (name, taskId, invocation) => select(name, invocation.grant).getTask(taskId, invocation),
+    };
+}
+const TERMINAL = new Set([
+    TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_FAILED, TaskState.TASK_STATE_CANCELED,
+    TaskState.TASK_STATE_REJECTED, TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED,
+]);
+/** External buyer/seller communication remains ordinary A2A; only local skill dispatch changes. */
+export function skillScopedExecutor(runtime, signal) {
+    function descriptor(service) {
+        const execution = service.execution;
+        if (execution.type !== 'skill' || service.id !== service.name)
+            throw new CommerceError('skill_name_mismatch', 'The service must use an exact skill name');
+        const matches = runtime.list().filter(s => s.name === service.id && s.digest === execution.skillDigest);
+        if (matches.length !== 1 || matches[0].cardUrl !== execution.cardUrl)
+            throw new CommerceError('skill_unavailable', 'The named installed skill or its pinned version is unavailable');
+        if (matches[0].access === 'free' && service.offers.some(offer => offer.pricing.kind !== 'free'))
+            throw new CommerceError('free_skill_price', 'A declared free helper cannot have paid offers');
+        return matches[0];
+    }
+    function grant(order, service, messageId = order.messageId) {
+        const selected = descriptor(service);
+        const free = new Set(runtime.list().filter(s => s.access === 'free').map(s => s.name));
+        return new SkillGrant(order, selected, free, messageId);
+    }
+    function checked(task, expectedId) {
+        if (!task || typeof task.id !== 'string' || !task.id || !task.status || (expectedId && task.id !== expectedId))
+            throw new CommerceError('invalid_agent_response', 'The skill runtime returned no stable A2A Task');
+        return task;
+    }
+    async function* observe(initial, order, service, authority) {
+        let task = checked(initial);
+        const deadline = Date.now() + service.contract.targetDurationSeconds * 1000;
+        for (;;) {
+            yield task;
+            if (TERMINAL.has(task.status?.state ?? 0))
+                return;
+            if (Date.now() >= deadline)
+                throw new CommerceError('execution_pending', 'Read the original Task to continue observing execution');
+            await sleep(1000, undefined, { signal });
+            task = checked(await runtime.getTask(service.id, task.id, {
+                orderId: order.id, messageId: authority.messageId, grant: authority,
+            }), task.id);
+        }
+    }
+    const execute = async function* (order, service) {
+        const authority = grant(order, service);
+        authority.require(service.id);
+        const task = await runtime.send(service.id, order.input, {
+            orderId: order.id, messageId: order.messageId, grant: authority,
+        });
+        yield* observe(task, order, service, authority);
+    };
+    execute.continue = async function* (order, service, continuation, remote) {
+        if (remote.origin !== service.execution.cardUrl)
+            throw new CommerceError('skill_origin_changed', 'The original skill Task belongs to another execution entry');
+        const authority = grant(order, service, continuation.messageId);
+        const task = checked(await runtime.send(service.id, continuation.input, {
+            orderId: order.id, messageId: continuation.messageId, taskId: remote.taskId,
+            contextId: remote.contextId, grant: authority,
+        }), remote.taskId);
+        yield* observe(task, order, service, authority);
+    };
+    execute.recover = async (order, service, remote) => {
+        if (remote.origin !== service.execution.cardUrl)
+            throw new CommerceError('skill_origin_changed', 'The original skill Task belongs to another execution entry');
+        // Reading an original Task must survive a removed/upgraded installed package.
+        if (service.execution.type !== 'skill')
+            throw new CommerceError('skill_required', 'Expected a skill Task');
+        const authority = new SkillGrant(order, { name: service.id, digest: service.execution.skillDigest, cardUrl: service.execution.cardUrl, access: 'paid' }, new Set());
+        return checked(await runtime.getTask(service.id, remote.taskId, {
+            orderId: order.id, messageId: order.messageId, grant: authority,
+        }), remote.taskId);
+    };
+    execute.assertSkill = descriptor;
+    return execute;
+}

package/dist/commerce/store.d.ts

@@ -80,8 +80,18 @@ export declare class CommerceStore implements TaskStore {
     hasUnresolvedContinuation(orderId: string): boolean;
     acknowledgeRecoveredContinuations(orderId: string, task: Task): void;
     recoverInterruptedDispatches(): number;
+    prepareExternalTask(orderId: string, principal: string): void;
+    externalTasks(principal: string, services: readonly string[]): {
+        order: OrderRecord;
+        claimId: string;
+    }[];
+    claimExternalTask(taskId: string, principal: string, services: readonly string[]): {
+        order: OrderRecord;
+        claimId: string;
+    };
+    externalClaim(taskId: string, principal: string, claimId: string, services: readonly string[]): OrderRecord;
     private scope;
-    save(task: Task, context: ServerCallContext): Promise<void>;
+    save(task: Task, context: ServerCallContext, expectedOriginal?: Task): Promise<void>;
     load(taskId: string, context: ServerCallContext): Promise<Task | undefined>;
     list(params: ListTasksRequest, context: ServerCallContext): Promise<ListTasksResponse>;
     fingerprint(order: OrderRecord): string;