@xandout/libra-harness 0.1.8

package/dist/extras/extensions/mcp/extension.test.js

@@ -0,0 +1,286 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, utimesSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { Agent } from '../../../agent.js';
+import { createMcpExtension } from './index.js';
+// ── Test MCP server ────────────────────────────────────────────────
+// Path to the minimal stdio MCP server script.
+const SERVER_SCRIPT = new URL('./test-server.mjs', import.meta.url).pathname;
+// ── Mock model ─────────────────────────────────────────────────────
+// Returns a fixed assistant message.
+function mockModel() {
+    return {
+        async generate() {
+            return {
+                message: { role: 'assistant', content: 'ok' },
+                finishReason: 'stop',
+            };
+        },
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────
+function makeConfig(path, servers) {
+    writeFileSync(path, JSON.stringify({ mcpServers: servers }, null, 2));
+}
+function stdioServer(command, args = []) {
+    return { type: 'stdio', command, args };
+}
+// ── Test setup ─────────────────────────────────────────────────────
+let tmpDir;
+let configPath;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'mcp-test-'));
+    configPath = join(tmpDir, 'mcpServers.json');
+});
+afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+// ── Tests ──────────────────────────────────────────────────────────
+describe('mcp extension', () => {
+    it('returns undefined when no mcpConfigPaths provided', async () => {
+        const ext = await createMcpExtension({});
+        expect(ext).toBeUndefined();
+    });
+    it('returns undefined when no servers in config', async () => {
+        makeConfig(configPath, {});
+        const ext = await createMcpExtension({ mcpConfigPaths: configPath });
+        expect(ext).toBeUndefined();
+    });
+    it('connects to a stdio server and discovers tools', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = await createMcpExtension({ mcpConfigPaths: configPath });
+        expect(ext).toBeDefined();
+        const agent = new Agent({ model: mockModel() });
+        agent.use(ext);
+        // MCP tools should NOT be registered on the agent at install time.
+        // They are injected per-turn via the beforeTurn hook.
+        const agentTools = agent.getTools();
+        expect(agentTools).not.toContain('test__echo');
+        expect(agentTools).not.toContain('test__ping');
+        // Meta-tools SHOULD be registered at install time.
+        expect(agentTools).toContain('list_resources');
+        expect(agentTools).toContain('read_resource');
+        expect(agentTools).toContain('list_prompts');
+        expect(agentTools).toContain('use_prompt');
+    });
+    it('injects MCP tools into turn.tools via beforeTurn hook', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = (await createMcpExtension({ mcpConfigPaths: configPath }));
+        const agent = new Agent({ model: mockModel() });
+        agent.use(ext);
+        // Run a turn and check that the model sees MCP tools.
+        let seenToolNames = [];
+        const model = {
+            async generate(req) {
+                seenToolNames = (req.tools ?? []).map((t) => t.function?.name ?? t.name);
+                return {
+                    message: { role: 'assistant', content: 'ok' },
+                    finishReason: 'stop',
+                };
+            },
+        };
+        const agent2 = new Agent({ model: model });
+        agent2.use(ext);
+        await agent2.run({ message: 'hi' });
+        expect(seenToolNames).toContain('test__echo');
+        expect(seenToolNames).toContain('test__ping');
+        // Meta-tools should also be visible.
+        expect(seenToolNames).toContain('list_resources');
+    });
+    it('can call an MCP tool through the agent', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = (await createMcpExtension({ mcpConfigPaths: configPath }));
+        let callCount = 0;
+        let toolResult = '';
+        const model = {
+            async generate(req) {
+                callCount++;
+                if (callCount === 1) {
+                    return {
+                        message: {
+                            role: 'assistant',
+                            content: '',
+                            toolCalls: [{
+                                    id: 'call_1',
+                                    name: 'test__echo',
+                                    arguments: JSON.stringify({ text: 'hello mcp' }),
+                                }],
+                        },
+                        finishReason: 'tool_calls',
+                    };
+                }
+                const toolMsg = req.messages.find((m) => m.role === 'tool');
+                toolResult = toolMsg?.content ?? '';
+                return {
+                    message: { role: 'assistant', content: 'done' },
+                    finishReason: 'stop',
+                };
+            },
+        };
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        const result = await agent.run({ message: 'echo hello mcp' });
+        expect(result.finishReason).toBe('stop');
+        expect(result.toolCalls?.some((tc) => tc.name === 'test__echo')).toBe(true);
+        expect(toolResult).toBe('hello mcp');
+    });
+    it('reloads when config file changes at runtime', async () => {
+        // Start with one server.
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = (await createMcpExtension({ mcpConfigPaths: configPath }));
+        let seenToolNames = [];
+        const model = {
+            async generate(req) {
+                seenToolNames = (req.tools ?? []).map((t) => t.function?.name ?? t.name);
+                return {
+                    message: { role: 'assistant', content: 'ok' },
+                    finishReason: 'stop',
+                };
+            },
+        };
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        // First turn: should see test__echo and test__ping.
+        await agent.run({ message: 'turn 1' });
+        expect(seenToolNames).toContain('test__echo');
+        expect(seenToolNames).toContain('test__ping');
+        // Modify the config to add a second server (same script, different name).
+        // We need to ensure the mtime changes — writeFileSync may not always
+        // update mtime on fast systems, so we force it with utimesSync.
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+            'test2': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        // Force mtime change (set to 1 second in the future).
+        const future = new Date(Date.now() / 1000 + 1);
+        utimesSync(configPath, future, future);
+        // Second turn: should see tools from both servers.
+        await agent.run({ message: 'turn 2' });
+        expect(seenToolNames).toContain('test__echo');
+        expect(seenToolNames).toContain('test2__echo');
+        expect(seenToolNames).toContain('test2__ping');
+    });
+    it('respects excludeTools pattern', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = (await createMcpExtension({
+            mcpConfigPaths: configPath,
+            excludeTools: ['test__ping'],
+        }));
+        let seenToolNames = [];
+        const model = {
+            async generate(req) {
+                seenToolNames = (req.tools ?? []).map((t) => t.function?.name ?? t.name);
+                return {
+                    message: { role: 'assistant', content: 'ok' },
+                    finishReason: 'stop',
+                };
+            },
+        };
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        await agent.run({ message: 'hi' });
+        expect(seenToolNames).toContain('test__echo');
+        expect(seenToolNames).not.toContain('test__ping');
+    });
+    it('meta-tools read from live state after reload', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = (await createMcpExtension({ mcpConfigPaths: configPath }));
+        let callCount = 0;
+        let resourceList = '';
+        const model = {
+            async generate(req) {
+                callCount++;
+                if (callCount === 1) {
+                    return {
+                        message: {
+                            role: 'assistant',
+                            content: '',
+                            toolCalls: [{
+                                    id: 'call_1',
+                                    name: 'list_resources',
+                                    arguments: '{}',
+                                }],
+                        },
+                        finishReason: 'tool_calls',
+                    };
+                }
+                const toolMsg = req.messages.find((m) => m.role === 'tool');
+                resourceList = toolMsg?.content ?? '';
+                return {
+                    message: { role: 'assistant', content: 'done' },
+                    finishReason: 'stop',
+                };
+            },
+        };
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        await agent.run({ message: 'list resources' });
+        expect(resourceList).toContain('test://greeting');
+    });
+    it('can read an MCP resource via read_resource tool', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = (await createMcpExtension({ mcpConfigPaths: configPath }));
+        let callCount = 0;
+        let resourceContent = '';
+        const model = {
+            async generate(req) {
+                callCount++;
+                if (callCount === 1) {
+                    return {
+                        message: {
+                            role: 'assistant',
+                            content: '',
+                            toolCalls: [{
+                                    id: 'call_1',
+                                    name: 'read_resource',
+                                    arguments: JSON.stringify({ uri: 'test://greeting' }),
+                                }],
+                        },
+                        finishReason: 'tool_calls',
+                    };
+                }
+                const toolMsg = req.messages.find((m) => m.role === 'tool');
+                resourceContent = toolMsg?.content ?? '';
+                return {
+                    message: { role: 'assistant', content: 'done' },
+                    finishReason: 'stop',
+                };
+            },
+        };
+        const agent = new Agent({ model: model });
+        agent.use(ext);
+        await agent.run({ message: 'read the greeting resource' });
+        expect(resourceContent).toContain('Hello from MCP');
+    });
+    it('close() cleans up client connections', async () => {
+        makeConfig(configPath, {
+            'test': stdioServer('node', [SERVER_SCRIPT]),
+        });
+        const ext = await createMcpExtension({ mcpConfigPaths: configPath });
+        if (!ext)
+            throw new Error('extension was undefined');
+        const agent = new Agent({ model: mockModel() });
+        agent.use(ext);
+        // Should not throw.
+        await ext.close();
+        // Unload should also work (calls close internally).
+        // We can't easily test that the subprocess is killed, but we can
+        // verify close() doesn't throw.
+    });
+});
+//# sourceMappingURL=extension.test.js.map

