feat: add personality editing to World Lab

ROADMAP.md

@@ -27,6 +27,8 @@ Implementation scope: six fixed agent profiles, a 61-cell Toledo development wor
 
 Prompt/personality editing, presets, cloning, respawning, reproducible starting worlds, provider/model configuration, and cost visibility.
 
+First focused slice: server-owned session personality editing for the six existing agents, five bounded presets, world reset that preserves active personality configuration, and a separate confirmed restore-default action. Persistence across process restarts, cloning, respawning, provider/model configuration, cost visibility, and social mechanics remain deferred to later focused slices or milestones.
+
 ## PR 4 — Social agents
 
 Range-limited messages, agent inboxes, relationship memories, communication visualization, cooperation, refusal, deception, and betrayal emerging through prompts rather than a large formal rules system.

apps/game-api/src/app.test.ts

@@ -9,8 +9,10 @@ import {
 import {
   h3CellSchema,
   resetSimulationResponseSchema,
+  restoreDefaultPersonalitiesResponseSchema,
   simulationSnapshotSchema,
   singleTurnResponseSchema,
+  updateAgentPersonalityResponseSchema,
 } from '@agentborne/shared';
 import { createApp } from './app';
 
@@ -160,19 +162,148 @@ describe('game API simulation boundary', () => {
     });
   });
 
