@onride/agent 0.0.0-stage → 0.5.1-rc.0

package/dist/agent/funding.js

@@ -0,0 +1,230 @@
+import { AgentError, result } from "./contracts.js";
+import { D, cash, fingerprint, now, uid } from "./domain.js";
+function owned(s, depositId) {
+    const d = s.deposits?.find((d) => d.id === depositId);
+    if (!d)
+        throw new AgentError("NOT_FOUND", "Funding request not found for this account.", false, 404);
+    if (d.provider !== "wallet")
+        throw new AgentError("UNSUPPORTED_ACTIVATION", "Prediction bridge funds are credited by the provider; check verified trading balance.");
+    return d;
+}
+const pending = (f) => f && ["submitting", "submitted", "uncertain"].includes(f.status);
+// Signing challenges stay on the authenticated human surface, never in MCP.
+export class FundingService {
+    repository;
+    adapter;
+    base;
+    constructor(repository, adapter, base) {
+        this.repository = repository;
+        this.adapter = adapter;
+        this.base = base;
+    }
+    async call(operation, user, input) {
+        if (!this.adapter.fundingOperation)
+            throw new AgentError("FUNDING_UNAVAILABLE", "Funding activation is unavailable on this deployment.", true, 503);
+        return this.adapter.fundingOperation(operation, user, input);
+    }
+    view(d, human = false) {
+        const f = d.funding;
+        return result({
+            funding: {
+                id: f.id,
+                deposit_id: d.id,
+                amount_usdc: f.amount_usdc,
+                status: f.status,
+                expires_at: f.expires_at,
+                preview_hash: f.preview_hash,
+                account_suffix: d.address.slice(-6),
+                network: "Arbitrum",
+                asset: "USDC",
+                destination: "Your Hyperliquid trading account",
+                confirmation_url: new URL(`/agent/fund/${d.id}`, this.base).href,
+                transaction_hash: f.transaction_hash ?? null,
+                receipt_status: f.receipt_status ?? null,
+                ...(human
+                    ? {
+                        requires_signature: !!f.quote.requires_signature,
+                        signing_wallet: f.quote.wallet.master,
+                        signing_challenge: f.quote.typed_data,
+                        activation: f.activation
+                            ? {
+                                ...f.activation,
+                                quote: undefined,
+                                requires_signature: !!f.activation.quote.requires_signature,
+                                signing_challenge: f.activation.quote.typed_data,
+                            }
+                            : null,
+                    }
+                    : {}),
+            },
+        }, f.status === "requires_confirmation"
+            ? "requires_confirmation"
+            : f.status === "credited"
+                ? "completed"
+                : f.status === "uncertain"
+                    ? "uncertain"
+                    : "queued");
+    }
+    async prepare(user, depositId, amount) {
+        return this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId);
+            const blocking = s.deposits?.find((x) => pending(x.funding));
+            if (blocking) {
+                if (blocking.id === depositId)
+                    return this.view(blocking);
+                throw new AgentError("FUNDING_PENDING", "An earlier funding submission is unresolved. Check its status before preparing another.");
+            }
+            if (d.funding?.status === "requires_confirmation" &&
+                d.funding.expires_at > now() &&
+                D(d.funding.amount_usdc).eq(amount))
+                return this.view(d);
+            const quote = await this.call("quote", user, {
+                amount_usdc: cash(amount),
+                expected_master: d.address,
+            });
+            if (!quote.wallet?.master ||
+                quote.wallet.master.toLowerCase() !== d.address.toLowerCase() ||
+                !D(quote.amount_usdc).eq(amount))
+                throw new AgentError("FUNDING_QUOTE_CHANGED", "Funding quote does not match the owned receiving account and selected amount.");
+            const expires = Math.min(now() + 5 * 60_000, quote.permit_deadline ? quote.permit_deadline * 1000 : Infinity);
+            if (expires <= now())
+                throw new AgentError("FUNDING_QUOTE_EXPIRED", "Review a fresh funding quote.");
+            const observed = await this.adapter.depositStatus?.(d, user);
+            if (observed?.trading_balance_usdc == null)
+                throw new AgentError("TRADING_BALANCE_UNAVAILABLE", "Verify current trading balance before preparing funding.", true);
+            quote.baseline_trading_available_usdc = cash(observed.trading_balance_usdc);
+            d.funding = {
+                id: uid("funding"),
+                amount_usdc: cash(amount),
+                created_at: now(),
+                expires_at: expires,
+                status: "requires_confirmation",
+                quote,
+                preview_hash: fingerprint({
+                    deposit_id: d.id,
+                    amount: cash(amount),
+                    quote,
+                    expires,
+                }),
+            };
+            return this.view(d);
+        });
+    }
+    async read(user, depositId) {
+        return this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId);
+            if (!d.funding)
+                throw new AgentError("FUNDING_NOT_PREPARED", "Choose the exact amount with prepare_deposit first.");
+            return this.view(d, true);
+        });
+    }
+    async confirm(user, depositId, hash, signature) {
+        // Persist consumption before network I/O. A timeout or process restart
+        // cannot roll it back and make the same money action executable again.
+        const selected = await this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId), f = d.funding;
+            if (!f)
+                throw new AgentError("NOT_FOUND", "Funding quote unavailable.");
+            if (f.preview_hash !== hash)
+                throw new AgentError("FUNDING_CHANGED", "Displayed funding parameters changed.");
+            if (f.status !== "requires_confirmation")
+                return { done: this.view(d, true) };
+            if (f.expires_at <= now())
+                throw new AgentError("FUNDING_QUOTE_EXPIRED", "Review a fresh funding quote.");
+            if (f.quote.requires_signature && !signature)
+                throw new AgentError("SIGNATURE_REQUIRED", "Confirm the wallet signature in Ride.");
+            f.status = "submitting";
+            return { funding: structuredClone(f), address: d.address };
+        });
+        if (selected.done)
+            return selected.done;
+        const f = selected.funding;
+        let response;
+        try {
+            response = await this.call("submit", user, {
+                amount_usdc: f.amount_usdc,
+                expected_master: selected.address,
+                request_id: f.id,
+                user_confirmed: true,
+                signature,
+                permit_nonce: f.quote.permit_nonce,
+                permit_deadline: f.quote.permit_deadline,
+            });
+        }
+        catch {
+            // No automatic retry, including a 4xx after a possible broadcast.
+            response = null;
+        }
+        return this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId);
+            if (d.funding?.id !== f.id)
+                throw new AgentError("FUNDING_CHANGED", "Funding identity changed.");
+            if (response?.submitted &&
+                /^0x[a-fA-F0-9]{64}$/.test(response.transaction_hash)) {
+                d.funding.status =
+                    response.receipt_status === "0x0" ? "failed" : "submitted";
+                d.funding.transaction_hash = response.transaction_hash;
+                d.funding.receipt_status = response.receipt_status;
+            }
+            else
+                d.funding.status = "uncertain";
+            return this.view(d, true);
+        });
+    }
+    async activationQuote(user, depositId) {
+        return this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId);
+            if (!d.funding ||
+                !["submitted", "credited", "uncertain"].includes(d.funding.status))
+                throw new AgentError("FUNDING_NOT_SUBMITTED", "Fund this account before activating it.");
+            const status = await this.adapter.depositStatus?.(d, user);
+            if (!status || !D(status.trading_balance_usdc ?? "0").gt(0))
+                throw new AgentError("TRADING_CREDIT_PENDING", "Wait for verified trading account credit before activation.", true);
+            const quote = await this.call("activate_quote", user, {
+                expected_master: d.address,
+            });
+            const expires = now() + 5 * 60_000;
+            d.funding.activation = {
+                quote,
+                expires_at: expires,
+                status: "requires_confirmation",
+                preview_hash: fingerprint({ deposit_id: d.id, quote, expires }),
+            };
+            return this.view(d, true);
+        });
+    }
+    async activate(user, depositId, hash, signature) {
+        const selected = await this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId), a = d.funding?.activation;
+            if (!a || a.preview_hash !== hash || a.expires_at <= now())
+                throw new AgentError("ACTIVATION_CHANGED", "Review a fresh activation request.");
+            if (a.status !== "requires_confirmation")
+                return { done: this.view(d, true) };
+            if (a.quote.requires_signature && !signature)
+                throw new AgentError("SIGNATURE_REQUIRED", "Confirm account activation with your wallet.");
+            a.status = "submitting";
+            return { quote: structuredClone(a.quote), address: d.address };
+        });
+        if (selected.done)
+            return selected.done;
+        let response;
+        try {
+            response = await this.call("activate_submit", user, {
+                expected_master: selected.address,
+                user_confirmed: true,
+                signature,
+                nonce: selected.quote.nonce,
+                expected_agent: selected.quote.typed_data?.message?.agentAddress,
+            });
+        }
+        catch {
+            response = null;
+        }
+        return this.repository.transact(user, async (s) => {
+            const d = owned(s, depositId);
+            d.funding.activation.status =
+                response?.wallet?.status === "active" ? "completed" : "uncertain";
+            return this.view(d, true);
+        });
+    }
+}

