8000 fix: report missed spell attacks, and tighten the agent runtime by Mnehmos · Pull Request #116 · Mnehmos/mnehmos.rpg.mcp · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
970de09
fix(math): bound dice expressions so a roll cannot hang or exhaust th…
claude Nov 9, 2026
9f626b0
fix(server): stop a dead event subscriber from taking the server down
claude Nov 9, 2026
8549668
fix(combat): a refused move has no consequences, and damage never heals
claude Nov 9, 2026
e7269b7
fix(deps): update MCP SDK to 1.32.2 for security advisories
claude Nov 9, 2026
805fb10
fix(combat): enforce turn order, reach and sane numbers on attacks
claude Nov 9, 2026
2bdec30
fix(storage): never close a campaign database out from under a runnin…
claude Nov 9, 2026
18ed707
fix(world): scope the in-memory world cache to its campaign and bound it
claude Nov 9, 2026
b9d509c
fix(storage): refuse a corrupted campaign database instead of replaci…
claude Nov 9, 2026
fe247eb
fix(audit): keep only the newest audit rows per campaign
claude Nov 9, 2026
324368b
fix(transport): compare transport tokens in constant time
claude Nov 9, 2026
4e2847c
chore: drop Node 18 from CI, quiet per-request startup logs, fix repo…
claude Nov 9, 2026
cb482a3
docs: correct tool and test counts
claude Nov 9, 2026
aa81cf6
fix(combat): accept range through the combat_action tool schema
claude Nov 9, 2026
cbc9e67
chore: merge already-merged branch history so the branch fast-forwards
claude Nov 9, 2026
222867b
fix(deps): upgrade zod 3 to 4 to clear the remaining security advisory
claude Nov 10, 2026
e9d9b8e
chore: record already-merged branch history so the branch fast-forwards
claude Nov 10, 2026
cbfe6fe
fix(magic): report the roll when a spell attack misses
claude Nov 10, 2026
95ed309
fix(agent): close the replay model loophole and bound agent timeouts
claude Nov 10, 2026
5b8b85f
chore: record already-merged branch history so the branch fast-forwards
claude Nov 10, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

The reference backend game engine. **36 MCP tools** (31 consolidated action-routed + 5 meta/event) for complete RPG mechanics, including LLM-driven NPCs via `agent_manage` and the Operator's constraint-perception lens via `perception_manage`.
**Philosophy:** "LLM describes, engine validates" - Database is source of truth.
**Status:** Alpha - 2373 tests passing (7 skipped), 161 test files, MCP Protocol fully integrated
**Status:** Alpha - 2383 tests passing (7 skipped), 162 test files, MCP Protocol fully integrated

## Who consumes this engine

Expand Down Expand Up @@ -60,7 +60,7 @@ src/
├── utils/ # Action router, fuzzy matching
└── math/ # Dice, algebra, physics

