@moxxy/sdk 0.26.0 → 0.28.0

package/src/mode/stuck-loop.ts

@@ -32,6 +32,13 @@ export interface StuckLoopDetector {
   readonly repeatThreshold: number;
   /** Record the call and report whether the loop guard should trip. */
   record(toolName: string, input: unknown): StuckSignal;
+  /**
+   * Clear both sliding windows. Used by the nudge (steer-don't-stop) stuck
+   * policy: after a trip is surfaced to the model, the detector starts a fresh
+   * episode — otherwise every subsequent call inside the still-full window
+   * would re-trip and re-nudge on each iteration.
+   */
+  reset(): void;
 }
 
 /**
@@ -102,5 +109,9 @@ export function createStuckLoopDetector(opts: LoopGuardSettings = {}): StuckLoop
       }
       return { stuck: false, count: Math.max(exactCount, nearCount), kind: 'exact' };
     },
+    reset(): void {
+      recent.length = 0;
+      recentNear.length = 0;
+    },
   };
 }

package/src/mode-helpers.ts

@@ -9,6 +9,8 @@
  *  - `./mode/single-shot.ts`      — single-shot (no-tools) provider turn
  *  - `./mode/stuck-loop.ts`       — sliding-window stuck-tool-call detector
  *  - `./mode/stable-hash.ts`      — key-order-canonical input hash util
+ *  - `./mode/react-loop.ts`       — the shared ReAct loop core (+ checkpoint gate)
+ *  - `./mode/checkpoint.ts`       — turn-end checkpoint contract
  */
 
 export {
@@ -33,3 +35,17 @@ export {
   type LoopGuardSettings,
 } from './mode/stuck-loop.js';
 export { stableHash } from './mode/stable-hash.js';
+export {
+  runReactLoop,
+  MAX_CONSECUTIVE_RETRIES,
+  __setRetrySleepForTests,
+  type ReactLoopOptions,
+  type ProviderSuccessInfo,
+  type ToolBatchInfo,
+  type StopDirective,
+} from './mode/react-loop.js';
+export type {
+  CheckpointContext,
+  CheckpointResult,
+  TurnCheckpoint,
+} from './mode/checkpoint.js';

package/src/mode.ts

@@ -46,6 +46,13 @@ export interface PluginHostHandle {
     kinds?: ReadonlyArray<string>;
   }>;
   reload(): Promise<void>;
+  /**
+   * The plugin (package) that contributed the named tool, or undefined for
+   * unknown / dynamically-attached tools. Optional so a thin-client
+   * `RemoteSession` can omit it; powers plugin-level security routing
+   * (`security.perPlugin`) and package-scoped audit views.
+   */
+  ownerOfTool?(toolName: string): string | undefined;
 }
 
 /**
@@ -124,14 +131,33 @@ export interface ModeContext {
    * Absent in synthetic test contexts that don't model a full Session.
    */
   readonly subagents?: SubagentSpawner;
+  /**
+   * True when this context belongs to a spawned child agent (set by the
+   * subagent runtime). The shared ReAct loop disarms turn-end checkpoints in
+   * subagent sessions — the recursion backstop that keeps a checkpoint which
+   * (mistakenly) spawns a child in a checkpoint-bearing mode from gating the
+   * child's turn-end and recursing forever.
+   */
+  readonly isSubagent?: boolean;
   /**
    * Request the session switch its active mode AFTER this turn fully drains.
    * Used by terminal workflow modes (BMAD finishing its last phase) to hand
    * control back to a normal mode so the next message isn't trapped in the
-   * workflow. The switch is applied post-turn by the runner; an unknown /
-   * unregistered mode name is ignored. Absent in synthetic test contexts.
+   * workflow, and by {@link ModeDef.transient} modes (goal) to disarm
+   * themselves once their objective concludes. The switch is applied
+   * post-turn by the runner; an unknown / unregistered mode name is ignored.
+   * Absent in synthetic test contexts.
    */
   readonly requestModeSwitch?: (modeName: string) => void;
