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.

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';
 

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');
+  });
+});

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<Insight>;
+  search(
+    scope: OperatorMemoryScope,
+    query: string,
+    limit?: number,
+  ): Promise<OperatorMemoryResult[]>;
+  recent(scope: OperatorMemoryScope, limit?: number): Promise<OperatorMemoryResult[]>;
+  stats(scope: OperatorMemoryScope): Promise<{ namespace: string; resultCount: number }>;
+  startupContext(scope: OperatorMemoryScope): Promise<OperatorMemoryResult[]>;
+}
+
+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<OperatorMemoryResult[]> =>
+    (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);
+    },
+  };
+}