LLM getNeighbours tool + contiguous region transfers (Stage 2 of #16 P2)
- llm.ts: LlmClient.chatWithTools — bounded OpenAI function-calling loop (default 6 tool rounds, then one forced no-tools request); shares the retry/backoff/reasoning-effort machinery with chat(); tools are only added to the request body when non-empty, so plain chat() bodies and their tests are unchanged; a tool-call response is a success (never a truncation); malformed tool arguments become an error tool-message. - engine.ts: GET_NEIGHBOURS_TOOL + makeNeighboursExecutor (degrades unknown tools/args/keys without throwing); playerFrontier (sorted, deduped, other-nation-owned only); buildSystemPrompt gains a tool variant (contiguity rules, frontier hint) used only when the tool is actually sent; buildUserPrompt emits a frontier field whenever a resolver is given; runTurn takes getNeighbours and uses chatWithTools when both the resolver and the client's capability are present, falling back to plain chat() otherwise. - applyTurnResult: snapshot-first sole-ownership algorithm — a region key transfers only with exactly one claimant and exactly one previous owner (different from the gainer); double claims and pre-existing double ownership are left untouched; lone losses are no-ops; every key has 0 or 2+ -> 1 owner post-turn, never orphaned or duplicated. - stub.ts: deterministic one-region contiguous conquest per turn from the prompt's frontier field (bypasses the tool loop; empty frontier -> no transfer, all existing assertions stay stable). - regions.ts: optional region-adjacency.json load; hasAdjacency() and neighboursOf(keys) (union, deduped, queried excluded, sorted). - index.ts: jump route passes the adjacency resolver when loaded. - tests: chatWithTools protocol (echo, executor args, bounded rounds, malformed args, retry), tool-path runTurn wiring + fallback, playerFrontier, executor, applyTurnResult invariants, neighboursOf/ hasAdjacency (105 unit tests, 14 e2e — all green).
This commit is contained in:
+223
-30
@@ -22,7 +22,14 @@ import {
|
||||
type TurnEventSpec,
|
||||
type TurnResult,
|
||||
} from '../shared/protocol';
|
||||
import { DEFAULT_MAX_TOKENS, type LlmClient } from './llm';
|
||||
import {
|
||||
DEFAULT_MAX_TOKENS,
|
||||
type ChatMessage,
|
||||
type LlmClient,
|
||||
type ToolDefinition,
|
||||
type ToolExecutor,
|
||||
type WireMessage,
|
||||
} from './llm';
|
||||
import { ADVISOR_MARKER } from './stub';
|
||||
|
||||
const VALID_EVENT_TYPES = new Set<string>(EVENT_TYPES);
|
||||
@@ -30,13 +37,117 @@ const VALID_RELATIONS = new Set<string>(RELATION_STATUSES);
|
||||
const VALID_OUTCOMES = new Set<string>(['success', 'failure', 'partial', 'neutral']);
|
||||
const VALID_STATS = new Set<string>(['military', 'economy', 'stability', 'population']);
|
||||
|
||||
// --- The LLM's getNeighbours tool (v0.21, #16 P2: contiguous region transfers) ---
|
||||
|
||||
/**
|
||||
* The single tool the turn loop exposes to the model: the precomputed region
|
||||
* adjacency manifest (public/region-adjacency.json, via the resolver injected
|
||||
* into runTurn). Given a set of region keys it returns the union of their
|
||||
* bordering keys (the queried keys themselves excluded, sorted for
|
||||
* determinism) — so the model can verify that a territory transfer is
|
||||
* *contiguous* (a nation gains a region it already abuts) before committing
|
||||
* it, instead of moving whole countries at a whim.
|
||||
*/
|
||||
export const GET_NEIGHBOURS_TOOL: ToolDefinition = {
|
||||
type: 'function',
|
||||
function: {
|
||||
name: 'getNeighbours',
|
||||
description:
|
||||
'List the region keys that share a land border with any of the given region keys. ' +
|
||||
'Pass a nation\'s territory keys (or a single region key) to see which regions are ' +
|
||||
'contiguous to it. Use it before transferring territory: a nation can realistically ' +
|
||||
'only gain regions that border its existing territory.',
|
||||
parameters: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
regionKeys: {
|
||||
type: 'array',
|
||||
items: { type: 'string' },
|
||||
description: 'One or more region keys to query (e.g. a gaining nation\'s territory).',
|
||||
},
|
||||
},
|
||||
required: ['regionKeys'],
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* Build the tool executor for the turn loop. Never throws: unknown tool
|
||||
* names, malformed arguments, and unknown region keys all degrade to a safe
|
||||
* response (an error object or an empty list) that the model can recover from.
|
||||
*/
|
||||
export function makeNeighboursExecutor(
|
||||
getNeighbours: (keys: string[]) => string[],
|
||||
validRegionKeys?: ReadonlySet<string>,
|
||||
): ToolExecutor {
|
||||
return (name, args) => {
|
||||
if (name !== GET_NEIGHBOURS_TOOL.function.name) {
|
||||
return JSON.stringify({ error: `unknown tool: ${name}` });
|
||||
}
|
||||
const raw = Array.isArray(args.regionKeys) ? args.regionKeys : [];
|
||||
const keys = raw.filter((k): k is string => typeof k === 'string' && k.length > 0);
|
||||
const valid = validRegionKeys ? keys.filter((k) => validRegionKeys.has(k)) : keys;
|
||||
if (valid.length === 0) return JSON.stringify({ neighbours: [] });
|
||||
return JSON.stringify({ neighbours: getNeighbours(valid) });
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The player's frontier: region keys owned by *other* nations that share a
|
||||
* land border with the player's territory (deduped, sorted — stable order for
|
||||
* the deterministic stub). Computed server-side from the adjacency manifest so
|
||||
* both the LLM (the `frontier` field of the user prompt) and the stub (which
|
||||
* cannot call tools) see the same candidates. Empty when there is no
|
||||
* adjacency data or no controllable border (e.g. the UK in 1939).
|
||||
*/
|
||||
export function playerFrontier(
|
||||
state: GameState,
|
||||
getNeighbours: (keys: string[]) => string[],
|
||||
): string[] {
|
||||
const player = state.nations[state.playerNationId];
|
||||
if (!player || player.territory.length === 0) return [];
|
||||
const playerKeys = new Set(player.territory);
|
||||
const candidates = new Set<string>();
|
||||
for (const key of getNeighbours(player.territory)) {
|
||||
if (!playerKeys.has(key)) candidates.add(key);
|
||||
}
|
||||
if (candidates.size === 0) return [];
|
||||
const frontier: string[] = [];
|
||||
for (const n of Object.values(state.nations)) {
|
||||
if (n.id === state.playerNationId) continue;
|
||||
for (const key of n.territory) {
|
||||
if (candidates.has(key)) {
|
||||
candidates.delete(key);
|
||||
frontier.push(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
return frontier.sort();
|
||||
}
|
||||
|
||||
// --- Prompt building ----------------------------------------------------------
|
||||
|
||||
/** The LLM system prompt: world context + rules + a strict JSON contract. */
|
||||
export function buildSystemPrompt(preset: Preset): string {
|
||||
/**
|
||||
* The LLM system prompt: world context + rules + a strict JSON contract.
|
||||
* When `withNeighboursTool` is set (the turn runs with the getNeighbours tool
|
||||
* available) the contract gains the contiguity rules for territory transfers
|
||||
* (v0.21, #16 P2): the model may only move regions across a shared border, and
|
||||
* may verify borders with the tool before answering.
|
||||
*/
|
||||
export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): string {
|
||||
const rules = preset.simulationRules
|
||||
.map((r) => `- ${r}`)
|
||||
.join('\n');
|
||||
const respondLine = withNeighboursTool
|
||||
? 'You have a getNeighbours tool: given region keys it returns the region keys that border them. You may call it (a few times) to verify land borders before deciding territory transfers. Once done, respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:'
|
||||
: 'Respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:';
|
||||
const territoryRules = withNeighboursTool
|
||||
? [
|
||||
'- Territory changes must be contiguous: a nation may only GAIN region keys that share a land border with a region it already owns (verify with getNeighbours) and may only LOSE region keys it currently owns. One region key has exactly one owner at all times — never assign a key to two nations or to none.',
|
||||
'- The "frontier" field of the user message lists region keys owned by other nations that border the player\'s territory — the natural targets of a player-led conquest this turn.',
|
||||
]
|
||||
: ['- Only change borders when war or a decisive political shift justifies it.'];
|
||||
return [
|
||||
`WORLD: ${preset.title} — ${preset.startDate}`,
|
||||
preset.worldBackground,
|
||||
@@ -45,7 +156,7 @@ export function buildSystemPrompt(preset: Preset): string {
|
||||
rules,
|
||||
'',
|
||||
'You are the world simulator. You advance the shared world state for ALL nations given the current state and the player\'s move.',
|
||||
'Respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:',
|
||||
respondLine,
|
||||
'{',
|
||||
' "date": "YYYY-MM-DD (a few days after the current date)",',
|
||||
' "events": [',
|
||||
@@ -62,7 +173,7 @@ export function buildSystemPrompt(preset: Preset): string {
|
||||
'- Prefer 1-4 events per turn; keep each text 1-3 sentences.',
|
||||
'- Keep your internal reasoning brief (a few sentences) and go straight to the JSON result; do not over-deliberate or re-derive facts already present in the state.',
|
||||
'- Keep every stat value between 0 and 100.',
|
||||
'- Only change borders when war or a decisive political shift justifies it.',
|
||||
...territoryRules,
|
||||
'- If a field is not relevant this turn, set it to an empty array.',
|
||||
].join('\n');
|
||||
}
|
||||
@@ -80,6 +191,13 @@ export function buildUserPrompt(
|
||||
state: GameState,
|
||||
items: RoundItem[],
|
||||
regionReference?: Record<string, string>,
|
||||
/**
|
||||
* The player's frontier: region keys owned by other nations that border the
|
||||
* player's territory (v0.21, #16 P2). Emitted verbatim (even when empty) so
|
||||
* the model — and the deterministic stub, which reads it — see the same
|
||||
* contiguous targets. Omitted entirely when undefined (no adjacency data).
|
||||
*/
|
||||
frontier?: string[],
|
||||
): string {
|
||||
const player = state.nations[state.playerNationId];
|
||||
const playerName = player?.name ?? state.playerNationId;
|
||||
@@ -116,6 +234,7 @@ export function buildUserPrompt(
|
||||
roundInstruction,
|
||||
};
|
||||
if (regionReference) payload.regions = regionReference;
|
||||
if (frontier !== undefined) payload.frontier = frontier;
|
||||
return JSON.stringify(payload, null, 2);
|
||||
}
|
||||
|
||||
@@ -312,24 +431,64 @@ export function applyTurnResult(state: GameState, result: TurnResult, validKeys?
|
||||
a.relations[r.b] = r.set;
|
||||
b.relations[r.a] = r.set;
|
||||
}
|
||||
for (const t of result.territoryChanges) {
|
||||
const n = next.nations[t.nation];
|
||||
if (!n) continue;
|
||||
const valid = (k: string) => !validKeys || validKeys.has(k);
|
||||
for (const key of t.gain) {
|
||||
if (!valid(key)) continue; // ignore a key that is not a real region
|
||||
for (const other of Object.values(next.nations)) {
|
||||
const i = other.territory.indexOf(key);
|
||||
if (i !== -1) other.territory.splice(i, 1);
|
||||
}
|
||||
if (!n.territory.includes(key)) n.territory.push(key);
|
||||
}
|
||||
for (const key of t.lose) {
|
||||
// --- Territory (v0.21, #16 P2: a region key has exactly one owner) ---
|
||||
//
|
||||
// Snapshot-first: BEFORE any mutation, compute who currently owns each
|
||||
// region key. A key transfers only when (a) exactly one nation claims to
|
||||
// gain it — a double claim (two or more gainers) is rejected so the key
|
||||
// stays where it is, (b) the key currently has exactly one owner — a
|
||||
// pre-existing double ownership (or unownership) is never touched, and
|
||||
// (c) that owner is not the gainer (a self-gain is a no-op). A transfer
|
||||
// removes the key from every nation first (defensive) and then grants it
|
||||
// to the gainer; "lose" entries are pure no-ops by design, because a lone
|
||||
// loss would orphan the key and a valid gain already removes it from the
|
||||
// old owner. Ownership is therefore conserved: a key can never end a turn
|
||||
// unowned or multiply-owned.
|
||||
const valid = (k: string) => !validKeys || validKeys.has(k);
|
||||
const ownerOf = new Map<string, string>(); // key -> sole owner id, or '' (0 or 2+ owners)
|
||||
for (const n of Object.values(state.nations)) {
|
||||
for (const key of n.territory) {
|
||||
if (!valid(key)) continue;
|
||||
const cur = ownerOf.get(key);
|
||||
if (cur === undefined) ownerOf.set(key, n.id);
|
||||
else if (cur !== '') ownerOf.set(key, '');
|
||||
}
|
||||
}
|
||||
// Claim pairs, deduped: one (key, gainer) per pair even if the model emits
|
||||
// duplicate entries; two DIFFERENT gainers for one key is a double claim.
|
||||
const claimPairs = new Set<string>();
|
||||
for (const t of result.territoryChanges) {
|
||||
if (!next.nations[t.nation]) continue;
|
||||
for (const key of new Set(t.gain)) {
|
||||
if (!valid(key)) continue;
|
||||
claimPairs.add(`${key}\u0000${t.nation}`);
|
||||
}
|
||||
}
|
||||
const claimants = new Map<string, Set<string>>(); // key -> distinct gainers
|
||||
for (const pair of claimPairs) {
|
||||
const idx = pair.indexOf('\u0000');
|
||||
const key = pair.slice(0, idx);
|
||||
const gainer = pair.slice(idx + 1);
|
||||
let set = claimants.get(key);
|
||||
if (set === undefined) {
|
||||
set = new Set();
|
||||
claimants.set(key, set);
|
||||
}
|
||||
set.add(gainer);
|
||||
}
|
||||
for (const [key, claiming] of claimants) {
|
||||
if (claiming.size !== 1) continue; // double claim: the key stays as it was
|
||||
const gainer = [...claiming][0];
|
||||
const owner = ownerOf.get(key);
|
||||
if (owner === undefined || owner === '' || owner === gainer) continue;
|
||||
for (const n of Object.values(next.nations)) {
|
||||
const i = n.territory.indexOf(key);
|
||||
if (i !== -1) n.territory.splice(i, 1);
|
||||
}
|
||||
next.nations[gainer].territory.push(key);
|
||||
}
|
||||
// "lose" entries are deliberate no-ops (see above): a valid gain already
|
||||
// removes the key from its old owner, and a lone loss would orphan it.
|
||||
return next;
|
||||
}
|
||||
|
||||
@@ -365,11 +524,18 @@ export function removeRoundItem(state: GameState, index: number | undefined): Ga
|
||||
}
|
||||
|
||||
/**
|
||||
* Run one turn end-to-end against the (injectable) LLM: build prompts, call the
|
||||
* model ONCE over the whole pending batch, parse/validate, retry once with a
|
||||
* nudge if the result is empty/invalid, and — if it is still invalid — emit a
|
||||
* generic "unclear" event and advance. The committed state has `pending` cleared.
|
||||
* Never throws on bad model output; only the underlying transport/network can throw.
|
||||
* Run one turn end-to-end against the (injectable) LLM: build prompts, parse/
|
||||
* validate, retry once with a nudge if the result is empty/invalid, and — if
|
||||
* it is still invalid — emit a generic "unclear" event and advance. The
|
||||
* committed state has `pending` cleared. Never throws on bad model output;
|
||||
* only the underlying transport/network can throw.
|
||||
*
|
||||
* When `getNeighbours` is provided AND the LLM client implements
|
||||
* `chatWithTools` (v0.21, #16 P2), the turn runs the bounded function-
|
||||
* calling loop with the getNeighbours tool (the model may verify land
|
||||
* borders before committing a territory transfer) and the user prompt gains
|
||||
* the player's `frontier` field. Otherwise it falls back to a plain chat()
|
||||
* call — same as before the tool existed.
|
||||
*/
|
||||
export async function runTurn(opts: {
|
||||
llm: LlmClient;
|
||||
@@ -380,25 +546,52 @@ export async function runTurn(opts: {
|
||||
regionReference?: Record<string, string>;
|
||||
/** Set of valid region keys; territory changes with other keys are ignored. */
|
||||
validRegionKeys?: ReadonlySet<string>;
|
||||
/**
|
||||
* Region adjacency resolver (keys -> bordering keys, from the precomputed
|
||||
* manifest). Its presence (together with the client's chatWithTools)
|
||||
* switches the turn onto the getNeighbours tool path.
|
||||
*/
|
||||
getNeighbours?: (keys: string[]) => string[];
|
||||
}): Promise<{ state: GameState; result: TurnResult }> {
|
||||
const { llm, preset, state, items, regionReference, validRegionKeys } = opts;
|
||||
const system = buildSystemPrompt(preset);
|
||||
const user = buildUserPrompt(state, items, regionReference);
|
||||
const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours } = opts;
|
||||
const chatWithTools = llm.chatWithTools;
|
||||
const useTools = getNeighbours !== undefined && chatWithTools !== undefined;
|
||||
const system = buildSystemPrompt(preset, useTools);
|
||||
const frontier = getNeighbours ? playerFrontier(state, getNeighbours) : undefined;
|
||||
const user = buildUserPrompt(state, items, regionReference, frontier);
|
||||
const nudge =
|
||||
'Your previous output was invalid. Respond with ONLY the JSON object described above for this batch — no prose, no fences.';
|
||||
|
||||
let result = parseTurnResult(await llm.chat([
|
||||
/**
|
||||
* One model call with the standard turn sampling: the bounded
|
||||
* function-calling loop when available, else a plain chat(). The nudge
|
||||
* re-send below always starts a FRESH history (no tool context carried
|
||||
* over).
|
||||
*/
|
||||
const call = async (history: WireMessage[]): Promise<string> => {
|
||||
if (useTools) {
|
||||
return await chatWithTools(
|
||||
history,
|
||||
[GET_NEIGHBOURS_TOOL],
|
||||
makeNeighboursExecutor(getNeighbours, validRegionKeys),
|
||||
{ temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS },
|
||||
);
|
||||
}
|
||||
return llm.chat(history as ChatMessage[], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS });
|
||||
};
|
||||
|
||||
let result = parseTurnResult(await call([
|
||||
{ role: 'system', content: system },
|
||||
{ role: 'user', content: user },
|
||||
], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS }));
|
||||
]));
|
||||
|
||||
if (result === null || !isMeaningful(result)) {
|
||||
result = parseTurnResult(await llm.chat([
|
||||
result = parseTurnResult(await call([
|
||||
{ role: 'system', content: system },
|
||||
{ role: 'user', content: user },
|
||||
{ role: 'assistant', content: '' },
|
||||
{ role: 'user', content: nudge },
|
||||
], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS }));
|
||||
]));
|
||||
}
|
||||
|
||||
if (result === null || !isMeaningful(result)) {
|
||||
|
||||
Reference in New Issue
Block a user