@owlmeans/agent 0.1.18-rc.7

package/tests/agent.spec.ts

@@ -0,0 +1,218 @@
+import { describe, expect, test } from 'bun:test'
+import { tool } from '@langchain/core/tools'
+import * as z from 'zod'
+import { ExecutionLevel, PromptBlock } from '@owlmeans/llm-common'
+import { makePromptService } from '@owlmeans/llm'
+import type { Execution, PromptService } from '@owlmeans/llm'
+import { AgentRunStatus } from '@owlmeans/agent-common'
+import { makeAgentModel } from '../src/index.js'
+import type { AgentPlugin, AgentToolSet } from '../src/index.js'
+import { scriptedModel } from './_tools/model.js'
+
+let seq = 0
+const promptService = (): PromptService =>
+  makePromptService({}, `agent-spec-prompts-${++seq}`)
+
+const execution = (prompts?: () => PromptService): Execution => ({
+  level: ExecutionLevel.Helper,
+  purpose: { dedication: 'project:p1' },
+  policy: { effort: 'standard' as never },
+  prompt: { role: 'You are a test agent.' },
+  models: (() => { throw new Error('unused') }) as never,
+  ...(prompts != null ? { prompts } : {}),
+} as unknown as Execution)
+
+const echo = tool(
+  async ({ value }: { value: string }) => `echoed:${value}`,
+  { name: 'echo', description: 'Echoes its argument.', schema: z.object({ value: z.string() }) },
+) as unknown as AgentToolSet[string]
+
+describe('agent — the tool loop', () => {
+  test('answers without tools when the model asks for none', async () => {
+    const scripted = scriptedModel([{ content: 'done' }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+    })
+
+    const result = await agent.invoke('do the thing')
+
+    expect(result.message.content).toBe('done')
+    expect(scripted.turns()).toBe(1)
+  })
+
+  test('runs a requested tool and asks again with its result', async () => {
+    const scripted = scriptedModel([
+      { toolCalls: [{ name: 'echo', args: { value: 'hi' } }] },
+      { content: 'finished' },
+    ])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: { echo },
+    })
+
+    const result = await agent.invoke('use the tool')
+
+    expect(result.message.content).toBe('finished')
+    expect(scripted.turns()).toBe(2)
+    // The tool's answer has to reach the second ask, or the loop is a no-op with extra steps.
+    expect(JSON.stringify(scripted.asked()[1])).toContain('echoed:hi')
+  })
+
+  test('survives a tool that fails, feeding the error back to the model', async () => {
+    const explodes = tool(
+      async () => { throw new Error('nope') },
+      { name: 'explodes', description: 'Throws.', schema: z.object({}) },
+    ) as unknown as AgentToolSet[string]
+    const scripted = scriptedModel([
+      { toolCalls: [{ name: 'explodes', args: {} }] },
+      { content: 'recovered' },
+    ])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: { explodes },
+    })
+
+    const result = await agent.invoke('break it')
+
+    expect(result.message.content).toBe('recovered')
+    expect(JSON.stringify(scripted.asked()[1])).toContain('nope')
+  })
+
+  test('stops at the turn ceiling instead of looping on a model that never answers', async () => {
+    // A model that keeps calling tools forever is the ordinary failure of an unsatisfied loop.
+    // Without a ceiling it spends the caller's budget until something else kills it.
+    const scripted = scriptedModel([{ toolCalls: [{ name: 'echo', args: { value: 'again' } }] }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: { echo }, maxTurns: 3,
+    })
+
+    expect(agent.invoke('spin')).rejects.toThrow(/loop-exhausted/)
+  })
+})
+
+describe('agent — plugins', () => {
+  const collecting = (): { plugin: AgentPlugin, finished: unknown[] } => {
+    const finished: unknown[] = []
+    return {
+      finished,
+      plugin: {
+        alias: 'collector',
+        context: async () => ['REMEMBERED CONTEXT'],
+        onFinish: async (_run, _result, outcome) => { finished.push(outcome) },
+      },
+    }
+  }
+
+  test('contributes context into the prompt and fires on finish', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const { plugin, finished } = collecting()
+    const agent = makeAgentModel({
+      exec: execution(promptService), agentModel: scripted.model, tools: {}, plugins: [plugin],
+    })
+
+    await agent.invoke('go')
+
+    expect(JSON.stringify(scripted.asked()[0])).toContain('REMEMBERED CONTEXT')
+    expect(finished).toHaveLength(1)
+    expect((finished[0] as { status: string }).status).toBe(AgentRunStatus.Ok)
+  })
+
+  test('contributed context lands in the volatile block, never in the cached prefix', async () => {
+    // The Context block is the only one a provider will not put a cache breakpoint on. Volatile
+    // material anywhere above it invalidates the prefix every call that shares the persona pays for.
+    const prompts = promptService()
+    const composed = await prompts.compose(
+      { role: 'You are a test agent.', context: ['REMEMBERED CONTEXT'] },
+      [],
+      { model: scriptedModel([]).model },
+    )
+
+    const context = composed.blocks.find(block => block.block === PromptBlock.Context)
+    const role = composed.blocks.find(block => block.block === PromptBlock.Role)
+
+    expect(context?.text).toContain('REMEMBERED CONTEXT')
+    expect(role?.text).not.toContain('REMEMBERED CONTEXT')
+  })
+
+  test('a plugin that throws while contributing does not stop the run', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [{ alias: 'broken', context: async () => { throw new Error('no memory today') } }],
+    })
+
+    expect((await agent.invoke('go')).message.content).toBe('ok')
+  })
+
+  test('reports a failed run to its plugins before rethrowing', async () => {
+    // A run that vanishes from the history is one the next session repeats verbatim.
+    const scripted = scriptedModel([{ toolCalls: [{ name: 'echo', args: { value: 'x' } }] }])
+    const { plugin, finished } = collecting()
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: { echo }, maxTurns: 1,
+      plugins: [plugin],
+    })
+
+    expect(agent.invoke('spin')).rejects.toThrow()
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    expect((finished[0] as { status: string })?.status).toBe(AgentRunStatus.Failed)
+  })
+
+  test('seats a re-registered plugin in place rather than emitting it twice', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const agent = makeAgentModel({ exec: execution(promptService), agentModel: scripted.model, tools: {} })
+
+    agent.use({ alias: 'ctx', context: async () => ['ONCE'] })
+    agent.use({ alias: 'ctx', context: async () => ['ONCE'] })
+
+    await agent.invoke('go')
+
+    const asked = JSON.stringify(scripted.asked()[0])
+    expect(asked.split('ONCE').length - 1).toBe(1)
+  })
+})
+
+describe('agent — finalization', () => {
+  test('defers finalization when the caller owns the outcome', async () => {
+    // Free flight validates and repairs AFTER the model stops talking; a compaction written before
+    // that describes a state which did not survive it.
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const finished: unknown[] = []
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {}, autoFinish: false,
+      plugins: [{ alias: 'c', onFinish: async (_r, _res, outcome) => { finished.push(outcome) } }],
+    })
+
+    const result = await agent.invoke('go')
+    expect(finished).toHaveLength(0)
+
+    await result.run.finish({ status: AgentRunStatus.Ok, note: 'fixers clean' })
+    expect((finished[0] as { note: string }).note).toBe('fixers clean')
+  })
+
+  test('a second finish is a no-op, never a second event', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const finished: unknown[] = []
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {}, autoFinish: false,
+      plugins: [{ alias: 'c', onFinish: async () => { finished.push(1) } }],
+    })
+
+    const result = await agent.invoke('go')
+    await result.run.finish({ status: AgentRunStatus.Ok })
+    await result.run.finish({ status: AgentRunStatus.Ok })
+
+    expect(finished).toHaveLength(1)
+  })
+
+  test('a failing plugin does not fail the run it is finalizing', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {}, autoFinish: false,
+      plugins: [{ alias: 'c', onFinish: async () => { throw new Error('store is down') } }],
+    })
+
+    const result = await agent.invoke('go')
+
+    expect(result.run.finish({ status: AgentRunStatus.Ok })).resolves.toBeUndefined()
+  })
+})