package/dist/extras/extensions/mcp/extension.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.test.js","sourceRoot":"","sources":["../../../../src/extras/extensions/mcp/extension.test.ts"],"names":[],"mappings":"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"}

package/dist/extras/extensions/mcp/index.d.ts

@@ -0,0 +1,3 @@
+export { default as createMcpExtension } from './extension.js';
+export type { McpExtensionConfig } from './extension.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extras/extensions/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/extras/extensions/mcp/index.js

@@ -0,0 +1,2 @@
+export { default as createMcpExtension } from './extension.js';
+//# sourceMappingURL=index.js.map

package/dist/extras/extensions/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/extras/extensions/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/extras/extensions/mem-session/extension.d.ts

@@ -0,0 +1,24 @@
+import type { Extension } from '../../../extension.js';
+import type { Message } from '../../../types.js';
+/**
+ * A simple in-memory session extension.
+ *
+ * Stores conversation history per session ID in a Map. On each turn:
+ * - `beforeTurn`: loads prior messages and prepends them to the turn context
+ * - `afterTurn`: saves the full conversation (including this turn) back
+ *
+ * Low priority so it loads after mutators (emoji, timestamp) — this means
+ * `afterTurn` saves the final decorated response, and `beforeTurn` prepends
+ * history after other extensions have processed the raw input.
+ *
+ * The returned extension has extra methods (`getMessages`, `clear`,
+ * `clearAll`) on the object for host-side inspection. These are not part
+ * of the `Extension` interface — the host can access them by finding the
+ * extension in the loaded array and casting.
+ */
+export default function createMemSessionExtension(): Extension & {
+    getMessages(sessionId?: string): Message[];
+    clear(sessionId?: string): void;
+    clearAll(): void;
+};
+//# sourceMappingURL=extension.d.ts.map

