@moxxy/sdk 0.19.0 → 0.21.0

package/src/mode/stuck-loop.ts

@@ -34,6 +34,27 @@ export interface StuckLoopDetector {
   record(toolName: string, input: unknown): StuckSignal;
 }
 
+/**
+ * User-tunable loop-guard settings (config `context.loopGuard`). All optional —
+ * omitted fields use the defaults below. Set `enabled: false` to turn the guard
+ * off entirely and rely solely on the mode's `maxIterations` cap.
+ */
+export interface LoopGuardSettings {
+  readonly enabled?: boolean;
+  readonly windowSize?: number;
+  readonly repeatThreshold?: number;
+  readonly nearWindowSize?: number;
+  readonly nearThreshold?: number;
+}
+
+/** Default exact-repeat window + trip count. Deliberately generous: the
+ *  `maxIterations` cap (500 in default mode) is the real runaway backstop, so
+ *  this only needs to catch a *tight* same-call loop, not legitimately repeated
+ *  work (re-reading a file, re-running `git status` across steps, a couple of
+ *  retries). Tunable via `context.loopGuard`. */
+export const DEFAULT_LOOP_WINDOW_SIZE = 12;
+export const DEFAULT_LOOP_REPEAT_THRESHOLD = 8;
+
 /** Identity arguments that pin "the same target" across volatile-arg variation,
  *  best-first. The first present string field wins. */
 const IDENTITY_ARG_KEYS = ['url', 'file_path', 'path', 'command', 'cmd', 'query', 'pattern'];
@@ -48,19 +69,13 @@ function identityArg(input: unknown): string | null {
   return null;
 }
 