package/tests/plugins.spec.ts

@@ -0,0 +1,257 @@
+import { describe, expect, test } from 'bun:test'
+import { ExecutionLevel } from '@owlmeans/llm-common'
+import type { Execution, LlmModel, PromptService } from '@owlmeans/llm'
+import { makePromptService } from '@owlmeans/llm'
+import { AgentRunStatus } from '@owlmeans/agent-common'
+import {
+  createMemoryConversationStore, createMemoryEventStore, createMemoryGraphStore, makeAgentModel,
+  memoryEvents, memoryEventsPlugin, memoryGraph, memoryGraphPlugin, summarizePlugin,
+} from '../src/index.js'
+import { scriptedModel } from './_tools/model.js'
+
+let seq = 0
+const execution = (): Execution => ({
+  level: ExecutionLevel.Helper,
+  purpose: { dedication: 'project:p1' },
+  policy: { effort: 'standard' as never },
+  prompt: { role: 'You are a test agent.' },
+  models: (() => { throw new Error('unused') }) as never,
+  prompts: () => makePromptService({}, `plugins-spec-${++seq}`) as PromptService,
+} as unknown as Execution)
+
+const answering = (answer: unknown): LlmModel =>
+  ({ invoke: async () => answer, ask: async () => answer as string } as unknown as LlmModel)
+
+describe('agent — the summarize plugin', () => {
+  test('stores a two-part compaction when a run finishes', async () => {
+    const store = createMemoryConversationStore()
+    const scripted = scriptedModel([{ content: 'renamed it' }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [summarizePlugin({
+        store, model: () => answering({ summary: 'renamed the header', advice: 'run the build' }),
+      })],
+    })
+
+    await agent.invoke('rename the header')
+
+    const [event] = await store.last({ conversationId: 'project:p1', scope: 'p1' }, 5)
+    expect(event).toMatchObject({
+      summary: 'renamed the header', advice: 'run the build', status: AgentRunStatus.Ok,
+      prompt: 'rename the header',
+    })
+  })
+
+  test('puts the last sessions and the newest advice back into the next run', async () => {
+    const store = createMemoryConversationStore()
+    for (const [summary, advice] of [['did A', 'then B'], ['did B', 'then C']]) {
+      await store.append({
+        conversationId: 'project:p1', scope: 'p1', summary, advice, status: AgentRunStatus.Ok,
+      })
+    }
+
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [summarizePlugin({ store, model: () => answering({ summary: 's', advice: 'a' }) })],
+    })
+
+    await agent.invoke('carry on')
+
+    const asked = JSON.stringify(scripted.asked()[0])
+    expect(asked).toContain('did A')
+    expect(asked).toContain('did B')
+    // Only the NEWEST advice: two conflicting "do this next" instructions is worse than none.
+    expect(asked).toContain('then C')
+    expect(asked.split('then B').length - 1).toBe(0)
+  })
+
+  test('honours the window rather than replaying the whole conversation', async () => {
+    const store = createMemoryConversationStore()
+    for (const summary of ['one', 'two', 'three', 'four']) {
+      await store.append({
+        conversationId: 'project:p1', scope: 'p1', summary, status: AgentRunStatus.Ok,
+      })
+    }
+
+    const scripted = scriptedModel([{ content: 'ok' }])
+    await makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [summarizePlugin({ store, window: 2, model: () => answering({ summary: 's', advice: '' }) })],
+    }).invoke('go')
+
+    const asked = JSON.stringify(scripted.asked()[0])
+    expect(asked).toContain('four')
+    expect(asked).toContain('three')
+    expect(asked).not.toContain('"one"')
+  })
+
+  test('contributes nothing on the very first run', async () => {
+    const scripted = scriptedModel([{ content: 'ok' }])
+    await makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [summarizePlugin({ store: createMemoryConversationStore() })],
+    }).invoke('go')
+
+    expect(JSON.stringify(scripted.asked()[0])).not.toContain('Earlier in this conversation')
+  })
+
+  test('is a no-op with no store bound', async () => {
+    // An application that has not wired persistence still runs agents; it just has no memory.
+    const scripted = scriptedModel([{ content: 'ok' }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {}, plugins: [summarizePlugin({})],
+    })
+
+    expect((await agent.invoke('go')).message.content).toBe('ok')
+  })
+
+  test('records a failed run so the next session does not repeat it verbatim', async () => {
+    const store = createMemoryConversationStore()
+    const scripted = scriptedModel([{ toolCalls: [{ name: 'missing', args: {} }] }])
+    const agent = makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {}, maxTurns: 1,
+      plugins: [summarizePlugin({ store })],
+    })
+
+    expect(agent.invoke('do the impossible')).rejects.toThrow()
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    const [event] = await store.last({ conversationId: 'project:p1', scope: 'p1' }, 5)
+    expect(event?.status).toBe(AgentRunStatus.Failed)
+  })
+})
+
+describe('agent — the subsystem memory graph', () => {
+  test('merges into a node instead of replacing it', async () => {
+    // Replacing would make every write a potential act of forgetting.
+    const graph = memoryGraph(createMemoryGraphStore())
+    await graph.write('p1', 'auth', 'uses OIDC')
+    await graph.write('p1', 'auth', 'tokens live 1h')
+
+    const [node] = await graph.read('p1', 'auth')
+    expect(node.content).toContain('uses OIDC')
+    expect(node.content).toContain('tokens live 1h')
+  })
+
+  test('compacts a node that outgrows its budget', async () => {
+    const graph = memoryGraph(createMemoryGraphStore(), {
+      maxNodeChars: 60,
+      model: () => answering('the folded account'),
+      run: {} as never,
+    })
+    await graph.write('p1', 'auth', 'A'.repeat(50))
+    await graph.write('p1', 'auth', 'B'.repeat(50))
+
+    const [node] = await graph.read('p1', 'auth')
+    expect(node.content.length).toBeLessThanOrEqual(60)
+    expect(node.content).toBe('the folded account')
+  })
+
+  test('accumulates links and never links a node to itself', async () => {
+    const graph = memoryGraph(createMemoryGraphStore())
+    await graph.write('p1', 'auth', 'x', ['db'])
+    await graph.write('p1', 'auth', 'y', ['api', 'auth'])
+
+    const [node] = await graph.read('p1', 'auth')
+    expect(node.links.sort()).toEqual(['api', 'db'])
+  })
+
+  test('follows links to the requested depth and no further', async () => {
+    const graph = memoryGraph(createMemoryGraphStore())
+    await graph.write('p1', 'auth', 'a', ['db'])
+    await graph.write('p1', 'db', 'b', ['storage'])
+    await graph.write('p1', 'storage', 'c')
+
+    expect((await graph.read('p1', 'auth', 0)).map(node => node.subsystem)).toEqual(['auth'])
+    expect((await graph.read('p1', 'auth', 1)).map(node => node.subsystem)).toEqual(['auth', 'db'])
+    expect((await graph.read('p1', 'auth', 2)).map(node => node.subsystem))
+      .toEqual(['auth', 'db', 'storage'])
+  })
+
+  test('survives a cycle in the graph', async () => {
+    const graph = memoryGraph(createMemoryGraphStore())
+    await graph.write('p1', 'a', 'x', ['b'])
+    await graph.write('p1', 'b', 'y', ['a'])
+
+    expect((await graph.read('p1', 'a', 5)).map(node => node.subsystem)).toEqual(['a', 'b'])
+  })
+
+  test('injects the index but never the content of a node', async () => {
+    // Bulk-injecting notes spends the context window on knowledge the run cannot tell apart from
+    // what it needs; the agent pulls what it wants by name.
+    const store = createMemoryGraphStore()
+    await memoryGraph(store).write('p1', 'auth', 'a long private note', ['db'])
+
+    const scripted = scriptedModel([{ content: 'ok' }])
+    await makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [memoryGraphPlugin({ store })],
+    }).invoke('go')
+
+    const asked = JSON.stringify(scripted.asked()[0])
+    expect(asked).toContain('auth')
+    expect(asked).not.toContain('a long private note')
+  })
+
+  test('offers its tools to the agent', async () => {
+    const store = createMemoryGraphStore()
+    const scripted = scriptedModel([
+      { toolCalls: [{ name: 'memory_write', args: { subsystem: 'auth', content: 'noted' } }] },
+      { content: 'done' },
+    ])
+
+    await makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [memoryGraphPlugin({ store })],
+    }).invoke('remember something')
+
+    expect((await store.read('p1', 'auth'))?.content).toBe('noted')
+  })
+})
+
+describe('agent — the event sequence memory', () => {
+  test('keeps only the most recent entries', async () => {
+    const events = memoryEvents(createMemoryEventStore(), { limit: 2 })
+    for (const content of ['a', 'b', 'c']) {
+      await events.append('p1', 'note', content)
+    }
+
+    expect((await events.read('p1', 10)).map(event => event.content)).toEqual(['c', 'b'])
+  })
+
+  test('caps a single entry — an event is a line, not a document', async () => {
+    const events = memoryEvents(createMemoryEventStore(), { maxEventChars: 20 })
+    await events.append('p1', 'note', 'x'.repeat(500))
+
+    expect((await events.read('p1', 1))[0].content.length).toBeLessThanOrEqual(20)
+  })
+
+  test('injects the recent window into a run', async () => {
+    const store = createMemoryEventStore()
+    await memoryEvents(store).append('p1', 'deploy', 'shipped version 3')
+
+    const scripted = scriptedModel([{ content: 'ok' }])
+    await makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [memoryEventsPlugin({ store })],
+    }).invoke('go')
+
+    expect(JSON.stringify(scripted.asked()[0])).toContain('shipped version 3')
+  })
+
+  test('lets an agent append through its tool', async () => {
+    const store = createMemoryEventStore()
+    const scripted = scriptedModel([
+      { toolCalls: [{ name: 'event_append', args: { kind: 'fix', content: 'patched the header' } }] },
+      { content: 'done' },
+    ])
+
+    await makeAgentModel({
+      exec: execution(), agentModel: scripted.model, tools: {},
+      plugins: [memoryEventsPlugin({ store })],
+    }).invoke('fix it')
+
+    expect((await store.read('p1', 5))[0].content).toBe('patched the header')
+  })
+})