package/dist/extras/extensions/mem-session/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/mem-session/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,yBAAyB,IAAI,SAAS,GAAG;IAC/D,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;IAC3C,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,IAAI,IAAI,CAAC;CAClB,CAiCA"}

package/dist/extras/extensions/mem-session/extension.js

@@ -0,0 +1,49 @@
+/**
+ * A simple in-memory session extension.
+ *
+ * Stores conversation history per session ID in a Map. On each turn:
+ * - `beforeTurn`: loads prior messages and prepends them to the turn context
+ * - `afterTurn`: saves the full conversation (including this turn) back
+ *
+ * Low priority so it loads after mutators (emoji, timestamp) — this means
+ * `afterTurn` saves the final decorated response, and `beforeTurn` prepends
+ * history after other extensions have processed the raw input.
+ *
+ * The returned extension has extra methods (`getMessages`, `clear`,
+ * `clearAll`) on the object for host-side inspection. These are not part
+ * of the `Extension` interface — the host can access them by finding the
+ * extension in the loaded array and casting.
+ */
+export default function createMemSessionExtension() {
+    const store = new Map();
+    return {
+        name: 'mem-session',
+        priority: -100,
+        install(agent) {
+            agent.hook('beforeTurn', 'mem-session', async (ctx) => {
+                const sessionId = ctx.turn.request.metadata?.sessionId ?? 'default';
+                const history = store.get(sessionId);
+                if (history && history.length > 0) {
+                    ctx.turn.messages = [...history, ...ctx.turn.messages];
+                }
+            });
+            agent.hook('afterTurn', 'mem-session', async (ctx) => {
+                const sessionId = ctx.turn.request.metadata?.sessionId ?? 'default';
+                store.set(sessionId, [...ctx.turn.messages]);
+            });
+        },
+        /** Get the messages for a session. */
+        getMessages(sessionId = 'default') {
+            return store.get(sessionId) ?? [];
+        },
+        /** Clear a single session. */
+        clear(sessionId = 'default') {
+            store.delete(sessionId);
+        },
+        /** Clear all sessions. */
+        clearAll() {
+            store.clear();
+        },
+    };
+}
+//# sourceMappingURL=extension.js.map

package/dist/extras/extensions/mem-session/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../../../../src/extras/extensions/mem-session/extension.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,UAAU,yBAAyB;IAK/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,QAAQ,EAAE,CAAC,GAAG;QACd,OAAO,CAAC,KAAK;YACX,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBACpD,MAAM,SAAS,GAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAoB,IAAI,SAAS,CAAC;gBAChF,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACrC,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAClC,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACzD,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBACnD,MAAM,SAAS,GAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAoB,IAAI,SAAS,CAAC;gBAChF,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC/C,CAAC,CAAC,CAAC;QACL,CAAC;QACD,sCAAsC;QACtC,WAAW,CAAC,SAAS,GAAW,SAAS;YACvC,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACpC,CAAC;QACD,8BAA8B;QAC9B,KAAK,CAAC,SAAS,GAAW,SAAS;YACjC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;QACD,0BAA0B;QAC1B,QAAQ;YACN,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/extras/extensions/mem-session/extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "mem-session",
+  "description": "In-memory session extension. Stores conversation history per session ID. Low priority so afterTurn saves the final response after mutators have decorated it.",
+  "enabled": true,
+  "priority": -100
+}