-export function createStuckLoopDetector(
-  opts: {
-    windowSize?: number;
-    repeatThreshold?: number;
-    nearWindowSize?: number;
-    nearThreshold?: number;
-  } = {},
-): StuckLoopDetector {
-  const windowSize = opts.windowSize ?? 8;
-  const repeatThreshold = opts.repeatThreshold ?? 3;
+export function createStuckLoopDetector(opts: LoopGuardSettings = {}): StuckLoopDetector {
+  const enabled = opts.enabled ?? true;
+  const windowSize = opts.windowSize ?? DEFAULT_LOOP_WINDOW_SIZE;
+  const repeatThreshold = opts.repeatThreshold ?? DEFAULT_LOOP_REPEAT_THRESHOLD;
   // Near-dups need a higher count + a wider window (they're spread out across a
   // burst of other calls), and tolerate a couple of legit "bigger refetch" tries.
-  const nearWindowSize = opts.nearWindowSize ?? Math.max(windowSize * 2, 16);
+  const nearWindowSize = opts.nearWindowSize ?? Math.max(windowSize * 2, 24);
   const nearThreshold = opts.nearThreshold ?? Math.max(repeatThreshold + 2, 5);
   const recent: string[] = [];
   const recentNear: string[] = [];
@@ -68,6 +83,8 @@ export function createStuckLoopDetector(
     windowSize,
     repeatThreshold,
     record(toolName, input): StuckSignal {
+      // Disabled → never trip (rely on the maxIterations cap alone).
+      if (!enabled) return { stuck: false, count: 0, kind: 'exact' };
       const key = `${toolName}|${stableHash(input)}`;
       recent.push(key);
       if (recent.length > windowSize) recent.shift();

package/src/mode-helpers.ts

@@ -30,5 +30,6 @@ export {
   createStuckLoopDetector,
   type StuckLoopDetector,
   type StuckSignal,
+  type LoopGuardSettings,
 } from './mode/stuck-loop.js';
 export { stableHash } from './mode/stable-hash.js';

package/src/mode.test.ts

@@ -1,5 +1,24 @@
 import { describe, expect, it } from 'vitest';
-import { migrateModeName } from './mode.js';
+import { migrateModeName, isSelectableMode } from './mode.js';
+
+describe('isSelectableMode', () => {
+  it('treats a plain mode (no `special`) as selectable', () => {
+    expect(isSelectableMode({ special: undefined })).toBe(true);
+    expect(isSelectableMode({})).toBe(true);
+  });
+  it('treats a special mode as NOT selectable (any descriptor, even empty)', () => {
+    expect(isSelectableMode({ special: {} })).toBe(false);
+    expect(isSelectableMode({ special: { invokedBy: 'collab' } })).toBe(false);
+  });
+  it('filters special modes out of a list, keeping plain ones', () => {
+    const modes = [
+      { name: 'default' },
+      { name: 'goal' },
+      { name: 'collaborative', special: { invokedBy: 'collab' } },
+    ];
+    expect(modes.filter(isSelectableMode).map((m) => m.name)).toEqual(['default', 'goal']);
+  });
+});
 
 describe('migrateModeName', () => {
   it('maps every legacy mode name to its current target', () => {

package/src/mode.ts

@@ -2,10 +2,12 @@ import type { CacheStrategyDef } from './cache-strategy.js';
 import type { CompactorDef } from './compactor.js';
 import type { EmittedEvent, MoxxyEvent } from './events.js';
 import type { HookDispatcher } from './hooks.js';
+import type { ServiceRegistry } from './services.js';
 import type { SessionId, TurnId } from './ids.js';
 import type { EventLogReader } from './log.js';
 import type { PermissionResolver } from './permission.js';
 import type { LLMProvider } from './provider.js';
+import type { LoopGuardSettings } from './mode/stuck-loop.js';
 import type { Skill } from './skill.js';
 import type { SubagentSpawner } from './subagent.js';
 import type { ToolDef } from './tool.js';
@@ -106,8 +108,15 @@ export interface ModeContext {
   readonly approval?: ApprovalResolver;
   readonly hooks: HookDispatcher;
   readonly pluginHost: PluginHostHandle;
+  /** Inter-plugin service registry (mirrors {@link AppContext.services}). */
+  readonly services: ServiceRegistry;
   readonly signal: AbortSignal;
   readonly maxIterations?: number;
+  /**
+   * Loop-guard tuning (config `context.loopGuard`), forwarded to each mode's
+   * stuck-loop detector. When omitted the detector uses its defaults.
+   */
+  readonly loopGuard?: LoopGuardSettings;
   /**
    * Spawn one or more child agents that share the parent's registries
    * but run in isolation. Children stream their events back to the
@@ -197,9 +206,43 @@ export interface ModeDef {
    * accent badge while this mode is active. See {@link ModeBadge}.
    */
   readonly badge?: ModeBadge;
+  /**
+   * Marks a "special" mode — one the user does NOT pick from `/mode`. Set this
+   * and the mode is, uniformly across every surface (TUI, mobile, desktop):
+   *   - **hidden** from every mode list / picker (presence), and
+   *   - **refused** by the normal mode-switch by name (execution) — it can only
+   *     be entered through its own invocation (a slash command, a spawned
+   *     agent's `MOXXY_MODE`, …) via the raw registry `setActive`.
+   * The mode stays registered + runnable; it's just never *offered* or
+   * name-switched. Extensible: any number of special modes (collaborative today,
+   * more later) opt in the same way. See {@link isSelectableMode}.
+   */
+  readonly special?: ModeSpecial;
   run(ctx: ModeContext): AsyncIterable<MoxxyEvent>;
 }
 
+/** Descriptor for a {@link ModeDef.special} mode — see that field. */
+export interface ModeSpecial {
+  /**
+   * Human-facing entry point that enters this mode, e.g. `'collab'` (the
+   * `/collab` command). Surfaced when the user tries to pick/switch it ("entered
+   * via /collab") so the UI can point at the right action.
+   */
+  readonly invokedBy?: string;
+}
+
+/**
+ * Whether a mode is user-selectable — i.e. NOT a {@link ModeDef.special} mode.
+ * The single predicate every surface (TUI/mobile/desktop mode lists + the
+ * by-name mode-switch) uses to filter/refuse special modes uniformly. The
+ * parameter is intentionally loose (`{ special? }`) so it also applies to the
+ * minimal `{ name }` rows the swap-UI registries expose — non-mode defs simply
+ * carry no `special` and are always selectable.
+ */
+export function isSelectableMode(mode: { readonly special?: unknown }): boolean {
+  return mode.special === undefined;
+}
+
 /**
  * Legacy mode-name → current-name map for backward compatibility. Modes were
  * renamed/slimmed: `tool-use`→`default`, `deep-research`→`research`, and the

package/src/plugin.ts

@@ -16,8 +16,9 @@ import type { SynthesizerDef } from './synthesizer.js';
 import type { ViewRendererDef } from './view-renderer.js';
 import type { TunnelProviderDef } from './tunnel.js';
 import type { WorkflowExecutorDef } from './workflow.js';
+import type { EventStoreDef } from './event-store.js';
 
-export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'surface' | 'hooks' | 'agent' | 'command' | 'transcriber' | 'synthesizer' | 'embedder' | 'isolator' | 'workflow-executor';
+export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'surface' | 'hooks' | 'agent' | 'command' | 'transcriber' | 'synthesizer' | 'embedder' | 'isolator' | 'workflow-executor' | 'event-store';
 
 export interface PluginSpec {
   readonly name: string;
@@ -44,6 +45,14 @@ export interface PluginSpec {
    * the proxy relay). One active per session; core seeds a `localhost` no-op.
    */
   readonly tunnelProviders?: ReadonlyArray<TunnelProviderDef>;
+  /**
+   * Event-store backends — the storage behind a session's event log. Core seeds
+   * a protected JSONL default; a plugin can contribute an alternative (SQLite,
+   * remote, encrypted), activated only by explicit `plugins.eventStore.default`
+   * (a discovered store is registered but never auto-active — the trust
+   * boundary, since the store sees every event). See {@link EventStoreDef}.
+   */
+  readonly eventStores?: ReadonlyArray<EventStoreDef>;
   readonly channels?: ReadonlyArray<ChannelDef>;
   /**
    * Interactive surfaces contributed by the plugin — long-lived panes a human

package/src/services.ts

@@ -0,0 +1,47 @@
+/**
+ * Minimal read-only view of a name-keyed registry. The host publishes its core
+ * registries (agents, tools, …) on the {@link ServiceRegistry} under these
+ * names, so a discovery-loaded plugin can resolve one in `onInit` (e.g.
+ * `ctx.services.require<NamedRegistry<AgentDef>>('agents')`) without importing
+ * `@moxxy/core`'s concrete registry types. Core's `DefMapRegistry`-based
+ * registries satisfy it structurally.
+ *
+ * Well-known service names the host publishes: `'agents'`, `'tools'`,
+ * `'providers'`, `'viewRenderers'`, `'synthesizers'`.
+ */
+export interface NamedRegistry<T> {
+  get(name: string): T | undefined;
+  list(): ReadonlyArray<T>;
+  has(name: string): boolean;
+}
+
+/**
+ * Inter-plugin service registry. A plugin can **publish** a named service in its
+ * `onInit` hook (e.g. the vault plugin publishes its secret store) and another
+ * plugin can **consume** it in its own `onInit` — decoupling cross-plugin
+ * dependencies from the host's constructor wiring so a plugin can be
+ * discovery-loaded (default-exported, no `build*({deps})` closure) instead of
+ * hand-built by the orchestrator.
+ *
+ * Ordering is by plugin requirements: declare `moxxy.requirements` on the
+ * consumer (e.g. `@moxxy/plugin-oauth` requires `@moxxy/plugin-vault`) so the
+ * provider's `onInit` runs first and the service is registered before the
+ * consumer resolves it. Exposed on {@link AppContext.services}.
+ *
+ * Plugin `onInit` already runs with full in-process privileges (the security
+ * isolation wraps *tool* execution, not plugin code), so reaching a sibling
+ * plugin's service here doesn't widen the effective trust surface.
+ */
+export interface ServiceRegistry {
+  /** Publish a named service for other plugins to consume in their `onInit`. */
+  register<T>(name: string, impl: T): void;
+  /** Resolve a published service, or `undefined` when it isn't registered. */
+  get<T>(name: string): T | undefined;
+  /**
+   * Resolve a published service or throw — use when a declared requirement
+   * guarantees the provider ran first.
+   */
+  require<T>(name: string): T;
+  /** Whether a service has been published. */
+  has(name: string): boolean;
+}

package/src/session-like.ts

@@ -289,6 +289,37 @@ export interface LoadedPluginView {
   readonly version: string;
   /** Contribution categories (e.g. `['provider']`, `['tool','command']`). */
   readonly kinds: ReadonlyArray<string>;
+  /**
+   * True when discovered from `~/.moxxy/plugins` (installed on demand), false/
+   * absent when statically bundled into the binary. Lets surfaces distinguish
+   * "installed" from "built-in". Optional so a thin-client `RemoteSession` may
+   * omit it (treated as built-in).
+   */
+  readonly installed?: boolean;
+}
+
+/** One swappable contribution within a {@link CategoryView}. */
+export interface CategoryItemView {
+  /** Contribution name (e.g. provider `anthropic`, compactor `summarize`). */
+  readonly name: string;
+  /** Whether this item is the active default for its category. */
+  readonly isDefault: boolean;
+}
+
+/**
+ * One registry category in {@link PluginsAdminView.categories} — the active
+ * default plus the available items to swap between. Powers the per-category
+ * tabs in the `/plugins` picker and the `list_defaults` tool.
+ */
+export interface CategoryView {
+  /** Registry kind, e.g. `provider` | `compactor` | `mode`. */
+  readonly category: string;
+  /** Active default contribution name, or null when the category is empty. */
+  readonly active: string | null;
+  /** The protected floor's name (never disableable), or null when none. */
+  readonly floor: string | null;
+  /** Swappable contributions registered for this category. */
+  readonly items: ReadonlyArray<CategoryItemView>;
 }
 
 /**
@@ -301,12 +332,24 @@ export interface LoadedPluginView {
 export interface PluginsAdminView {
   /** Currently-loaded plugins with their contribution kinds (for kind tabs). */
   loaded(): ReadonlyArray<LoadedPluginView>;
-  /** Package names currently disabled (config `plugins[name].enabled=false`). */
+  /** Package names currently disabled (config `plugins.packages[name].enabled=false`). */
   disabled(): ReadonlyArray<string>;
+  /** Kernel package names that cannot be disabled (swap their default instead). */
+  protectedPackages(): ReadonlyArray<string>;
   /** Curated installable-plugin catalog for the picker's "Installable" tab. */
   catalog(): ReadonlyArray<InstallablePluginView>;
-  /** Persist `plugins[name].enabled` AND apply it to the live session. */
+  /** Persist `plugins.packages[name].enabled` AND apply it to the live session. */
   setEnabled(packageName: string, enabled: boolean): Promise<void>;
+  /**
+   * Per-category active default + swappable items (the swap axis). Powers the
+   * `/plugins` category tabs and the `list_defaults` tool.
+   */
+  categories(): ReadonlyArray<CategoryView>;
+  /**
+   * Persist `plugins.<category>.default` AND apply it to the live session
+   * (`setActive`). Rejects an unknown category or an unregistered name.
+   */
+  setCategoryDefault(category: string, name: string): Promise<void>;
 }
 
 /**

package/src/stuck-loop.test.ts

@@ -3,7 +3,7 @@ import { createStuckLoopDetector, stableHash } from './mode-helpers.js';
 
 describe('createStuckLoopDetector', () => {
   it('trips on exact-input repeats at repeatThreshold', () => {
-    const d = createStuckLoopDetector(); // repeatThreshold 3
+    const d = createStuckLoopDetector({ repeatThreshold: 3 });
     const input = { x: 1 };
     expect(d.record('Read', input).stuck).toBe(false);
     expect(d.record('Read', input).stuck).toBe(false);
@@ -11,8 +11,21 @@ describe('createStuckLoopDetector', () => {
     expect(sig).toMatchObject({ stuck: true, count: 3, kind: 'exact' });
   });
 
+  it('uses a generous default exact threshold (does not trip on a few repeats)', () => {
+    const d = createStuckLoopDetector(); // default repeatThreshold = 8
+    const input = { x: 1 };
+    for (let i = 0; i < 7; i++) expect(d.record('Read', input).stuck).toBe(false);
+    expect(d.record('Read', input).stuck).toBe(true); // 8th identical call trips
+  });
+
+  it('never trips when disabled (relies on maxIterations alone)', () => {
+    const d = createStuckLoopDetector({ enabled: false, repeatThreshold: 2 });
+    const input = { x: 1 };
+    for (let i = 0; i < 20; i++) expect(d.record('Read', input).stuck).toBe(false);
+  });
+
   it('trips on same-target near-dups even when volatile args vary', () => {
-    const d = createStuckLoopDetector(); // nearThreshold 5
+    const d = createStuckLoopDetector({ repeatThreshold: 3 }); // nearThreshold → 5
     const url = 'https://example.com/big';
     // Same url, different maxBytes each time — exact check never fires.
     for (let i = 0; i < 4; i++) {
@@ -44,7 +57,7 @@ describe('createStuckLoopDetector', () => {
   // dispatch path; a throw there crashes the whole turn. These assert it stays
   // total on hostile/partial input — the worst case the provider can hand us.
   it('does not throw recording a tool input with a circular reference', () => {
-    const d = createStuckLoopDetector();
+    const d = createStuckLoopDetector({ repeatThreshold: 3 });
     const input: Record<string, unknown> = { a: 1 };
     input.self = input;
     expect(() => d.record('weird', input)).not.toThrow();

package/src/tool-dispatch.ts

@@ -37,6 +37,7 @@ export async function* dispatchToolCall(
       cwd: ctx.cwd,
       log: ctx.log,
       env: ctx.env,
+      services: ctx.services,
       turnId: ctx.turnId,
       iteration,
       call: { callId: asToolCallId(t.id), name: t.name, input: t.input },