-  it('resets the complete simulation', async () => {
+  it('resets world progress while preserving personality configuration', async () => {
     const app = createApp({
       provider: new ScriptedAgentProvider([
         { requestedAction: { type: 'infect' }, summary: 'Infect.' },
       ]),
     });
+    const initial = simulationSnapshotSchema.parse(
+      await (await app.request('/api/simulation')).json(),
+    );
+    await app.request(
+      `/api/simulation/agents/${initial.world.agents[0]!.id}/personality`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ personality: 'Preserved through reset.' }),
+      },
+    );
     await app.request('/api/simulation/turn', { method: 'POST' });
     const response = await app.request('/api/simulation/reset', {
       method: 'POST',
     });
     const reset = resetSimulationResponseSchema.parse(await response.json());
     expect(reset.snapshot.turnNumber).toBe(0);
     expect(reset.snapshot.world.events).toEqual([]);
+    expect(reset.snapshot.world.agents[0]!.personality).toBe(
+      'Preserved through reset.',
+    );
+  });
+
+  it('updates one agent personality through a runtime-validated safe response', async () => {
+    const app = createApp({
+      provider: new ScriptedAgentProvider([
+        { requestedAction: { type: 'wait' }, summary: 'Wait.' },
+      ]),
+    });
+    const initial = simulationSnapshotSchema.parse(
+      await (await app.request('/api/simulation')).json(),
+    );
+    const agent = initial.world.agents[0]!;
+    const response = await app.request(
+      `/api/simulation/agents/${agent.id}/personality`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ personality: '  Explore open edges.  ' }),
+      },
+    );
+    expect(response.status).toBe(200);
+    const payload = updateAgentPersonalityResponseSchema.parse(
+      await response.json(),
+    );
+    expect(payload.agent.personality).toBe('Explore open edges.');
+    expect(payload.snapshot.world.agents[0]!.personality).toBe(
+      'Explore open edges.',
+    );
+    expect(JSON.stringify(payload)).not.toMatch(/api[_-]?key|secret|prompt/i);
+  });
+
+  it.each([
+    JSON.stringify({ personality: '' }),
+    JSON.stringify({ personality: 42 }),
+    '{malformed',
+  ])('rejects invalid personality request bodies safely', async (body) => {
+    const app = createApp({
+      provider: new ScriptedAgentProvider([
+        { requestedAction: { type: 'wait' }, summary: 'Wait.' },
+      ]),
+    });
+    const response = await app.request(
+      '/api/simulation/agents/128f3f38-6b7d-4db7-9e95-751b4ce2681e/personality',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      },
+    );
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      error: {
+        code: 'invalid_personality',
+        message: 'Personality must contain 1 to 600 characters.',
+      },
+    });
+  });
+
+  it('returns typed invalid and unknown agent errors without internal details', async () => {
+    const app = createApp({
+      provider: new ScriptedAgentProvider([
+        { requestedAction: { type: 'wait' }, summary: 'Wait.' },
+      ]),
+    });
+    for (const [agentId, status, code] of [
+      ['not-a-uuid', 400, 'invalid_agent_id'],
+      ['aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', 404, 'unknown_agent'],
+    ] as const) {
+      const response = await app.request(
+        `/api/simulation/agents/${agentId}/personality`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ personality: 'Valid request.' }),
+        },
+      );
+      expect(response.status).toBe(status);
+      const body = await response.json();
+      expect(body).toMatchObject({ error: { code } });
+      expect(JSON.stringify(body)).not.toMatch(
+        /stack|provider|openrouter|secret/i,
+      );
+    }
+  });
+
+  it('restores all default personalities without resetting progress', async () => {
+    const app = createApp({
+      provider: new ScriptedAgentProvider([
+        { requestedAction: { type: 'infect' }, summary: 'Infect.' },
+      ]),
+    });
+    const initial = simulationSnapshotSchema.parse(
+      await (await app.request('/api/simulation')).json(),
+    );
+    const agent = initial.world.agents[0]!;
+    await app.request(`/api/simulation/agents/${agent.id}/personality`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ personality: 'Custom.' }),
+    });
+    await app.request('/api/simulation/turn', { method: 'POST' });
+
+    const response = await app.request(
+      '/api/simulation/personalities/restore-defaults',
+      { method: 'POST' },
+    );
+    expect(response.status).toBe(200);
+    const restored = restoreDefaultPersonalitiesResponseSchema.parse(
+      await response.json(),
+    );
+    expect(restored.snapshot.turnNumber).toBe(1);
+    expect(restored.snapshot.world.events).toHaveLength(1);
+    expect(restored.snapshot.world.agents[0]!.personality).toBe(
+      agent.personality,
+    );
   });
 
   it('returns typed conflicts for an overlapping turn and reset', async () => {
@@ -194,6 +325,29 @@ describe('game API simulation boundary', () => {
     expect(
       (await app.request('/api/simulation/reset', { method: 'POST' })).status,
     ).toBe(409);
+    const agentId = simulationSnapshotSchema.parse(
+      await (await app.request('/api/simulation')).json(),
+    ).world.agents[0]!.id;
+    const editConflict = await app.request(
+      `/api/simulation/agents/${agentId}/personality`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ personality: 'Blocked.' }),
+      },
+    );
+    expect(editConflict.status).toBe(409);
+    await expect(editConflict.json()).resolves.toMatchObject({
+      error: { code: 'personality_conflict' },
+    });
+    const restoreConflict = await app.request(
+      '/api/simulation/personalities/restore-defaults',
+      { method: 'POST' },
+    );
+    expect(restoreConflict.status).toBe(409);
+    await expect(restoreConflict.json()).resolves.toMatchObject({
+      error: { code: 'personality_conflict' },
+    });
     release({
       decision: { requestedAction: { type: 'wait' }, summary: 'Done.' },
       metadata: {

apps/game-api/src/app.ts

@@ -8,15 +8,20 @@ import {
 } from '@agentborne/agent-runtime';
 import {
   apiErrorSchema,
+  PERSONALITY_MAX_LENGTH,
   resetSimulationResponseSchema,
+  restoreDefaultPersonalitiesResponseSchema,
   simulationSnapshotSchema,
   singleTurnResponseSchema,
+  updateAgentPersonalityRequestSchema,
+  updateAgentPersonalityResponseSchema,
   worldSnapshotSchema,
 } from '@agentborne/shared';
 import { createDevelopmentWorld } from '@agentborne/world-engine';
 import {
   SimulationConflictError,
   SimulationService,
+  SimulationValidationError,
 } from './simulation-service';
 
 export const healthResponseSchema = worldSnapshotSchema
@@ -115,6 +120,73 @@ export function createApp(options: AppOptions = {}) {
     }
   });
 
+  app.post('/api/simulation/agents/:agentId/personality', async (context) => {
+    const request = updateAgentPersonalityRequestSchema.safeParse(
+      await context.req.json().catch(() => undefined),
+    );
+    if (!request.success) {
+      return context.json(
+        apiErrorSchema.parse({
+          error: {
+            code: 'invalid_personality',
+            message: `Personality must contain 1 to ${PERSONALITY_MAX_LENGTH} characters.`,
+          },
+        }),
+        400,
+      );
+    }
+    try {
+      const agent = service.updateAgentPersonality(
+        context.req.param('agentId'),
+        request.data.personality,
+      );
+      return context.json(
+        updateAgentPersonalityResponseSchema.parse({
+          snapshot: service.getSnapshot(),
+          agent,
+        }),
+      );
+    } catch (error) {
+      if (error instanceof SimulationConflictError) {
+        return context.json(
+          apiErrorSchema.parse({
+            error: { code: 'personality_conflict', message: error.message },
+          }),
+          409,
+        );
+      }
+      if (error instanceof SimulationValidationError) {
+        return context.json(
+          apiErrorSchema.parse({
+            error: { code: error.code, message: error.message },
+          }),
+          error.code === 'unknown_agent' ? 404 : 400,
+        );
+      }
+      throw error;
+    }
+  });
+
+  app.post('/api/simulation/personalities/restore-defaults', (context) => {
+    try {
+      return context.json(
+        restoreDefaultPersonalitiesResponseSchema.parse({
+          snapshot: service.restoreDefaultPersonalities(),
+        }),
+      );
+    } catch (error) {
+      if (error instanceof SimulationConflictError) {
+        return context.json(
+          apiErrorSchema.parse({
+            error: { code: 'personality_conflict', message: error.message },
+          }),
+          409,
+        );
+      }
+      throw error;
+    }
+  });
+
   app.notFound((context) =>
     context.json(
       apiErrorSchema.parse({