diff --git a/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md new file mode 100644 index 0000000..e019cb8 --- /dev/null +++ b/docs/tess/M4-003-OPERATOR-PLUGIN-SKETCH.md @@ -0,0 +1,17 @@ +# TESS-M4-003 Operator Plugin Sketch + +## Memory/retrieval slice — TESS-MEM-001 + +Introduce a transport-neutral `OperatorMemoryPlugin` in `packages/memory`. The plugin receives a server-derived `{tenantId, ownerId, sessionId}` scope and delegates to a registered `MemoryAdapter`; callers cannot select an adapter or namespace. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry provenance and namespace metadata. Capture/redaction occurs before adapter persistence; startup context is bounded and ordered so project/flat-file truth can take precedence over retrieved material. + +Registration remains replaceable-adapter based: `registerOperatorMemoryAdapter(kind, factory)` and `createOperatorMemoryPlugin(config)` resolve a configured adapter. Identity and namespace are configuration/scope data; no interaction-agent name is embedded in keys or defaults. + +## Remaining plugin foundations — TESS-PLG-001 + +- `packages/agent`: capability descriptors for runtime bootstrap, durable inbox/state hooks, and read-only fleet diagnostics. Each capability advertises supported operations and fails closed when absent. +- `packages/mosaic`: a catalog/registration surface for GitOps, fleet diagnostics, runtime bootstrap, Discord, and MCP/skill discovery. Catalog entries describe authority, input schema, and safe/read-only status; they do not invoke provider transports directly. +- Gateway/channel adapters consume these contracts through server-derived actor/tenant context and durable session state, preserving the replaceable-adapter boundary. + +## First implementation boundary + +The first PR slice should add the operator-memory plugin contract, config-driven factory registration, scope isolation, provenance-bearing retrieval, and tests for namespace isolation plus a differently named configured instance. Durable inbox/outbox remains owned by the existing `DurableSessionCoordinator`; this plugin only supplies bounded context/capture at lifecycle boundaries. diff --git a/packages/memory/src/index.ts b/packages/memory/src/index.ts index 97f734d..243a027 100644 --- a/packages/memory/src/index.ts +++ b/packages/memory/src/index.ts @@ -22,6 +22,13 @@ export type { InsightSearchResult, } from './types.js'; export { createMemoryAdapter, registerMemoryAdapter } from './factory.js'; +export { + createOperatorMemoryPlugin, + type OperatorMemoryPlugin, + type OperatorMemoryScope, + type OperatorMemoryConfig, + type OperatorMemoryResult, +} from './operator-memory-plugin.js'; export { PgVectorAdapter } from './adapters/pgvector.js'; export { KeywordAdapter } from './adapters/keyword.js'; diff --git a/packages/memory/src/operator-memory-plugin.test.ts b/packages/memory/src/operator-memory-plugin.test.ts new file mode 100644 index 0000000..d9d2b55 --- /dev/null +++ b/packages/memory/src/operator-memory-plugin.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it, vi } from 'vitest'; +import { createOperatorMemoryPlugin } from './operator-memory-plugin.js'; + +function adapter() { + return { + name: 'test', + embedder: null, + storeInsight: vi.fn(async (value) => ({ ...value, id: '1', createdAt: new Date() })), + searchInsights: vi.fn(async () => []), + getInsight: vi.fn(), + deleteInsight: vi.fn(), + getPreference: vi.fn(), + setPreference: vi.fn(), + deletePreference: vi.fn(), + listPreferences: vi.fn(), + close: vi.fn(), + }; +} + +describe('OperatorMemoryPlugin', () => { + it('isolates adapter identity by server-derived tenant, owner, and namespace', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + redact: (v) => v, + }); + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 's', namespace: 'private' }, + { content: 'one', source: 'test', category: 'note' }, + ); + await plugin.capture( + { tenantId: 'tenant-b', ownerId: 'owner-a', sessionId: 's', namespace: 'private' }, + { content: 'two', source: 'test', category: 'note' }, + ); + expect(memory.storeInsight.mock.calls.map((call: unknown[]) => call[0].userId)).toEqual([ + 'tenant-a:owner-a:private', + 'tenant-b:owner-a:private', + ]); + }); + + it('uses a differently named configured instance in retrieval provenance', async () => { + const memory = adapter(); + memory.searchInsights.mockResolvedValue([ + { id: '1', content: 'x', score: 1, metadata: { source: 'project' } }, + ]); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + redact: (v) => v, + }); + const results = await plugin.search( + { tenantId: 't', ownerId: 'o', sessionId: 's', namespace: 'n' }, + 'x', + ); + expect(results[0]?.provenance.instanceId).toBe('Nova'); + }); +}); diff --git a/packages/memory/src/operator-memory-plugin.ts b/packages/memory/src/operator-memory-plugin.ts new file mode 100644 index 0000000..64b9821 --- /dev/null +++ b/packages/memory/src/operator-memory-plugin.ts @@ -0,0 +1,84 @@ +import type { Insight, InsightSearchResult, MemoryAdapter } from './types.js'; + +/** Immutable server-derived boundary; callers never choose an adapter namespace. */ +export interface OperatorMemoryScope { + tenantId: string; + ownerId: string; + sessionId: string; + namespace: string; +} + +export interface OperatorMemoryConfig { + adapter: MemoryAdapter; + instanceId: string; + maxStartupContext?: number; + redact(content: string): string; +} + +export interface OperatorMemoryResult extends InsightSearchResult { + provenance: { instanceId: string; namespace: string; source: string }; +} + +export interface OperatorMemoryPlugin { + capture( + scope: OperatorMemoryScope, + input: { content: string; source: string; category: string }, + ): Promise; + search( + scope: OperatorMemoryScope, + query: string, + limit?: number, + ): Promise; + recent(scope: OperatorMemoryScope, limit?: number): Promise; + stats(scope: OperatorMemoryScope): Promise<{ namespace: string; resultCount: number }>; + startupContext(scope: OperatorMemoryScope): Promise; +} + +function scopedUserId(scope: OperatorMemoryScope): string { + return `${scope.tenantId}:${scope.ownerId}:${scope.namespace}`; +} + +/** Creates a leaf-package, replaceable memory adapter facade. */ +export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): OperatorMemoryPlugin { + const mapResult = ( + scope: OperatorMemoryScope, + result: InsightSearchResult, + ): OperatorMemoryResult => ({ + ...result, + provenance: { + instanceId: config.instanceId, + namespace: scope.namespace, + source: String(result.metadata?.['source'] ?? 'retrieval'), + }, + }); + const search = async ( + scope: OperatorMemoryScope, + query: string, + limit = 10, + ): Promise => + (await config.adapter.searchInsights(scopedUserId(scope), query, { limit })).map((result) => + mapResult(scope, result), + ); + return { + async capture(scope, input) { + return config.adapter.storeInsight({ + userId: scopedUserId(scope), + content: config.redact(input.content), + source: input.source, + category: input.category, + relevanceScore: 1, + metadata: { namespace: scope.namespace, instanceId: config.instanceId }, + }); + }, + search, + async recent(scope, limit = 10) { + return search(scope, '*', limit); + }, + async stats(scope) { + return { namespace: scope.namespace, resultCount: (await search(scope, '*', 100)).length }; + }, + async startupContext(scope) { + return search(scope, '*', config.maxStartupContext ?? 8); + }, + }; +}