package/dist/agent/http.js

@@ -0,0 +1,40 @@
+import { AgentError, failure, inputs, mutationTools, stateTools, publicResult, TOOL_NAMES, } from "./contracts.js";
+import { invokeAgent } from "./mcp.js";
+import { accountCopiesInput } from "../account_reads.js";
+export function mountAgentProxy(app, auth, backend, readOnly = false, accountRead) {
+    app.post("/agent/v1/:operation", auth, async (req, res) => {
+        try {
+            const name = req.params.operation;
+            if (typeof name !== "string" ||
+                (!TOOL_NAMES.includes(name) &&
+                    name !== "proposal" &&
+                    !(accountRead && name === "get_my_copies")))
+                throw new AgentError("NOT_FOUND", "Unknown operation.", false, 404);
+            if (readOnly &&
+                (mutationTools.has(name) ||
+                    (stateTools.has(name) && name !== "recommend_traders") ||
+                    name === "proposal"))
+                throw new AgentError("READ_ONLY", "Trading is not enabled on this deployment.", false, 403);
+            const scope = mutationTools.has(name)
+                ? "ride:trade"
+                : "ride:read";
+            if (!req.auth?.scopes.includes(scope))
+                throw new AgentError("SCOPE_REQUIRED", `Missing ${scope} permission.`, false, 403);
+            const coreToken = req.auth?.extra?.rideAuthToken;
+            if (typeof coreToken !== "string")
+                throw new AgentError("AUTH_REQUIRED", "A Ride OAuth session is required.", false, 401);
+            const args = name === "proposal"
+                ? req.body
+                : name === "get_my_copies"
+                    ? accountCopiesInput.parse(req.body)
+                    : inputs[name].parse(req.body);
+            const value = accountRead && (name === "get_portfolio" || name === "get_my_copies")
+                ? await accountRead(name, args, coreToken)
+                : await invokeAgent(backend, coreToken, name, args);
+            res.set("Cache-Control", "no-store").json(publicResult(value));
+        }
+        catch (e) {
+            res.status(e instanceof AgentError ? e.httpStatus : 400).json(failure(e));
+        }
+    });
+}

