diff --git a/docs/scratchpads/tess-m4-003-operator-plugins.md b/docs/scratchpads/tess-m4-003-operator-plugins.md new file mode 100644 index 0000000..90c690d --- /dev/null +++ b/docs/scratchpads/tess-m4-003-operator-plugins.md @@ -0,0 +1,27 @@ +# TESS-M4-003 — Operator Plugin Foundations + +- **Task:** TESS-M4-003 / TESS-MEM-001 +- **Branch/base:** `feat/tess-operator-plugins` rebased on `origin/main` `76325ca3` +- **Scope:** first leaf-package memory/retrieval slice only; no durable inbox ownership, gateway integration, or Mosaic catalog implementation. + +## Handoff + +Coder4's uncommitted implementation was preserved first in commit `5b99c821` before review. The completion pass corrected the contract so namespace is injected configuration rather than caller-selected scope data, storage keys include tenant/owner/session via collision-safe tuple encoding, and malformed runtime scope values fail closed. + +## Delivered boundary + +- `OperatorMemoryPlugin` exposes `capture`, `search`, `recent`, `stats`, and `startupContext` through `MemoryAdapter` only. +- Scope is server-derived `{tenantId, ownerId, sessionId}`; adapter and namespace are configuration, not operation input. +- Capture redacts before persistence and records configured instance/namespace/source provenance. +- Wildcard retrieval is documented at the `MemoryAdapter` boundary and implemented by the keyword adapter. +- Startup context uses a bounded 64-result candidate window, then prioritizes project and flat-file provenance before slicing the configured output limit. +- No `Tess` identity is hardcoded in storage keys or defaults; tests use configured `Nova`. + +## Verification + +- `pnpm --filter @mosaicstack/memory test` — PASS (32 tests) +- `pnpm --filter @mosaicstack/memory typecheck` — PASS +- `pnpm --filter @mosaicstack/memory lint` — PASS +- `pnpm --filter @mosaicstack/memory build` — PASS +- Codex code review — APPROVE after remediation +- Codex security review — no findings after runtime scope-validation remediation 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..5bacf6a --- /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`; adapter and namespace are injected configuration, never caller input. Its operations are `capture`, `search`, `recent`, `stats`, and `startupContext`. Results carry configured instance, provenance, and namespace metadata. Capture/redaction occurs before adapter persistence; startup context uses a bounded candidate window ordered so project/flat-file truth takes precedence within returned material. + +Registration remains replaceable-adapter based: the existing `registerMemoryAdapter(kind, factory)` / `createMemoryAdapter(config)` seam supplies the injected adapter to `createOperatorMemoryPlugin(config)`. Identity and namespace are configuration 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, configuration-injected adapter seam, 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/adapters/keyword.test.ts b/packages/memory/src/adapters/keyword.test.ts index 2a0ac85..a56b800 100644 --- a/packages/memory/src/adapters/keyword.test.ts +++ b/packages/memory/src/adapters/keyword.test.ts @@ -274,6 +274,20 @@ describe('KeywordAdapter', () => { expect(results).toHaveLength(1); }); + it('should return all scoped insights for the explicit wildcard query', async () => { + await adapter.storeInsight({ + userId: 'u1', + content: 'A literal * marker is still ordinary content', + source: 'chat', + category: 'technical', + relevanceScore: 0.7, + }); + + const results = await adapter.searchInsights('u1', '*'); + expect(results).toHaveLength(4); + expect(results.every((result) => result.score === 1)).toBe(true); + }); + it('should return empty for empty query', async () => { const results = await adapter.searchInsights('u1', ' '); expect(results).toHaveLength(0); diff --git a/packages/memory/src/adapters/keyword.ts b/packages/memory/src/adapters/keyword.ts index 7575076..ea188e7 100644 --- a/packages/memory/src/adapters/keyword.ts +++ b/packages/memory/src/adapters/keyword.ts @@ -132,19 +132,23 @@ export class KeywordAdapter implements MemoryAdapter { opts?: { limit?: number; embedding?: number[] }, ): Promise { const limit = opts?.limit ?? 10; - const words = query - .toLowerCase() - .split(/\s+/) - .filter((w) => w.length > 0); + const normalizedQuery = query.trim(); + const matchAll = normalizedQuery === '*'; + const words = matchAll + ? [] + : normalizedQuery + .toLowerCase() + .split(/\s+/) + .filter((word) => word.length > 0); - if (words.length === 0) return []; + if (words.length === 0 && !matchAll) return []; const rows = await this.storage.find(INSIGHTS, { userId }); const scored: InsightSearchResult[] = []; for (const row of rows) { const content = row.content.toLowerCase(); - let score = 0; + let score = matchAll ? 1 : 0; for (const word of words) { if (content.includes(word)) score++; } 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..26649db --- /dev/null +++ b/packages/memory/src/operator-memory-plugin.test.ts @@ -0,0 +1,147 @@ +import { describe, expect, it, vi } from 'vitest'; +import { createOperatorMemoryPlugin } from './operator-memory-plugin.js'; +import type { Insight, InsightSearchResult, NewInsight } from './types.js'; + +function adapter() { + return { + name: 'test', + embedder: null, + storeInsight: vi.fn( + async (value: NewInsight): Promise => ({ + ...value, + id: '1', + createdAt: new Date(), + }), + ), + searchInsights: vi.fn(async (): Promise => []), + 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 configured namespace storage across server-derived tenant, owner, and session scopes', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + redact: (value) => value, + }); + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-a' }, + { content: 'one', source: 'test', category: 'note' }, + ); + await plugin.capture( + { tenantId: 'tenant-b', ownerId: 'owner-a', sessionId: 'session-a' }, + { content: 'two', source: 'test', category: 'note' }, + ); + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-b' }, + { content: 'three', source: 'test', category: 'note' }, + ); + + expect( + memory.storeInsight.mock.calls.map((call: unknown[]) => (call[0] as NewInsight).userId), + ).toEqual([ + '["operator-memory","tenant-a","owner-a","session-a"]', + '["operator-memory","tenant-b","owner-a","session-a"]', + '["operator-memory","tenant-a","owner-a","session-b"]', + ]); + }); + + it('rejects an incomplete runtime scope before it can produce a shared storage key', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + redact: (value) => value, + }); + + await expect( + plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: ' ' }, + { content: 'note', source: 'test', category: 'note' }, + ), + ).rejects.toThrow('Operator memory session ID is required'); + expect(memory.storeInsight).not.toHaveBeenCalled(); + }); + + 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', + namespace: 'operator-memory', + redact: (value) => value, + }); + + const results = await plugin.search({ tenantId: 't', ownerId: 'o', sessionId: 's' }, 'x'); + + expect(results[0]?.provenance).toEqual({ + instanceId: 'Nova', + namespace: 'operator-memory', + source: 'project', + }); + }); + + it('orders startup context with project and flat-file truth before retrieved material', async () => { + const memory = adapter(); + memory.searchInsights.mockResolvedValue([ + { id: 'retrieval', content: 'retrieval', score: 1 }, + { id: 'flat-file', content: 'flat-file', score: 1, metadata: { source: 'flat-file' } }, + { id: 'project', content: 'project', score: 1, metadata: { source: 'project' } }, + ]); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + maxStartupContext: 2, + redact: (value) => value, + }); + + const context = await plugin.startupContext({ + tenantId: 'tenant-a', + ownerId: 'owner-a', + sessionId: 'session-a', + }); + + expect(context.map((result) => result.id)).toEqual(['project', 'flat-file']); + expect(memory.searchInsights).toHaveBeenCalledWith(expect.any(String), '*', { limit: 64 }); + }); + + it('redacts content before adapter persistence and records configured provenance metadata', async () => { + const memory = adapter(); + const plugin = createOperatorMemoryPlugin({ + adapter: memory, + instanceId: 'Nova', + namespace: 'operator-memory', + redact: (value) => value.replace('secret', '[REDACTED]'), + }); + + await plugin.capture( + { tenantId: 'tenant-a', ownerId: 'owner-a', sessionId: 'session-a' }, + { content: 'secret note', source: 'project', category: 'note' }, + ); + + expect(memory.storeInsight).toHaveBeenCalledWith( + expect.objectContaining({ + content: '[REDACTED] note', + metadata: { + instanceId: 'Nova', + namespace: 'operator-memory', + source: 'project', + }, + }), + ); + }); +}); diff --git a/packages/memory/src/operator-memory-plugin.ts b/packages/memory/src/operator-memory-plugin.ts new file mode 100644 index 0000000..698d904 --- /dev/null +++ b/packages/memory/src/operator-memory-plugin.ts @@ -0,0 +1,154 @@ +import type { Insight, InsightSearchResult, MemoryAdapter } from './types.js'; + +const STARTUP_CONTEXT_CANDIDATE_LIMIT = 64; + +/** Immutable server-derived boundary; callers never choose an adapter namespace. */ +export interface OperatorMemoryScope { + readonly tenantId: string; + readonly ownerId: string; + readonly sessionId: string; +} + +export interface OperatorMemoryConfig { + /** Adapter injection is deployment/lifecycle configuration, never caller input. */ + readonly adapter: MemoryAdapter; + /** Configured agent identity; it is metadata rather than a storage key default. */ + readonly instanceId: string; + /** Configured storage partition; callers cannot select a namespace. */ + readonly namespace: string; + readonly 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, namespace: string): string { + const normalizedScope = normalizeScope(scope); + // JSON tuple encoding avoids delimiter collisions between independently scoped IDs. + return JSON.stringify([ + namespace, + normalizedScope.tenantId, + normalizedScope.ownerId, + normalizedScope.sessionId, + ]); +} + +function normalizeScope(scope: OperatorMemoryScope): OperatorMemoryScope { + if (typeof scope !== 'object' || scope === null) { + throw new Error('Operator memory scope is required'); + } + return Object.freeze({ + tenantId: requiredScopeId(scope.tenantId, 'tenant ID'), + ownerId: requiredScopeId(scope.ownerId, 'owner ID'), + sessionId: requiredScopeId(scope.sessionId, 'session ID'), + }); +} + +function requiredScopeId(value: unknown, field: string): string { + if (typeof value !== 'string' || value.trim().length === 0) { + throw new Error(`Operator memory ${field} is required`); + } + return value.trim(); +} + +function compareStartupContext(left: OperatorMemoryResult, right: OperatorMemoryResult): number { + return ( + startupSourcePriority(left.provenance.source) - startupSourcePriority(right.provenance.source) + ); +} + +function startupSourcePriority(source: string): number { + if (source === 'project') return 0; + if (source === 'flat-file') return 1; + return 2; +} + +function normalizeConfig(config: OperatorMemoryConfig): OperatorMemoryConfig { + const instanceId = config.instanceId.trim(); + const namespace = config.namespace.trim(); + const maxStartupContext = config.maxStartupContext ?? 8; + if (instanceId.length === 0 || namespace.length === 0) { + throw new Error('Operator memory instance ID and namespace must be configured'); + } + if (!Number.isSafeInteger(maxStartupContext) || maxStartupContext < 1) { + throw new Error('Operator memory startup context limit must be a positive integer'); + } + return Object.freeze({ ...config, instanceId, namespace, maxStartupContext }); +} + +/** Creates a leaf-package, replaceable memory adapter facade. */ +export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): OperatorMemoryPlugin { + const pluginConfig = normalizeConfig(config); + const mapResult = (result: InsightSearchResult): OperatorMemoryResult => ({ + ...result, + provenance: { + instanceId: pluginConfig.instanceId, + namespace: pluginConfig.namespace, + source: String(result.metadata?.['source'] ?? 'retrieval'), + }, + }); + const search = async ( + scope: OperatorMemoryScope, + query: string, + limit = 10, + ): Promise => + ( + await pluginConfig.adapter.searchInsights( + scopedUserId(scope, pluginConfig.namespace), + query, + { + limit, + }, + ) + ).map(mapResult); + return { + async capture(scope, input) { + return pluginConfig.adapter.storeInsight({ + userId: scopedUserId(scope, pluginConfig.namespace), + content: pluginConfig.redact(input.content), + source: input.source, + category: input.category, + relevanceScore: 1, + metadata: { + namespace: pluginConfig.namespace, + instanceId: pluginConfig.instanceId, + source: input.source, + }, + }); + }, + search, + async recent(scope, limit = 10) { + return search(scope, '*', limit); + }, + async stats(scope) { + return { + namespace: pluginConfig.namespace, + resultCount: (await search(scope, '*', 100)).length, + }; + }, + async startupContext(scope) { + const maxStartupContext = pluginConfig.maxStartupContext ?? 8; + // Prioritize authoritative sources within a bounded candidate window. + const candidateLimit = Math.max(maxStartupContext, STARTUP_CONTEXT_CANDIDATE_LIMIT); + const context = await search(scope, '*', candidateLimit); + return [...context].sort(compareStartupContext).slice(0, maxStartupContext); + }, + }; +} diff --git a/packages/memory/src/types.ts b/packages/memory/src/types.ts index 47f9bf0..22aeb41 100644 --- a/packages/memory/src/types.ts +++ b/packages/memory/src/types.ts @@ -49,6 +49,10 @@ export interface MemoryAdapter { // Insights storeInsight(insight: NewInsight): Promise; getInsight(id: string): Promise; + /** + * Searches within one scoped user ID. The reserved `*` query returns scoped + * recent/all results rather than performing backend-specific wildcard parsing. + */ searchInsights( userId: string, query: string,