package/dist/extras/extensions/mem-session/index.d.ts

@@ -0,0 +1,2 @@
+export { default as createMemSessionExtension } from './extension.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extras/extensions/mem-session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/mem-session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/extras/extensions/mem-session/index.js

@@ -0,0 +1,2 @@
+export { default as createMemSessionExtension } from './extension.js';
+//# sourceMappingURL=index.js.map

package/dist/extras/extensions/mem-session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/extras/extensions/mem-session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/extras/extensions/memory/extension.d.ts

@@ -0,0 +1,54 @@
+import type { Extension } from '../../../extension.js';
+import type { MemoryExtensionConfig } from './types.js';
+/**
+ * Memory extension — persistent, session-scoped knowledge across turns.
+ *
+ * The agent does not manage memory explicitly. Memories are:
+ * - **Retrieved** automatically in `beforeContext` and injected as a
+ *   system message before the LLM loop.
+ * - **Extracted** automatically in `afterTurn` and persisted to the store.
+ *
+ * Both paths are non-fatal: retrieval or extraction failures are logged
+ * and the turn proceeds normally. Memory is convenience infrastructure,
+ * not a correctness requirement.
+ *
+ * ## Hook footprint
+ *
+ * Only two hooks:
+ * - `beforeContext` — retrieve and inject memories
+ * - `afterTurn` — extract and persist memories
+ *
+ * This avoids conflicts with session extensions (which use `beforeTurn`)
+ * and observability extensions (which use `afterLLM`/`afterTurn`).
+ *
+ * ## Ordering
+ *
+ * Priority defaults to -95 (between session at -100 and mutators at 0).
+ * In `beforeContext`, the memory system message is unshifted to index 0,
+ * ahead of session history loaded in `beforeTurn`:
+ *
+ * ```
+ * [memory system msg] [session history...] [user message]
+ * ```
+ *
+ * In `afterTurn`, memory reads the final `turn.messages` and
+ * `turn.response` — both are set by the core before `afterTurn` fires.
+ *
+ * @example
+ * ```typescript
+ * const store = new MyVectorStore();
+ * const extractor = createLlmExtractor(model);
+ * const memoryExt = createMemoryExtension({ store, extractor });
+ *
+ * const agent = new Agent({ model });
+ * agent.use(memoryExt);
+ *
+ * await agent.run({
+ *   message: "My name is Kristi",
+ *   metadata: { sessionId: 'slack_C123' },
+ * });
+ * // Next turn in the same session: the agent remembers "Kristi".
+ * ```
+ */
+export default function createMemoryExtension(config: MemoryExtensionConfig): Extension;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extras/extensions/memory/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../../src/extras/extensions/memory/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EACV,qBAAqB,EAItB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,OAAO,UAAU,qBAAqB,CAC3C,MAAM,EAAE,qBAAqB,GAC5B,SAAS,CAsGX"}

package/dist/extras/extensions/memory/extension.js

