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

package/dist/server.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { GUIDE_INSTRUCTIONS, packagedGuide, registerGuide } from "./guide.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl, } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { RideOAuthProvider, InMemoryOAuthStateStore, createRedisOAuthStateStore, createRideOAuthApprovalRouter, RIDE_OAUTH_SCOPES, } from "./oauth.js";
+import { createRideHttpApp, requestBodyErrorHandler } from "./http_security.js";
+import { registerAgentTools, registerAppAccountRead, invokeAgent, } from "./agent/mcp.js";
+import { invokeAccountRead } from "./account_reads.js";
+import { mountAgentProxy } from "./agent/http.js";
+import { mountHumanConfirmation } from "./agent/human.js";
+import { redisHumanHandoffs } from "./agent/human_handoffs.js";
+import { validateCoreIdentity } from "./agent/backend.js";
+import { AgentError, mutationTools } from "./agent/contracts.js";
+import { VERSION } from "./version.js";
+async function main() {
+    const required = (key) => {
+        const v = process.env[key];
+        if (!v)
+            throw new Error(`${key} is required`);
+        return v;
+    };
+    const host = process.env.HOST ?? "127.0.0.1", port = Number(process.env.PORT ?? 3333), base = new URL(required("PUBLIC_BASE_URL")), backend = required("RIDE_AGENT_BACKEND_URL"), graphql = required("RIDE_GRAPHQL_URL");
+    if (base.protocol !== "https:" &&
+        !["127.0.0.1", "localhost"].includes(base.hostname))
+        throw new Error("Public issuer must use HTTPS");
+    if (!process.env.REDIS_URL &&
+        !["127.0.0.1", "localhost"].includes(base.hostname))
+        throw new Error("Hosted OAuth requires Redis");
+    const store = process.env.REDIS_URL
+        ? await createRedisOAuthStateStore({ url: process.env.REDIS_URL })
+        : new InMemoryOAuthStateStore();
+    const config = {
+        privyAppId: required("PRIVY_APP_ID"),
+        privyClientId: process.env.PRIVY_CLIENT_ID ?? "",
+        jsSdkUrl: process.env.PRIVY_JS_SDK_URL ??
+            "https://esm.sh/@privy-io/js-sdk-core@0.67.0",
+        manualTokenAuthEnabled: false,
+    };
+    const exchange = async (input) => {
+        const response = await fetch(graphql, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: "mutation AgentLogin($input:SyncPrivyUserInput!){syncPrivyUser(input:$input){accessToken user{id username}}}",
+                variables: {
+                    input: {
+                        ...input,
+                        authProvider: input.authProvider ?? "GOOGLE",
+                        appVersion: "1.0.0",
+                        platform: "WEB",
+                        deviceName: "Ride Agent",
+                    },
+                },
+            }),
+            signal: AbortSignal.timeout(15000),
+            redirect: "error",
+        });
+        const data = (await response.json());
+        const login = data.data?.syncPrivyUser;
+        if (!response.ok ||
+            data.errors?.length ||
+            !login?.accessToken ||
+            !login.user?.id)
+            throw new AgentError("AUTH_REQUIRED", "Ride sign-in failed.", false, 401);
+        return {
+            rideAuthToken: login.accessToken,
+            identity: {
+                subject: login.user.id,
+                displayName: login.user.username ?? "Ride user",
+            },
+        };
+    };
+    const provider = new RideOAuthProvider({
+        store,
+        validateRideToken: async (token) => ({
+            subject: await validateCoreIdentity(token, graphql),
+        }),
+        exchangePrivyToken: exchange,
+        authPage: config,
+    });
+    const app = createRideHttpApp(host), resource = new URL("/mcp", base), auth = requireBearerAuth({
+        verifier: provider,
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resource),
+    }), readOnly = process.env.RIDE_PUBLIC_SUBMISSION_MODE === "true";
+    app.use(mcpAuthRouter({
+        provider,
+        issuerUrl: base,
+        baseUrl: base,
+        resourceServerUrl: resource,
+        scopesSupported: [...RIDE_OAUTH_SCOPES],
+        resourceName: "Ride",
+    }));
+    app.use(createRideOAuthApprovalRouter(provider));
+    const accountRead = (name, args, token) => invokeAccountRead(name, args, token, graphql, () => invokeAgent(backend, token, "get_portfolio", args));
+    mountAgentProxy(app, auth, backend, readOnly, accountRead);
+    if (!readOnly) {
+        mountHumanConfirmation(app, {
+            backend,
+            base: base.href,
+            cookieKey: required("RIDE_AGENT_HUMAN_COOKIE_KEY"),
+            auth: config,
+            exchange,
+            handoffs: process.env.REDIS_URL
+                ? await redisHumanHandoffs(process.env.REDIS_URL)
+                : undefined,
+        });
+    }
+    app.get("/health", (_req, res) => res.json({
+        service: "ride-agent-mcp",
+        version: "3",
+        release: VERSION,
+        public_submission_mode: readOnly,
+    }));
+    app.post("/mcp", auth, async (req, res) => {
+        const server = new McpServer({ name: "ride", title: "Ride Agent", version: VERSION }, { instructions: GUIDE_INSTRUCTIONS });
+        registerGuide(server);
+        registerAgentTools(server, async (name, args, extra) => {
+            if (!extra.authInfo?.scopes?.includes(mutationTools.has(name) ? "ride:trade" : "ride:read"))
+                throw new AgentError("SCOPE_REQUIRED", "Ride OAuth scope is missing.", false, 403);
+            const token = extra.authInfo?.extra?.rideAuthToken;
+            if (name === "get_portfolio" && typeof token === "string")
+                return accountRead(name, args, token);
+            return invokeAgent(backend, typeof token === "string" ? token : undefined, name, args);
+        }, readOnly, {
+            base: base.href,
+            readProposal: (id, extra) => invokeAgent(backend, extra.authInfo?.extra?.rideAuthToken, "proposal", { proposal_id: id }),
+        });
+        registerAppAccountRead(server, async (args, extra) => {
+            if (!extra.authInfo?.scopes?.includes("ride:read"))
+                throw new AgentError("SCOPE_REQUIRED", "Missing ride:read permission.", false, 403);
+            const token = extra.authInfo?.extra?.rideAuthToken;
+            if (typeof token !== "string")
+                throw new AgentError("AUTH_REQUIRED", "A Ride OAuth session is required.", false, 401);
+            return accountRead("get_my_copies", args, token);
+        });
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch {
+            if (!res.headersSent)
+                res.status(500).json({ error: "mcp_request_failed" });
+        }
+    });
+    app.get("/mcp", (_req, res) => res.status(405).json({ error: "method_not_allowed" }));
+    app.get("/ride/guide", async (_req, res) => {
+        try {
+            res.setHeader("Cache-Control", "no-store");
+            res.json(await packagedGuide());
+        }
+        catch {
+            res.status(503).json({ error: "guide_unavailable" });
+        }
+    });
+    app.use(requestBodyErrorHandler);
+    app.listen(port, host, () => console.error(`Ride Agent listening on ${base.origin}/mcp`));
+}
+main().catch(() => {
+    console.error("Ride Agent startup failed. Check required OAuth and backend configuration.");
+    process.exitCode = 1;
+});

