AI Copilot Architecture

Draft design notes for the Darksun Copilot integration. Update these notes as the implementation evolves.

Objectives

• Provide a conversational assistant that can manipulate the simulation through the same validated actions as the UI.
• Keep user data and prompts scoped to the authenticated user.
• Reuse existing physics and mission-planning controllers instead of inventing a separate command layer.
• Keep tool execution and result formatting deterministic so the Copilot UI can render structured replies.

High-Level Flow

1. Frontend

   • The Copilot panel lives in src/components/copilot/ and reads/writes state through src/services/copilot/.
   • User messages are sent through authenticated API calls and tool results are rendered back into the chat stream.
   • UI widgets render tool payloads such as mission screenshots, spacecraft summaries, and planning outputs.

2. API and tool layer

   • Copilot stream endpoints live under apps/api/src/app/api/v1/copilot/respond/stream.
   • The physics MCP server and its tool registry live under server/mcp/.
   • Server-side handlers own authentication, session ownership, and tool execution. The frontend only consumes structured results.

3. OpenAI Responses API

   • The backend forwards a bounded tool list and the current mission context to the model.
   • The prompt should stay anchored to current mission-planning docs and runtime state, not to archived design notes.

Tool Catalogue

The Copilot should rely on the same mission-planning and physics primitives that power the app:

Tool	Purpose	Canonical Reference
list_spacecraft	Return the current spacecraft roster and orbit metadata.	src/services/copilot/tools/
create_spacecraft	Create a spacecraft using the same validation as the wizard.	src/services/copilot/tools/
plan_maneuver	Add maneuver nodes and preview the resulting orbit.	apps/docs/docs/mission-planning/quickstart.md
set_sim_time	Change the active simulation epoch.	src/store/physics/actions/
get_celestial_body_info	Inspect a celestial body’s current state.	src/services/copilot/tools/
capture_mission_screenshot	Capture a screenshot from the active mission scene.	server/mcp/tools/screenshot.tools.ts

The exact tool list should stay in sync with the server registry and the UI renderers.

Prompt References

Use the current docs as the source of truth for the assistant prompt:

• apps/docs/docs/mission-planning/quickstart.md
• apps/docs/docs/mission-planning/workflows.md
• apps/docs/docs/physics/reference-frames.md
• apps/docs/docs/reference/settings.md

These pages describe the mission scripting conventions, frame conventions, and simulation controls that the Copilot needs to reason about correctly.

Privacy & Data Handling

• Session data should be scoped by authenticated user and mission/session identifier.
• The frontend must never see API secrets or backend-only credentials.
• Tool results should be filtered before they are surfaced to the model or rendered in the UI.
• Screenshot and other large binary payloads should stay out of model context unless explicitly needed.

Failure Handling

• Invalid tool names or malformed arguments should return a recoverable assistant error, not a crash.
• Tool execution failures should be rendered as structured errors so the assistant can retry or ask for clarification.
• Network and rate-limit errors should surface a clear user-facing failure state.

Simulation Reference Notes

• epochMs is the UTC Unix epoch used as the simulation anchor.
• State vectors are propagated in the current physics frame used by the app’s simulation layer.
• Mission planner scripts should use the current quickstart/workflow syntax, not archived examples.

Open Questions

• Whether session transcripts should be persisted for analytics.
• Whether the Copilot should expose more of the mission planner directly or stay constrained to curated tools.
• Whether additional prompt context should come from docs pages or from server-side tool schemas only.