+  /**
+   * Name of the mode that was active before the current one (per the mode
+   * registry), when known. Lets a {@link ModeDef.transient} mode hand control
+   * back to whatever the user was in before arming it (`/goal` from research
+   * mode reverts to research, not blindly to default). Absent when the
+   * registry has no history (first mode of the session) or in synthetic test
+   * contexts — callers should fall back to `'default'`.
+   */
+  readonly previousModeName?: string;
   emit(event: EmittedEvent): Promise<MoxxyEvent>;
 }
 
@@ -218,6 +244,21 @@ export interface ModeDef {
    * more later) opt in the same way. See {@link isSelectableMode}.
    */
   readonly special?: ModeSpecial;
+  /**
+   * Marks a mode that arms for a SINGLE objective rather than becoming the
+   * session's standing behavior (goal mode). Uniformly across surfaces:
+   *
+   *   - it is never persisted as the category default (`plugins.mode.default`)
+   *     — `/goal` once must not make every future session boot autonomous;
+   *   - a persisted/config default naming it is refused at boot (the
+   *     protected default stays active instead);
+   *   - the mode itself is expected to hand control back (via
+   *     `ctx.requestModeSwitch`, typically to `ctx.previousModeName`) when
+   *     its objective concludes.
+   *
+   * Switching INTO it (picker, `/goal`, `setMode` RPC) still works normally.
+   */
+  readonly transient?: boolean;
   run(ctx: ModeContext): AsyncIterable<MoxxyEvent>;
 }
 

package/src/plugin.ts

