Singleship Agents

High-level architecture

• HTTP Client Layer
  • Wraps vibe.d HTTP client; handles auth tokens, session management, retries, backoff, and rate limiting.
  • Exposes typed methods like getShipState(), postAction(NavigateTo ...), subscribeEvents().
• Domain Models
  • structs/classes for ShipState, WorldState, Goal, Policy, Action, etc., as the internal canonical representation.
  • All HTTP JSON is translated into and out of these types so the rest of the agent never sees raw JSON.
• Perception Module
  • Periodically (or event‑driven) pulls data via HTTP (ship status, local space, contacts, missions) and normalizes it into Domain Models.
  • Can precompute derived values (threat levels, fuel margin, ETA) so the policy engine consumes higher‑level features.
• Decision / Policy Engine
  • Chooses the next high‑level action given current ShipState, WorldState, and active Goal set.
  • Initially rule‑based (D code / tables); later you can swap or augment it with RL or LLM‑assisted policies without touching the HTTP or domain layers.
• Planning Module
  • Expands goals like “survey system X” into an ordered/branching plan: navigate → scan → log results → refuel if needed.
  • Maintains an action queue that the executor consumes; can replan when perception reports big state changes.
• Action Executor
  • Dequeues actions (e.g., ChangeCourse, FireThrusters, ScanSector, Dock) and turns them into concrete HTTP calls to the Galaxy Simulator API.
  • Interprets responses, handles transient failures, and feeds success/failure back into Domain Models and the Learning Module.
• Learning Module
  • Records tuples like (state features, chosen action, outcome, reward) in a local store (files, embedded DB) for offline or online learning.
  • Periodically updates the Policy Engine (e.g., tweak thresholds, choose better heuristics, or retrain an external model that the D agent queries).
• Persistence & Logs
  • Stores configuration (policy parameters, personality), last known state, and detailed logs for GM replay/debugging.
  • Lets a GM reload an agent with its “experience” and reattach it to a running ship.
• Telemetry / Debug Interface
  • Simple HTTP (or WebSocket) endpoint served by the agent itself, or a CLI/REPL, exposing introspection: current plans, goals, recent decisions.
  • A GM/Developer Console can connect here to observe or nudge the agent without going through the Galaxy Simulator API.

This Architecture implies a set of HTTP endpoints and behaviors

• Authentication & identity
  • Endpoint to authenticate a Character (NPC/PC) and bind it to a specific Singleship (captain).[1]
  • Session or token model that supports long‑running NPC processes without frequent manual reauth.
• Simulation state query
  • GET /ship/{id}: position, velocity, fuel, hull, systems health, cargo, crew, current orders.
  • GET /local-space: nearby objects, hazards, stations, ships, signals, plus timestamps/simulation ticks.
  • GET /character/{id}/goals or a mission/contract endpoint for high‑level objectives.
• Action commands
  • Navigation: set course, set thrust, warp/jump, hold position.
  • Sensors: active/passive scans, targeted scans, long‑range probes, retrieve scan reports.
  • Comms: send messages, accept/reject hails, respond to mission offers.
  • Engineering: power allocation, repair orders, subsystem toggles, jettison/fuel transfer, module activation.
  • Each action should have clear preconditions, synchronous response (accepted/rejected), and possibly an action‑id for later status checks.
• Event / notification model
  • Polling or push: events like “arrival at waypoint”, “hostile contact”, “scan complete”, “critical damage”, “new mission offer”.
  • Ideally: GET /events?since=token or a streaming endpoint; the agent’s Perception Module can drive off these instead of brute polling.
• Time and determinism controls (for learning)
  • Ability to run a ship or scenario in “sim time”, maybe even at accelerated speed, with deterministic seeds so you can replay runs for training and debugging.
  • Endpoint to snapshot and restore ship/sector state so the agent can repeatedly practice specific situations.

Mapping to PCs vs NPCs

• NPC Singleship Agent (D program)
  • Runs headless; talks directly to the Galaxy Simulator HTTP API as a Character (captain) controlling a specific ship.
  • GM can inspect and steer via the Telemetry Interface, but the NPC’s decisions originate from the Policy/Planning modules.
• PC client
  • GUI speaks the same Galaxy Simulator HTTP API, but the Decision Engine is the human’s brain; the client mostly mirrors state and sends user‑chosen actions.
  • You could optionally add a “copilot” agent: a local or server‑side Singleship Agent that suggests actions to the human, using exactly the same architecture but with a “human override” mode.