tests/ # Mirror of src/ structure (161 files)
tests/ # Mirror of src/ structure (162 files)
docs/ # White paper, ADRs, LLM spatial guide
```

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,7 +374,7 @@ the consolidated contracts, and the adapter matrix is enforced by

```bash
npm test
# 2373 tests passing, 7 skipped
# 2383 tests passing, 7 skipped
# 148 test files
# Coverage across all 36 tools (31 consolidated + 5 meta/event)
```
Expand Down
9 changes: 8 additions & 1 deletion src/agent/audit/replay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@

import { AgentRuntimeDeps } from '../runtime/deps.js';
import { ChatMessage, ProviderError } from '../provider/types.js';
import { effectiveTimeoutMs, isProModel } from '../../schema/agent.js';

export interface ReplayInput {
callId: string;
Expand Down Expand Up @@ -80,6 +81,12 @@ export async function replayCall(
}

// ─── Live mode: direct provider call with the override model ───
// The model comes straight from the caller here, so the rule that invoke
// enforces through the competency ladder has to be applied explicitly.
if (isProModel(input.model)) {
return { error: true, message: `Pro model variants are not allowed: ${input.model}` };
}

const agent = deps.agentRepo.findById(call.agentId);
if (!agent) {
return { error: true, message: `Agent for original call is gone: ${call.agentId}` };
Expand Down Expand Up @@ -108,7 +115,7 @@ export async function replayCall(
}

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), agent.timeoutMs);
const timeout = setTimeout(() => controller.abort(), effectiveTimeoutMs(agent.timeoutMs));

try {
const out = await provider.call({
Expand Down
9 changes: 8 additions & 1 deletion src/agent/provider/openai.ts
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,14 @@ export class OpenAIProvider implements LLMProvider {
throw classifyFetchError(err);
}

const rawText = await response.text();
// The abort signal cancels the body read too; classify that the same
// way as an abort before the headers arrived.
let rawText: string;
try {
rawText = await response.text();
} catch (err) {
throw classifyFetchError(err);
}
const durationMs = Date.now() - start;

if (!response.ok) {
Expand Down
9 changes: 8 additions & 1 deletion src/agent/provider/openrouter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,14 @@ export class OpenRouterProvider implements LLMProvider {
throw classifyFetchError(err);
}

const rawText = await response.text();
// The abort signal cancels the body read too; classify that the same
// way as an abort before the headers arrived.
let rawText: string;
try {
rawText = await response.text();
} catch (err) {
throw classifyFetchError(err);
}
const durationMs = Date.now() - start;

if (!response.ok) {
Expand Down
3 changes: 2 additions & 1 deletion src/agent/runtime/competency.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { z } from 'zod';
import { isProModel } from '../../schema/agent.js';

export const ReasoningEffortSchema = z.enum(['low', 'medium', 'high', 'xhigh']);
export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
Expand Down Expand Up @@ -29,7 +30,7 @@ export interface ResolvedCompetency extends CompetencyLadderEntry {
const LADDER_PATH = fileURLToPath(new URL('../../../config/competency-ladder.json', import.meta.url));

function assertNoProModel(model: string): void {
if (/-pro\b/i.test(model)) {
if (isProModel(model)) {
throw new Error(`Competency model "${model}" violates the no-pro-model rule`);
}
}
Expand Down
4 changes: 2 additions & 2 deletions src/agent/runtime/invoke.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
* Never throws to the caller — always returns a structured result the DM/UI can display.
*/

import { Agent, AgentCallStatus } from '../../schema/agent.js';
import { Agent, AgentCallStatus, effectiveTimeoutMs } from '../../schema/agent.js';
import { Character, NPC } from '../../schema/character.js';
import { AgentRuntimeDeps } from './deps.js';
import { preflight } from './preflight.js';
Expand Down Expand Up @@ -243,7 +243,7 @@ export async function invokeAgent(input: InvokeInput, deps: AgentRuntimeDeps): P

// 5. Call provider with timeout
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), agent.timeoutMs);
const timeout = setTimeout(() => controller.abort(), effectiveTimeoutMs(agent.timeoutMs));

try {
const result = await provider.call({
Expand Down
28 changes: 26 additions & 2 deletions src/schema/agent.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,28 @@ export const CompetencyOverrideSchema = z.object({
});
export type CompetencyOverride = z.infer<typeof CompetencyOverrideSchema>;

/**
* Longest an agent's provider call may run.
*
* The call happens inside its campaign's unit of work, holding that campaign's
* lock and an open write transaction, so every other call on the campaign
* waits behind it. The timeout is the only bound on that wait.
*/
export const MAX_AGENT_TIMEOUT_MS = 120_000;

/** Timeout accepted from a caller when creating or updating an agent. */
export const AgentTimeoutInputSchema = z.number().int().positive().max(MAX_AGENT_TIMEOUT_MS);

/** The timeout to actually use: rows stored before the limit existed are clamped. */
export function effectiveTimeoutMs(timeoutMs: number): number {
return Math.min(timeoutMs, MAX_AGENT_TIMEOUT_MS);
}

/** Pro model variants are not allowed anywhere an agent's model is chosen. */
export function isProModel(model: string): boolean {
return /-pro\b/i.test(model);
}

export const AgentSchema = z.object({
id: z.string(),
characterId: z.string(),
Expand Down Expand Up @@ -169,7 +191,7 @@ export const AgentCreateInputSchema = z.object({
maxTokens: z.number().int().positive().optional(),
budgetTokens: z.number().int().positive().nullable().optional(),
tokensUsed: z.number().int().nonnegative().optional(),
timeoutMs: z.number().int().positive().optional(),
timeoutMs: AgentTimeoutInputSchema.optional(),
consecutiveFailures: z.number().int().nonnegative().optional(),
circuitState: AgentCircuitStateSchema.optional(),
competencyOverride: CompetencyOverrideSchema.nullable().optional()
Expand All @@ -181,5 +203,7 @@ export const AgentUpdateInputSchema = AgentSchema.omit({
characterId: true,
createdAt: true,
updatedAt: true
}).partial();
}).partial().extend({
timeoutMs: AgentTimeoutInputSchema.optional()
});
export type AgentUpdateInput = z.infer<typeof AgentUpdateInputSchema>;
5 changes: 3 additions & 2 deletions src/server/consolidated/agent-manage.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ import {
AgentSliceKindSchema,
AgentSecretImportanceSchema,
AgentJournalKindSchema,
AgentTimeoutInputSchema,
CompetencyOverrideSchema
} from '../../schema/agent.js';
import { createActionRouter, ActionDefinition, McpResponse } from '../../utils/action-router.js';
Expand Down Expand Up @@ -104,7 +105,7 @@ const CreateSchema = z.object({
temperature: z.number().min(0).max(2).optional(),
maxTokens: z.number().int().positive().optional(),
budgetTokens: z.number().int().positive().optional(),
timeoutMs: z.number().int().positive().optional()
timeoutMs: AgentTimeoutInputSchema.optional()
});

const GetSchema = z.object({
Expand All @@ -131,7 +132,7 @@ const UpdateSchema = z.object({
temperature: z.number().min(0).max(2).optional(),
maxTokens: z.number().int().positive().optional(),
budgetTokens: z.number().int().positive().nullable().optional(),
timeoutMs: z.number().int().positive().optional()
timeoutMs: AgentTimeoutInputSchema.optional()
}).refine(d => d.agentId || d.characterId, { message: 'agentId or characterId required' });

const DeleteSchema = z.object({
Expand Down
4 changes: 3 additions & 1 deletion src/server/handlers/combat-handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2008,7 +2008,9 @@ export async function handleExecuteCombatAction(args: unknown, ctx: SessionConte
output += ` • ${dr.name}: ${dr.hpBefore} → ${dr.hpAfter} HP${defeatIcon}\n`;
}
}
} else if (damageResults.length === 1) {
} else if (damageResults.length === 1 || resolution.hit === false) {
// A spell attack that missed damages no one, so damageResults is
// empty — but the roll and the miss still have to be reported.
output = formatSpellCastResult(actor.name, resolution, primaryTarget, targetHpBefore);
} else {
output = `\n✨ ${actor.name} casts ${spell.name}!\n`;
Expand Down
38 changes: 38 additions & 0 deletions tests/agent/audit/replay.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -295,3 +295,41 @@ describe('replayCall', () => {
expect(after.circuitState).toBe(before.circuitState);
});
});

describe('replayCall model policy', () => {
let db: ReturnType<typeof initDB>;
let deps: ReturnType<typeof buildAgentRuntime>;

beforeEach(() => {
cleanup();
db = initDB(TEST_DB);
migrate(db);
deps = buildAgentRuntime(db, new ProviderFactory());
});

afterEach(() => {
db.close();
cleanup();
});

// invoke refuses pro model variants (the competency ladder and overrides
// both enforce it). Replay takes a model straight from the caller, so it
// was a way around the rule.
it('live mode: refuses a pro model override without calling the provider', async () => {
new CharacterRepository(db).create(char('char-1'));
const agent = deps.agentRepo.create({ characterId: 'char-1', provider: 'openai', model: 'gpt-4o-mini' });
let calls = 0;
deps.providerFactory.register('openai', provider(async () => {
calls++;
return { text: 'ok', promptTokens: 1, completionTokens: 1, raw: '{}', durationMs: 1 };
}));
const original = await invokeAgent({ agentId: agent.id, situation: 'go' }, deps);
expect(calls).toBe(1);

const result = await replayCall({ callId: original.callId!, model: 'gpt-5-pro' }, deps);

expect('error' in result).toBe(true);
if ('error' in result) expect(result.message).toMatch(/pro model/i);
expect(calls).toBe(1);
});
});
28 changes: 28 additions & 0 deletions tests/agent/provider/openai.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -413,3 +413,31 @@ describe('OpenAIProvider', () => {
expect(() => new OpenAIProvider({ apiKey: '' })).toThrow(/apiKey/);
});
});

describe('provider timeout while reading the response body', () => {
// The abort signal also cancels the body read. That rejection used to
// escape as a bare AbortError, so the call was recorded as a generic
// error instead of a timeout.
const abortingBody = (async () => ({
ok: true,
status: 200,
text: async () => {
const error = new Error('This operation was aborted');
error.name = 'AbortError';
throw error;
},
})) as unknown as typeof fetch;

it('OpenAI: classifies it as a timeout', async () => {
const provider = new OpenAIProvider({ apiKey: 'k', fetchImpl: abortingBody });
await expect(provider.call({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'hi' }] }))
.rejects.toMatchObject({ name: 'ProviderError', kind: 'timeout' });
});

it('OpenRouter: classifies it as a timeout', async () => {
const { OpenRouterProvider } = await import('../../../src/agent/provider/openrouter');
const provider = new OpenRouterProvider({ apiKey: 'k', fetchImpl: abortingBody });
await expect(provider.call({ model: 'openai/gpt-4o-mini', messages: [{ role: 'user', content: 'hi' }] }))
.rejects.toMatchObject({ name: 'ProviderError', kind: 'timeout' });
});
});
26 changes: 26 additions & 0 deletions tests/agent/runtime/timeout-bounds.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
import { describe, it, expect } from 'vitest';
import { AgentCreateInputSchema, AgentUpdateInputSchema, MAX_AGENT_TIMEOUT_MS, effectiveTimeoutMs } from '../../../src/schema/agent';

/**
* An agent's provider call runs inside its campaign's unit of work, which
* holds the campaign's lock and an open write transaction. The timeout is the
* only thing bounding that, so it cannot be arbitrarily large.
*/
describe('agent timeout bounds', () => {
const base = { characterId: 'c1', provider: 'openai', model: 'gpt-4o-mini' };

it('rejects a timeout above the maximum on create and update', () => {
expect(AgentCreateInputSchema.safeParse({ ...base, timeoutMs: MAX_AGENT_TIMEOUT_MS + 1 }).success).toBe(false);
expect(AgentUpdateInputSc E73D hema.safeParse({ timeoutMs: 3_600_000 }).success).toBe(false);
});

it('accepts timeouts up to the maximum', () => {
expect(AgentCreateInputSchema.safeParse({ ...base, timeoutMs: MAX_AGENT_TIMEOUT_MS }).success).toBe(true);
expect(AgentCreateInputSchema.safeParse({ ...base, timeoutMs: 25_000 }).success).toBe(true);
});

it('clamps a stored timeout that predates the limit', () => {
expect(effectiveTimeoutMs(3_600_000)).toBe(MAX_AGENT_TIMEOUT_MS);
expect(effectiveTimeoutMs(25_000)).toBe(25_000);
});
});
22 changes: 21 additions & 1 deletion tests/server/spellcasting.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1377,7 +1377,27 @@ describe('Category 11: Class-Specific Spellcasting', () => {
describe('Category 12: Edge Cases & Exploits', () => {

// 12.1 - Cantrip scaling by character level
test('12.1 - fire bolt damage scales with character level', { retry: 3 }, async () => {
// A spell attack that misses is still a result the caller has to narrate.
// It used to come back as a bare "casts Fire Bolt!" with no roll at all,
// indistinguishable from a hit for zero damage.
test('12.0 - a missed spell attack reports the roll and the miss', async () => {
const wizard = await createWizard(1, { cantripsKnown: ['Fire Bolt'] });
const random = vi.spyOn(Math, 'random').mockReturnValue(0); // every d20 is a 1
try {
const result = await castSpell(wizard.id!, 'Fire Bolt');
expect(result.rawText).toMatch(/Attack Roll: 1 \(d20\)/);
expect(result.rawText).toMatch(/MISS/);
expect(result.rawText).toMatch(/missed/i);
expect(result.diceRolled).toBe('1d10');
expect(result.damage ?? 0).toBe(0);
} finally {
random.mockRestore();
}
});

// 12.1 depended on all three attacks hitting and was retried to hide it.
// With misses reported properly, the dice are in the response either way.
test('12.1 - fire bolt damage scales with character level', async () => {
const wizard1 = await createWizard(1, { cantripsKnown: ['Fire Bolt'] });
const wizard5 = await createWizard(5, { cantripsKnown: ['Fire Bolt'] });
const wizard11 = await createWizard(11, { cantripsKnown: ['Fire Bolt'] });
Expand Down
Loading
0