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:
+189
-9
@@ -23,12 +23,55 @@
|
||||
// to 3 total attempts and 2s→3s backoff (±20% jitter). HTTP 4xx is a
|
||||
// deterministic client error and throws immediately, with no retry. Every
|
||||
// call is logged: one line on success, one on final failure.
|
||||
//
|
||||
// Function calling: `chatWithTools()` extends `chat()` with the OpenAI tool
|
||||
// loop. When the model answers with `finish_reason: "tool_calls"`, the client
|
||||
// runs the provided executor for every requested call, appends the assistant
|
||||
// tool-call message plus one `tool` result message per call, and re-sends the
|
||||
// growing history until the model produces a final `content`. The loop is
|
||||
// bounded to DEFAULT_MAX_TOOL_ROUNDS (6) tool rounds; if the budget is spent
|
||||
// without a final answer, one last *no-tools* request forces the model to
|
||||
// commit. The same retry/backoff/reasoning-effort machinery applies per
|
||||
// request, so an injectable transport only has to forward `tools` in the body
|
||||
// and accept `assistant`/`tool` messages in the history. The deterministic
|
||||
// stub answers plain `content` (no tool calls) and therefore bypasses the
|
||||
// loop in a single round.
|
||||
|
||||
export interface ChatMessage {
|
||||
role: 'system' | 'user' | 'assistant';
|
||||
content: string;
|
||||
}
|
||||
|
||||
/** One OpenAI-style function call the model requests (`finish_reason: "tool_calls"`). */
|
||||
export interface ToolCallSpec {
|
||||
id: string;
|
||||
type: 'function';
|
||||
function: { name: string; arguments: string };
|
||||
}
|
||||
|
||||
/** A function the model may call (one OpenAI `tools` entry). */
|
||||
export interface ToolDefinition {
|
||||
type: 'function';
|
||||
function: {
|
||||
name: string;
|
||||
description?: string;
|
||||
parameters?: Record<string, unknown>;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The full message vocabulary a request can carry: plain chat messages, plus
|
||||
* assistant messages that request tool calls and the `tool` results that
|
||||
* answer them (the OpenAI function-calling wire shape).
|
||||
*/
|
||||
export type WireMessage =
|
||||
| ChatMessage
|
||||
| { role: 'assistant'; content: string | null; tool_calls: ToolCallSpec[] }
|
||||
| { role: 'tool'; tool_call_id: string; content: string };
|
||||
|
||||
/** Executes one tool call; the returned string is fed back to the model as the `tool` result. */
|
||||
export type ToolExecutor = (name: string, args: Record<string, unknown>) => string;
|
||||
|
||||
/** A network call. The default implementation is native fetch. */
|
||||
export type Transport = (url: string, init?: RequestInit) => Promise<Response>;
|
||||
|
||||
@@ -39,6 +82,18 @@ export interface ChatOptions {
|
||||
|
||||
export interface LlmClient {
|
||||
chat(messages: ChatMessage[], opts?: ChatOptions): Promise<string>;
|
||||
/**
|
||||
* The function-calling variant of chat() — see the file header for the loop
|
||||
* semantics (bounded tool rounds, then a forced final answer). Optional on
|
||||
* the interface: minimal test doubles may omit it, and callers (the
|
||||
* engine's runTurn) fall back to chat() when it is absent.
|
||||
*/
|
||||
chatWithTools?(
|
||||
messages: WireMessage[],
|
||||
tools: ToolDefinition[],
|
||||
executeTool: ToolExecutor,
|
||||
opts?: ChatOptions & { maxRounds?: number },
|
||||
): Promise<string>;
|
||||
listModels(): Promise<string[]>;
|
||||
}
|
||||
|
||||
@@ -63,9 +118,17 @@ export const DEFAULT_MAX_TOKENS = 4000;
|
||||
*/
|
||||
export const DEFAULT_REASONING_EFFORT = 'low';
|
||||
|
||||
/** Total attempts `chat()` makes before giving up (1 initial + 2 retries). */
|
||||
/** Total attempts per request (chat / chatWithTools) before giving up (1 initial + 2 retries). */
|
||||
export const MAX_ATTEMPTS = 3;
|
||||
|
||||
/**
|
||||
* Max tool-call rounds (assistant tool_calls → tool results) a chatWithTools
|
||||
* loop may make before a final no-tools request forces the answer. Keeps a
|
||||
* turn bounded even if the model keeps asking for data; a realistic turn uses
|
||||
* 0–2 rounds.
|
||||
*/
|
||||
export const DEFAULT_MAX_TOOL_ROUNDS = 6;
|
||||
|
||||
/** Base retry backoff: retry 1 waits 2000ms, retry 2 waits 3000ms, each ±20% jitter. */
|
||||
const RETRY_BASE_DELAY_MS = 2000;
|
||||
|
||||
@@ -154,6 +217,30 @@ function isNetworkError(err: unknown): boolean {
|
||||
);
|
||||
}
|
||||
|
||||
/** Parse the wire `tool_calls` array into validated ToolCallSpecs (malformed entries are dropped). */
|
||||
function parseToolCalls(raw: unknown): ToolCallSpec[] {
|
||||
if (!Array.isArray(raw)) return [];
|
||||
const out: ToolCallSpec[] = [];
|
||||
for (const tc of raw) {
|
||||
if (!tc || typeof tc !== 'object') continue;
|
||||
const t = tc as Record<string, unknown>;
|
||||
const fn = t.function as Record<string, unknown> | undefined;
|
||||
if (!fn || typeof fn.name !== 'string' || fn.name === '') continue;
|
||||
const argumentsText =
|
||||
typeof fn.arguments === 'string'
|
||||
? fn.arguments
|
||||
: fn.arguments != null
|
||||
? JSON.stringify(fn.arguments)
|
||||
: '{}';
|
||||
out.push({
|
||||
id: typeof t.id === 'string' && t.id !== '' ? t.id : `call_${out.length}`,
|
||||
type: 'function',
|
||||
function: { name: fn.name, arguments: argumentsText },
|
||||
});
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/** One transport attempt, classified as success / retryable / fatal. */
|
||||
interface Attempt {
|
||||
status?: number;
|
||||
@@ -161,6 +248,7 @@ interface Attempt {
|
||||
retryable: boolean;
|
||||
content?: string;
|
||||
finishReason?: string | null;
|
||||
toolCalls?: ToolCallSpec[];
|
||||
}
|
||||
|
||||
export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
@@ -179,7 +267,7 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
|
||||
/**
|
||||
* One POST to /chat/completions. Classifies the outcome:
|
||||
* - success → content + finish_reason
|
||||
* - success → content and/or tool_calls
|
||||
* - retryable → timeout/abort, HTTP 5xx, network error, null/empty content
|
||||
* - fatal → HTTP 4xx (deterministic client error) or an unexpected throw
|
||||
*/
|
||||
@@ -213,12 +301,27 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
const body = (await res.json()) as {
|
||||
choices?: {
|
||||
finish_reason?: string | null;
|
||||
message?: { content?: string; reasoning?: string | null };
|
||||
message?: { content?: string; reasoning?: string | null; tool_calls?: unknown };
|
||||
}[];
|
||||
};
|
||||
const choice = body.choices?.[0];
|
||||
const message = choice?.message;
|
||||
// A tool-call round is a SUCCESS even though `content` is null there: the
|
||||
// model is asking for data, not failing (never treat it as truncation).
|
||||
const toolCalls = parseToolCalls(message?.tool_calls);
|
||||
if (toolCalls.length > 0) {
|
||||
return {
|
||||
status: res.status,
|
||||
retryable: false,
|
||||
content:
|
||||
typeof message?.content === 'string' && message.content !== '' ? message.content : undefined,
|
||||
finishReason: choice?.finish_reason ?? null,
|
||||
toolCalls,
|
||||
};
|
||||
}
|
||||
// The reasoning model can exhaust its output budget on the CoT and return
|
||||
// a null `content` — treat that as a retryable truncation, not a success.
|
||||
const content = body.choices?.[0]?.message?.content;
|
||||
const content = message?.content;
|
||||
if (typeof content !== 'string' || content === '') {
|
||||
return {
|
||||
status: res.status,
|
||||
@@ -230,11 +333,16 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
status: res.status,
|
||||
retryable: false,
|
||||
content,
|
||||
finishReason: body.choices?.[0]?.finish_reason ?? null,
|
||||
finishReason: choice?.finish_reason ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
async function chat(messages: ChatMessage[], opts: ChatOptions = {}): Promise<string> {
|
||||
/** Build one /chat/completions request body. `tools` is only included when non-empty, so plain chat() keeps its exact legacy shape. */
|
||||
function buildPayload(
|
||||
messages: WireMessage[],
|
||||
tools: ToolDefinition[] | undefined,
|
||||
opts: ChatOptions,
|
||||
): Record<string, unknown> {
|
||||
const payload: Record<string, unknown> = {
|
||||
model,
|
||||
messages,
|
||||
@@ -245,7 +353,16 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
};
|
||||
if (opts.temperature != null) payload.temperature = opts.temperature;
|
||||
if (sendEffort) payload.reasoning_effort = effort;
|
||||
if (tools && tools.length > 0) payload.tools = tools;
|
||||
return payload;
|
||||
}
|
||||
|
||||
/**
|
||||
* One request with the standard retry/backoff: up to MAX_ATTEMPTS per
|
||||
* request; resolves with a successful Attempt (content and/or toolCalls) or
|
||||
* throws the last error once the attempts are spent.
|
||||
*/
|
||||
async function requestWithRetry(payload: Record<string, unknown>): Promise<Attempt> {
|
||||
const totalStart = Date.now();
|
||||
let lastStatus: number | undefined;
|
||||
let lastError: Error = new Error('chat failed: no attempt completed');
|
||||
@@ -255,12 +372,13 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
if (out.status !== undefined) lastStatus = out.status;
|
||||
if (out.error) lastError = out.error;
|
||||
|
||||
if (out.content !== undefined) {
|
||||
if (out.content !== undefined || out.toolCalls !== undefined) {
|
||||
console.log('[llm] chat ok', {
|
||||
ms: Date.now() - totalStart,
|
||||
finishReason: out.finishReason ?? null,
|
||||
toolCalls: out.toolCalls?.length ?? 0,
|
||||
});
|
||||
return out.content;
|
||||
return out;
|
||||
}
|
||||
// Give up on a non-retryable failure, or when the last attempt is spent.
|
||||
if (!out.retryable || attempt === MAX_ATTEMPTS) {
|
||||
@@ -278,6 +396,68 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
throw lastError;
|
||||
}
|
||||
|
||||
async function chat(messages: ChatMessage[], opts: ChatOptions = {}): Promise<string> {
|
||||
const out = await requestWithRetry(buildPayload(messages, undefined, opts));
|
||||
return out.content ?? '';
|
||||
}
|
||||
|
||||
/**
|
||||
* The function-calling loop — see the file header. Bounded: at most
|
||||
* `maxRounds` tool rounds, then one final no-tools request forces an answer.
|
||||
* Throws like chat() only on transport-level exhaustion (the engine maps that
|
||||
* to a 502; bad *content* never throws, it is parsed defensively downstream).
|
||||
*/
|
||||
async function chatWithTools(
|
||||
initial: WireMessage[],
|
||||
tools: ToolDefinition[],
|
||||
executeTool: ToolExecutor,
|
||||
opts: ChatOptions & { maxRounds?: number } = {},
|
||||
): Promise<string> {
|
||||
const maxRounds = Math.max(1, opts.maxRounds ?? DEFAULT_MAX_TOOL_ROUNDS);
|
||||
const messages: WireMessage[] = [...initial];
|
||||
for (let round = 0; round < maxRounds; round++) {
|
||||
const out = await requestWithRetry(buildPayload(messages, tools, opts));
|
||||
// Tool calls win over any partial content: the model asked for data
|
||||
// before it finished.
|
||||
if (out.toolCalls && out.toolCalls.length > 0) {
|
||||
messages.push({
|
||||
role: 'assistant',
|
||||
content: out.content ?? null,
|
||||
tool_calls: out.toolCalls,
|
||||
});
|
||||
for (const tc of out.toolCalls) {
|
||||
let result: string;
|
||||
try {
|
||||
const parsed: unknown =
|
||||
tc.function.arguments !== '' ? JSON.parse(tc.function.arguments) : {};
|
||||
const args =
|
||||
parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
|
||||
? (parsed as Record<string, unknown>)
|
||||
: {};
|
||||
result = executeTool(tc.function.name, args);
|
||||
} catch (err) {
|
||||
// Malformed arguments are not fatal: hand the model an error
|
||||
// result so it can re-call with valid arguments or move on.
|
||||
result = JSON.stringify({
|
||||
error: `invalid tool arguments: ${err instanceof Error ? err.message : String(err)}`,
|
||||
});
|
||||
}
|
||||
messages.push({ role: 'tool', tool_call_id: tc.id, content: result });
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (out.content !== undefined) return out.content;
|
||||
}
|
||||
// The tool budget is spent without a final answer: one last no-tools
|
||||
// request forces the model to commit.
|
||||
messages.push({
|
||||
role: 'user',
|
||||
content: 'You have reached your tool budget. Answer now with the final result only.',
|
||||
});
|
||||
const out = await requestWithRetry(buildPayload(messages, undefined, opts));
|
||||
return out.content ?? '';
|
||||
}
|
||||
|
||||
async function listModels(): Promise<string[]> {
|
||||
const res = await transport(`${apiBase}/models`, {
|
||||
signal: AbortSignal.timeout(timeoutMs),
|
||||
@@ -287,5 +467,5 @@ export function createLlmClient(deps: LlmClientDeps = {}): LlmClient {
|
||||
return (body.data ?? []).map((m) => m.id);
|
||||
}
|
||||
|
||||
return { chat, listModels };
|
||||
return { chat, chatWithTools, listModels };
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user