@moxxy/sdk 0.18.0 → 0.20.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.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

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

@@ -1,4 +1,4 @@
-import type { MoxxyEvent, UserPromptAttachment } from './events.js';
+import type { MoxxyEvent, TriggerOrigin, UserPromptAttachment } from './events.js';
 import type { SessionId, TurnId } from './ids.js';
 import type { EventLogReader } from './log.js';
 import type { ApprovalResolver, ModeBadge } from './mode.js';
@@ -22,6 +22,13 @@ export interface RunTurnOptions {
   readonly signal?: AbortSignal;
   /** Inline attachments shipped alongside the prompt (images, audio, stdin). */
   readonly attachments?: ReadonlyArray<UserPromptAttachment>;
+  /**
+   * Provenance for a machine-initiated turn (a fired webhook/schedule/workflow).
+   * Stamped onto the resulting {@link UserPromptEvent} so renderers show a
+   * compact "trigger fired" marker instead of the raw synthesized prompt. Omit
+   * for an ordinary user-typed turn.
+   */
+  readonly origin?: TriggerOrigin;
   /**
    * Pre-minted turn id. When omitted, `runTurn` mints one. The runner passes
    * this so it can return the id to the client *before* the turn starts and
@@ -191,6 +198,12 @@ export interface WorkflowSummaryView {
   readonly steps: number;
   /** Human-readable trigger summary, e.g. `cron(0 8 * * *)` or `on-demand`. */
   readonly triggers: string;
+  /**
+   * Session this workflow's triggered runs are pinned to (where they run +
+   * display), or null when unpinned. Optional for wire back-compat — an older
+   * runner omits it; the desktop treats absent as null.
+   */
+  readonly targetSessionId?: string | null;
 }
 
 /** Result of running a workflow from the modal. */
@@ -278,6 +291,30 @@ export interface LoadedPluginView {
   readonly kinds: ReadonlyArray<string>;
 }
 
+/** 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>;
+}
+
 /**
  * The slice of plugin management a channel needs to drive the `/plugins`
  * picker: which plugins are disabled, what's installable, and a persist+
@@ -288,12 +325,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 },

package/src/workflow.ts

@@ -151,6 +151,26 @@ export interface Workflow {
   readonly enabled: boolean;
   readonly inputs: Record<string, WorkflowInputSpec>;
   readonly on?: WorkflowTrigger;
+  /**
+   * Pin this workflow's *triggered* runs (schedule / fileChanged / afterWorkflow)
+   * to one chosen runner's session — identified by that runner's
+   * `MOXXY_SESSION_ID` — so the run executes and displays in the session the user
+   * picked. On the desktop, one `moxxy serve` runner == one session.
+   *
+   * - schedule: the scheduler mirror row is stamped with this as its owner, so the
+   *   existing poller owner-gate fires the run on the target runner.
+   * - fileChanged: only the runner whose id matches watches/fires the trigger. If
+   *   that runner is offline when the file changes, the event is missed — there is
+   *   no fs-event replay (unlike webhooks/schedules, which catch up).
+   * - afterWorkflow: a dependent pinned to a *different* session than the runner
+   *   that observed the parent's completion is skipped (the completion event is
+   *   in-process); co-locate the chain or use a schedule trigger for fan-out.
+   *
+   * Unset (the default) preserves today's ambient behavior: triggered runs fire
+   * once across runners via the cross-process lock. Ignored in single-process
+   * CLI/TUI (no `MOXXY_SESSION_ID`).
+   */
+  readonly targetSessionId?: string;
   readonly delivery?: WorkflowDelivery;
   /** GUI-only metadata persisted with the YAML artifact. */
   readonly ui?: WorkflowUi;