@kybernesis/payments 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @kybernesis/payments
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Link wallet for an eve agent, on its owner's behalf.
+
+Stripe's Link eve integration gives an agent `link__create_spend_request` and
+friends: the agent names a merchant and a total, the person approves it in the
+Link app, and Link issues a one-time card for exactly that purchase. This
+package adds the two pieces that make it usable by a Kybernesis agent:
+
+- **`linkTool(name)`** — Link's tool catalog (`@stripe/link-sdk/tools`) as eve tools, one per file. `create_spend_request` asks the person in eve before Link asks them again; every result is stripped of card fields.
+- **`linkCliAuth()`** — the owner's `link-cli` sign-in as the agent's wallet
+  credential. The owner runs `npx link-cli auth login --client-name <agent>` on
+  the agent's host once (a device-code flow approved in the Link app); the CLI
+  keeps and refreshes the tokens in its own config file, and this provider reads
+  that file for each call. No token in env, none in source. Single-owner by
+  design: this is a personal agent paying from its owner's wallet.
+- **`payOnComputerTool()`** (`pay_on_computer`) — once a spend request is
+  approved, types the one-time card into the checkout form open in the agent's
+  own browser via `@kybernesis/computer`'s fill primitive. The model supplies CSS
+  selectors; the card goes Link → page and comes back only as brand + last four.
+
+```ts title="agent/tools/create_spend_request.ts"
+import { linkTool } from "@kybernesis/payments";
+export default linkTool("create_spend_request"); // one file per Link tool; see LINK_TOOL_NAMES
+```
+
+```ts title="agent/tools/pay_on_computer.ts"
+import { payOnComputerTool } from "@kybernesis/payments";
+export default payOnComputerTool();
+```
+
+`PAYMENTS_INSTRUCTIONS` is the order of operations the agent follows: agree the
+exact total from the real checkout page, create one spend request, send the
+approval link, wait, fill, screenshot, submit, report with `link__create_report`.
+
+## Requirements
+
+- `@kybernesis/computer` ≥ 0.2.0 mounted as the root sandbox (that is where the
+  browser is).
+- `link-cli` signed in on the host. Without it every wallet tool fails with a
+  message saying exactly that; the agent cannot complete the sign-in itself.
+- The install is `eve add @kybernesis/payments` from the Kybernesis registry.
+
+## Gotchas
+
+- Stripe's own eve extension (`@stripe/link-integrations-eve`, built with eve 0.66) does not mount on eve 0.68 — that is why the tools are wrapped here from the SDK instead.
+- Link may require 3-D Secure or a verification step the agent cannot complete.
+  The instructions tell it to stop and describe the screen; the person can take
+  over the computer.

package/dist/extension.d.ts

@@ -0,0 +1,10 @@
+import { type LinkCliAuthOptions } from "./link-cli-auth.js";
+/**
+ * Stripe's Link eve extension, mounted behind the owner's link-cli sign-in.
+ *
+ * ```ts title="agent/extensions/link.ts"
+ * import { linkWallet } from "@kybernesis/payments";
+ * export default linkWallet();
+ * ```
+ */
+export declare function linkWallet(options?: LinkCliAuthOptions): import("eve/extension").MountedExtension;

package/dist/extension.js