package/dist/agent/human.js

@@ -0,0 +1,298 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual, } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { AgentError, failure, publicResult, output } from "./contracts.js";
+import { MemoryHumanHandoffs } from "./human_handoffs.js";
+import { claudeCardDomain } from "./card_hosts.js";
+export function mountHumanConfirmation(app, options) {
+    if (options.cookieKey.length < 32)
+        throw new Error("Human session cookie key must contain at least 32 characters");
+    const key = createHash("sha256").update(options.cookieKey).digest(), origin = new URL(options.base).origin, handoffs = options.handoffs ?? new MemoryHumanHandoffs();
+    const proposalId = z.string().regex(/^proposal_[a-zA-Z0-9_-]{8,100}$/);
+    const browserCookie = "ride_agent_human", embedCookie = "ride_agent_embedded";
+    const requireOrigin = (req) => {
+        if (req.get("origin") !== origin)
+            throw new AgentError("ORIGIN_REQUIRED", "Ride browser origin is required.", false, 403);
+    };
+    const cookies = (req) => Object.fromEntries((req.headers.cookie ?? "").split(";").map((x) => x.trim().split("=")));
+    const seal = (v) => {
+        const iv = randomBytes(12), cipher = createCipheriv("aes-256-gcm", key, iv), body = Buffer.concat([cipher.update(JSON.stringify(v)), cipher.final()]);
+        return Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url");
+    };
+    const unseal = (v) => {
+        try {
+            const b = Buffer.from(v, "base64url"), decipher = createDecipheriv("aes-256-gcm", key, b.subarray(0, 12));
+            decipher.setAuthTag(b.subarray(12, 28));
+            const s = JSON.parse(Buffer.concat([
+                decipher.update(b.subarray(28)),
+                decipher.final(),
+            ]).toString());
+            if (typeof s.token !== "string" ||
+                !s.token ||
+                typeof s.csrf !== "string" ||
+                !Number.isFinite(s.expires_at) ||
+                s.expires_at <= Date.now())
+                throw 0;
+            return s;
+        }
+        catch {
+            throw new AgentError("AUTH_REQUIRED", "Sign in to Ride to confirm.", false, 401);
+        }
+    };
+    const sessionFor = (req) => {
+        const embedded = req.get("x-ride-embedded") === "1";
+        const raw = cookies(req)[embedded ? embedCookie : browserCookie] ?? "";
+        const session = unseal(raw);
+        if (!!session.embedded !== embedded)
+            throw new AgentError("AUTH_REQUIRED", "Sign in to Ride.", false, 401);
+        return { session, raw };
+    };
+    const checkCsrf = (req, csrf) => {
+        const given = Buffer.from(req.get("x-ride-csrf") ?? ""), expected = Buffer.from(csrf);
+        if (given.length !== expected.length || !timingSafeEqual(given, expected))
+            throw new AgentError("CSRF_REQUIRED", "Refresh the Ride sign-in session.", false, 403);
+    };
+    // A same-origin read restores the anti-CSRF token without exposing the Core JWT
+    // or renewing the original 15-minute human session.
+    app.post("/agent/human/session", (req, res) => {
+        try {
+            requireOrigin(req);
+            const { session } = sessionFor(req);
+            res
+                .set("Cache-Control", "no-store")
+                .json({ csrf: session.csrf, expires_at: session.expires_at });
+        }
+        catch (e) {
+            res.status(e instanceof AgentError ? e.httpStatus : 400).json(failure(e));
+        }
+    });
+    app.post("/agent/human/embed-ticket", async (req, res) => {
+        try {
+            requireOrigin(req);
+            if (req.get("x-ride-embedded"))
+                throw new AgentError("AUTH_REQUIRED", "Open Ride sign-in.", false, 401);
+            const { session, raw } = sessionFor(req);
+            checkCsrf(req, session.csrf);
+            const input = z
+                .object({
+                proposal_id: proposalId,
+                challenge: z.string().regex(/^[a-f0-9]{64}$/),
+            })
+                .strict()
+                .parse(req.body);
+            const ticket = await handoffs.issue({
+                ...input,
+                session: raw,
+                expires_at: Math.min(session.expires_at, Date.now() + 60_000),
+            });
+            res.set("Cache-Control", "no-store").json({ ticket });
+        }
+        catch (e) {
+            res.status(e instanceof AgentError ? e.httpStatus : 400).json(failure(e));
+        }
+    });
+    app.post("/agent/human/embed-session", async (req, res) => {
+        try {
+            requireOrigin(req);
+            const input = z
+                .object({
+                ticket: z.string().regex(/^[a-zA-Z0-9_-]{43}$/),
+                proposal_id: proposalId,
+                challenge: z.string().regex(/^[a-f0-9]{64}$/),
+            })
+                .strict()
+                .parse(req.body);
+            const handoff = await handoffs.consume(input.ticket);
+            if (!handoff ||
+                handoff.challenge !== input.challenge ||
+                handoff.proposal_id !== input.proposal_id)
+                throw new AgentError("AUTH_REQUIRED", "Ride sign-in handoff expired. Reopen sign-in.", false, 401);
+            const session = unseal(handoff.session);
+            const embedded = {
+                ...session,
+                embedded: true,
+                csrf: randomBytes(32).toString("base64url"),
+            };
+            res.cookie(embedCookie, seal(embedded), {
+                httpOnly: true,
+                secure: true,
+                sameSite: "none",
+                partitioned: true,
+                path: "/agent",
+                maxAge: Math.max(0, session.expires_at - Date.now()),
+            });
+            res
+                .set("Cache-Control", "no-store")
+                .json({ csrf: embedded.csrf, expires_at: embedded.expires_at });
+        }
+        catch (e) {
+            res.status(e instanceof AgentError ? e.httpStatus : 400).json(failure(e));
+        }
+    });
+    app.get(["/agent/card/:proposalId", "/agent/card-demo"], async (req, res) => {
+        const demo = req.path === "/agent/card-demo";
+        if (!demo && !proposalId.safeParse(req.params.proposalId).success) {
+            res.status(404).end();
+            return;
+        }
+        const template = await readFile(fileURLToPath(new URL("../../public/confirm.html", import.meta.url)), "utf8");
+        const ancestors = options.frameAncestors ?? [
+            "'self'",
+            "https://chatgpt.com",
+            "https://*.chatgpt.com",
+            "https://*.oaiusercontent.com",
+            "codex-sandbox://*.web-sandbox.oaiusercontent.com",
+            "https://claude.ai",
+            // Claude assigns each MCP endpoint its own sandbox origin. Allow only
+            // this server's origin, rather than every connector hosted by Claude.
+            `https://${claudeCardDomain(options.base)}`,
+        ];
+        if (ancestors.some((x) => /[;\r\n]/.test(x)))
+            throw Error("Invalid card frame ancestor");
+        // Only the dedicated card route can be framed; existing confirmation,
+        // OAuth, funding, App and API routes retain DENY/frame-ancestors none.
+        res.removeHeader("X-Frame-Options");
+        res.set("Content-Security-Policy", `base-uri 'self'; frame-ancestors ${ancestors.join(" ")}; object-src 'none'`);
+        res
+            .set("Cache-Control", "no-store")
+            .type("html")
+            .send(template.replace("/*CONFIG*/{}", JSON.stringify({
+            proposal_id: req.params.proposalId,
+            embedded: true,
+            demo,
+            privy_app_id: options.auth.privyAppId,
+            privy_client_id: options.auth.privyClientId,
+            privy_sdk: options.auth.jsSdkUrl,
+        }).replaceAll("<", "\\u003c")));
+    });
+    app.get("/agent/confirm/:proposalId", async (req, res) => {
+        if (!/^proposal_[a-zA-Z0-9_-]{8,100}$/.test(req.params.proposalId)) {
+            res.status(404).end();
+            return;
+        }
+        const template = await readFile(fileURLToPath(new URL("../../public/confirm.html", import.meta.url)), "utf8");
+        const config = {
+            proposal_id: req.params.proposalId,
+            privy_app_id: options.auth.privyAppId,
+            privy_client_id: options.auth.privyClientId,
+            privy_sdk: options.auth.jsSdkUrl,
+        };
+        res
+            .set("Cache-Control", "no-store")
+            .type("html")
+            .send(template.replace("/*CONFIG*/{}", JSON.stringify(config).replaceAll("<", "\\u003c")));
+    });
+    app.get("/agent/fund/:depositId", async (req, res) => {
+        if (!/^deposit_[a-f0-9]{32}$/.test(req.params.depositId)) {
+            res.status(404).end();
+            return;
+        }
+        const template = await readFile(fileURLToPath(new URL("../../public/fund.html", import.meta.url)), "utf8");
+        const config = {
+            deposit_id: req.params.depositId,
+            privy_app_id: options.auth.privyAppId,
+            privy_client_id: options.auth.privyClientId,
+            privy_sdk: options.auth.jsSdkUrl,
+        };
+        res
+            .set("Cache-Control", "no-store")
+            .type("html")
+            .send(template.replace("/*CONFIG*/{}", JSON.stringify(config).replaceAll("<", "\\u003c")));
+    });
+    app.post("/agent/human/login", async (req, res) => {
+        try {
+            if (req.get("origin") !== origin)
+                throw new AgentError("ORIGIN_REQUIRED", "Ride browser origin is required.", false, 403);
+            const input = z
+                .object({
+                privyId: z.string().min(1),
+                privyAccessToken: z.string().min(1),
+                email: z.string().optional(),
+                walletAddress: z.string().optional(),
+                privyWalletId: z.string().optional(),
+                authProvider: z.string().optional(),
+                accessCode: z.string().optional(),
+            })
+                .strict()
+                .parse(req.body);
+            const exchanged = await options.exchange(input), csrf = randomBytes(32).toString("base64url");
+            res.cookie(browserCookie, seal({
+                token: exchanged.rideAuthToken,
+                csrf,
+                expires_at: Date.now() + 15 * 60_000,
+            }), {
+                httpOnly: true,
+                secure: new URL(origin).protocol === "https:",
+                sameSite: "strict",
+                path: "/agent",
+                maxAge: 15 * 60_000,
+            });
+            res.set("Cache-Control", "no-store").json({ csrf });
+        }
+        catch (e) {
+            res.status(e instanceof AgentError ? e.httpStatus : 400).json(failure(e));
+        }
+    });
+    const allowed = new Set([
+        "funding",
+        "funding_prepare",
+        "funding_confirm",
+        "funding_activation_quote",
+        "funding_activate",
+        "funding_status",
+        "proposal",
+        "confirm",
+        "reject",
+        "authorize",
+        "revoke",
+        "portfolio",
+        "updates",
+        "update",
+    ]);
+    app.post("/agent/human/:operation", async (req, res) => {
+        try {
+            if (!allowed.has(req.params.operation))
+                throw new AgentError("NOT_FOUND", "Unknown human operation.", false, 404);
+            let token;
+            const authorization = req.get("authorization");
+            if (authorization) {
+                // Native Ride sends its Core JWT. The backend validates it against
+                // authenticated Core identity; MCP's opaque OAuth tokens fail there.
+                if (!authorization.startsWith("Bearer ") || !authorization.slice(7))
+                    throw new AgentError("AUTH_REQUIRED", "Sign in to Ride.", false, 401);
+                token = authorization.slice(7);
+            }
+            else {
+                if (req.get("origin") !== origin)
+                    throw new AgentError("ORIGIN_REQUIRED", "Ride browser origin is required.", false, 403);
+                const { session } = sessionFor(req);
+                checkCsrf(req, session.csrf);
+                if (session.embedded &&
+                    !["proposal", "confirm", "reject"].includes(req.params.operation))
+                    throw new AgentError("NOT_FOUND", "This operation is unavailable in a confirmation card.", false, 404);
+                token = session.token;
+            }
+            const response = await fetch(new URL(`/agent/human/${req.params.operation}`, options.backend), {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(req.body),
+                signal: AbortSignal.timeout(req.params.operation.startsWith("funding") ? 120000 : 25000),
+                redirect: "error",
+            });
+            const body = await response.json();
+            // Verified signing challenges belong only to this authenticated human
+            // page; MCP routes continue to reject raw trading identities.
+            const value = req.params.operation.startsWith("funding")
+                ? output.parse(body)
+                : publicResult(body);
+            res.status(response.status).set("Cache-Control", "no-store").json(value);
+        }
+        catch (e) {
+            res.status(e instanceof AgentError ? e.httpStatus : 503).json(failure(e));
+        }
+    });
+}