package/tests/runtime.spec.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from 'bun:test'
+import { makeFlowModel } from '@owlmeans/flow'
+import { ExecutionLevel } from '@owlmeans/llm-common'
+import type { ExecutionState } from '@owlmeans/llm-common'
+import type { Execution } from '@owlmeans/llm'
+import { AGENT_RUN_FLOW, AgentRunStep, AgentRunTransition, agentRunFlow } from '@owlmeans/agent-common'
+import {
+  createMemoryConversationStore, createMemoryEventStore, createMemoryGraphStore,
+  createMemoryRunStateStore, inProcessTransport, makeAgentExecutionPlugin, makeStaticFlowProvider,
+} from '../src/index.js'
+
+const state = (extra: Record<string, unknown> = {}): ExecutionState => ({
+  level: ExecutionLevel.Project,
+  purpose: { dedication: 'project:p1' },
+  policy: { effort: 'standard' as never },
+  ...extra,
+} as ExecutionState)
+
+const exec = (): Execution => ({ ...state(), models: (() => {}) as never } as unknown as Execution)
+
+describe('agent — the static flow provider', () => {
+  test('serves a declared flow and restores a serialized run', async () => {
+    const provider = makeStaticFlowProvider([agentRunFlow])
+    const model = await makeFlowModel(agentRunFlow)
+    model.transit(AgentRunTransition.Prepare, true)
+    const token = model.transit(AgentRunTransition.Work, true)
+
+    expect((await provider(AGENT_RUN_FLOW)).flow).toBe(AGENT_RUN_FLOW)
+    expect((await makeFlowModel(token, provider)).step().step).toBe(AgentRunStep.Working)
+  })
+
+  test('throws on an unknown flow, which is what makes token recovery work', async () => {
+    // `makeFlowModel` reads a string as a flow NAME first and only re-reads it as a serialized
+    // token once the provider throws. Returning null here would break every restore.
+    expect(makeStaticFlowProvider([])('nothing-declared')).rejects.toThrow()
+  })
+})
+
+describe('agent — the execution checkpoint plugin', () => {
+  test('persists a checkpointed state and restores it by key', async () => {
+    const store = createMemoryRunStateStore()
+    const plugin = makeAgentExecutionPlugin({ store })
+
+    await plugin.onCheckpoint!(state({ phase: 'develop' }), exec(), 'run-1')
+
+    expect(await plugin.onRestore!('run-1')).toMatchObject({ phase: 'develop' })
+  })
+
+  test('recovers the conversation from the execution dedication', async () => {
+    const store = createMemoryRunStateStore()
+    await makeAgentExecutionPlugin({ store }).onCheckpoint!(state(), exec(), 'run-2')
+
+    expect((await store.load('run-2'))?.conversationId).toBe('project:p1')
+  })
+
+  test('refuses a state too large to belong in a checkpoint', async () => {
+    // A project execution carries the whole specification. Writing that on every checkpoint is a
+    // storage problem that surfaces much later and much worse than a skipped write.
+    const store = createMemoryRunStateStore()
+    const plugin = makeAgentExecutionPlugin({ store, maxStateChars: 200 })
+
+    await plugin.onCheckpoint!(state({ project: { specification: 'x'.repeat(5_000) } }), exec(), 'run-3')
+
+    expect(await store.load('run-3')).toBeNull()
+  })
+
+  test('returns null for a key that was never checkpointed', async () => {
+    const plugin = makeAgentExecutionPlugin({ store: createMemoryRunStateStore() })
+
+    expect(await plugin.onRestore!('never-seen')).toBeNull()
+  })
+
+  test('announces a saved checkpoint on the transport by reference', async () => {
+    // The message carries a reference, not the state: a queue whose messages hold a whole project
+    // specification falls over on the first large project.
+    const transport = inProcessTransport()
+    const seen: unknown[] = []
+    await transport.consume(async message => { seen.push(message) })
+
+    await makeAgentExecutionPlugin({ store: createMemoryRunStateStore(), transport })
+      .onCheckpoint!(state(), exec(), 'run-4')
+
+    expect(seen).toEqual([{ id: 'run-4', conversationId: 'project:p1', flow: '', stateRef: 'run-4' }])
+  })
+})
+
+describe('agent — in-memory stores', () => {
+  test('a conversation allocates monotonic sequence numbers per thread', async () => {
+    const store = createMemoryConversationStore()
+    const base = { scope: 'p1', summary: 's', status: 'ok' as never }
+
+    await store.append({ ...base, conversationId: 'a' })
+    await store.append({ ...base, conversationId: 'b' })
+    const third = await store.append({ ...base, conversationId: 'a' })
+
+    expect(third.seq).toBe(2)
+    expect((await store.last({ conversationId: 'b', scope: 'p1' }, 10))).toHaveLength(1)
+  })
+
+  test('a conversation reads back newest first', async () => {
+    const store = createMemoryConversationStore()
+    const ref = { conversationId: 'a', scope: 'p1' }
+    for (const summary of ['first', 'second', 'third']) {
+      await store.append({ conversationId: 'a', scope: 'p1', summary, status: 'ok' as never })
+    }
+
+    expect((await store.last(ref, 2)).map(event => event.summary)).toEqual(['third', 'second'])
+  })
+
+  test('a memory graph node is replaced in place rather than appended', async () => {
+    const store = createMemoryGraphStore()
+    await store.write({ scope: 'p1', subsystem: 'auth', content: 'old', links: [] })
+    await store.write({ scope: 'p1', subsystem: 'auth', content: 'new', links: ['db'] })
+
+    expect(await store.index('p1')).toHaveLength(1)
+    expect((await store.read('p1', 'auth'))?.content).toBe('new')
+  })
+
+  test('the graph index carries names and links but not content', async () => {
+    const store = createMemoryGraphStore()
+    await store.write({ scope: 'p1', subsystem: 'auth', content: 'secret detail', links: ['db'] })
+
+    const index = await store.index('p1')
+
+    expect(index[0]).toEqual({ subsystem: 'auth', links: ['db'], updatedAt: expect.any(String) })
+    expect(JSON.stringify(index)).not.toContain('secret detail')
+  })
+
+  test('event memory prunes its own scope only', async () => {
+    // A shared cap would let a chatty subject evict a quiet one's whole history.
+    const store = createMemoryEventStore()
+    await store.append({ scope: 'quiet', kind: 'note', content: 'keep me' }, 2)
+    for (const content of ['a', 'b', 'c', 'd']) {
+      await store.append({ scope: 'busy', kind: 'note', content }, 2)
+    }
+
+    expect((await store.read('busy', 10)).map(event => event.content)).toEqual(['d', 'c'])
+    expect(await store.read('quiet', 10)).toHaveLength(1)
+  })
+})