@@ -0,0 +1,13 @@
+import link from "@stripe/link-integrations-eve";
+import { linkCliAuth } from "./link-cli-auth.js";
+/**
+ * Stripe's Link eve extension, mounted behind the owner's link-cli sign-in.
+ *
+ * ```ts title="agent/extensions/link.ts"
+ * import { linkWallet } from "@kybernesis/payments";
+ * export default linkWallet();
+ * ```
+ */
+export function linkWallet(options = {}) {
+    return link({ auth: linkCliAuth(options) });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { linkCliAuth, linkCliAuthFile, readStoredAuth, NOT_SIGNED_IN, type LinkCliAuthOptions } from "./link-cli-auth.js";
+export { payOnComputerTool } from "./pay-on-computer.js";
+export { PAYMENTS_INSTRUCTIONS } from "./instructions.js";
+export { linkTool, linkClient, sanitizeLinkOutput, LINK_TOOL_NAMES, type LinkToolName } from "./link-tools.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { linkCliAuth, linkCliAuthFile, readStoredAuth, NOT_SIGNED_IN } from "./link-cli-auth.js";
+export { payOnComputerTool } from "./pay-on-computer.js";
+export { PAYMENTS_INSTRUCTIONS } from "./instructions.js";
+export { linkTool, linkClient, sanitizeLinkOutput, LINK_TOOL_NAMES } from "./link-tools.js";

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare const PAYMENTS_INSTRUCTIONS = "## Paying for things\n\nYou can buy things with the person's Link wallet. Every purchase is their decision twice over: creating a spend request asks them here, and Link asks them again in their Link app before any card exists. Never work around either step.\n\nThe order, every time:\n1. Agree the exact purchase first: merchant, items, final total including tax and shipping, in the right currency. Get these from the actual checkout page in your own browser (open_browser, then look), not from memory.\n2. `create_spend_request` with that merchant, those line items and that total. If it comes back without an approval link, call `request_spend_approval`. Send the person the approval link as a plain link, and wait. Do not create a second request for the same purchase.\n3. When `retrieve_spend_request` says approved, use `pay_on_computer` to type the one-time card into the checkout. You give it the selectors of the card fields you can see; the card itself never comes to you. Check the filled form in a screenshot, confirm the total still matches, then submit.\n4. Report the outcome with `create_report`: succeeded, failed, or what the merchant said. If the merchant needs more (3-D Secure, a code), stop and tell the person exactly what is on the screen; they can take over your screen.\n\nNever read card numbers or CVCs aloud, never paste them into chat or a file, never guess a total. If Link asks for verification you cannot complete, say so.\n";

package/dist/instructions.js

@@ -0,0 +1,12 @@
+export const PAYMENTS_INSTRUCTIONS = `## Paying for things
+
+You can buy things with the person's Link wallet. Every purchase is their decision twice over: creating a spend request asks them here, and Link asks them again in their Link app before any card exists. Never work around either step.
+
+The order, every time:
+1. Agree the exact purchase first: merchant, items, final total including tax and shipping, in the right currency. Get these from the actual checkout page in your own browser (open_browser, then look), not from memory.
+2. \`create_spend_request\` with that merchant, those line items and that total. If it comes back without an approval link, call \`request_spend_approval\`. Send the person the approval link as a plain link, and wait. Do not create a second request for the same purchase.
+3. When \`retrieve_spend_request\` says approved, use \`pay_on_computer\` to type the one-time card into the checkout. You give it the selectors of the card fields you can see; the card itself never comes to you. Check the filled form in a screenshot, confirm the total still matches, then submit.
+4. Report the outcome with \`create_report\`: succeeded, failed, or what the merchant said. If the merchant needs more (3-D Secure, a code), stop and tell the person exactly what is on the screen; they can take over your screen.
+
+Never read card numbers or CVCs aloud, never paste them into chat or a file, never guess a total. If Link asks for verification you cannot complete, say so.
+`;

package/dist/link-cli-auth.d.ts

@@ -0,0 +1,34 @@
+import type { ToolAuthProvider } from "eve/tools";
+/**
+ * The owner's Link sign-in, as the agent's wallet credential.
+ *
+ * `link-cli auth login` on the agent's host is a device-code flow the owner
+ * approves in the Link app; the CLI keeps the resulting tokens in its config
+ * file and refreshes them itself. This provider reads that file for the live
+ * access token and, when it is about to expire, asks the CLI to refresh by
+ * running one harmless command. No token is ever copied into env or source.
+ *
+ * Single-owner by design: every tool call through this mount spends from the
+ * wallet signed in on this host. That is what Sid is — Ian's agent paying from
+ * Ian's wallet, with Ian approving each purchase in Link. A shared agent needs
+ * per-person OAuth through the control plane instead.
+ */
+export interface LinkCliAuthOptions {
+    /** The CLI's config file. Defaults to LINK_AUTH_FILE, else the CLI's own default location. */
+    authFile?: string;
+    /** How close to expiry triggers a refresh. Default 2 minutes. */
+    refreshSkewMs?: number;
+    /** The CLI binary. Defaults to the one this package depends on. */
+    cliPath?: string;
+}
+interface StoredAuth {
+    access_token?: string;
+    refresh_token?: string;
+    expires_at?: number;
+}
+export declare function linkCliAuthFile(explicit?: string): string;
+export declare function readStoredAuth(file: string): StoredAuth | null;
+export declare const NOT_SIGNED_IN = "Link is not signed in on this host. The owner runs `npx link-cli auth login --client-name <agent>` here and approves it in the Link app; the agent cannot do this step.";
+/** An eve tool auth provider: the owner's current Link access token, refreshed through the CLI when near expiry. */
+export declare function linkCliAuth(options?: LinkCliAuthOptions): ToolAuthProvider;
+export {};

package/dist/link-cli-auth.js

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function linkCliAuthFile(explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.LINK_AUTH_FILE)
+        return process.env.LINK_AUTH_FILE;
+    // `conf` with projectName "link-cli": ~/.config/link-cli-nodejs/config.json on Linux and macOS.
+    const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(base, "link-cli-nodejs", "config.json");
+}
+export function readStoredAuth(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return parsed.auth ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export const NOT_SIGNED_IN = "Link is not signed in on this host. The owner runs `npx link-cli auth login --client-name <agent>` here and approves it in the Link app; the agent cannot do this step.";
+function runCli(cliPath, args, env) {
+    return new Promise((resolve) => {
+        const child = spawn(cliPath, args, { stdio: ["ignore", "ignore", "ignore"], env });
+        child.on("error", () => resolve(1));
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+/** An eve tool auth provider: the owner's current Link access token, refreshed through the CLI when near expiry. */
+export function linkCliAuth(options = {}) {
+    const file = linkCliAuthFile(options.authFile);
+    const skew = options.refreshSkewMs ?? 120_000;
+    const cli = options.cliPath ?? "link-cli";
+    return {
+        principalType: "app",
+        displayName: "Link wallet (owner's link-cli sign-in)",
+        async getToken() {
+            let auth = readStoredAuth(file);
+            if (!auth?.access_token)
+                throw new Error(NOT_SIGNED_IN);
+            if (auth.expires_at !== undefined && auth.expires_at - Date.now() < skew) {
+                // Any authenticated command makes the CLI refresh and persist. user-info is read-only.
+                await runCli(cli, ["user-info", "retrieve", "--format", "json"], { ...process.env, LINK_AUTH_FILE: file, NO_UPDATE_NOTIFIER: "1" });
+                auth = readStoredAuth(file);
+                if (!auth?.access_token)
+                    throw new Error(NOT_SIGNED_IN);
+            }
+            return { token: auth.access_token, ...(auth.expires_at ? { expiresAt: auth.expires_at } : {}) };
+        },
+    };
+}

package/dist/link-tools.d.ts

@@ -0,0 +1,29 @@
+import { Link } from "@stripe/link-sdk";
+import { type ToolDefinition } from "eve/tools";
+import { type LinkCliAuthOptions } from "./link-cli-auth.js";
+/**
+ * Stripe's Link tools, mounted the Kybernesis way.
+ *
+ * Stripe ships an eve extension, but it is built against an older eve and
+ * eve 0.68 refuses to mount it. The same tool catalog is available
+ * framework-free from `@stripe/link-sdk/tools`, so each one is wrapped here as
+ * an eve tool: the owner's link-cli sign-in supplies the token on every call,
+ * creating a spend request asks the person in eve before it asks them in Link,
+ * and anything that could carry a card number is stripped from what the model
+ * sees — the card has exactly one path, `pay_on_computer`.
+ */
+export declare const LINK_TOOL_NAMES: readonly ["retrieve_user_info", "list_payment_methods", "list_shipping_addresses", "list_spend_requests", "create_spend_request", "update_spend_request", "cancel_spend_request", "request_spend_approval", "retrieve_spend_request", "create_report"];
+export type LinkToolName = (typeof LINK_TOOL_NAMES)[number];
+/** A Link client whose token is the owner's current link-cli sign-in, read at call time. */
+export declare function linkClient(options?: LinkCliAuthOptions): Link;
+/** Remove anything that is or contains a card credential before it reaches the model. */
+export declare function sanitizeLinkOutput<T>(value: T): T;
+/**
+ * One Link tool as an eve tool. Mount each in `agent/tools/<name>.ts`:
+ *
+ * ```ts
+ * import { linkTool } from "@kybernesis/payments";
+ * export default linkTool("create_spend_request");
+ * ```
+ */
+export declare function linkTool<N extends LinkToolName>(name: N, options?: LinkCliAuthOptions): ToolDefinition<Record<string, unknown>, unknown>;

package/dist/link-tools.js

@@ -0,0 +1,71 @@
+import { Link } from "@stripe/link-sdk";
+import { createLinkTools } from "@stripe/link-sdk/tools";
+import { defineTool } from "eve/tools";
+import { always, never } from "eve/tools/approval";
+import { linkCliAuth } from "./link-cli-auth.js";
+/**
+ * Stripe's Link tools, mounted the Kybernesis way.
+ *
+ * Stripe ships an eve extension, but it is built against an older eve and
+ * eve 0.68 refuses to mount it. The same tool catalog is available
+ * framework-free from `@stripe/link-sdk/tools`, so each one is wrapped here as
+ * an eve tool: the owner's link-cli sign-in supplies the token on every call,
+ * creating a spend request asks the person in eve before it asks them in Link,
+ * and anything that could carry a card number is stripped from what the model
+ * sees — the card has exactly one path, `pay_on_computer`.
+ */
+export const LINK_TOOL_NAMES = [
+    "retrieve_user_info",
+    "list_payment_methods",
+    "list_shipping_addresses",
+    "list_spend_requests",
+    "create_spend_request",
+    "update_spend_request",
+    "cancel_spend_request",
+    "request_spend_approval",
+    "retrieve_spend_request",
+    "create_report",
+];
+/** A Link client whose token is the owner's current link-cli sign-in, read at call time. */
+export function linkClient(options = {}) {
+    const auth = linkCliAuth(options);
+    return new Link({ getAccessToken: async () => (await auth.getToken({})).token });
+}
+/** Remove anything that is or contains a card credential before it reaches the model. */
+export function sanitizeLinkOutput(value) {
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeLinkOutput(v));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (k === "card" || k === "credential" || k === "number" || k === "cvc" || k === "payment_token" || k === "shared_payment_token")
+                continue;
+            out[k] = sanitizeLinkOutput(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * One Link tool as an eve tool. Mount each in `agent/tools/<name>.ts`:
+ *
+ * ```ts
+ * import { linkTool } from "@kybernesis/payments";
+ * export default linkTool("create_spend_request");
+ * ```
+ */
+export function linkTool(name, options = {}) {
+    const catalog = createLinkTools(linkClient(options));
+    const tool = catalog[name];
+    return defineTool({
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        // Asking Link for money starts with asking the person here. Reading and
+        // reporting do not; Link's own approval step still gates every card.
+        approval: name === "create_spend_request" ? always() : never(),
+        async execute(input, ctx) {
+            const result = await tool.execute(input, ctx);
+            return sanitizeLinkOutput(result);
+        },
+    });
+}

package/dist/pay-on-computer.d.ts

@@ -0,0 +1,51 @@
+import type { LinkCliAuthOptions } from "./link-cli-auth.js";
+/**
+ * Type the one-time card of an APPROVED Link spend request into a checkout
+ * form on the agent's own computer. The card number and CVC go from Link to
+ * the page and nowhere else: not into this tool's result, not into the
+ * transcript, not into a screenshot caption.
+ *
+ * Eve's approval is deliberately `never()` here — the money decision already
+ * happened twice: the agent asked eve's user approval to create the spend
+ * request, and the person approved the purchase in Link. Filling the card for
+ * a request that is not approved is refused.
+ */
+export declare function payOnComputerTool(options?: LinkCliAuthOptions): import("eve/tools").ToolDefinition<{
+    spend_request_id: string;
+    page_url: string;
+    fields: {
+        field: "number" | "cvc" | "name" | "exp_month" | "exp_year" | "expiration" | "postal_code";
+        selector: string;
+        frameUrl?: string | undefined;
+        format?: "MM/YY" | "MM/YYYY" | undefined;
+    }[];
+}, {
+    ok: boolean;
+    filled: number;
+    missing: readonly string[];
+    card: {
+        brand: string;
+        last4: string;
+    };
+    note: string;
+}> & {
+    execute(input: {
+        spend_request_id: string;
+        page_url: string;
+        fields: {
+            field: "number" | "cvc" | "name" | "exp_month" | "exp_year" | "expiration" | "postal_code";
+            selector: string;
+            frameUrl?: string | undefined;
+            format?: "MM/YY" | "MM/YYYY" | undefined;
+        }[];
+    }, ctx: import("eve/tools").ToolContext): Promise<{
+        ok: boolean;
+        filled: number;
+        missing: readonly string[];
+        card: {
+            brand: string;
+            last4: string;
+        };
+        note: string;
+    }>;
+};

package/dist/pay-on-computer.js

@@ -0,0 +1,73 @@
+import { fillOnComputer } from "@kybernesis/computer";
+import { defineTool } from "eve/tools";
+import { never } from "eve/tools/approval";
+import { z } from "zod";
+import { linkClient } from "./link-tools.js";
+const fieldSchema = z.object({
+    field: z.enum(["name", "number", "exp_month", "exp_year", "expiration", "cvc", "postal_code"]),
+    selector: z.string().min(1).max(500).describe("CSS selector of that input on the checkout page."),
+    frameUrl: z.string().url().optional().describe("If the input lives in an iframe (common for card fields), that frame's URL prefix."),
+    format: z.enum(["MM/YY", "MM/YYYY"]).optional().describe("For a combined expiration field."),
+});
+/**
+ * Type the one-time card of an APPROVED Link spend request into a checkout
+ * form on the agent's own computer. The card number and CVC go from Link to
+ * the page and nowhere else: not into this tool's result, not into the
+ * transcript, not into a screenshot caption.
+ *
+ * Eve's approval is deliberately `never()` here — the money decision already
+ * happened twice: the agent asked eve's user approval to create the spend
+ * request, and the person approved the purchase in Link. Filling the card for
+ * a request that is not approved is refused.
+ */
+export function payOnComputerTool(options = {}) {
+    const link = linkClient(options);
+    return defineTool({
+        description: "Type the one-time card from an APPROVED Link spend request into the checkout form open in your own browser. Give the CSS selector of each card field you can see (name, number, expiration or exp_month/exp_year, cvc, postal code). The card details never come back to you; the result says which fields were filled. Open the checkout with open_browser first and look at it.",
+        inputSchema: z.object({
+            spend_request_id: z.string().min(1).max(200),
+            page_url: z.string().url().describe("The checkout page's URL, as shown in the browser."),
+            fields: z.array(fieldSchema).min(2).max(7),
+        }),
+        approval: never(),
+        async execute(input, ctx) {
+            const request = await link.spendRequests.retrieve(input.spend_request_id, { include: ["card"] });
+            if (!request)
+                throw new Error("That spend request does not exist.");
+            if (request.status !== "approved") {
+                throw new Error(`Spend request is ${request.status}, not approved. Send the approval link and wait for the person to approve it in Link.`);
+            }
+            const card = request.card;
+            if (!card)
+                throw new Error("Link did not return a card for this request; it may need a different credential type.");
+            const yy = String(card.exp_year).slice(-2);
+            const mm = String(card.exp_month).padStart(2, "0");
+            const values = {
+                name: card.billing_address?.name,
+                number: card.number,
+                exp_month: mm,
+                exp_year: String(card.exp_year),
+                cvc: card.cvc,
+                postal_code: card.billing_address?.postal_code,
+            };
+            const fields = [];
+            for (const f of input.fields) {
+                const value = f.field === "expiration" ? (f.format === "MM/YYYY" ? `${mm}/${card.exp_year}` : `${mm}/${yy}`) : values[f.field];
+                if (value === undefined)
+                    continue;
+                fields.push({ selector: f.selector, value, ...(f.frameUrl ? { frameUrl: f.frameUrl } : {}) });
+            }
+            const sandbox = await ctx.getSandbox();
+            const result = await fillOnComputer(sandbox, { pageOrigin: new URL(input.page_url).origin, fields });
+            return {
+                ok: result.ok,
+                filled: result.filled.length,
+                missing: result.missing,
+                card: { brand: card.brand ?? "card", last4: card.number.slice(-4) },
+                note: result.ok
+                    ? "Card details are in the form. Take a screenshot, check the totals match the spend request, then submit the order and report the outcome with create_report."
+                    : "Some fields could not be found; look at the page again and correct the selectors.",
+            };
+        },
+    });
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@kybernesis/payments",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Stripe Link as an eve agent's wallet, on its owner's behalf: Link's tool catalog mounted as eve tools behind the owner's link-cli sign-in, the person's approval on every purchase, and a one-time card typed into a checkout on the agent's own computer without the model ever seeing it.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KybernesisAI/platform.git",
+    "directory": "packages/payments"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish.mjs",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "dependencies": {
+    "@stripe/link-cli": "^0.26.0",
+    "@stripe/link-sdk": "^0.11.0"
+  },
+  "peerDependencies": {
+    "@kybernesis/computer": ">=0.2.0 <0.3.0",
+    "eve": ">=0.68.0 <0.69.0",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@kybernesis/computer": "*",
+    "eve": "0.68.0",
+    "zod": "^4.0.0",
+    "typescript": "^5.9.0",
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}