@@ -17,8 +17,9 @@ 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';
+import type { ReflectorDef } from './reflector.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' | 'event-store';
+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' | 'reflector';
 
 export interface PluginSpec {
   readonly name: string;
@@ -53,6 +54,14 @@ export interface PluginSpec {
    * boundary, since the store sees every event). See {@link EventStoreDef}.
    */
   readonly eventStores?: ReadonlyArray<EventStoreDef>;
+  /**
+   * Reflector backends — the learning-loop block that watches a finished turn
+   * and *proposes* memory/skill improvements without silently writing. One
+   * active at a time, selected via `plugins.reflector.default`. NULLABLE: core
+   * seeds no floor, so reflection is opt-in — no registered reflector means the
+   * session never reflects. See {@link ReflectorDef}.
+   */
+  readonly reflectors?: ReadonlyArray<ReflectorDef>;
   readonly channels?: ReadonlyArray<ChannelDef>;
   /**
    * Interactive surfaces contributed by the plugin — long-lived panes a human

package/src/reflector.ts

@@ -0,0 +1,61 @@
+import type { EventLogReader } from './log.js';
+import type { SessionId, TurnId } from './ids.js';
+import type { ServiceRegistry } from './services.js';
+
+/**
+ * The learning-loop block — a swappable strategy that watches a finished turn
+ * and *proposes* (never silently writes) memory/skill improvements. It is the
+ * def-only sibling of the other single-active registries (compactor, cache
+ * strategy, …) but NULLABLE: core seeds NO floor, so reflection is entirely
+ * opt-in — a session with no registered reflector simply never reflects.
+ *
+ * The trust boundary is the "propose, don't write" contract. A reflector reads
+ * the turn's events and returns {@link ReflectionProposal}s; the driver that
+ * hosts it delivers those as a one-time nudge on the next provider call, phrased
+ * so the *model* may choose to call `memory_save` / `synthesize_skill` — which
+ * still go through the existing permission prompts. Nothing a reflector returns
+ * mutates memory or skills on its own.
+ */
+
+/**
+ * The context handed to {@link ReflectorDef.reflect}. Scoped to one finished
+ * turn: `log.byTurn(turnId)` yields exactly that turn's events. `services`
+ * exposes the host's inter-plugin registry (e.g. `services.get('providers')`
+ * for a side-channel LLM pass); `signal` bounds the whole reflection (a timeout
+ * and/or session shutdown) so a slow provider can never wedge it.
+ */
+export interface ReflectContext {
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly cwd: string;
+  readonly log: EventLogReader;
+  readonly services: ServiceRegistry;
+  readonly signal: AbortSignal;
+}
+
+/**
+ * One improvement a reflector suggests. `kind` picks the target surface
+ * (`'memory'` → a fact worth `memory_save`; `'skill'` → a repeated procedure
+ * worth `synthesize_skill`); `title` is a short label; `nudge` is a
+ * one-paragraph suggestion addressed to the assistant. A proposal is a HINT,
+ * not a command — the model decides whether to act, and any resulting write
+ * still hits its own permission prompt.
+ */
+export interface ReflectionProposal {
+  readonly kind: 'memory' | 'skill';
+  readonly title: string;
+  /** One-paragraph suggestion addressed to the assistant. */
+  readonly nudge: string;
+}
+
+/**
+ * A registered reflector backend. `reflect` inspects the just-finished turn and
+ * returns 0 or more proposals (an empty array = "nothing worth suggesting").
+ * It MUST be side-effect-free with respect to memory/skills — it only reads and
+ * proposes — and MUST honor `ctx.signal` (abort/timeout).
+ */
+export interface ReflectorDef {
+  readonly name: string;
+  readonly displayName?: string;
+  reflect(ctx: ReflectContext): Promise<ReadonlyArray<ReflectionProposal>>;
+}

package/src/schemas.ts

@@ -16,6 +16,7 @@ const pluginKindSchema = z.enum([
   'command',
   'transcriber',
   'synthesizer',
+  'reflector',
 ]);
 
 export const requirementSchema = z.object({
@@ -89,11 +90,51 @@ export const pluginManifestSchema = z.object({
  *   requirements may be authored; per-tool/per-transcriber/per-anything
  *   runtime declarations were removed in favor of static analysis.
  */
+/**
+ * One field of a plugin's declarative setup step (`package.json#moxxy.setup`).
+ * Declarative-only so EVERY frontend (the init wizard, the TUI, desktop
+ * onboarding) can render it without executing plugin code:
+ * - `secret` values land in the VAULT (never plaintext config); the plugin's
+ *   `options.<key>` gets a `${vault:<name>}` ref, resolved at boot.
+ * - other kinds land at `plugins.packages.<pkg>.options.<key>` in the user
+ *   config through the shared schema-validated writer.
+ */
+export const pluginSetupFieldSchema = z.object({
+  key: z.string().min(1).regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, 'key must be an identifier'),
+  label: z.string().min(1),
+  description: z.string().optional(),
+  kind: z.enum(['secret', 'string', 'boolean', 'select']),
+  /** Vault entry name for `secret` fields. Default: `<PKG>_<KEY>` upper-snake. */
+  vaultKey: z.string().min(1).optional(),
+  /** Choices for `select` fields. */
+  options: z.array(z.string().min(1)).optional(),
+  /** Required fields block completion; optional ones may stay unset. */
+  required: z.boolean().optional(),
+  placeholder: z.string().optional(),
+});
+
+/**
+ * A plugin's declarative configuration step, walked by `moxxy init` (and
+ * surfaced after an on-demand install). `required: true` means the plugin is
+ * left DISABLED until its required fields are provided — the author's way to
+ * say "this cannot work unconfigured".
+ */
+export const pluginSetupSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  fields: z.array(pluginSetupFieldSchema).min(1),
+});
+
 export const moxxyPackageSchema = z.object({
   plugin: pluginManifestSchema.optional(),
   requirements: z.array(requirementSchema).optional(),
+  /** Declarative setup step users walk through in init / post-install. */
+  setup: pluginSetupSchema.optional(),
 });
 
+export type PluginSetupField = z.infer<typeof pluginSetupFieldSchema>;
+export type PluginSetupSpec = z.infer<typeof pluginSetupSchema>;
 export type SkillFrontmatterInput = z.infer<typeof skillFrontmatterSchema>;
 export type PluginManifestInput = z.infer<typeof pluginManifestSchema>;
 export type MoxxyPackageInput = z.infer<typeof moxxyPackageSchema>;

package/src/session-like.ts

@@ -1,9 +1,11 @@
 import type { MoxxyEvent, TriggerOrigin, UserPromptAttachment } from './events.js';
 import type { SessionId, TurnId } from './ids.js';
+import type { CapabilitySpec } from './isolation.js';
 import type { EventLogReader } from './log.js';
 import type { ApprovalResolver, ModeBadge } from './mode.js';
 import type { PermissionResolver } from './permission.js';
 import type { ModelDescriptor, ProviderKeyValidation } from './provider.js';
+import type { PluginSetupSpec } from './schemas.js';
 import type { ToolCompactPresentation } from './tool.js';
 
 /**
@@ -365,7 +367,42 @@ export interface PluginsAdminView {
   install?(idOrSpec: string): Promise<{
     readonly installed: string;
     readonly registered: Readonly<Partial<Record<string, ReadonlyArray<string>>>>;
+    /**
+     * Combined capability surface of the tools this install registered —
+     * the package's blast radius, so a channel can render post-install
+     * consent (third-party packages) or an info line (first-party). Absent
+     * when the install registered no tools or the host cannot introspect
+     * isolation specs.
+     */
+    readonly capabilities?: {
+      /** Tools that declared an isolation spec. */
+      readonly declared: number;
+      /** Tools the install registered. */
+      readonly total: number;
+      /** Widest-wins union of the declared specs. */
+      readonly surface: CapabilitySpec;
+      /** Tools with NO declaration: their surface is unknown, not empty. */
+      readonly undeclaredTools?: ReadonlyArray<string>;
+    };
+    /** Present when the package declares a `moxxy.setup` step to complete. */
+    readonly needsSetup?: { readonly title: string; readonly required: boolean };
   }>;
+  /**
+   * The package's declarative setup step (`moxxy.setup`), read from its
+   * installed package.json — plain data, safe to render anywhere. Null when
+   * absent. Powers the post-install dialog and `/setup`.
+   */
+  setupSpec?(packageName: string): Promise<PluginSetupSpec | null>;
+  /**
+   * Persist collected setup values: secrets → vault + `${vault:NAME}` option
+   * ref; other kinds → `plugins.packages.<pkg>.options.<key>`. A complete
+   * required setup re-enables the package; an incomplete one disables it
+   * (mirrors the init wizard). Optional capability per the seam convention.
+   */
+  applySetup?(
+    packageName: string,
+    values: Readonly<Record<string, string | boolean>>,
+  ): Promise<{ readonly complete: boolean; readonly missing: ReadonlyArray<string> }>;
 }
 
 /** IO a channel supplies to drive an interactive OAuth flow inside its own
@@ -470,4 +507,16 @@ export interface SessionLike {
   pluginsAdmin?: PluginsAdminView;
   /** Provider onboarding slice backing in-channel connect (key entry / OAuth). */
   providerSetup?: ProviderSetupView;
