@moxxy/core 0.26.0 → 0.28.0

package/src/plugins/registry-kinds.test.ts

@@ -37,6 +37,7 @@ import { EmbedderRegistry } from '../registries/embedders.js';
 import { IsolatorRegistry } from '../registries/isolators.js';
 import { WorkflowExecutorRegistry } from '../registries/workflow-executors.js';
 import { EventStoreRegistry } from '../registries/event-stores.js';
+import { ReflectorRegistry } from '../registries/reflectors.js';
 import { RequirementRegistry } from '../requirements.js';
 import { HookDispatcherImpl } from './lifecycle.js';
 import { PluginHost } from './host.js';
@@ -87,6 +88,7 @@ const everyKindPlugin = definePlugin({
       readPage: async () => ({ events: [], prevCursor: null }),
     },
   ],
+  reflectors: [{ name: 'refl-1', reflect: async () => [] }],
 });
 
 function makeHost() {
@@ -108,6 +110,7 @@ function makeHost() {
     isolators: new IsolatorRegistry(),
     workflowExecutors: new WorkflowExecutorRegistry(),
     eventStores: new EventStoreRegistry(),
+    reflectors: new ReflectorRegistry(),
   };
   const requirements = new RequirementRegistry({
     tools: registries.tools,
@@ -147,6 +150,7 @@ function makeHost() {
     isolator: registries.isolators,
     workflowExecutor: registries.workflowExecutors,
     eventStore: registries.eventStores,
+    reflector: registries.reflectors,
   };
   return { host, byKind };
 }

package/src/plugins/registry-kinds.ts

@@ -17,6 +17,7 @@ import type {
   TunnelProviderDef,
   WorkflowExecutorDef,
   EventStoreDef,
+  ReflectorDef,
 } from '@moxxy/sdk';
 import type { PluginHostOptions } from './host-options.js';
 
@@ -44,6 +45,7 @@ export interface RegistryNameRecord {
   readonly isolatorNames: ReadonlyArray<string>;
   readonly workflowExecutorNames: ReadonlyArray<string>;
   readonly eventStoreNames: ReadonlyArray<string>;
+  readonly reflectorNames: ReadonlyArray<string>;
 }
 
 /**
@@ -243,4 +245,15 @@ export const REGISTRY_KINDS: ReadonlyArray<RegistryKind<unknown>> = [
     register: (o, e: EventStoreDef) => o.eventStores.register(e),
     unregister: (o, n) => o.eventStores.unregister(n),
   } satisfies RegistryKind<EventStoreDef>,
+  {
+    kind: 'reflector',
+    recordField: 'reflectorNames',
+    defs: (p) => p.reflectors ?? [],
+    nameOf: (r: ReflectorDef) => r.name,
+    // Throw-on-duplicate `register` (NOT `replace`): a discovered reflector is
+    // added but auto-adopts only when nothing is active yet (the registry is
+    // nullable — no core floor). The user swaps via `plugins.reflector.default`.
+    register: (o, r: ReflectorDef) => o.reflectors.register(r),
+    unregister: (o, n) => o.reflectors.unregister(n),
+  } satisfies RegistryKind<ReflectorDef>,
 ] as ReadonlyArray<RegistryKind<unknown>>;

package/src/registries/modes.test.ts

@@ -84,3 +84,30 @@ describe('ModeRegistry legacy-name migration', () => {
     expect(after).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('ModeRegistry previous-mode tracking', () => {
+  it('records the previously active mode across switches', () => {
+    const reg = new ModeRegistry();
+    reg.register(mode('default')); // auto-active, no previous
+    expect(reg.getPreviousActiveName()).toBeNull();
+
+    reg.register(mode('goal'));
+    reg.setActive('goal');
+    expect(reg.getPreviousActiveName()).toBe('default');
+
+    // Reverting (a transient mode handing back) updates previous too.
+    reg.setActive('default');
+    expect(reg.getPreviousActiveName()).toBe('goal');
+  });
+
+  it('a same-name setActive does not clobber the previous mode', () => {
+    const reg = new ModeRegistry();
+    reg.register(mode('default'));
+    reg.register(mode('goal'));
+    reg.setActive('goal');
+    // Re-arming goal (e.g. /goal twice in a row) keeps 'default' as the mode
+    // to hand back to — activate() early-returns on the name match.
+    reg.setActive('goal');
+    expect(reg.getPreviousActiveName()).toBe('default');
+  });
+});

package/src/registries/modes.ts

@@ -3,6 +3,7 @@ import { migrateModeName, type ModeDef } from '@moxxy/sdk';
 export class ModeRegistry {
   private readonly modes = new Map<string, ModeDef>();
   private active: string | null = null;
+  private previous: string | null = null;
   private readonly changeListeners = new Set<() => void>();
 
   /** Observe active-mode changes — used by the runner to broadcast
@@ -67,6 +68,16 @@ export class ModeRegistry {
     return this.active;
   }
 
+  /**
+   * Name of the mode that was active before the current one, or null when
+   * there is no history (session boot). Lets a transient mode (goal) revert
+   * to whatever the user was in before arming it — carried onto the
+   * ModeContext as `previousModeName` by run-turn.
+   */
+  getPreviousActiveName(): string | null {
+    return this.previous;
+  }
+
   setActive(name: string): void {
     // Prefer the literal name; only when it isn't registered fall back to the
     // legacy-name map (e.g. a persisted "tool-use" → "default"). This never
@@ -86,6 +97,7 @@ export class ModeRegistry {
 
   private activate(mode: ModeDef): void {
     if (this.active === mode.name) return;
+    this.previous = this.active;
     this.active = mode.name;
     this.notifyChange();
   }

package/src/registries/reflectors.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import type { ReflectorDef } from '@moxxy/sdk';
+import { Session, autoAllowResolver, silentLogger } from '../index.js';
+
+function makeSession(): Session {
+  return new Session({ cwd: '/tmp', logger: silentLogger, permissionResolver: autoAllowResolver });
+}
+
+const def = (name: string): ReflectorDef => ({ name, reflect: async () => [] });
+
+describe('Reflector registry (nullable, no floor)', () => {
+  it('starts empty — no core-seeded floor, reflection is off by default', () => {
+    const session = makeSession();
+    expect(session.reflectors.getActiveName()).toBeNull();
+    expect(session.reflectors.getFloorName()).toBeNull();
+    expect(session.reflectors.list()).toEqual([]);
+    expect(session.reflectors.getActive()).toBeNull();
+  });
+
+  it('publishes the registry on the service registry for the driver to resolve', () => {
+    const session = makeSession();
+    expect(session.services.get('reflectors')).toBe(session.reflectors);
+  });
+
+  it('auto-adopts the first registered reflector as active', () => {
+    const session = makeSession();
+    session.reflectors.register(def('default'));
+    expect(session.reflectors.getActiveName()).toBe('default');
+    expect(session.reflectors.getActive()?.name).toBe('default');
+  });
+
+  it('throws on a duplicate name and swaps via setActive', () => {
+    const session = makeSession();
+    session.reflectors.register(def('default'));
+    expect(() => session.reflectors.register(def('default'))).toThrow(/already registered/);
+    session.reflectors.register(def('smart'));
+    // Second registration does NOT steal active from the first.
+    expect(session.reflectors.getActiveName()).toBe('default');
+    session.reflectors.setActive('smart');
+    expect(session.reflectors.getActiveName()).toBe('smart');
+  });
+
+  it('reverts to null (no floor) when the active reflector is unregistered', () => {
+    const session = makeSession();
+    session.reflectors.register(def('default'));
+    session.reflectors.unregister('default');
+    expect(session.reflectors.getActiveName()).toBeNull();
+    expect(session.reflectors.getActive()).toBeNull();
+  });
+});

package/src/registries/reflectors.ts

@@ -0,0 +1,17 @@
+import type { ReflectorDef } from '@moxxy/sdk';
+import { ActiveDefRegistry } from './active-def-registry.js';
+
+/**
+ * The single-active Reflector registry (the learning-loop block that watches a
+ * finished turn and proposes memory/skill improvements). NULLABLE by design:
+ * unlike the event-store/compactor registries there is NO core-seeded protected
+ * floor, so `getActive()` returns null until a plugin registers one — reflection
+ * is opt-in exactly like transcriber/synthesizer. `autoAdoptFirst` (the default)
+ * means the first registered reflector becomes active, and `unregister` reverts
+ * to null (no floor to fall back to). Uses throw-on-duplicate `register`.
+ */
+export class ReflectorRegistry extends ActiveDefRegistry<ReflectorDef> {
+  constructor() {
+    super({ noun: 'Reflector', autoAdoptFirst: true });
+  }
+}

package/src/run-turn.ts

@@ -94,6 +94,7 @@ export async function* runTurn(
     session.lastResolvedModel = model;
 
     const strategy = session.modes.getActive();
+    const previousModeName = session.modes.getPreviousActiveName();
     // Combine the session's signal, the per-turn one (if provided), and the
     // generator-scoped abandonment signal so any of them firing cancels the turn.
     const effectiveSignal = AbortSignal.any(
@@ -140,6 +141,10 @@ export async function* runTurn(
       requestModeSwitch: (modeName: string) => {
         requestedModeSwitch = modeName;
       },
+      // Only surface a previous mode that is STILL registered — a transient
+      // mode reverting to an since-unregistered name would throw in the
+      // post-turn setActive and strand the session in the transient mode.
+      ...(previousModeName && session.modes.has(previousModeName) ? { previousModeName } : {}),
       emit: (event: EmittedEvent) => session.log.append(event),
     };
 

package/src/session-runtime.ts

@@ -48,9 +48,13 @@ export interface SessionRuntime {
   readonly modes: {
     getActive(): ModeDef;
     list(): ReadonlyArray<ModeDef>;
+    has(name: string): boolean;
     /** Post-turn mode hand-off (one mode handing back to another). Throws on an
      *  unknown name; run-turn guards the call. */
     setActive(name: string): void;
+    /** Mode active before the current one (or null) — surfaced onto the
+     *  ModeContext so a transient mode (goal) can revert to it. */
+    getPreviousActiveName(): string | null;
   };
   readonly compactors: { getActive(): CompactorDef | null };
   readonly cacheStrategies: { getActive(): CacheStrategyDef | null };

package/src/session.ts

@@ -35,6 +35,7 @@ import { EmbedderRegistry } from './registries/embedders.js';
 import { IsolatorRegistry } from './registries/isolators.js';
 import { WorkflowExecutorRegistry } from './registries/workflow-executors.js';
 import { EventStoreRegistry } from './registries/event-stores.js';
+import { ReflectorRegistry } from './registries/reflectors.js';
 import { ServiceRegistryImpl } from './registries/services.js';
 import { jsonlEventStore } from './sessions/jsonl-event-store.js';
 import { RequirementRegistry } from './requirements.js';
@@ -50,6 +51,7 @@ import type {
   WorkflowsView,
   PluginsAdminView,
   ProviderSetupView,
+  SessionLike,
   PendingToolCall,
   PermissionContext,
   PermissionDecision,
@@ -136,6 +138,12 @@ export class Session implements ClientSession, SessionRuntime {
   readonly isolators: IsolatorRegistry;
   readonly workflowExecutors: WorkflowExecutorRegistry;
   readonly eventStores: EventStoreRegistry;
+  /**
+   * The learning-loop block: watches finished turns and proposes memory/skill
+   * improvements. NULLABLE — no core-seeded floor, so it stays empty until a
+   * reflector plugin (e.g. @moxxy/reflector-default) registers one.
+   */
+  readonly reflectors: ReflectorRegistry;
   /** Inter-plugin service registry — plugins publish/consume services in onInit. */
   readonly services: ServiceRegistryImpl;
   readonly requirements: RequirementRegistry;
@@ -186,6 +194,7 @@ export class Session implements ClientSession, SessionRuntime {
   workflows?: WorkflowsView;
   pluginsAdmin?: PluginsAdminView;
   providerSetup?: ProviderSetupView;
+  configAdmin?: SessionLike['configAdmin'];
   readonly dispatcher: HookDispatcherImpl;
   readonly pluginHost: PluginHost;
   private readonly controller = new AbortController();
@@ -241,6 +250,8 @@ export class Session implements ClientSession, SessionRuntime {
     this.services.register('synthesizers', this.synthesizers);
     this.services.register('skills', this.skills);
     this.services.register('tunnelProviders', this.tunnelProviders);
+    // The memory plugin (discovery-loadable) resolves its lazy embedder here.
+    this.services.register('embedders', this.embedders);
     // A stable accessor for the active provider's stored credentials. The
     // resolver itself is installed late (by activateProvider, after plugins are
     // built), so close over `this` and read it lazily at call time — lets
@@ -270,6 +281,12 @@ export class Session implements ClientSession, SessionRuntime {
     // Seed the built-in JSONL store as the protected floor — the storage backend
     // behind the event log always exists and can be swapped but never removed.
     this.eventStores.register(jsonlEventStore, { protected: true });
+    // Reflectors are nullable — no core floor is seeded, so reflection stays off
+    // until a reflector plugin registers one. Published on the service registry
+    // so a discovery-loaded driver (the reflector plugin's own hooks) can resolve
+    // the active reflector in onTurnEnd without importing @moxxy/core.
+    this.reflectors = new ReflectorRegistry();
+    this.services.register('reflectors', this.reflectors);
     this.requirements = new RequirementRegistry({
       tools: this.tools,
       providers: this.providers,
@@ -317,6 +334,7 @@ export class Session implements ClientSession, SessionRuntime {
       isolators: this.isolators,
       workflowExecutors: this.workflowExecutors,
       eventStores: this.eventStores,
+      reflectors: this.reflectors,
       requirements: this.requirements,
       dispatcher: this.dispatcher,
       loader: opts.pluginLoader,

package/src/sessions/event-shape.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'vitest';
+import type { MoxxyEventOfType, MoxxyEventType } from '@moxxy/sdk';
+import { isMoxxyEventShape } from './event-shape.js';
+
+/** Shared valid envelope for building variant samples. */
+const base = {
+  id: 'e1' as never,
+  seq: 0,
+  ts: 1,
+  sessionId: 's1' as never,
+  turnId: 't1' as never,
+  source: 'user' as const,
+};
+
+/**
+ * One valid sample of EVERY variant, typed as an exhaustive record over
+ * `MoxxyEventType` — adding a variant to the sdk union fails this file's
+ * typecheck until a sample (and thus guard coverage) is added, and a sample
+ * that drifts from its variant's shape fails to compile.
+ */
+const samples: { readonly [T in MoxxyEventType]: MoxxyEventOfType<T> } = {
+  user_prompt: { ...base, type: 'user_prompt', text: 'hello' },
+  assistant_chunk: { ...base, type: 'assistant_chunk', delta: 'hi ' },
+  assistant_message: {
+    ...base,
+    type: 'assistant_message',
+    content: 'hi there',
+    stopReason: 'end_turn',
+  },
+  reasoning_chunk: { ...base, type: 'reasoning_chunk', delta: 'thinking…' },
+  reasoning_message: { ...base, type: 'reasoning_message', content: 'thought about it' },
+  tool_call_requested: {
+    ...base,
+    type: 'tool_call_requested',
+    callId: 'c1' as never,
+    name: 'read_file',
+    input: { path: '/tmp/x' },
+  },
+  tool_call_approved: {
+    ...base,
+    type: 'tool_call_approved',
+    callId: 'c1' as never,
+    decidedBy: 'policy',
+    mode: 'allow',
+  },
+  tool_call_denied: {
+    ...base,
+    type: 'tool_call_denied',
+    callId: 'c1' as never,
+    decidedBy: 'resolver',
+    reason: 'denied by user',
+  },
+  tool_result: { ...base, type: 'tool_result', callId: 'c1' as never, ok: true, output: 'done' },
+  skill_invoked: {
+    ...base,
+    type: 'skill_invoked',
+    skillId: 'sk1' as never,
+    name: 'add-a-tool',
+    reason: 'manual',
+  },
+  skill_created: {
+    ...base,
+    type: 'skill_created',
+    skillId: 'sk1' as never,
+    name: 'new-skill',
+    path: '/tmp/skill.md',
+    scope: 'user',
+    originatingPrompt: 'make a skill',
+  },
+  plugin_registered: {
+    ...base,
+    type: 'plugin_registered',
+    pluginId: 'p1' as never,
+    name: '@moxxy/plugin-x',
+    version: '1.0.0',
+    kind: ['tools'],
+  },
+  plugin_unregistered: {
+    ...base,
+    type: 'plugin_unregistered',
+    pluginId: 'p1' as never,
+    name: '@moxxy/plugin-x',
+    reason: 'reload',
+  },
+  mode_iteration: { ...base, type: 'mode_iteration', strategy: 'default', iteration: 2 },
+  compaction: {
+    ...base,
+    type: 'compaction',
+    compactor: 'summarizer',
+    replacedRange: [0, 9],
+    summary: 'earlier chatter',
+    tokensSaved: 1234,
+  },
+  elision: {
+    ...base,
+    type: 'elision',
+    elidedThrough: 40,
+    stubbedRanges: [[0, 40]],
+    elideConversational: false,
+    conversationalRecallThreshold: 3,
+    maxRecallBytes: 65536,
+    neverElideTools: ['recall'],
+    tokensSaved: 5678,
+  },
+  provider_request: { ...base, type: 'provider_request', provider: 'anthropic', model: 'claude' },
+  provider_response: {
+    ...base,
+    type: 'provider_response',
+    provider: 'anthropic',
+    model: 'claude',
+    outputTokens: 10,
+  },
+  error: { ...base, type: 'error', kind: 'retryable', message: 'rate limited' },
+  abort: { ...base, type: 'abort', reason: 'user pressed esc' },
+  plugin_event: {
+    ...base,
+    type: 'plugin_event',
+    pluginId: 'p1' as never,
+    subtype: 'frame',
+    payload: { n: 1 },
+  },
+};
+
+/** Round-trip through JSON, faithful to how the real read path sees a line. */
+function throughJson(value: unknown): unknown {
+  return JSON.parse(JSON.stringify(value)) as unknown;
+}
+
+describe('isMoxxyEventShape', () => {
+  it('accepts a valid sample of every event variant (JSON round-tripped)', () => {
+    for (const [type, sample] of Object.entries(samples)) {
+      expect(isMoxxyEventShape(throughJson(sample)), `variant ${type}`).toBe(true);
+    }
+  });
+
+  it('rejects non-object values and objects missing the envelope', () => {
+    expect(isMoxxyEventShape(null)).toBe(false);
+    expect(isMoxxyEventShape(undefined)).toBe(false);
+    expect(isMoxxyEventShape('user_prompt')).toBe(false);
+    expect(isMoxxyEventShape(42)).toBe(false);
+    expect(isMoxxyEventShape([samples.user_prompt])).toBe(false);
+    expect(isMoxxyEventShape({})).toBe(false);
+    expect(isMoxxyEventShape({ foo: 'bar' })).toBe(false);
+    // Each strict envelope field, individually missing or mistyped.
+    const { id: _id, ...noId } = samples.user_prompt;
+    expect(isMoxxyEventShape(noId)).toBe(false);
+    const { seq: _seq, ...noSeq } = samples.user_prompt;
+    expect(isMoxxyEventShape(noSeq)).toBe(false);
+    const { ts: _ts, ...noTs } = samples.user_prompt;
+    expect(isMoxxyEventShape(noTs)).toBe(false);
+    const { type: _type, ...noType } = samples.user_prompt;
+    expect(isMoxxyEventShape(noType)).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.user_prompt, seq: '0' })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.user_prompt, id: 7 })).toBe(false);
+  });
+
+  it('rejects non-finite numbers (JSON.parse CAN produce them: 1e999 → Infinity)', () => {
+    const line = JSON.stringify({ ...samples.user_prompt, seq: 0 }).replace('"seq":0', '"seq":1e999');
+    const parsed: unknown = JSON.parse(line);
+    expect((parsed as { seq: number }).seq).toBe(Number.POSITIVE_INFINITY);
+    expect(isMoxxyEventShape(parsed)).toBe(false);
+  });
+
+  it('tolerates absent sessionId/turnId/source (legacy logs) but rejects present-wrong-type', () => {
+    const { sessionId: _s, turnId: _t, source: _src, ...bare } = samples.user_prompt;
+    expect(isMoxxyEventShape(bare)).toBe(true);
+    expect(isMoxxyEventShape({ ...bare, sessionId: null })).toBe(true);
+    expect(isMoxxyEventShape({ ...samples.user_prompt, sessionId: 42 })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.user_prompt, turnId: {} })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.user_prompt, source: 9 })).toBe(false);
+  });
+
+  it('keeps an unknown (newer) event type with a valid envelope — floor-rollback forward-compat', () => {
+    expect(isMoxxyEventShape({ ...base, type: 'surface_frame_from_the_future', blob: 'x' })).toBe(
+      true,
+    );
+  });
+
+  it('keeps a known variant carrying an unknown enum member — forward-compat on enum drift', () => {
+    expect(
+      isMoxxyEventShape({ ...samples.assistant_message, stopReason: 'brand_new_reason' }),
+    ).toBe(true);
+  });
+
+  it('rejects known variants missing or mistyping their required fields', () => {
+    const { text: _text, ...promptNoText } = samples.user_prompt;
+    expect(isMoxxyEventShape(promptNoText)).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.user_prompt, text: 42 })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.tool_result, ok: 'yes' })).toBe(false);
+    const { replacedRange: _rr, ...compactionNoRange } = samples.compaction;
+    expect(isMoxxyEventShape(compactionNoRange)).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.compaction, replacedRange: ['0', '9'] })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.compaction, replacedRange: [0] })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.compaction, summary: null })).toBe(false);
+    const { maxRecallBytes: _mrb, ...elisionSlim } = samples.elision;
+    expect(isMoxxyEventShape(elisionSlim)).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.mode_iteration, iteration: 'two' })).toBe(false);
+    expect(isMoxxyEventShape({ ...samples.plugin_registered, kind: 'tools' })).toBe(false);
+  });
+
+  it('tolerates a tool_call_requested whose input key was dropped by JSON.stringify', () => {
+    // `input: undefined` at emit time serializes to a line with NO input key —
+    // a presence check would drop a legitimate event.
+    const line = { ...samples.tool_call_requested, input: undefined };
+    expect(isMoxxyEventShape(throughJson(line))).toBe(true);
+  });
+});