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

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.

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

packages/memory/src/adapters/keyword.ts

@@ -132,19 +132,23 @@ export class KeywordAdapter implements MemoryAdapter {
     opts?: { limit?: number; embedding?: number[] },
   ): Promise<InsightSearchResult[]> {
     const limit = opts?.limit ?? 10;
-    const words = query
+    const normalizedQuery = query.trim();
+    const matchAll = normalizedQuery === '*';
+    const words = matchAll
+      ? []
+      : normalizedQuery
           .toLowerCase()
           .split(/\s+/)
-      .filter((w) => w.length > 0);
+          .filter((word) => word.length > 0);
 
-    if (words.length === 0) return [];
+    if (words.length === 0 && !matchAll) return [];
 
     const rows = await this.storage.find<InsightRecord>(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++;
       }

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,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<Insight> => ({
+        ...value,
+        id: '1',
+        createdAt: new Date(),
+      }),
+    ),
+    searchInsights: vi.fn(async (): Promise<InsightSearchResult[]> => []),
+    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',
+        },
+      }),
+    );
+  });
+});

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<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, 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<OperatorMemoryResult[]> =>
+    (
+      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);
+    },
+  };
+}

packages/memory/src/types.ts

@@ -49,6 +49,10 @@ export interface MemoryAdapter {
   // Insights
   storeInsight(insight: NewInsight): Promise<Insight>;
   getInsight(id: string): Promise<Insight | null>;
+  /**
+   * 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,