+  /**
+   * Re-read the merged config from disk and live-apply the safe subset —
+   * backs the TUI /settings panel's write-then-apply. Structurally matches
+   * @moxxy/config's ConfigApplyResult (the SDK stays config-free). Absent on
+   * a RemoteSession: writes still land, but apply waits for a restart.
+   */
+  configAdmin?: {
+    apply(): Promise<{
+      readonly applied: ReadonlyArray<string>;
+      readonly pending: ReadonlyArray<string>;
+    }>;
+  };
 }

package/src/tool-dispatch.test.ts

@@ -9,7 +9,10 @@ import {
   dispatchToolCall,
   executeToolUses,
   emitRequestsAndDetectStuck,
+  emitRequestsAndNudgeOnStuck,
   type StuckLoopReport,
+  type StuckNudgeReport,
+  type StuckTripInfo,
 } from './tool-dispatch.js';
 
 /**
@@ -213,3 +216,77 @@ describe('emitRequestsAndDetectStuck — stuck trip', () => {
     expect(events.filter((e) => e.type === 'tool_result')).toHaveLength(0);
   });
 });
+
+describe('emitRequestsAndNudgeOnStuck — steer, never stop', () => {
+  const nudgeReport: StuckNudgeReport = {
+    nearHint: 'with nearly identical input',
+    warnMessage: ({ toolName, count }) => `repetitive: ${toolName} x${count}`,
+    extraOnStuck: ({ toolName }) => [
+      {
+        type: 'plugin_event',
+        sessionId: asSessionId('s1'),
+        turnId: asTurnId('t1'),
+        source: 'plugin',
+        pluginId: 'test' as never,
+        subtype: 'test_stuck',
+        payload: { toolName },
+      },
+    ],
+  };
+
+  function nudgeDetector(trip: StuckSignal): StuckLoopDetector & { resets: number } {
+    const d = {
+      resets: 0,
+      record: () => trip,
+      reset: () => {
+        d.resets += 1;
+      },
+    };
+    return d as unknown as StuckLoopDetector & { resets: number };
+  }
+
+  it('on a trip: warns (retryable, not fatal), emits extra events, resets the detector, and does NOT synthesize results', async () => {
+    const { ctx, events } = makeCtx();
+    const det = nudgeDetector({ stuck: true, kind: 'exact', count: 8 });
+    const trip = (await drain(
+      emitRequestsAndNudgeOnStuck(ctx, [tool], det, nudgeReport),
+    )) as StuckTripInfo | null;
+
+    // Trip info is returned for the loop's volatile nudge…
+    expect(trip).toEqual({ toolName: 'Read', count: 8, kind: 'exact', how: 'with identical input' });
+    // …the detector started a fresh episode…
+    expect(det.resets).toBe(1);
+    // …the request stands (the batch will execute — no synthesized results)…
+    expect(events.some((e) => e.type === 'tool_call_requested')).toBe(true);
+    expect(events.filter((e) => e.type === 'tool_result')).toHaveLength(0);
+    // …the warning is visible but NON-fatal, with the extra event before it.
+    const err = events.find((e) => e.type === 'error') as
+      | { kind: string; message: string }
+      | undefined;
+    expect(err?.kind).toBe('retryable');
+    expect(err?.message).toBe('repetitive: Read x8');
+    expect(events.some((e) => e.type === 'plugin_event' && e.subtype === 'test_stuck')).toBe(true);
+  });
+
+  it('a near trip uses the report nearHint wording', async () => {
+    const { ctx } = makeCtx();
+    const trip = (await drain(
+      emitRequestsAndNudgeOnStuck(
+        ctx,
+        [tool],
+        nudgeDetector({ stuck: true, kind: 'near', count: 5 }),
+        nudgeReport,
+      ),
+    )) as StuckTripInfo | null;
+    expect(trip?.how).toBe('with nearly identical input');
+  });
+
+  it('returns null and stays quiet when the detector does not trip', async () => {
+    const { ctx, events } = makeCtx();
+    const det = nudgeDetector({ stuck: false, kind: 'exact', count: 0 });
+    const trip = await drain(emitRequestsAndNudgeOnStuck(ctx, [tool], det, nudgeReport));
+    expect(trip).toBeNull();
+    expect(det.resets).toBe(0);
+    expect(events.filter((e) => e.type !== 'tool_call_requested')).toHaveLength(0);
+  });
+});

package/src/tool-dispatch.ts

@@ -2,7 +2,11 @@ import { asToolCallId } from './ids.js';
 import type { EmittedEvent, MoxxyEvent } from './events.js';
 import type { ModeContext } from './mode.js';
 import type { ToolCallVerdict } from './hooks.js';
-import type { CollectedToolUse, StuckLoopDetector, StuckSignal } from './mode-helpers.js';
+// Import the concrete modules, not the './mode-helpers.js' barrel: the barrel
+// re-exports the ReAct loop core, which imports THIS file — going through the
+// barrel here closes that loop into a real import cycle.
+import type { CollectedToolUse } from './mode/collect-stream.js';
+import type { StuckLoopDetector, StuckSignal } from './mode/stuck-loop.js';
 
 /**
  * Execute a single tool-use end-to-end: dispatch `dispatchToolCall` hooks, run
@@ -282,3 +286,80 @@ export async function* emitRequestsAndDetectStuck(
   }
   return false;
 }
+
+/** A stuck-detector trip, as surfaced to the nudge policy. */
+export interface StuckTripInfo {
+  readonly toolName: string;
+  readonly count: number;
+  readonly kind: StuckSignal['kind'];
+  /** Human phrasing of HOW it repeated ("with identical input" / the near hint). */
+  readonly how: string;
+}
+
+/** Wording + extra events for {@link emitRequestsAndNudgeOnStuck}. */
+export interface StuckNudgeReport {
+  /** Explanation for a `near` match (an `exact` match always reads
+   *  "with identical input"). */
+  readonly nearHint: string;
+  /** Build the visible (non-fatal) warning surfaced to the user on a trip. */
+  readonly warnMessage: (info: StuckTripInfo) => string;
+  /** Extra events to emit right before the warning — goal mode surfaces a
+   *  `goal_stuck` plugin_event here. */
+  readonly extraOnStuck?: StuckLoopReport['extraOnStuck'];
+}
+
+/**
+ * The steer-don't-stop counterpart of {@link emitRequestsAndDetectStuck}: emit
+ * a `tool_call_requested` per call and feed the detector, but a trip NEVER
+ * aborts the turn — the batch still executes (the repeated calls are usually
+ * legitimate work, e.g. re-running a failing build between edits). Instead the
+ * trip is surfaced as a visible warning + the report's extra events, the
+ * detector is reset (fresh episode — no re-trip on every subsequent call while
+ * the window is still full), and the trip info is returned so the loop can
+ * steer the model with a volatile nudge on its next provider call.
+ *
+ * Used by modes that must never kill an unattended run on a repetition
+ * heuristic (goal mode). Returns the first trip of the batch, or null.
+ */
+export async function* emitRequestsAndNudgeOnStuck(
+  ctx: ModeContext,
+  toolUses: ReadonlyArray<CollectedToolUse>,
+  detector: StuckLoopDetector,
+  report: StuckNudgeReport,
+): AsyncGenerator<MoxxyEvent, StuckTripInfo | null, unknown> {
+  let trip: StuckTripInfo | null = null;
+  for (const t of toolUses) {
+    yield await ctx.emit({
+      type: 'tool_call_requested',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'model',
+      callId: asToolCallId(t.id),
+      name: t.name,
+      input: t.input,
+    });
+    const sig = detector.record(t.name, t.input);
+    if (!sig.stuck || trip) continue;
+    trip = {
+      toolName: t.name,
+      count: sig.count,
+      kind: sig.kind,
+      how: sig.kind === 'near' ? report.nearHint : 'with identical input',
+    };
+    detector.reset();
+    if (report.extraOnStuck) {
+      for (const e of report.extraOnStuck({ toolName: t.name, count: sig.count, kind: sig.kind })) {
+        yield await ctx.emit(e);
+      }
+    }
+    yield await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: 'retryable',
+      message: report.warnMessage(trip),
+    });
+  }
+  return trip;
+}