xonecas.io
5875
Os

ollama-space-molt-player / commit 846887b

docs: simplify documentation and update package versions

- Streamline AGENTS.md and README.md with clearer structure
- Consolidate client documentation and examples
- Update package versions across monorepo

xonecas2026-02-03 846887b4459b66fa701ec3ad76e7db3585579aa8 parent bf38cf9

5 files changed

AGENTS.md+97−163
@@ -1,209 +1,143 @@
1-# Agent Guide for ollama-spacemolt-player
1+# Agent Guidelines
22
3-Help coding agents work safely and consistently in this repo.
3+## Project Overview
44
5-## Important References
5+This is an autonomous AI agent client for SpaceMolt, an MMO for AI agents. The client uses MCP (Model Context Protocol) to communicate with the game server and Ollama for local LLM inference with tool calling.
66
7-**Design Document**: `docs/2026-02-03-client-refactor-design.md` - Primary source of truth for architecture and design decisions
7+## Architecture
88
9-**Game Server WebSocket API**: https://www.spacemolt.com/api.md
9+### Core Components
1010
11-## Workspace Structure
11+- **MCP Client** (`mcp-client.ts`): Connects to SpaceMolt's MCP server, discovers tools, executes tool calls
12+- **Ollama Client** (`ollama.ts`): Wraps Ollama's `/api/chat` endpoint with tool support
13+- **Game Client** (`game-client.ts`): Orchestrates the agent loop between MCP and Ollama
14+- **Database** (`db.ts`): SQLite persistence for accounts and message history
1215
13-This is a Bun workspace with the following layout:
16+### Agent Loop
1417
1518 ```
16-ollama-spacemolt-workspace/
17-├── packages/
18-│ └── client/ # WebSocket client package
19-│ ├── src/ # Source code
20-│ ├── tests/ # Unit tests
21-│ └── package.json
22-├── scripts/
23-│ └── strip-comments.ts # Comment removal script
24-├── docs/
25-│ └── 2026-02-03-client-refactor-design.md # Sacred design document
26-├── package.json # Workspace root
27-├── tsconfig.json # Base TypeScript config
28-└── .prettierrc.json # Prettier configuration
19+1. LLM receives messages + available tools
20+2. LLM responds with tool_calls (or content)
21+3. Execute each tool call via MCP
22+4. Append results to messages
23+5. Repeat until LLM responds without tool calls (max 10 iterations)
24+6. Wait 1 second, start next round
2925 ```
3026
31-## Design Principles
27+### Message Persistence
3228
33-From `docs/2026-02-03-client-refactor-design.md`:
29+All interactions are saved to SQLite:
3430
35-1. **Reduce abstraction** - Minimize layers between client and server
36-2. **Direct connection** - Connect to WebSocket without intermediate libraries
37-3. **Neutral errors** - Use language from api.md, avoid behavioral bias
38-4. **Single bias point** - Only `prompt` field influences LLM behavior
39-5. **Minimal translation** - Forward game events directly to LLM
31+- Tool calls saved as `{ tool, arguments }` (sender: client)
32+- Tool results saved as `{ tool, success, content }` (sender: server)
33+- Final LLM responses saved as `{ response }` (sender: client)
4034
41-## Commands
35+On restart, message history is restored to provide context continuity.
4236
43-### Workspace Level
44-
45-```bash
46-# Install dependencies
47-bun install
48-
49-# Run all checks (format, lint, test)
50-bun run check
51-
52-# Individual checks
53-bun run strip-comments # Strip comments from TypeScript files
54-bun run check:format # Format with Prettier
55-bun run check:lint # TypeScript compilation check
56-bun run check:test # Run tests
57-```
58-
59-### Client Package
60-
61-```bash
62-cd packages/client
63-
64-# Run checks
65-bun run check
66-
67-# Start client (once implemented)
68-bun run start
69-```
70-
71-## Code Style Guidelines
72-
73-### Formatting
74-
75-- Use Prettier for all formatting
76-- TypeScript compilation (`tsc --noEmit`) for linting
77-- Tabs for indentation (2-space width)
78-- 100 character line width
79-- Semicolons, double quotes, trailing commas
80-
81-### Naming Conventions
82-
83-- Types/interfaces: `PascalCase`
84-- Functions and variables: `camelCase`
85-- Constants: `SCREAMING_SNAKE_CASE`
86-- File names: `kebab-case.ts`
37+## Code Conventions
8738
8839 ### TypeScript
8940
90-- `strict` mode enabled
91-- Avoid `any`, use `unknown` then narrow
92-- Explicit return types for public functions
93-- Prefer `null` over `undefined` for absent values
94-
95-### Testing
96-
97-- Use Bun's built-in test runner (`bun test`)
98-- Target: 80% coverage for client code
99-- Unit tests for core logic
100-- Manual tests for TUI (screenshots)
101-
102-## Database
41+- Use strict TypeScript with `noEmit` for type checking
42+- Prefer interfaces over types for object shapes
43+- Use explicit return types on public methods
10344
104-SQLite via `bun:sqlite`:
45+### Error Handling
10546
106-- Pattern: `memory-{instance-id}.sqlite`
107-- Two tables: `account_details`, `messages`
108-- Maximum 5000 messages, sorted by tick
109-- Unique instance ID per client (4 characters)
47+- Log errors with `logClientError()`, include context
48+- Don't swallow errors silently
49+- MCP tool failures should be passed to LLM (it learns from errors)
11050
111-## Tick Processing
112-
113-The client uses a server-driven tick system with critical safety mechanisms:
114-
115-**Processing Lock:**
51+### Testing
11652
117-- Only one tick can process at a time (enforced by `isProcessingTick` flag)
118-- If a new tick arrives while previous tick is still processing, it is skipped
119-- Prevents parallel LLM calls that would violate game server rate limits
120-- Skipped ticks are logged but not saved to database
53+- Tests use Bun's built-in test runner
54+- Mock external services (Ollama, MCP) in tests
55+- Run `bun run check` before committing
12156
122-**Flow:**
57+### Formatting
12358
124-1. Server sends tick message every ~10 seconds
125-2. Client checks if currently processing (`isProcessingTick`)
126-3. If processing: log skip and return
127-4. If not: set lock, process tick (LLM call + command send), release lock
59+- Prettier handles formatting
60+- Run `bun run check:format` to format all files
12861
129-**Why this matters:**
62+## File Organization
13063
131-- LLM calls can take 8-12 seconds (variable)
132-- Tick interval is 10 seconds (fixed)
133-- Without lock: overlapping ticks cause rate limiting errors
134-- With lock: sequential processing matches game server expectations
64+```
65+packages/client/src/
66+├── mcp-client.ts # MCP connection and tool execution
67+├── ollama.ts # Ollama chat API
68+├── game-client.ts # Main orchestration
69+├── db.ts # SQLite persistence
70+├── types.ts # TypeScript types
71+├── logging.ts # Structured logging
72+├── archetypes.ts # Character personalities
73+├── model-config.ts # Model configuration loader
74+├── cli.ts # CLI argument parser
75+└── index.ts # Entry point
76+```
13577
136-## Error Handling
78+## Adding New Features
13779
138-- Neutral, factual language only
139-- Follow error terminology from api.md
140-- No behavioral bias in error messages
141-- Client errors logged but don't stop tick loop
80+### New Tool Handling
14281
143-## Development Workflow
82+Tools come dynamically from MCP. To add special handling for a tool result:
14483
145-1. Read `docs/2026-02-03-client-refactor-design.md` for context
146-2. Make changes aligned with design principles
147-3. Run `bun run check` before committing (strips comments, formats, lints, tests)
148-4. Keep abstractions minimal
149-5. Test with real game server when possible
84+```typescript
85+// In game-client.ts executeToolCall()
86+if (name === "your_tool" && result.success) {
87+ await this.handleYourToolSuccess(args, result.content);
88+}
89+```
15090
151-## Code Quality
91+### New Model Support
15292
153-### No Comments Policy
93+Add to `player-models.json`:
15494
155-**Comments are automatically stripped from all TypeScript files during the check process.** This prevents outdated comments from misleading future agents as code evolves.
95+```json
96+{
97+ "your-model": {
98+ "displayName": "Your Model",
99+ "ollama": {
100+ "model": "actual-ollama-model-name",
101+ "options": { "temperature": 0.7 }
102+ },
103+ "recommendedMessages": 50
104+ }
105+}
106+```
156107
157-**Why this matters for AI agents:**
108+Model must support Ollama's tool calling format.
158109
159-- Agents make edits in chunks and often miss contextual comments
160-- Outdated comments create false assumptions about code behavior
161-- Comments can contradict actual implementation after refactoring
162-- Self-documenting code is more reliable than potentially stale documentation
110+## Common Tasks
163111
164-**When comments are stripped:**
112+### Running the Client
165113
166-- During `bun run check` (after formatting, before linting)
167-- Applies to all `.ts` files in `packages/*/src/**` and `packages/*/tests/**`
168-- ALL comments are removed: single-line (`//`), multi-line (`/* */`), JSDoc
114+```bash
115+cd packages/client
116+bun start -- -i test1 -v
117+```
169118
170-**Write self-documenting code instead:**
119+### Running Tests
171120
172-- Clear variable and function names that explain intent
173-- Small, focused functions (easier to understand at a glance)
174-- Type annotations for function signatures
175-- Well-structured code organization
176-- Descriptive constant names instead of magic numbers
121+```bash
122+bun run check # All checks
123+bun test # Tests only
124+bun test --watch # Watch mode
125+```
177126
178-**Example - Instead of:**
127+### Debugging
179128
180-```typescript
181-const d = Math.sqrt((x2 - x1) ** 2 + (y2 - y1) ** 2);
182-```
129+Enable verbose mode with `-v` flag to see:
183130
184-**Write:**
131+- Tool calls and arguments
132+- Tool results
133+- LLM thinking (if model supports it)
185134
186-```typescript
187-function calculateDistance(point1: Point, point2: Point): number {
188- const deltaX = point2.x - point1.x;
189- const deltaY = point2.y - point1.y;
190- return Math.sqrt(deltaX ** 2 + deltaY ** 2);
191-}
192-```
135+## Key Design Decisions
193136
194-**Where to document:**
137+1. **LLM has full agency**: The client doesn't make decisions - the LLM decides everything including when to poll notifications, how to handle rate limits, what to do next.
195138
196-- Design decisions → `docs/2026-02-03-client-refactor-design.md`
197-- Architecture patterns → `AGENTS.md` (this file)
198-- User instructions → `README.md`
199-- API reference → Markdown files or separate docs
139+2. **MCP over WebSocket**: Uses HTTP-based MCP transport instead of WebSocket for simpler connection handling.
200140
201-## What NOT to Do
141+3. **In-memory + SQLite**: Messages kept in memory for fast access, persisted to SQLite for restart recovery.
202142
203-- Do not add intermediate translation layers
204-- Do not add behavioral bias outside `prompt` field
205-- Do not modify sacred `docs/2026-02-03-client-refactor-design.md`
206-- Do not commit `*.sqlite` or `*.log` files
207-- Do not create backward compatibility with old implementation
208-- **Do not access files outside of the repo root** - All file operations must stay within `/home/xonecas/src/ollama-spacemolt-player`
209-- **Run all commands in the repo root** - Use the `workdir` parameter if needed, but default to repo root
143+4. **Single agent loop**: One round at a time, max 10 tool iterations per round, 1 second delay between rounds.
README.md+93−97
@@ -1,132 +1,128 @@
1-# ollama-spacemolt-workspace
1+# ollama-spacemolt-player
22
3-Bun workspace for LLM-controlled SpaceMolt game client.
3+Autonomous AI agent that plays [SpaceMolt](https://spacemolt.com) using local LLMs via Ollama.
44
5-## Project Structure
5+## Overview
66
7-This is a monorepo using Bun workspaces:
7+This client connects to SpaceMolt's MCP (Model Context Protocol) server and uses Ollama's native tool calling to let an LLM play the game autonomously. The LLM has full agency - it decides when to mine, trade, fight, chat with other players, and explore the galaxy.
88
9-- `packages/client/` - WebSocket client that connects LLM to game server
10-- `docs/2026-02-03-client-refactor-design.md` - Architecture and design decisions
11-- `AGENTS.md` - Guide for coding agents working in this repo
9+## Architecture
1210
13-## Design Philosophy
11+```
12+┌──────────────────────────────────────────────────────────┐
13+│ GameClient │
14+│ │
15+│ ┌─────────────┐ ┌─────────────────────┐ │
16+│ │ MCP Client │◄───────►│ SpaceMolt MCP │ │
17+│ │ (94 tools) │ │ game.spacemolt.com │ │
18+│ └──────┬──────┘ └─────────────────────┘ │
19+│ │ │
20+│ ▼ │
21+│ ┌─────────────┐ ┌─────────────────────┐ │
22+│ │ Ollama Chat │◄───────►│ Ollama Server │ │
23+│ │ (tool calls)│ │ (local LLM) │ │
24+│ └─────────────┘ └─────────────────────┘ │
25+│ │
26+│ Agent Loop: LLM → tool_calls → MCP execute → repeat │
27+└──────────────────────────────────────────────────────────┘
28+```
1429
15-See `docs/2026-02-03-client-refactor-design.md` for full details. Key principles:
30+### How It Works
1631
17-- Direct WebSocket connection to game server
18-- Minimal abstraction layers
19-- Neutral error messaging
20-- Single behavioral bias point (LLM prompt field)
32+1. **MCP Connection**: Client connects to `https://game.spacemolt.com/mcp` and discovers 94 game tools
33+2. **Tool Conversion**: MCP tools are converted to Ollama's tool format
34+3. **Agent Loop**: LLM receives game context, makes tool calls, results fed back, repeat
35+4. **Persistence**: All tool calls and results saved to SQLite for context restoration on restart
2136
2237 ## Quick Start
2338
24-```bash
25-# Install dependencies
26-bun install
27-
28-# Configure Ollama server (REQUIRED)
29-export OLLAMA_CONTEXT_LENGTH=16384
39+### Prerequisites
3040
31-# Start Ollama server
32-ollama serve
41+- [Bun](https://bun.sh) v1.0+
42+- [Ollama](https://ollama.ai) running locally
3343
34-# In another terminal, pull the default model
35-ollama pull lfm2.5-thinking
44+```bash
45+# Install recommended model
46+ollama pull qwen3:8b
3647
37-# Run all checks (format, lint, test)
38-bun run check
48+# Clone and install
49+git clone https://github.com/sacenox/ollama-space-molt-player.git
50+cd ollama-space-molt-player
51+bun install
3952
40-# Work in client package
53+# Start playing
4154 cd packages/client
42-bun run start
55+bun start
4356 ```
4457
45-ollama logs: journalctl -u ollama -f -n 100
46-
47-**Important:** Set `OLLAMA_CONTEXT_LENGTH=16384` before starting the Ollama server. The default limit (4096) truncates prompts and causes the bot to forget recent game history.
48-
49-Model configurations are defined in `player-models.json` at the repo root.
50-
51-## Code Quality
52-
53-### No Comments Policy
54-
55-This project automatically strips all code comments during the check process. This may seem unusual, but it serves an important purpose:
56-
57-**Why no comments?**
58-
59-- AI agents make incremental edits and often miss updating related comments
60-- Outdated comments mislead future developers and agents more than missing comments
61-- Forces code to be self-documenting through clear naming and structure
62-
63-**When are comments stripped?**
64-
65-- Automatically during `bun run check`
66-- After formatting and before linting/testing
67-
68-**How to write self-documenting code:**
58+### CLI Options
6959
70-- Use descriptive variable and function names
71-- Keep functions small and focused
72-- Use type annotations to document interfaces
73-- Structure code logically with clear separation of concerns
74-- Extract complex logic into named functions
75-
76-**What about documentation?**
77-
78-- User-facing documentation belongs in markdown files (README.md, design docs)
79-- API documentation can use JSDoc in declaration files if needed
80-- Design decisions should be captured in `docs/2026-02-03-client-refactor-design.md`
60+```bash
61+bun start [OPTIONS]
62+
63+Options:
64+ -i, --instance <id> Instance ID (4 chars, auto-generated if not provided)
65+ -m, --model <name> Model config name (default: qwen3-8b)
66+ -a, --archetype <name> Character archetype: diplomat, opportunist, agitator
67+ --hint <text> Guidance injected into LLM context
68+ --ollama-timeout <ms> Ollama API timeout (default: 30000)
69+ -s, --server <url> MCP server URL (default: https://game.spacemolt.com/mcp)
70+ -cw, --context-window <n> Max messages in context (default: 50)
71+ -v, --verbose Verbose logging
72+```
8173
82-## Workspace Commands
74+### Examples
8375
84-- `bun run check` - Run format, lint, and tests
85-- `bun run check:format` - Format code with Prettier
86-- `bun run check:lint` - Type-check with TypeScript
87-- `bun run check:test` - Run tests with Bun
76+```bash
77+# New character with diplomat personality
78+bun start -- -i abc1 -a diplomat
8879
89-## Troubleshooting
80+# Resume existing instance with hint
81+bun start -- -i abc1 --hint "Focus on mining titanium"
9082
91-### Ollama truncation warnings
83+# Use different model
84+bun start -- -m llama3.1-8b
85+```
9286
93-If you see `truncating input prompt` warnings in Ollama server logs:
87+## Project Structure
9488
95-**Symptom:** Bot forgets recent game events and repeats failed actions
89+```
90+packages/client/
91+├── src/
92+│ ├── mcp-client.ts # MCP SDK connection, tool discovery, execution
93+│ ├── ollama.ts # Ollama chat API with tool calling
94+│ ├── game-client.ts # Agent loop orchestration
95+│ ├── db.ts # SQLite persistence
96+│ ├── archetypes.ts # Character personalities
97+│ ├── logging.ts # Structured logging
98+│ └── cli.ts # CLI argument parser
99+└── tests/
100+```
96101
97-**Cause:** Ollama's default context limit (4096 tokens) is too small for game state history
102+## Models
98103
99-**Solution:**
104+Configured in `player-models.json`:
100105
101-1. Stop Ollama server
102-2. Set environment variable: `export OLLAMA_CONTEXT_LENGTH=16384`
103-3. Restart: `ollama serve`
106+| Config Name | Model | Tool Support | Notes |
107+| ------------ | ------------ | ------------ | -------------------- |
108+| qwen3-8b | qwen3:8b | Yes | Default, recommended |
109+| qwen3-4b | qwen3:4b | Yes | Lighter weight |
110+| llama3.1-8b | llama3.1:8b | Yes | Good alternative |
111+| mistral-nemo | mistral-nemo | Yes | Larger context |
104112
105-**For systemd service:**
113+## Development
106114
107115 ```bash
108-sudo systemctl edit ollama
109-```
116+# Run all checks
117+bun run check
110118
111-Add to the override file:
119+# Run tests
120+bun test
112121
113-```ini
114-[Service]
115-Environment="OLLAMA_CONTEXT_LENGTH=16384"
122+# Format code
123+bun run check:format
116124 ```
117125
118-Then restart the service:
119-
120-```bash
121-sudo systemctl restart ollama
122-```
123-
124-## References
125-
126-- Game Server API: https://www.spacemolt.com/api.md
127-- Design Document: `docs/2026-02-03-client-refactor-design.md`
128-- Agent Guide: `AGENTS.md`
129-
130-## Development
126+## License
131127
132-See `packages/client/README.md` for client-specific documentation.
128+MIT
package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "ollama-spacemolt-workspace",
3- "version": "0.2.0",
3+ "version": "0.3.0",
44 "private": true,
55 "workspaces": [
66 "packages/*"
packages/client/README.md+99−142
@@ -1,64 +1,64 @@
11 # @spacemolt/client
22
3-LLM-controlled WebSocket client for SpaceMolt game server.
3+Autonomous AI agent for SpaceMolt using MCP and Ollama tool calling.
44
55 ## Design Principles
66
7-- **Direct connection**: Connect to `wss://game.spacemolt.com/ws` without intermediate libraries
8-- **Minimal abstraction**: Reduce layers between client and server
9-- **Neutral errors**: Use language from api.md, avoid behavioral bias
10-- **Single bias point**: Only the `prompt` field influences LLM behavior
7+- **MCP Integration**: Connect to `https://game.spacemolt.com/mcp` for tool discovery and execution
8+- **LLM Agency**: The LLM has full control - it decides all game actions
9+- **Minimal Abstraction**: Thin bridge between Ollama and MCP server
10+- **Single Bias Point**: Only the character `prompt` field influences LLM behavior
1111
1212 ## Architecture
1313
1414 ### How It Works
1515
16-1. **Initialization**: Client connects to game server via WebSocket
17-2. **Auto-login**: If account exists in database, automatically login
18-3. **Game Loop**: Server-driven tick processing (~10 seconds per tick):
19- - Server sends tick message
20- - Check processing lock (only one tick processes at a time)
21- - If already processing: skip tick with log message
22- - If not processing: acquire lock and process tick
23- - Fetch last 5 messages from history
24- - Build context: `{ prompt, hint, recent_game_messages, api, accounts }`
25- - Send to Ollama for LLM decision
26- - Parse JSON response and forward to server
27- - Save messages to database
28- - Release processing lock
29-4. **Registration**: When LLM calls `register`, intercept and generate character prompt using archetype
16+1. **MCP Connection**: Client connects to game server via MCP, discovers 94 tools
17+2. **Auto-login**: If account exists in database, prompt LLM to login
18+3. **Agent Loop**: Continuous processing:
19+ - Send messages + tools to Ollama
20+ - Receive tool_calls from LLM
21+ - Execute each tool via MCP
22+ - Append results to messages
23+ - Repeat until LLM responds without tools (max 10 iterations)
24+ - Wait 1 second, start next round
25+4. **Registration**: When LLM calls `register`, intercept and generate character prompt
3026
31-### Processing Lock
27+### Message Flow
3228
33-The client uses a processing lock (`isProcessingTick`) to prevent parallel tick processing:
34-
35-- **Problem**: LLM calls can take 8-12 seconds, but ticks arrive every 10 seconds
36-- **Solution**: Only one tick processes at a time; subsequent ticks are skipped if lock is held
37-- **Behavior**: Skipped ticks are logged but not saved to database
38-- **Benefits**: Prevents rate limiting violations and resource waste from parallel LLM calls
39-
40-### Database Schema
41-
42-Two tables using SQLite with automatic truncation at 5000 messages:
29+```
30+┌─────────┐ ┌──────────┐ ┌─────────────┐
31+│ Ollama │◄───►│ Client │◄───►│ MCP Server │
32+│ (LLM) │ │ │ │ (SpaceMolt) │
33+└─────────┘ └──────────┘ └─────────────┘
34+ │
35+ ▼
36+ ┌──────────┐
37+ │ SQLite │
38+ │ (history)│
39+ └──────────┘
40+```
4341
44-- `account_details`: credentials, username, id, hint, prompt
45-- `messages`: raw JSON server communication, id, tick, client/server sender enum
42+### Persistence
4643
47-**Message Truncation**: SQL trigger automatically keeps oldest 5000 messages, deleting older ones by tick order.
44+All interactions saved to SQLite (`memory-{instance}.sqlite`):
4845
49-### API Extensions
46+| Data Type | Sender | Format |
47+| ------------ | ------ | ---------------------------- |
48+| Tool call | client | `{ tool, arguments }` |
49+| Tool result | server | `{ tool, success, content }` |
50+| LLM response | client | `{ response }` |
5051
51-Custom fields added to game server API:
52+On restart, message history is restored into the LLM context.
5253
53-- `prompt`: Generated at registration from character traits and archetype
54-- `hint`: Optional injected message, refreshed every tick from database
54+**Auto-truncation**: SQL trigger keeps max 5000 messages.
5555
5656 ### Instance Management
5757
58-Each running client has an independent database file:
58+Each client instance has independent state:
5959
60-- Pattern: `memory-{instance-id}.sqlite`
61-- Instance ID: 4-character random identifier
60+- Database: `memory-{instance-id}.sqlite`
61+- Instance ID: 4-character identifier (auto-generated or specified)
6262 - Complete data separation between instances
6363
6464 ## Usage
@@ -67,36 +67,28 @@ Each running client has an independent database file:
6767
6868 - [Bun](https://bun.sh) installed
6969 - [Ollama](https://ollama.ai) running locally on port 11434
70-- Recommended model: `lfm2.5-thinking` (default)
7170
7271 ```bash
73-# Install default model
74-ollama pull lfm2.5-thinking
75-
76-# Or install other supported models
72+# Install recommended model
7773 ollama pull qwen3:8b
78-ollama pull deepseek-r1:7b
79-
80-# Start Ollama server (if not already running)
81-ollama serve
8274 ```
8375
8476 ### Basic Usage
8577
8678 ```bash
87-# Start client with auto-generated instance ID
79+# Start with auto-generated instance ID
8880 bun run start
8981
90-# Start with specific instance ID and archetype
82+# Start with specific instance and archetype
9183 bun run start -- --instance abc1 --archetype diplomat
9284
93-# Start with hint and custom model
94-bun run start -- --hint "Focus on trading" --model llama3:8b
85+# Start with hint and verbose logging
86+bun run start -- -i abc1 --hint "Focus on trading" -v
9587 ```
9688
9789 ### Commands
9890
99-**start** - Start the game client (default command)
91+**start** - Start the game client (default)
10092
10193 ```bash
10294 bun run start [OPTIONS]
@@ -114,73 +106,47 @@ bun run start update-hint --instance <id> --hint <text>
114106 bun run start list-instances
115107 ```
116108
117-**help** - Show help message
118-
119-```bash
120-bun run start help
121-```
122-
123109 ### Options
124110
125-| Option | Short | Description | Default |
126-| ----------------------- | ----- | ----------------------------------------------------- | ----------------------------- |
127-| `--instance <id>` | `-i` | Instance ID (4 chars, auto-generated if not provided) | Auto |
128-| `--hint <text>` | | Hint message injected into LLM context each tick | None |
129-| `--model <name>` | `-m` | Model configuration name (see player-models.json) | `lfm-thinking` |
130-| `--archetype <name>` | `-a` | Character archetype (see below) | None |
131-| `--ollama-timeout <ms>` | | Ollama API timeout in milliseconds | `30000` |
132-| `--server <url>` | `-s` | WebSocket server URL | `wss://game.spacemolt.com/ws` |
133-| `--context-window <n>` | `-cw` | Number of recent messages to include in LLM context | Model's recommendedMessages |
111+| Option | Short | Description | Default |
112+| ----------------------- | ----- | ----------------------- | -------------------------------- |
113+| `--instance <id>` | `-i` | Instance ID (4 chars) | Auto |
114+| `--hint <text>` | | Guidance for LLM | None |
115+| `--model <name>` | `-m` | Model config name | `qwen3-8b` |
116+| `--archetype <name>` | `-a` | Character archetype | None |
117+| `--ollama-timeout <ms>` | | Ollama timeout | `30000` |
118+| `--server <url>` | `-s` | MCP server URL | `https://game.spacemolt.com/mcp` |
119+| `--context-window <n>` | `-cw` | Max messages in context | `50` |
120+| `--verbose` | `-v` | Verbose logging | `false` |
134121
135122 ### Archetypes
136123
137-Character archetypes define gameplay personality:
138-
139-- **diplomat**: Seeks alliances through negotiation and mutual benefit. Prioritizes faction reputation, mediates conflicts, builds cooperative trade networks.
140-- **opportunist**: Adapts strategy based on maximum personal gain. Engages in strategic alliances when beneficial, switches loyalties based on opportunity.
141-- **agitator**: Thrives on chaos and manipulation. Spreads misinformation, provokes faction conflicts, forms temporary alliances to backstab later.
124+- **diplomat**: Seeks alliances, mediates conflicts, builds trade networks
125+- **opportunist**: Adapts for maximum personal gain, switches loyalties
126+- **agitator**: Thrives on chaos, spreads misinformation, backstabs
142127
143128 ### Model Configuration
144129
145-Models are configured in `player-models.json` at the repo root. Each configuration includes:
146-
147-- **Ollama model name**: The actual model to load (e.g., `lfm2.5-thinking`)
148-- **Options**: Model-specific parameters (temperature, etc.)
149-- **Context window**: Token limit for this model
150-- **Recommended messages**: Default history size for this model
151-- **Metadata**: Display name, description, recommendation status
152-
153-**Available Models:**
154-
155-| Config Name | Size | Context | Messages | Thinking | Best For |
156-| ------------ | ----- | ------- | -------- | -------- | -------------------- |
157-| lfm-thinking | 731MB | 128K | 10 | ✅ | Fast, minimal VRAM |
158-| deepseek-r1 | 4.7GB | 131K | 12 | ✅ | Advanced reasoning |
159-| qwen3 | 5.2GB | 40K | 15 | ✅ | Tools + thinking |
160-| ministral-3 | 6.0GB | 262K | 20 | ❌ | Maximum game history |
130+Models configured in `player-models.json`:
161131
162-**Messages** column shows the recommended context window size (number of game state messages) for each model.
132+| Config Name | Model | Notes |
133+| ------------ | ------------ | -------------------- |
134+| qwen3-8b | qwen3:8b | Default, recommended |
135+| qwen3-4b | qwen3:4b | Lighter weight |
136+| llama3.1-8b | llama3.1:8b | Good alternative |
137+| mistral-nemo | mistral-nemo | Larger context |
163138
164139 **Adding Custom Models:**
165140
166-Edit `player-models.json` and add your configuration:
167-
168141 ```json
169142 {
170- "models": {
171- "your-model": {
172- "displayName": "Your Model Name",
173- "description": "Brief description",
174- "ollama": {
175- "model": "actual-ollama-name",
176- "options": {
177- "temperature": 1.2
178- }
179- },
180- "contextWindow": 32768,
181- "recommendedMessages": 12,
182- "recommended": false
183- }
143+ "your-model": {
144+ "displayName": "Your Model",
145+ "ollama": {
146+ "model": "actual-ollama-name",
147+ "options": { "temperature": 0.7 }
148+ },
149+ "recommendedMessages": 50
184150 }
185151 }
186152 ```
@@ -188,20 +154,17 @@ Edit `player-models.json` and add your configuration:
188154 ### Examples
189155
190156 ```bash
191-# New player with diplomat archetype (uses default lfm-thinking model)
157+# New diplomat character
192158 bun run start -- -i xyz9 -a diplomat
193159
194-# Use Qwen3 model with explicit thinking support
195-bun run start -- -i xyz9 -a diplomat --model qwen3
196-
197-# Use DeepSeek for large context tasks
198-bun run start -- -i xyz9 -a agitator --model deepseek-r1
160+# Resume with guidance
161+bun run start -- -i xyz9 --hint "Explore new systems"
199162
200-# Connect to custom server for testing
201-bun run start -- -i test -s ws://localhost:8080
163+# Different model
164+bun run start -- -i xyz9 -m llama3.1-8b
202165
203-# Update hint for running instance
204-bun run start update-hint --instance xyz9 --hint "Explore new systems"
166+# Custom server (testing)
167+bun run start -- -i test -s http://localhost:8080/mcp
205168 ```
206169
207170 ## Development
@@ -210,16 +173,13 @@ bun run start update-hint --instance xyz9 --hint "Explore new systems"
210173 # Install dependencies
211174 bun install
212175
213-# Run all checks (format, lint, test)
176+# Run all checks
214177 bun run check
215178
216179 # Individual checks
217-bun run check:format
218-bun run check:lint
219-bun run check:test
220-
221-# Start client
222-bun run start
180+bun run check:format # Prettier
181+bun run check:lint # TypeScript
182+bun run check:test # Tests
223183 ```
224184
225185 ## Testing
@@ -228,38 +188,35 @@ bun run start
228188 # Run all tests
229189 bun test
230190
231-# Run specific test file
191+# Specific file
232192 bun test tests/db.test.ts
233193
234194 # Watch mode
235195 bun test --watch
236196 ```
237197
238-Test coverage: 108 tests across 8 test suites
239-
240198 ## Project Structure
241199
242200 ```
243201 src/
244-├── types.ts # TypeScript types from api.md
245-├── db.ts # SQLite database operations
246-├── ws-client.ts # WebSocket client with reconnection
247-├── ollama.ts # Ollama HTTP client
248-├── archetypes.ts # Character personality archetypes
249-├── api-definition.ts # Game API definition
250-├── game-client.ts # Main game client orchestration
251-├── cli.ts # CLI argument parser
202+├── mcp-client.ts # MCP SDK connection and tool execution
203+├── ollama.ts # Ollama chat API with tools
204+├── game-client.ts # Agent loop orchestration
205+├── db.ts # SQLite persistence
206+├── types.ts # TypeScript types
207+├── archetypes.ts # Character personalities
208+├── model-config.ts # Model config loader
209+├── logging.ts # Structured logging
210+├── cli.ts # CLI parser
252211 └── index.ts # Entry point
253212
254213 tests/
255-├── db.test.ts # Database unit tests
256-├── ws-client.test.ts # WebSocket client tests
257-├── ollama.test.ts # Ollama client tests
258-├── cli.test.ts # CLI parser tests
259-├── json-extraction.test.ts # JSON extraction from LLM responses
260-└── mock-server.ts # Mock WebSocket server for testing
214+├── db.test.ts
215+├── ollama.test.ts
216+├── cli.test.ts
217+└── model-config.test.ts
261218 ```
262219
263220 ## API Reference
264221
265-See [SpaceMolt API Documentation](https://www.spacemolt.com/api.md) for full game server API.
222+See [SpaceMolt API Documentation](https://www.spacemolt.com/api.md) for game server API.
packages/client/package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "@spacemolt/client",
3- "version": "0.1.0",
3+ "version": "0.2.0",
44 "private": true,
55 "type": "module",
66 "scripts": {