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:
+350
-7
@@ -1,14 +1,17 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { GameState, Preset, RoundItem } from '../shared/types';
|
||||
import { makeEvent, type TurnResult } from '../shared/protocol';
|
||||
import type { LlmClient } from './llm';
|
||||
import type { LlmClient, ToolDefinition, WireMessage } from './llm';
|
||||
import { makeStubLlmClient } from './stub';
|
||||
import {
|
||||
applyTurnResult,
|
||||
buildSystemPrompt,
|
||||
buildUserPrompt,
|
||||
GET_NEIGHBOURS_TOOL,
|
||||
isMeaningful,
|
||||
makeNeighboursExecutor,
|
||||
parseTurnResult,
|
||||
playerFrontier,
|
||||
queueRoundItem,
|
||||
removeRoundItem,
|
||||
runTurn,
|
||||
@@ -88,7 +91,10 @@ const validResult = JSON.stringify({
|
||||
{ nation: 'de', stat: 'economy', op: 'add', value: 10 },
|
||||
],
|
||||
relations: [{ a: 'uk', b: 'us', set: 'ally' }],
|
||||
territoryChanges: [{ nation: 'de', gain: ['POL'], lose: [] }],
|
||||
// v0.21 (#16 P2): DE gains the UK's GBR — the key has exactly one previous
|
||||
// owner, so the transfer applies (an unowned key like 'POL' would be ignored
|
||||
// by the new sole-ownership rules in applyTurnResult).
|
||||
territoryChanges: [{ nation: 'de', gain: ['GBR'], lose: [] }],
|
||||
});
|
||||
|
||||
describe('runTurn', () => {
|
||||
@@ -109,8 +115,10 @@ describe('runTurn', () => {
|
||||
// relations are symmetric
|
||||
expect(state.nations.uk.relations.us).toBe('ally');
|
||||
expect(state.nations.us.relations.uk).toBe('ally');
|
||||
// territory moved to DE
|
||||
expect(state.nations.de.territory).toContain('POL');
|
||||
// territory moved to DE: it gains GBR (the UK's sole previous owner) and
|
||||
// the old owner correspondingly loses it (v0.21 #16 P2: one owner per key)
|
||||
expect(state.nations.de.territory).toContain('GBR');
|
||||
expect(state.nations.uk.territory).not.toContain('GBR');
|
||||
// one event appended, tagged with the turn that was resolved (1)
|
||||
expect(state.events).toHaveLength(1);
|
||||
expect(state.events[0].turn).toBe(1);
|
||||
@@ -121,7 +129,8 @@ describe('runTurn', () => {
|
||||
// and the original state object is NOT mutated
|
||||
expect(original.turn).toBe(1);
|
||||
expect(original.nations.uk.stats.military).toBe(80);
|
||||
expect(original.nations.de.territory).not.toContain('POL');
|
||||
expect(original.nations.de.territory).not.toContain('GBR');
|
||||
expect(original.nations.uk.territory).toContain('GBR');
|
||||
});
|
||||
|
||||
it('clamps out-of-range stat values into 0-100', async () => {
|
||||
@@ -475,6 +484,8 @@ describe('applyTurnResult', () => {
|
||||
|
||||
it('with a validKeys set: applies real region keys, ignores hallucinated ones', () => {
|
||||
const state = baseState();
|
||||
// give the fixture's uk a real key ('wales-bbbb') for DE to be able to take
|
||||
state.nations.uk.territory = ['GBR', 'wales-bbbb'];
|
||||
const result: TurnResult = {
|
||||
date: '1939-09-03',
|
||||
events: [],
|
||||
@@ -485,7 +496,7 @@ describe('applyTurnResult', () => {
|
||||
territoryChanges: [{ nation: 'de', gain: ['wales-bbbb', 'not-a-region-xyz'], lose: [] }],
|
||||
};
|
||||
const next = applyTurnResult(state, result, new Set(['wales-bbbb']));
|
||||
// the valid key was gained (stolen from its owner); the bogus one was ignored
|
||||
// the valid key was gained (taken from its sole previous owner); the bogus one was ignored
|
||||
expect(next.nations.de.territory).toContain('wales-bbbb');
|
||||
expect(next.nations.uk.territory).not.toContain('wales-bbbb');
|
||||
// the bogus key never entered any nation's territory
|
||||
@@ -496,16 +507,348 @@ describe('applyTurnResult', () => {
|
||||
|
||||
it('without a validKeys set: applies every listed key (legacy/unit path)', () => {
|
||||
const state = baseState();
|
||||
state.nations.uk.territory = ['GBR', 'wales-bbbb'];
|
||||
const result: TurnResult = {
|
||||
date: '1939-09-03',
|
||||
events: [],
|
||||
stateChanges: [],
|
||||
relations: [],
|
||||
// 'wales-bbbb' has a sole previous owner (uk) -> it transfers; 'POL' is
|
||||
// owned by no one -> it is IGNORED (a key may not end a turn unowned).
|
||||
territoryChanges: [{ nation: 'de', gain: ['POL', 'wales-bbbb'], lose: [] }],
|
||||
};
|
||||
const next = applyTurnResult(state, result); // no validKeys -> nothing filtered
|
||||
expect(next.nations.de.territory).toContain('POL');
|
||||
expect(next.nations.de.territory).toContain('wales-bbbb');
|
||||
expect(next.nations.uk.territory).not.toContain('wales-bbbb');
|
||||
expect(next.nations.de.territory).not.toContain('POL');
|
||||
});
|
||||
});
|
||||
|
||||
describe('applyTurnResult (sole-ownership invariants, v0.21 #16 P2)', () => {
|
||||
const noEvents = {
|
||||
date: '1939-09-03',
|
||||
events: [],
|
||||
stateChanges: [],
|
||||
relations: [],
|
||||
};
|
||||
|
||||
it('a double claim (two different gainers, one key) is rejected: the key stays with its original owner', () => {
|
||||
const state = baseState();
|
||||
state.nations.uk.territory = ['GBR', 'wales-bbbb'];
|
||||
const next = applyTurnResult(state, {
|
||||
...noEvents,
|
||||
territoryChanges: [
|
||||
{ nation: 'de', gain: ['wales-bbbb'], lose: [] },
|
||||
{ nation: 'us', gain: ['wales-bbbb'], lose: [] },
|
||||
],
|
||||
});
|
||||
expect(next.nations.uk.territory).toContain('wales-bbbb');
|
||||
expect(next.nations.de.territory).not.toContain('wales-bbbb');
|
||||
expect(next.nations.us.territory).not.toContain('wales-bbbb');
|
||||
});
|
||||
|
||||
it('duplicate gain entries for the SAME nation are deduped (one claim, one copy)', () => {
|
||||
const state = baseState();
|
||||
state.nations.uk.territory = ['GBR', 'wales-bbbb'];
|
||||
const next = applyTurnResult(state, {
|
||||
...noEvents,
|
||||
territoryChanges: [
|
||||
{ nation: 'de', gain: ['wales-bbbb'], lose: [] },
|
||||
{ nation: 'de', gain: ['wales-bbbb'], lose: [] },
|
||||
],
|
||||
});
|
||||
expect(next.nations.de.territory.filter((k) => k === 'wales-bbbb')).toHaveLength(1);
|
||||
expect(next.nations.uk.territory).not.toContain('wales-bbbb');
|
||||
});
|
||||
|
||||
it('a lone "lose" is a no-op: the key cannot be orphaned (zero owners)', () => {
|
||||
const state = baseState();
|
||||
const next = applyTurnResult(state, {
|
||||
...noEvents,
|
||||
territoryChanges: [{ nation: 'uk', gain: [], lose: ['GBR'] }],
|
||||
});
|
||||
expect(next.nations.uk.territory).toContain('GBR');
|
||||
});
|
||||
|
||||
it('a self-gain is a no-op (a nation keeps exactly one copy of its own key)', () => {
|
||||
const state = baseState();
|
||||
const next = applyTurnResult(state, {
|
||||
...noEvents,
|
||||
territoryChanges: [{ nation: 'uk', gain: ['GBR'], lose: [] }],
|
||||
});
|
||||
expect(next.nations.uk.territory.filter((k) => k === 'GBR')).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('a pre-existing double ownership is never touched (a key with 2 owners keeps 2)', () => {
|
||||
const state = baseState();
|
||||
state.nations.us.territory = ['USA', 'GBR']; // uk AND us already share GBR
|
||||
const next = applyTurnResult(state, {
|
||||
...noEvents,
|
||||
territoryChanges: [{ nation: 'de', gain: ['GBR'], lose: [] }],
|
||||
});
|
||||
expect(next.nations.uk.territory).toContain('GBR');
|
||||
expect(next.nations.us.territory).toContain('GBR');
|
||||
expect(next.nations.de.territory).not.toContain('GBR');
|
||||
});
|
||||
|
||||
it('ownership is conserved across a transfer: exactly one owner before and after', () => {
|
||||
const state = baseState();
|
||||
state.nations.uk.territory = ['GBR', 'wales-bbbb'];
|
||||
const count = (s: GameState) =>
|
||||
Object.values(s.nations).reduce(
|
||||
(acc, n) => acc + n.territory.filter((k) => k === 'wales-bbbb').length,
|
||||
0,
|
||||
);
|
||||
const next = applyTurnResult(state, {
|
||||
...noEvents,
|
||||
territoryChanges: [{ nation: 'de', gain: ['wales-bbbb'], lose: [] }],
|
||||
});
|
||||
expect(count(state)).toBe(1);
|
||||
expect(count(next)).toBe(1);
|
||||
expect(next.nations.de.territory).toContain('wales-bbbb');
|
||||
expect(next.nations.uk.territory).not.toContain('wales-bbbb');
|
||||
});
|
||||
});
|
||||
|
||||
describe('makeNeighboursExecutor (v0.21 #16 P2)', () => {
|
||||
const getNeighbours = (keys: string[]) => keys.map((k) => `nb-${k}`);
|
||||
|
||||
it('answers getNeighbours with the resolver output', () => {
|
||||
const exec = makeNeighboursExecutor(getNeighbours);
|
||||
expect(exec('getNeighbours', { regionKeys: ['a', 'b'] })).toBe(
|
||||
JSON.stringify({ neighbours: ['nb-a', 'nb-b'] }),
|
||||
);
|
||||
});
|
||||
|
||||
it('degrades unknown tools, malformed args, and unknown keys without throwing', () => {
|
||||
const exec = makeNeighboursExecutor(getNeighbours, new Set(['a']));
|
||||
expect(exec('otherTool', {})).toBe(JSON.stringify({ error: 'unknown tool: otherTool' }));
|
||||
expect(exec('getNeighbours', { regionKeys: 'not-an-array' })).toBe(
|
||||
JSON.stringify({ neighbours: [] }),
|
||||
);
|
||||
expect(exec('getNeighbours', { regionKeys: ['a', 'zzz-not-valid'] })).toBe(
|
||||
JSON.stringify({ neighbours: ['nb-a'] }), // the unknown key is filtered out
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('playerFrontier (v0.21 #16 P2)', () => {
|
||||
const adjacency: Record<string, string[]> = {
|
||||
GBR: ['DEU', 'USA'],
|
||||
GBR2: ['DEU'],
|
||||
DEU: ['GBR', 'GBR2', 'USA'],
|
||||
USA: ['GBR', 'DEU'],
|
||||
};
|
||||
const getNeighbours = (keys: string[]) =>
|
||||
[...new Set(keys.flatMap((k) => adjacency[k] ?? []))]
|
||||
.filter((k) => !keys.includes(k))
|
||||
.sort();
|
||||
|
||||
it('is the sorted, deduped set of other-nation keys bordering the player', () => {
|
||||
const state = baseState();
|
||||
state.nations.uk.territory = ['GBR', 'GBR2']; // the player owns both
|
||||
// DEU (de) and USA (us) border the player; deduped and sorted
|
||||
expect(playerFrontier(state, getNeighbours)).toEqual(['DEU', 'USA']);
|
||||
});
|
||||
|
||||
it('drops candidates the player itself owns (a sloppy resolver may report them)', () => {
|
||||
const state = baseState();
|
||||
state.nations.uk.territory = ['GBR', 'GBR2'];
|
||||
const sloppy = () => ['GBR2', 'DEU'];
|
||||
expect(playerFrontier(state, sloppy)).toEqual(['DEU']);
|
||||
});
|
||||
|
||||
it('is empty when the player has no territory or no controllable border', () => {
|
||||
const empty = baseState();
|
||||
empty.nations.uk.territory = [];
|
||||
expect(playerFrontier(empty, getNeighbours)).toEqual([]);
|
||||
const noBorders = () => [];
|
||||
expect(playerFrontier(baseState(), noBorders)).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('runTurn (getNeighbours tool path, v0.21 #16 P2)', () => {
|
||||
const adjacency: Record<string, string[]> = {
|
||||
GBR: ['DEU'],
|
||||
DEU: ['GBR', 'USA'],
|
||||
USA: ['DEU'],
|
||||
};
|
||||
const getNeighbours = (keys: string[]) =>
|
||||
[...new Set(keys.flatMap((k) => adjacency[k] ?? []))]
|
||||
.filter((k) => !keys.includes(k))
|
||||
.sort();
|
||||
|
||||
const finalTurn = JSON.stringify({
|
||||
date: '1939-09-03',
|
||||
events: [
|
||||
{
|
||||
nation: 'uk',
|
||||
type: 'military',
|
||||
title: 'The border region falls',
|
||||
text: 'UK seizes the contiguous region.',
|
||||
outcome: 'success',
|
||||
},
|
||||
],
|
||||
stateChanges: [],
|
||||
relations: [],
|
||||
// the player gains its only frontier region (DEU, owned by de)
|
||||
territoryChanges: [{ nation: 'uk', gain: ['DEU'], lose: [] }],
|
||||
});
|
||||
|
||||
/**
|
||||
* A fake LlmClient implementing BOTH chat() and chatWithTools(). The
|
||||
* chatWithTools fake plays the model's side of the protocol: it records
|
||||
* the initial messages + tools, executes the scripted tool calls through
|
||||
* the executor the engine handed it, and returns the final content.
|
||||
*/
|
||||
function toolLlm(final: string, scriptedCalls: Array<{ name: string; args: Record<string, unknown> }>) {
|
||||
const seen: {
|
||||
firstMessages: WireMessage[];
|
||||
tools: ToolDefinition[];
|
||||
executorCalls: Array<{ name: string; args: Record<string, unknown>; result: string }>;
|
||||
chatCalls: number;
|
||||
} = { firstMessages: [], tools: [], executorCalls: [], chatCalls: 0 };
|
||||
const client: LlmClient = {
|
||||
chat: async (messages) => {
|
||||
seen.chatCalls += 1;
|
||||
seen.firstMessages = messages as WireMessage[];
|
||||
return final;
|
||||
},
|
||||
listModels: async () => [],
|
||||
chatWithTools: async (messages, tools, executeTool) => {
|
||||
seen.firstMessages = messages;
|
||||
seen.tools = tools;
|
||||
for (const call of scriptedCalls) {
|
||||
seen.executorCalls.push({ ...call, result: executeTool(call.name, call.args) });
|
||||
}
|
||||
return final;
|
||||
},
|
||||
};
|
||||
return { client, seen };
|
||||
}
|
||||
|
||||
it('uses chatWithTools with the tool, a frontier in the prompt, the wired executor, and applies the transfer', async () => {
|
||||
const original = baseState();
|
||||
original.pending = [{ kind: 'action', text: 'Seize the border region' }];
|
||||
const { client, seen } = toolLlm(finalTurn, [
|
||||
{ name: 'getNeighbours', args: { regionKeys: ['GBR'] } },
|
||||
]);
|
||||
const { state } = await runTurn({
|
||||
llm: client,
|
||||
preset,
|
||||
state: original,
|
||||
items: original.pending,
|
||||
getNeighbours,
|
||||
});
|
||||
|
||||
// the tool was offered and the system prompt advertises it
|
||||
expect(seen.tools.map((t) => t.function.name)).toEqual([GET_NEIGHBOURS_TOOL.function.name]);
|
||||
const system = seen.firstMessages[0] as { role: 'system'; content: string };
|
||||
expect(system.content).toContain('getNeighbours');
|
||||
|
||||
// the user payload carries the player's frontier (DEU: the player's only
|
||||
// controllable border, owned by de)
|
||||
const user = seen.firstMessages[1] as { role: 'user'; content: string };
|
||||
const payload = JSON.parse(user.content) as { frontier?: string[] };
|
||||
expect(payload.frontier).toEqual(['DEU']);
|
||||
|
||||
// the executor the engine built answers from the resolver
|
||||
expect(seen.executorCalls).toHaveLength(1);
|
||||
expect(seen.executorCalls[0].args).toEqual({ regionKeys: ['GBR'] });
|
||||
expect(seen.executorCalls[0].result).toBe(JSON.stringify({ neighbours: ['DEU'] }));
|
||||
|
||||
// chat() was never used on the tool path
|
||||
expect(seen.chatCalls).toBe(0);
|
||||
|
||||
// the contiguous transfer was applied: uk gains DEU, de loses it
|
||||
expect(state.nations.uk.territory).toContain('DEU');
|
||||
expect(state.nations.de.territory).not.toContain('DEU');
|
||||
});
|
||||
|
||||
it('falls back to plain chat() when the client lacks chatWithTools (no tool; the frontier hint stays in the prompt)', async () => {
|
||||
const original = baseState();
|
||||
const { client, seen } = toolLlm(validResult, []);
|
||||
delete client.chatWithTools; // simulate a minimal client (chat only)
|
||||
const { state } = await runTurn({
|
||||
llm: client,
|
||||
preset,
|
||||
state: original,
|
||||
items: original.pending,
|
||||
getNeighbours,
|
||||
});
|
||||
expect(seen.chatCalls).toBe(1);
|
||||
expect(seen.tools).toEqual([]); // the tool path was never entered
|
||||
const system = seen.firstMessages[0] as { content: string };
|
||||
expect(system.content).not.toContain('getNeighbours');
|
||||
const user = seen.firstMessages[1] as { content: string };
|
||||
const payload = JSON.parse(user.content) as { frontier?: string[] };
|
||||
// the frontier hint stays (a resolver was given) even without the tool —
|
||||
// it also tells the model which borders are realistically contestable
|
||||
expect(payload.frontier).toEqual(['DEU']);
|
||||
// the canned result still applied (GBR moved uk -> de)
|
||||
expect(state.nations.de.territory).toContain('GBR');
|
||||
expect(state.nations.uk.territory).not.toContain('GBR');
|
||||
});
|
||||
});
|
||||
|
||||
describe('deterministic stub (one contiguous conquest per turn, v0.21 #16 P2)', () => {
|
||||
const adjacency: Record<string, string[]> = {
|
||||
GBR: ['DEU'],
|
||||
DEU: ['GBR', 'USA'],
|
||||
USA: ['DEU'],
|
||||
};
|
||||
const getNeighbours = (keys: string[]) =>
|
||||
[...new Set(keys.flatMap((k) => adjacency[k] ?? []))]
|
||||
.filter((k) => !keys.includes(k))
|
||||
.sort();
|
||||
|
||||
it('transfers the first frontier region to the player (and its owner loses it)', async () => {
|
||||
const original = baseState();
|
||||
original.pending = [{ kind: 'action', text: 'March on the border region' }];
|
||||
const { state } = await runTurn({
|
||||
llm: makeStubLlmClient(),
|
||||
preset,
|
||||
state: original,
|
||||
items: original.pending,
|
||||
getNeighbours,
|
||||
});
|
||||
expect(state.nations.uk.territory).toContain('DEU'); // frontier[0]
|
||||
expect(state.nations.de.territory).not.toContain('DEU');
|
||||
// the rest of the stub behavior is unchanged
|
||||
expect(state.turn).toBe(2);
|
||||
expect(state.date).toBe('1939-09-03');
|
||||
expect(state.nations.uk.stats.military).toBe(85); // clamp(80 + 5)
|
||||
expect(state.events).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('with an empty frontier (no controllable border, like the UK in wwii-1939): no transfer, the turn still advances', async () => {
|
||||
const original = baseState();
|
||||
original.pending = [{ kind: 'action', text: 'Hold the line' }];
|
||||
const { state } = await runTurn({
|
||||
llm: makeStubLlmClient(),
|
||||
preset,
|
||||
state: original,
|
||||
items: original.pending,
|
||||
getNeighbours: () => [], // no borders at all
|
||||
});
|
||||
expect(state.nations.uk.territory).toEqual(['GBR']); // untouched
|
||||
expect(state.nations.de.territory).toEqual(['DEU']);
|
||||
expect(state.nations.us.territory).toEqual(['USA']);
|
||||
expect(state.turn).toBe(2);
|
||||
expect(state.events).toHaveLength(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe('buildSystemPrompt (tool mode, v0.21 #16 P2)', () => {
|
||||
it('mentions the getNeighbours tool and the contiguity rules only when the tool is sent', () => {
|
||||
const plain = buildSystemPrompt(preset);
|
||||
expect(plain).not.toContain('getNeighbours');
|
||||
expect(plain).toMatch(/Only change borders when war/i); // the legacy rule stays
|
||||
const withTool = buildSystemPrompt(preset, true);
|
||||
expect(withTool).toContain('getNeighbours');
|
||||
expect(withTool).toMatch(/contiguous/i);
|
||||
expect(withTool).toMatch(/frontier/i);
|
||||
expect(withTool).not.toMatch(/Only change borders when war/i);
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
Reference in New Issue
Block a user