@@ -0,0 +1,143 @@
+import { messageContentToText } from '../../../types.js';
+/**
+ * Memory extension — persistent, session-scoped knowledge across turns.
+ *
+ * The agent does not manage memory explicitly. Memories are:
+ * - **Retrieved** automatically in `beforeContext` and injected as a
+ *   system message before the LLM loop.
+ * - **Extracted** automatically in `afterTurn` and persisted to the store.
+ *
+ * Both paths are non-fatal: retrieval or extraction failures are logged
+ * and the turn proceeds normally. Memory is convenience infrastructure,
+ * not a correctness requirement.
+ *
+ * ## Hook footprint
+ *
+ * Only two hooks:
+ * - `beforeContext` — retrieve and inject memories
+ * - `afterTurn` — extract and persist memories
+ *
+ * This avoids conflicts with session extensions (which use `beforeTurn`)
+ * and observability extensions (which use `afterLLM`/`afterTurn`).
+ *
+ * ## Ordering
+ *
+ * Priority defaults to -95 (between session at -100 and mutators at 0).
+ * In `beforeContext`, the memory system message is unshifted to index 0,
+ * ahead of session history loaded in `beforeTurn`:
+ *
+ * ```
+ * [memory system msg] [session history...] [user message]
+ * ```
+ *
+ * In `afterTurn`, memory reads the final `turn.messages` and
+ * `turn.response` — both are set by the core before `afterTurn` fires.
+ *
+ * @example
+ * ```typescript
+ * const store = new MyVectorStore();
+ * const extractor = createLlmExtractor(model);
+ * const memoryExt = createMemoryExtension({ store, extractor });
+ *
+ * const agent = new Agent({ model });
+ * agent.use(memoryExt);
+ *
+ * await agent.run({
+ *   message: "My name is Kristi",
+ *   metadata: { sessionId: 'slack_C123' },
+ * });
+ * // Next turn in the same session: the agent remembers "Kristi".
+ * ```
+ */
+export default function createMemoryExtension(config) {
+    const { store, extractor, maxRecall = 10, scopeKey = 'sessionId', priority = -95, } = config;
+    // Default retriever: pass-through to store.search.
+    const retriever = config.retriever ?? {
+        async retrieve({ scope, text }) {
+            return store.search({ scope, text, maxResults: maxRecall });
+        },
+    };
+    return {
+        name: 'memory',
+        priority,
+        install(agent) {
+            // ── beforeContext: retrieve and inject ────────────────────
+            agent.hook('beforeContext', 'memory', async (ctx) => {
+                const scope = ctx.turn.request.metadata?.[scopeKey] ?? 'default';
+                const text = messageContentToText(ctx.turn.request.message);
+                let memories;
+                try {
+                    memories = await retriever.retrieve({ scope, text, store });
+                }
+                catch (err) {
+                    console.error('[memory] retrieval failed:', err);
+                    return; // proceed without memories
+                }
+                if (memories.length === 0)
+                    return;
+                const memoryText = memories
+                    .map((m, i) => `${i + 1}. ${m.content}`)
+                    .join('\n');
+                ctx.turn.messages.unshift({
+                    role: 'system',
+                    content: `Relevant memories from prior conversations:\n${memoryText}`,
+                });
+            });
+            // ── afterTurn: extract and persist ─────────────────────────
+            agent.hook('afterTurn', 'memory', async (ctx) => {
+                const scope = ctx.turn.request.metadata?.[scopeKey] ?? 'default';
+                // Load existing memories so the extractor can dedup/update/delete.
+                let existing;
+                try {
+                    existing = await store.listByScope(scope);
+                }
+                catch (err) {
+                    console.error('[memory] failed to load existing memories:', err);
+                    return; // skip extraction — can't dedup without existing context
+                }
+                let extractions;
+                try {
+                    const result = await extractor.extract({
+                        scope,
+                        messages: ctx.turn.messages,
+                        response: ctx.turn.response,
+                        existingMemories: existing,
+                    });
+                    // Guard against malformed extractor output — a non-array
+                    // would throw during iteration, escaping the try/catch.
+                    extractions = Array.isArray(result) ? result : [];
+                }
+                catch (err) {
+                    console.error('[memory] extraction failed:', err);
+                    return;
+                }
+                // Apply each operation. Individual failures are logged and
+                // skipped — partial persistence is acceptable.
+                for (const ext of extractions) {
+                    try {
+                        if (ext.action === 'create') {
+                            await store.save({
+                                content: ext.content,
+                                scope,
+                                metadata: ext.metadata,
+                            });
+                        }
+                        else if (ext.action === 'update' && ext.targetId) {
+                            await store.update(ext.targetId, {
+                                content: ext.content,
+                                metadata: ext.metadata,
+                            });
+                        }
+                        else if (ext.action === 'delete' && ext.targetId) {
+                            await store.delete(ext.targetId);
+                        }
+                    }
+                    catch (err) {
+                        console.error(`[memory] failed to ${ext.action} memory:`, err);
+                    }
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=extension.js.map

package/dist/extras/extensions/memory/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../../../../src/extras/extensions/memory/extension.ts"],"names":[],"mappings":"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"}

package/dist/extras/extensions/memory/extension.json

@@ -0,0 +1,7 @@
+{
+  "name": "memory",
+  "description": "Session-scoped memory extension. Automatically retrieves relevant memories in beforeContext and extracts new memories in afterTurn. Requires a MemoryStore and MemoryExtractor (provided via config). Non-fatal: memory failures never crash a turn.",
+  "enabled": false,
+  "priority": -95,
+  "configKeys": ["store", "extractor", "retriever", "maxRecall", "scopeKey"]
+}