package/dist/start.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Keep service roles intact when a platform falls back to npm start.
+const entrypoint = process.env.RIDE_SERVICE_ENTRYPOINT ?? "server";
+switch (entrypoint) {
+    case "server":
+        await import("./server.js");
+        break;
+    case "backend":
+        await import("./backend.js");
+        break;
+    case "bridge":
+        await import("./bridge.js");
+        break;
+    default:
+        console.error("RIDE_SERVICE_ENTRYPOINT must be server, backend or bridge.");
+        process.exitCode = 1;
+}
+export {};

package/dist/version.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+const metadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+export const VERSION = metadata.version;
+export const PACKAGE_NAME = metadata.name;
+// Follow the reviewed package metadata after repository transfers and renames.
+export const GITHUB_REPOSITORY = new URL(metadata.repository.url.replace(/^git\+/, "")).pathname
+    .replace(/^\//, "")
+    .replace(/\.git$/, "");
+export function distributionPackage(distribution) {
+    return distribution === "npm"
+        ? `${PACKAGE_NAME}@${VERSION}`
+        : `github:${GITHUB_REPOSITORY}#v${VERSION}`;
+}
+export function mcpLaunchArgs(distribution, server) {
+    return distribution === "npm"
+        ? [
+            "-y",
+            "--prefer-online",
+            `${PACKAGE_NAME}@latest`,
+            "mcp",
+            "--server",
+            server,
+        ]
+        : ["-y", distributionPackage(distribution), "mcp", "--server", server];
+}

package/docs/confirmation-cards.md

@@ -0,0 +1,118 @@
+# Human confirmation cards and session reuse
+
+`show_confirmation_card` is a read-only render tool. `mode: demo` returns a
+clearly labelled 0-USDC interface demo and never reads an account, creates a
+financial proposal or calls the executor. `mode: proposal` reads an owned frozen
+proposal; the backend continues to validate its owner. Recommendation and
+preference tools keep their conversation-first outputs.
+
+MCP Apps use the versioned `ui://ride/agent-v7-confirmation.html` resource. The
+previous v6, v5, v4 and v3 URIs remain registered. Only the configured Ride origin is added to
+the resource's frame policy. The card embeds `/agent/card/:proposalId`; its
+content and human approval requests run at the Ride origin, separate from the
+model and the MCP App sandbox. Existing confirmation, OAuth and funding pages
+retain `DENY` / `frame-ancestors 'none'`. Only the dedicated card routes allow the
+ChatGPT hosts, Codex's observed `codex-sandbox://*.web-sandbox.oaiusercontent.com`
+sandbox ancestor, `https://claude.ai`, and the Claude MCP sandbox derived from
+`sha256(<this server's canonical /mcp URL>)[:32] + .claudemcpcontent.com`.
+The resource explicitly declares that stable origin in `_meta.ui.domain`.
+Other Claude connectors' sandbox origins are not allowlisted. This only permits
+framing: human endpoints still require the exact Ride origin, session, ownership
+and CSRF checks. A normal confirmation-page link remains available as a fallback.
+The 0-USDC demo also returns a public demo URL for hosts without MCP Apps support.
+If the trusted frame has not reported readiness after eight seconds, the outer
+card hides the unavailable frame and directs the user to that normal Ride page.
+A later verified message from the exact Ride frame can restore the embedded UI.
+This also handles Claude web's observed nested-frame block without changing CSP,
+moving approval controls into the host sandbox or exposing session credentials.
+
+Opening a confirmation page first restores its HttpOnly human cookie through a
+same-origin POST. This returns only its CSRF token and original expiry, never a
+Core JWT, and does not extend the 15-minute lifetime. If that session has expired,
+the page tries the existing Privy session before offering Google sign-in. It
+never initiates Google automatically. Funding pages also reuse a valid human
+cookie while retaining the separate wallet-signing requirements.
+
+The first embedded connection opens the normal Ride sign-in window. An existing
+browser session is reused. That window issues a 60-second, single-use handoff
+bound to a random challenge and proposal ID. It sends the ticket only to its
+same-origin opener. The trusted child frame checks the popup source and origin,
+then exchanges it for a separate HttpOnly, Secure, SameSite=None, Partitioned
+cookie. Redis GETDEL consumes tickets atomically across gateway replicas. The
+embedded cookie retains the original human-session expiry and is limited to
+proposal reads, confirm and reject. It cannot grant autonomous authority or fund
+an account. Blocked popups or unavailable partitioned storage fall back to the
+normal Ride page; no authentication or approval checks are bypassed.
+
+Only sanitized status/height notifications leave the trusted frame. Tokens,
+CSRF values, handoff tickets and signing challenges never enter tool results,
+host messages or model context. No confirm/reject/grant tool is added to MCP.
+Preview hashes, ownership, expiry, portfolio revision and backend idempotency
+remain authoritative. A failed or timed-out confirmation disables repeat
+submission and offers a read of the same proposal ID.
+
+All source changes belong to the independent Ride MCP gateway and its UI. Core,
+GraphQL, workers, legacy App endpoints/schema, approved portfolio settings and
+existing copy configurations are unchanged. Only the gateway needs deployment;
+do not redeploy the bridge, backend or legacy App services for this change.
+
+## Acceptance
+
+Client setup must use the canonical `https://mcp.onride.me/mcp` endpoint. A legacy
+Claude connector pointing at `https://ride-mcp-production.up.railway.app/mcp` was
+observed as Connected with no tools on October 16, 2026. That status does not
+prove a functioning MCP connection. Migrate the URL, complete the client's OAuth
+flow, then verify a real tool call. Use `ride:read` for this acceptance: no trade
+scope, real proposal creation, signing or execution is needed.
+
+Claude and Grok Bot acceptance must distinguish authentication to the AI client,
+Ride MCP OAuth, UI rendering, human confirmation session reuse and actual financial
+execution. A paid-plan or trial gate is a client-access blocker, not a Ride or
+OAuth failure. Do not start a subscription or trial on the user's behalf.
+Protocol compatibility and local fixtures do not establish live host support.
+
+The host bridge distinguishes incoming JSON-RPC requests from responses before
+matching pending IDs. Host and view request IDs are independent: a host `ping`
+using the same ID as `ui/initialize` must receive its own response without
+completing initialization. The view answers `ping` and `ui/resource-teardown`,
+cleans up detached frame listeners/timers, and reports its content height through
+`ui/notifications/size-changed` after initialization and layout changes. A fixed
+host height is respected. These protocol fixes require a fresh resource version
+and a client tool-list refresh; they do not change human authorization.
+
+`/fixture/protocol-host` in the loopback preview tests the real postMessage
+protocol without an OpenAI shim. It deliberately sends a colliding ping before
+the initialization response, delivers a zero-USDC demo, resizes its frame, and
+provides a teardown check. No account or financial operation is available.
+
+Claude web can also fail before any view code runs: its own
+`/v1/toolbox/shttp/mcp/...` proxy was observed returning 405 while all matching
+Ride requests succeeded and no Claude GET reached Ride. This matches the open
+[Claude proxy issue](https://github.com/anthropics/claude-ai-mcp/issues/636).
+Do not label that external failure repaired from protocol tests alone or add an
+unauthenticated transport to work around it. Live acceptance must separately
+check a new card, repeated page reload/resume, the normal Ride fallback and
+session reuse on an already completed proposal, without real submission.
+
+October 16 live acceptance: Claude web renders the outer MCP App at its stable
+origin, but its host blocks the nested Ride frame (`chrome-error://chromewebdata/`).
+Its official open-link flow successfully opens the public demo. Grok Bot 0.71.2
+calls the tools and returns the fallback URL, but does not render MCP Apps in its
+chat. Public demo confirmation and cancellation work on the production gateway.
+These results do not establish inline financial confirmation in either client.
+
+- Current Codex: the user expanded an existing Ride MCP card; its DOM rendered
+  the frozen proposal and clicking the parameter disclosure worked. This proves
+  card rendering and basic interaction, not the new nested confirmation flow.
+- `npm run build`, `npm run check`, `npm test` validate the package and HTTP/MCP
+  contracts. Tests cover cookie reuse, original expiry, tamper/origin/CSRF
+  rejection, replay and embedded operation restrictions. No venue is contacted.
+- `npx tsx scripts/confirmation-preview.ts` serves a loopback fixture. It imports
+  no venue adapter or worker. `/fixture/status` exposes login, read and mock
+  confirmation counters plus a fixed `real_orders: 0`. Browser acceptance covers
+  demo confirm/cancel, normal-page reload without another exchange, popup handoff,
+  repeated card opens without another login and mock proposal confirmation.
+- The new gateway build must be deployed and the Ride connection refreshed
+  before calling `show_confirmation_card` in Codex. Test `mode: demo` first. A
+  successful local fixture does not prove that the current host accepts the new
+  nested frame or that real Google OAuth works inside its popup.

package/docs/conversation-v050.md

@@ -0,0 +1,30 @@
+# Ride Agent conversation flow — 2026-10-15
+
+This revision follows Ride MCP 1015 and the user's subsequent budget-and-risk-first requirements. It retains the six fixes in `widget-account-v043.md`. Earlier V17/v0.4.2 onboarding and batch descriptions are historical; this document and the current live guide supersede those parts.
+
+## Conversation and planning
+
+1. Read saved preferences and ask only for missing USDC budget and risk preference (low/medium/high). Preserve partial answers in either order. A previously explicit numerical risk constraint remains a custom answer. Do not infer a budget from account balance.
+2. Preserve explicit choices; otherwise disclose unrestricted Crypto/RWA, no symbol preset, both markets allowed and Ride-recommended copy mode. Market `both` allows results from either market independently. No initial count, market, loss percentage or execution questionnaire.
+3. Suggest editable numerical portfolio triggers using planning preset v1 (10/20/30% for low/medium/high). Record provenance as `user`, `default`, or `recommended`. Explicit numbers override presets. Suggestions are not user consent and are not guaranteed maximum losses.
+4. Recommend up to four feasible traders, including one. An explicit count/selection supports 1–8 and is never silently reduced. New Agent Perps plans have no 50-USDC product allocation floor and accept a 20-USDC total budget. Keep positive micro-USDC precision, risk/venue leverage caps and execution restrictions. Perps order minimums apply to the actual net opening leg after quantity rounding, with a fresh bridge check and an Agent-only Core check on rounded wire price/size before signing. Skip under-minimum entries without increasing quantity or leverage; expose the reason. Missing venue rules block increases; reduce-only dust closes keep venue exemptions. Prediction allocation rules are unchanged. Existing frozen/approved legacy plans retain their semantics.
+5. Return `recommended_portfolio` and `candidate_table` for two compact native chat tables. The initial `candidate_page` covers the five-row table with total, timestamp and account-bound next cursor. The legacy full `candidates` array remains independent of plan failure. “Best” means prioritized within this verified source pool and constraints.
+6. `browse_traders` sorts the complete verified snapshot by score, historical drawdown or ROI; missing metrics sort last. Page sizes are 1–20; “more 10” uses limit 10 and the same query/cursor. Compare public IDs with `compare_ids`. Unknown metric windows remain unknown and are explicitly non-comparable. Production Perps currently profiles at most the top 30 by Copy Score, plus enabled Prediction results; do not call this all market traders.
+7. `trader_ids` pins the user's selected IDs, mapping one to single and multiple to basket. Preference edits preserve the selection and valid customized amounts/caps/exits. Explain conflicts without substituting traders or resetting allocations. `selection: system` explicitly clears the pin. Paging/sorting/comparison never replace the saved plan. No one-free-change quota remains; old batch inputs are retained only for compatibility.
+8. Patch preferences and allocation settings progressively. Recalculation preserves omitted settings and creates a new immutable preview. Show amount, allocation, unallocated budget, copy mode, leverage caps and portfolio/sleeve exit rules. Then verify per-market funds and create a frozen proposal for human Ride confirmation. No funds or trades are authorized by the preview.
+
+## Presentation and compatibility
+
+Discovery, preference and account tools no longer force a Widget. Their normal surface is AI conversation and small tables. Financial proposals retain the Ride review resource. The manually opened Widget offers a compact two-answer fallback; it no longer exposes a fourteen-field onboarding form or batch quota controls.
+
+The Skill, hosted guide, MCP tool descriptions and CLI use the same flow. `ride traders --sort drawdown --limit 10` and `ride traders --json '{"compare_ids":["PUBLIC_ID_A","PUBLIC_ID_B"]}'` use the same contracts. Existing tool arguments remain accepted; recalculate preferences/allocations can now be partial. State additions are optional JSON fields within the independent Agent table. No legacy App service, schema, account binding, approved portfolio or runner policy is changed.
+
+Unrestricted assets, raw OK removal, full per-market account balances, candidate visibility on failed plans, 1/2/3/4 plans and actionable diagnostics remain covered. Meme account coverage and historical loss correlation remain unavailable rather than zero. New Perps Ride-recommended plans follow verified source leverage with no extra user cap by default and an optional App-style editable 1–40x cap. Explicit caps are independent of the recommendation; execution uses the minimum of source leverage, approved user cap and fresh per-asset venue limit. Existing approved caps are preserved until explicitly changed and confirmed. Budget/margin/loss/entry/minimum-order checks remain active. No extra user cap is represented by `leverage_cap: null`, rather than an arbitrary large number; proportional sizing is separate.
+
+## Acceptance and release boundary
+
+Tests cover partial onboarding, provenance and explicit overrides, automatic 1–4 plans, exact manual counts, paging without duplicates, whole-snapshot sorting, comparisons, cursor ownership/expiry, selected allocation preservation, conditional Fixed settings and proposal-only execution. The shared execution/accounting fixture explicitly requests six traders to keep legacy receipts comparable; new automatic-count scenarios run separately.
+
+`npm run check`, the full suite with a disposable PostgreSQL database, real HTTP/MCP/OAuth/CLI functional scenarios, package install verification and local browser checks are separate evidence. The browser preview uses a clearly labelled scripted client with simulated venue/account data. It does not substitute for live AI-client or real-funds acceptance. Production deployment and npm publishing must be recorded separately; preparing version 0.5.0 does not mean it is released.
+
+Local evidence for this revision: 136/136 tests passed with PostgreSQL enabled; 44/44 real HTTP/MCP/OAuth/CLI scenarios passed; package verification passed clean installs/setup for Codex, Claude Code and Cursor, including no-argument setup. The v0.4.3 managed Skill/client migration is covered, and customized Skills remain protected. Word PRD was rendered and visually checked on all eight pages. No real funding, signing, orders, production deployment or npm publishing was performed for this revision.

package/docs/conversational-v17.md

@@ -0,0 +1,48 @@
+# Conversational V17 implementation · 0.4.0
+
+Historical release reference. Budget/risk-first onboarding and candidate browsing now follow [conversation-v050.md](conversation-v050.md); old upfront-field and batch-quota rules below are superseded.
+
+The supplied HTML is a simulated reference. Production uses the same exploration, preview, funding and review sequence inside the MCP card resource. The host owns the conversation sidebar/composer; Ride owns tool data and cards. The original reference file is preserved.
+
+## Behavior
+
+| Reference requirement | Implementation |
+| --- | --- |
+| Trader exploration before deposit | Primary “View traders first”; recommendations do not require balance |
+| Resume after funding | Saved plans remain account scoped; `get_portfolio` returns the last preview when no portfolio exists; `recalculate_plan` refreshes into a new plan |
+| Alternatives and repeated editing | Selection controls call server validation directly; a single active editor uses its own element references; old cards cannot contribute duplicate amounts |
+| Basket/risk rules | Explicit new single plans use one trader; baskets use 2–8; the historical 50-USDC Perps allocation floor is superseded by per-order venue validation (see conversation-v050.md); Prediction retains its allocation minimum; older plans retain 3–6 unique traders, exact USDC decimals, capital weight ≤55%, Perps recommended caps 3–8× bounded by risk/venue, prediction 1×; live gross concentration ≤60% |
+| Loss rules | New `pause_then_exit` plans pause increases at 30% by default and initiate emergency exits at 70%; legacy `exit` plans retain their original threshold. Portfolio stops can exit everyone first. No guaranteed maximum loss. |
+| Execution | Frozen proposals and human Ride confirmation; distinct configuration/submission/partial/uncertain/settlement states |
+| Replacement | Close/wind down and reconcile old lots, verify available funds, then confirm replacement; one per rolling seven days, old copy preserved |
+| Historical reports | Immutable hourly/event accounting marks, deposits/withdrawals excluded; displayed daily UTC series; gaps return null period profit |
+| Diagnosis | Same-window source fills, attributed follower fills, decisions, historical parameters, funding and execution status; no invented pairing/counterfactual profit |
+| Notifications | Opt-in daily Ride App digest, local time/IANA timezone, durable per-day deduplication and retry, digest backlog cancelled on opt-out |
+| Funding | Account/network/asset selection from verified provider routes, owned addresses and QR, persisted request IDs and status. Perps funding wallet receipt is separate from venue deposit; prediction bridge completion still requires available-collateral refresh |
+| Copy setup | Separate risk tolerance and fixed/proportional settings; Fixed uses verified source fills and recorded pre-trade positions; gaps block increases |
+| Recommendation batches | One free batch change, stored Batch 1/2, quota retained after edits, browsing keeps the edited basket |
+| Compatibility | Shared assets/direction/holding/style flags and improving alternatives; explicit acknowledgment binds to the immutable plan; unknown historical loss correlation is unavailable |
+| Daily return | Account-scoped local-date check-in key, offer once per day; no unsolicited host message |
+| Charts | Persisted net-profit/account-value switch, gaps remain gaps, recorded fills retain original attribution |
+| RWA | Official asset taxonomy and historical RWA category, exact qualified symbols, verified USDC collateral and Standard account mode, independent scoped collateral validation |
+| Other hosts | Same twenty Agent tools, Skill and CLI; MCP App buttons use the standard `tools/call` method |
+
+The MCP App protocol follows the [official extension overview](https://apps.extensions.modelcontextprotocol.io/api/documents/Overview.html). Cards communicate through the host; no client signing secrets or direct venue requests are embedded.
+
+## Coverage and limits
+
+Recording starts when the new monitor observes an owned account. Earlier periods and missing event-time configurations cannot be backfilled from current trader selection. Old receipts are not reconstructed using current settings. Prediction source fill history remains explicitly unavailable; verified follower accounting remains usable. Source/follower fills are displayed as separate evidence unless causal linkage is recorded. Diagnostics do not prove hypothetical missed returns.
+
+Daily UTC display marks are capped at the latest 366 days, with `series_truncated` and `full_snapshot_count` disclosed. Underlying snapshots remain stored. Push readiness requires Firebase configuration and a registered Ride App device. “Delivered” in the outbox means the provider accepted the request, not that the user viewed it.
+
+This release adds optional JSON fields and tool/API routes in the independent Agent services. New private Agent Core API/gRPC and the independent execution worker opt into scoped markets. The database guard adjusts only Agent execution tables, rejects non-Agent qualified assets and does not add an SQLx migration version, so old App binaries can restart with their existing migration registry. Legacy App GraphQL/RPC contracts, API/gRPC/worker deployments and copy tables are unchanged. Full native App regression and funded exchange/push acceptance require the corresponding live accounts/devices.
+
+## Acceptance
+
+Run `npm run check`, `npm test` with an isolated `RIDE_AGENT_TEST_DATABASE_URL`, `npm run test:functional` with `RIDE_AGENT_FUNCTIONAL_DATABASE_URL`, and `npm run verify:package`.
+
+The functional harness exercises real HTTP, MCP, OAuth PKCE, CLI and PostgreSQL with simulated Core identities and venue fills. It covers zero-balance preview, expired-plan refresh, repeated edits, owner isolation, fresh confirmation, execution and accounting boundaries, histories, diagnostics and notification persistence. It does not place exchange orders.
+
+For browser acceptance in a cloned repository, run `npm run preview:cards` and open `http://127.0.0.1:17830/preview`. The local host explicitly labels its simulated venue and exposes fixture-only funding/confirmation controls. It is bound to loopback and excluded from the distributed package. The production card HTML and actual Agent HTTP handlers are used unchanged.
+
+Prepare the independent Agent gRPC with `RIDE_AGENT_V17_RWA_SCHEMA_ENABLED=true` and `RIDE_AGENT_RWA_ENABLED=true`, then the private Agent API with `RIDE_AGENT_INTERNAL_ONLY=true`. The API exposes only health/readiness and authenticated Agent Core operations and starts no legacy queue forwarders or Meme sync. Point only the independent Agent worker and bridge to these services. Deploy the bridge and Agent backend before the MCP gateway. Keep old App service sources and flags. Rollback to the previous source revision retains added JSON fields; the previous code preserves unknown fields when persisting state. Earlier releases do not schedule the new daily digest.

package/docs/deployment.md

@@ -0,0 +1,58 @@
+# Deploying V3
+
+The client installation is independent of server activation. Three Node services communicate with the additive private Ride Core gateway. Provision PostgreSQL and Redis, configure Privy approved origins/redirects, install the Core migrations and deploy the API/worker/scheduler changes, then deploy the public gateway and native App with matching URLs. Existing App behavior remains behind the default-off feature flags.
+
+## Gateway
+
+- `PUBLIC_BASE_URL`: HTTPS OAuth issuer, for example `https://mcp.onride.me`.
+- `RIDE_GRAPHQL_URL`: Ride Core GraphQL endpoint for authenticated login and identity.
+- `PRIVY_APP_ID`, optional `PRIVY_CLIENT_ID`: approved Privy application.
+- `REDIS_URL`: durable hosted OAuth state; required for non-loopback issuers.
+- `RIDE_AGENT_BACKEND_URL`: private control service URL.
+- `RIDE_AGENT_HUMAN_COOKIE_KEY`: at least 32-byte independent cookie encryption secret.
+- `RIDE_PUBLIC_SUBMISSION_MODE=true`: eight read tools, no machine write or browser confirmation routes.
+  Read-only CLI query routes remain available. Trading requests return `READ_ONLY`.
+
+The native App sends its existing Core JWT directly to `/agent/human/*`. OAuth machine tokens cannot confirm, authorize or revoke. The browser human surface signs in through Privy and uses encrypted, HttpOnly, SameSite cookies plus origin checks.
+
+## Agent service
+
+- `RIDE_AGENT_DATABASE_URL`: separate Agent PostgreSQL database.
+- `RIDE_AGENT_CURSOR_KEY`: at least 32 characters for user-bound update cursors.
+- `RIDE_GRAPHQL_URL`: authenticated Core identity validation.
+- `RIDE_AGENT_EXECUTOR_URL`, `RIDE_AGENT_EXECUTOR_TOKEN`: private bridge URL and service token.
+- `RIDE_AGENT_PRIVATE_HTTP_HOST`: optional exact bridge hostname ending in `.railway.internal` when using Railway's encrypted private network over HTTP. Public executor connections require HTTPS.
+- `PUBLIC_BASE_URL`: matching Ride human review base.
+- `RIDE_AGENT_ENABLED=true`: explicit service activation.
+- `RIDE_AGENT_READ_ONLY=true`: reject backend machine writes and human confirmation/grant operations; suspend the background trading monitor. Pair with the gateway read-only flag for initial production rollout.
+
+State and ledger records persist in PostgreSQL; each user transition locks its row and rolls back failed confirmation. The monitor starts with the service and polls independently of MCP clients. Keep a single monitor instance per Agent database until cross-process scheduling leases are added; user transactions serialize changes, but overlapping network observations should be avoided operationally.
+
+## Private execution bridge and Core
+
+- `RIDE_AGENT_CORE_URL`: private Core base URL with `/internal/agent-core/:operation`.
+- `RIDE_AGENT_CORE_SERVICE_TOKEN`: Core S2S token, at least 32 characters.
+- `RIDE_AGENT_DATABASE_URL`: Agent database for stable outbox and opaque outcome metadata.
+- `RIDE_AGENT_TRADER_ID_SALT`: stable, private trader-ID salt; changing it invalidates old public IDs.
+- `RIDE_AGENT_EXECUTOR_TOKEN`: separate token used by the Agent service.
+- `RIDE_AGENT_NETWORK=testnet|mainnet`: Perps execution network; default testnet.
+- `RIDE_AGENT_UNIFIED_ENABLED=true`: opt in to core/USDC unified accounts on the independent bridge and Strategy worker. Default off. The worker additionally requires Agent V3 metadata; legacy Strategy validation remains Standard-only. Unified USDC is read once from spot state, subtracts verified holds for available margin, and rejects other DEX exposure/orders. Portfolio margin and unified RWA execution remain unsupported. This flag does not change the user's account mode or transfer funds.
+- `RIDE_AGENT_PREDICTION_ENABLED=true` plus `RIDE_AGENT_POLYGON_RPC_URL`: explicit prediction activation on Polygon. Prediction has no paper-trading mode in this integration.
+- `FCM_SERVICE_ACCOUNT_JSON_BASE64`: reuse the existing Ride Firebase service account on `agent-bridge` only. Legacy raw `FIREBASE_SERVICE_ACCOUNT_JSON` / `FCM_SERVICE_ACCOUNT_JSON` remains supported. Never ship service-account credentials to clients.
+- `RIDE_AGENT_FCM_PROJECT_ID`: optional expected Firebase project; a mismatch fails closed. Existing Ride production uses `ride-fiamma`.
+
+## App daily-report links (0.3.1)
+
+FCM data preserves `type=ride_agent` and includes `event_id`, `event_kind` and, when present, `portfolio_id`. New App builds route a validated event ID to `/agent/reports/:eventId`; existing notification types retain their routes. The page reads `POST /agent/human/update` with `{ "event_id": "update_..." }` using the existing Core bearer session. OAuth MCP tokens cannot read this native endpoint. Missing and foreign reports both return 404. Reports preserve their generated snapshot, including incomplete coverage and null profit; they do not change a portfolio.
+
+Keep Core, the existing App backend and Firebase credential source unchanged. Deploy bridge and backend before updating the public gateway. Verify each terminal deployment and the gateway release independently. A Firebase API acceptance is provider acceptance; simulator injection verifies navigation, and neither establishes physical-device delivery.
+
+Core requires `RIDE_AGENT_CORE_ENABLED=true`, the same Core S2S token, and explicit `RIDE_AGENT_PREDICTION_ENABLED=true` for prediction execution. Set `RIDE_AGENT_NETWORK` consistently in Core and bridge; mainnet also requires Core `RIDE_AGENT_MAINNET_ENABLED=true`. The API and gRPC execution gateway must share their existing `STRATEGY_CONTROL_PLANE_SERVICE_TOKEN`; this is separate from the Node-to-Core token. Existing mainnet execution epoch controls continue to apply. Signing remains in existing workers. Apply all three additive migrations from the private implementation: execution mode/quantity, prediction ownership, and archived account reuse. Legacy mode retains its original policy caps.
+
+Perps account preparation and prediction wallet funding occur through Ride. A combined portfolio checks each market's funds independently and performs no implicit bridge/transfer. Core ownership blocks conflicting legacy writers while Agent owns the account. Release requires complete position and pending-order reconciliation.
+
+Initial production query deployments must also set `RIDE_AGENT_READ_ONLY=true` in Core, with mainnet and prediction execution disabled. The private Core read-only allowlist rejects account and order mutations even with a valid service token.
+
+## Acceptance before activation
+
+Validate OAuth from each supported host, native App proposal hash/owner/revision checks, dedicated account conflicts, unknown-submit restart recovery, partial fill and zero-fill cancellation, real funding/fee reconciliation, hedge removal and gap exits, notification delivery and rollback. Offline test success does not establish venue or deployed App acceptance. Preserve attention states for unresolved prediction redemption, ambiguous receipts and venue dust.

package/docs/perps-leverage.md

@@ -0,0 +1,43 @@
+# Perps source leverage and optional user cap
+
+New Agent Perps allocations use `leverage_mode: "follow_source"` and
+`leverage_cap: null`: there is no extra user cap by default. Numeric settings
+use `custom_cap`, editable from 1–40x like App Auto-Ride. Explicit `null` clears
+the cap; omitted fields preserve it. Prediction remains at 1x.
+
+Actual leverage is the minimum of verified source leverage, the optional user
+cap and fresh per-asset exchange metadata. Missing source/venue evidence blocks
+increases. Changed venue rules invalidate sizing even without a source trade;
+the bridge rejects an increase if its frozen leverage no longer fits fresh
+rules. Budget, gross margin, loss triggers, entry deviation and opening-order
+minimum checks remain in place. Under-minimum orders are skipped without
+increasing quantity or leverage.
+
+Old approved allocations with no `leverage_mode` retain their numeric caps and
+old validation. Changing or clearing a running cap creates a new frozen human
+confirmation proposal. A delegation with a numeric cap never silently approves
+a no-cap plan.
+
+## Isolated rollout
+
+Deploy only the independent Core gRPC, Core API and Core execution services
+first. Their rollout preserves existing approved settings. Verify the gRPC
+schema preflight and all three services before applying bridge/backend changes;
+publish the MCP gateway last. Keep old App API/worker/gRPC services
+on their current deployments. Publish the backend's nullable input support
+before exposing the new gateway tool schemas. No real plan activation or order
+is needed for acceptance.
+
+The opt-in Core bootstrap preserves old policy records, existing numeric
+precision, column-level immutable triggers, long-lived prepared statements,
+the current-policy view identity/permissions and the SQLx migration registry.
+Only execution checks expand within the existing NUMERIC(8,4) range; the
+existing Core 1–100 leverage wire range is not substituted for a user cap.
+Legacy bindings retain their 100% exposure checks. Use the independent gRPC
+pre-deploy command `RIDE_AGENT_SCHEMA_PREFLIGHT_ONLY=true ./grpc` so schema
+validation completes before replacing the running instance. Exchange limits
+and the approved policy are still checked on execution.
+
+Acceptance uses a disposable PostgreSQL database and simulated exchanges:
+20-USDC plans, 10-USDC sleeves, optional 20x/40x caps, clearing caps, verified
+source/venue limits above 40x, legacy 3x preservation and minimum-order skips.

package/docs/prediction-history.md

@@ -0,0 +1,28 @@
+# Prediction historical risk metrics
+
+Prediction candidates previously returned null historical ROI/drawdown. The first repair added a native economic-PnL path, but many upstream points carry old observations and some wallets lack a complete lifetime funding ledger. Those remain unavailable in that path; the checks are not relaxed.
+
+## Reconstruct historical equity independently
+
+The Agent bridge can now reconstruct a one-month daily inventory curve from the configured Polygon RPC and official Polymarket prices:
+
+1. Fix a confirmed chain block, network 137, and a common UTC daily grid covering at least 28 days.
+2. Enumerate current OPEN and REDEEMABLE_LOST outcome inventory, plus every relevant ERC-1155 transfer in the window. Losing unredeemed positions must be included because they can have had positive historical value.
+3. Follow both directions of `alchemy_getAssetTransfers` to explicit completion for the two collateral tokens and configured CTF contract. Retain raw integer ERC-20 and ERC-1155 amounts, token IDs, blocks and timestamps; de-duplicate self-transfers by log identity.
+4. Read actual cash and batch outcome balances at the end block, reverse the complete transfers to each historical instant, then independently read every balance at the start block. Every reconstructed boundary balance must match exactly. Wallet activity and chain transfers cross-check financial transaction coverage. Missing activity rows for direct ERC-20 transfers or exact Safe CALL transfers are independently decoded and matched to actual token/amount/from/to evidence as external capital. Arbitrary calls and delegatecalls are not inferred; complete 1:1 USDC.e/pUSD wrap or unwrap receipt pairs are internal conversions rather than external capital; the issuer's actual vault is resolved on-chain for unwrap receipts. Other unclassified movements fail closed.
+5. Value historical holdings from `/v2/prices-history`. A three-hour aggregate can be used only after its observation window has ended, with at most six hours of price age. Missing coarse bars can use a retained point-in-time observation from a finer tier only if the same no-future and six-hour age checks pass. When the v2 tier is missing a retained quote, a bounded official CLOB archive window can supply an independently timestamped mark, with the same age/no-future checks and a conservatively treated one-hour sampling interval. Out-of-window terminal points are discarded. Fallback sources are disclosed. No interpolation or unlimited carry-forward is allowed. The current anchor additionally uses a point-in-time price read, preserving the 1% reconciliation limit rather than widening it to accommodate a three-hour average. Actual CTF payout numerators/denominators determine settlement prices. The payout slot is derived by matching the actual token ID against CTF collection IDs and on-chain collateral identities; external outcome labels and CLOB indices are not assumed to be payout indices. Resolution block or transaction hints accelerate the lookup only after archive reads prove the zero-to-nonzero payout transition; otherwise binary search locates the first settled block, so current settlement cannot be applied to earlier holdings.
+6. Compare current marked equity with the independent official accounting snapshot, retaining the existing maximum 1% discrepancy rule and its exact disclosed value. Recheck the anchor block hash to reject reorgs.
+
+`E = cash + sum(outcome quantity * observed price)`. Link unit NAV using `(E[i] + interval withdrawals) / (E[i-1] + interval deposits)`; maximum peak-to-trough unit-NAV decline is drawdown, and cumulative unit-NAV change is ROI. Current and historical balances include actual trading fees, redemptions and wallet income without needing missing PnL atoms or a lifetime initial-deposit event. The complete activity feed identifies external deposits/withdrawals and tips for capital-flow adjustment. All arithmetic uses integer raw token units and Decimal.
+
+The results remain **daily sampled, cashflow-adjusted estimated account performance**, with explicit window, basis, three-hour mark resolution, maximum mark age, block range/hash, transfer/token counts and reconciliation difference. They are not all-time/intraday maximum drawdown, follower results, or a future loss bound. Sampling and interval cashflow timing can miss losses within a day. The supported reconstruction scope is the configured v1 CTF contract and two collateral tokens; unsupported token modules, missing prices, incomplete pagination or unclassified transfers remain unavailable with a reason.
+
+## Availability and compatibility
+
+Reconstruction runs outside recommendation latency, at most two wallet jobs and six external HTTP requests at a time, with read-only RPC calls batched in groups of at most twenty and a bounded shared historical-price cache, with a five-minute deadline per wallet. Verified metrics and curve evidence are persisted in the private Agent `ride_agent_prediction_history` cache under opaque trader IDs. A one-hour background refresh retains an earlier verified result only within the existing 36-hour history freshness window. Fresh records survive process restarts. While reconstruction is pending, the original validated PnL path remains available; missing evidence never becomes zero. Scores remain discoverable independently of history availability. No legacy App table, API, approved plan or execution path is changed.
+
+The source contracts are the official [Polymarket v2 Data API](https://data-api.polymarket.com/v2/docs), the official SDK's [accounting snapshot route](https://github.com/Polymarket/py-sdk/blob/main/src/polymarket/_internal/actions/data.py), and [Alchemy's Transfers API](https://www.alchemy.com/docs/data/transfers-api/transfers-endpoints/alchemy-get-asset-transfers).
+
+New recommendations also penalize partially shared topic/asset sets using intersection over union. Exact asset matches keep their existing penalty; style, direction and market penalties remain. This improves topic diversity without fabricating measured loss correlation or changing existing saved portfolios.
+
+The configured portfolio loss trigger, Prediction 1x cap, 50 USDC per-trader minimum, live execution preflight and final human confirmation remain in force.

package/docs/preferences-funding-v042.md

@@ -0,0 +1,17 @@
+# Preferences and trading-account funding · 0.4.2
+
+Historical release reference. Budget/risk-first onboarding and candidate browsing now follow [conversation-v050.md](conversation-v050.md); old upfront-field and batch-quota rules below are superseded.
+
+Recommendations return structured missing questions before reading candidates. `get_preferences` reads saved/partial answers; `set_preferences` merges supplied answers and returns remaining questions. Budget, acceptable loss and market are required; explicit basket/Fixed choices require their size/entry amount. Existing answers and portfolios are retained; older saved previews also restore preferences when their separate preference record was empty. The card starts with empty budget/loss and an unselected market. AI instructions forbid invented values.
+
+`get_deposit_address` and `check_deposit_status` distinguish receiving-wallet USDC from verified trading collateral. `prepare_deposit` freezes an exact amount and owned account, returns a human confirmation URL, and moves no funds. The browser can review a changed amount, then separately confirm funding and any required account activation. Embedded owners sign the existing Core Permit/approveAgent challenges; server-master owners explicitly confirm the existing Core relayer operation. Signatures/challenges are absent from MCP output. All confirmation requests use authenticated Core identity and browser CSRF; no machine confirmation tool is registered.
+
+The funding identity is durably consumed before external submission. Concurrent confirmations submit once; uncertain results block new funding requests. Credit requires the matching native-USDC Transfer log to the fixed Arbitrum bridge and observed trading available balance; wallet credit alone is insufficient. Verified trading balance and sufficient funds for the saved plan are reported separately. Prediction status also reads verified trading collateral instead of treating provider completion as ready.
+
+The isolated Core API opts in with `RIDE_AGENT_FUNDING_ENABLED=true` and `RIDE_AGENT_INTERNAL_ONLY=true`. Its adapter reuses existing funding, wallet-generation, signature-verification and writer-lease capabilities. Other API deployments cannot use this route. Only the isolated API receives references to existing relayer/Privy credentials; automatic deposit/close workers stay disabled. No old App binary, GraphQL/RPC contract, table migration or service deployment is changed.
+
+Acceptance before deployment: 105 TypeScript/PostgreSQL checks; 38 HTTP/MCP/OAuth/CLI/Pg scenarios using simulated identities and transactions; two Core read-only/epoch checks. Browser fixture verified missing-preference gating and funding confirmation through observed trading balance. Fixtures do not establish a real financial transaction. The signed-in Glen account is reserved for human-confirmed production acceptance.
+
+Production acceptance on 2026-10-13: the isolated Core API (`b4afbcf`) and all three MCP services (`ac18f8d`) reached Railway SUCCESS. The public health endpoint reports 0.4.2; authenticated MCP lists 24 tools and serves the updated workflow. Existing preferences and pre-upgrade deposit tickets remain readable. The quote-only preflight reaches the live Core adapter and rejects insufficient receiving-wallet funds without a submission. Trading readiness and saved-plan funding are reported independently. Production browser authentication succeeds; App copy reads have complete coverage, and the old App API readiness/GraphQL probes succeed. Acceptance excludes money movement, so real transfer, wallet signature and trading credit remain unverified. Private account evidence stays outside the distributed package.
+
+Limits: transfers still require the user's confirmation/signature. Unknown broadcasts require reconciliation, not another submission. Existing account ownership fences remain enforced. Funding to the Core Perps scope does not automatically move collateral into an RWA DEX scope. Physical App push/release remains separate.