package/dist/agent/human_handoffs.js

@@ -0,0 +1,39 @@
+import { randomBytes } from "node:crypto";
+import { createClient } from "redis";
+export class MemoryHumanHandoffs {
+    values = new Map();
+    async issue(value) {
+        for (const [key, entry] of this.values)
+            if (entry.expires_at <= Date.now())
+                this.values.delete(key);
+        const ticket = randomBytes(32).toString("base64url");
+        this.values.set(ticket, value);
+        return ticket;
+    }
+    async consume(ticket) {
+        const value = this.values.get(ticket);
+        this.values.delete(ticket);
+        return value && value.expires_at > Date.now() ? value : undefined;
+    }
+}
+export async function redisHumanHandoffs(url) {
+    const client = createClient({ url });
+    client.on("error", () => { });
+    await client.connect();
+    const prefix = "ride:agent:human-handoff:";
+    return {
+        async issue(value) {
+            const ticket = randomBytes(32).toString("base64url");
+            await client.set(prefix + ticket, JSON.stringify(value), { PX: 60_000 });
+            return ticket;
+        },
+        async consume(ticket) {
+            // GETDEL makes a browser handoff single-use across gateway replicas.
+            const raw = await client.getDel(prefix + ticket);
+            if (!raw)
+                return undefined;
+            const value = JSON.parse(raw);
+            return value.expires_at > Date.now() ? value : undefined;
+        },
+    };
+}