docs/ASSISTANT.md

Agent workspace

Coordinator update: see AGENT-COORDINATOR.md and COORDINATOR-ADAPTERS.md for the new durable multi-agent jobs. Older single-handoff descriptions below describe the retained legacy flow, not the complete current agent directory. Live release pilots and unrestricted code/test execution remain unverified.

Native Mastra Code Mode (rs_compute) now supports isolated research calculations while retaining the Codex login. See MASTRA-HARNESS.md for current versions, tool limits and the separate gameplay setup.

Research turns now run through a self-hosted Mastra workflow while retaining the existing Codex login and model selection. Connections opens the existing-agent Tincan setup; the assistant can read connection status, but message sending stays in the explicit human-reviewed handoff flow.

The right-side Assistant works in both RS-BLACKROCK and RS-PALANTIR. Chat, Activity, and Reports separate conversation, durable task progress, and interactive evidence. Activity can prepare a reviewed Tincan planning handoff; mission drafts open Command for review. Use the top Assistant button to open/close it. The panel includes current-view context, model and reasoning selectors, streamed answers, source links, copy, stop, expand and new conversation. Below 1050px it overlays the workspace; closing returns focus to the toggle. Chat history survives reload in the local SQLite database, with the current conversation ID saved in browser localStorage. New conversation starts a fresh ID without deleting prior stored messages.

Codex integration

Requires the local codex CLI and an existing signed-in account (codex login). RS_ASSISTANT_CODEX can select another executable. The service launches one lazy stdio codex app-server; there is no browser token, API-key copying, account login mutation, or direct call to an undocumented ChatGPT endpoint. Account/model discovery uses account/read and model/list. GPT-6.1 Sol / High is the requested default; unavailable models fail explicitly instead of silently falling back. Model selectors only expose account-discovered options/efforts.

Each answer uses an ephemeral Codex thread with a bounded recent conversation window. It does not import other Codex conversations, ChatGPT memories, or private files. Questions, selected screen context (optional), recent messages and requested research results are sent through the signed-in Codex account and consume its usage allowance. Opening the panel only discovers status/models; it does not generate an answer. This app owns the saved transcript. The Codex service may process/retain data according to the account's own settings.

Research boundaries

rs_research reads overview, lookup, quote, completed-trade history, opportunities, public bank previews, production, recipes, fleet, watchlist, world, economy, swarm, mission, supply-readiness and connection data. rs_mission_preview can save a structured draft for human review; it cannot approve or dispatch it. The client supplies a bounded operation/query/item/window, never arbitrary paths, commands or URLs. Public reads reuse BlackrockRoutes and its cache/budget. Six research calls per answer, one active answer per service, five-minute generation deadline, 4,000-character questions and bounded tool result sizes prevent runaway collection.

Threads disable environment access, shell tools, agents, external apps/plugins and configured MCP servers; use read-only sandbox and no approval escalation. Unexpected approval/tool requests are declined. Account responses are projected to connection type and model metadata; email and credentials are not returned. Existing loopback Host/Origin checks apply. No gameplay, trades, ownership changes, subscription writes or bot actions are exposed. Unknown/stale quantities remain unknown. Friendlies, ownership and watching stay distinct; public bank previews are not full inventories or identified order owners.

Endpoints:

GET /api/assistant/status — connection and model/effort availability.
POST /api/assistant/chat-sdk — AI SDK UI message stream, consumed by useChat / DefaultChatTransport. Body: {requestId: UUID, conversationId?: UUID, message, model, effort, context?}.
POST /api/assistant/chat — backward-compatible NDJSON stream.
GET /api/assistant/tasks?conversationId=UUID — latest 30 durable task receipts for this conversation.
GET /api/assistant/tasks/UUID — one persisted task, events, reports and final answer.
GET /api/assistant/conversation?id=UUID — latest 100 locally saved messages.
POST /api/assistant/cancel — cancel the matching active conversation.

Each request carries its question/model/effort and optional screen context. Messages retain model, effort, status, source references and local timestamp. Closing the panel leaves an in-progress answer running. Stop immediately aborts local streaming and separately requests server cancellation with a five-second confirmation limit; a timeout remains unconfirmed and saved task activity is reconciled. Service/browser shutdown can interrupt an in-flight answer. Existing conversations are read-only via this API; a supplied ID never resumes an unrelated Codex thread.

Streaming, tasks and reports

The browser uses AI SDK 7's supported message protocol. The backend adapts Codex app-server events into text, metadata and typed data-workspace events. Mastra still orchestrates the Codex turn; this is not a native Mastra model-provider Agent, and the app does not add provider API billing or silently change account authentication.

Every submitted task has a UUID idempotency key. Duplicate requests return a 409 with the saved receipt instead of running tools again. Tasks and bounded tool-event/report lists persist in local SQLite. Service restart marks unfinished tasks Interrupted, with unresolved tool outcomes explicit; it never resumes or replays an action automatically. Closing/reopening the panel restores recorded state. Network reconnection is not permission to resubmit.

Reports are deterministic projections of research results: numbers come from existing data services, not generated prose. OpenUI @openuidev/react-lang renders a single registered EvidenceReport component, backed by Frosted tables, item images and Recharts. The server validates bounded report schemas; the program is serialized by the app. No model-generated JavaScript, external data-fetching components or command runner is enabled. A failed renderer falls back to the verified report card. Supply reports unwrap the logistics response envelope and preserve full participant counts when names are compacted. Their POST-only source is displayed as a saved-source reference rather than a broken GET link. Reports preserve Unknown values, source capture/read timestamps, bounded excerpts and coverage limits; historical trades never become historical order books.

Report links navigate to existing app sections without reloading the world observer. Review links are navigation, never approval. Stopping an assistant response does not stop a gameplay mission; the independent Command controls remain authoritative.

Design and verification

Whop's Frosted primitives supply the panel's Heading, Text, Button, IconButton, Select, Badge, TextArea, Checkbox and Tooltip. Gray/accent/semantic color scales, spacing and radius tokens follow the installed theme. Motion animates panel/welcome entry and the selected research-navigation background; reduced-motion users avoid spatial transitions. Answers render escaped React text, modest inline formatting and local API citations, never raw generated HTML.

Sources checked through Context.dev on October 23, 2026:

Protocol fields were also checked against locally generated Codex CLI 0.163.0 TypeScript bindings. Motion 14.6.0 is installed in this app's pnpm workspace.

Current UI references checked through Context.dev on October 26, 2026:

Dependencies added: ai@7.0.153, @ai-sdk/react@4.0.157, @openuidev/react-lang@1.0.1. The existing Frosted theme remains the single design system. Tailwind is optional in Whop's guide; this implementation uses its installed components and shared CSS tokens without introducing a second build pipeline. AI Elements is not a dependency. OpenUI's optional telemetry postinstall remains disabled.