@moxxy/sdk 0.26.0 → 0.27.0

package/src/exit-after-pair.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { EXIT_AFTER_PAIR_FLAG, exitAfterPairRequested } from './channel.js';
+
+function ctx(
+  flags: Record<string, string | boolean | undefined>,
+  options?: Record<string, unknown>,
+): Parameters<typeof exitAfterPairRequested>[0] {
+  return {
+    args: { positional: [], flags },
+    deps: { cwd: '/tmp', ...(options ? { options } : {}) },
+  };
+}
+
+describe('exitAfterPairRequested', () => {
+  it('defaults to false (standalone pair keeps the channel running)', () => {
+    expect(exitAfterPairRequested(ctx({}))).toBe(false);
+  });
+
+  it('honors the flag via args.flags', () => {
+    expect(exitAfterPairRequested(ctx({ [EXIT_AFTER_PAIR_FLAG]: true }))).toBe(true);
+  });
+
+  it('honors the flag via deps.options (programmatic callers)', () => {
+    expect(exitAfterPairRequested(ctx({}, { [EXIT_AFTER_PAIR_FLAG]: true }))).toBe(true);
+  });
+
+  it('requires boolean true — a string "true" flag is not an opt-in', () => {
+    // argv flags are string|boolean; only an explicit boolean true counts, so
+    // `--exit-after-pair=weird` values can't accidentally change lifecycle.
+    expect(exitAfterPairRequested(ctx({ [EXIT_AFTER_PAIR_FLAG]: 'true' }))).toBe(false);
+  });
+});

package/src/first-party.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { FIRST_PARTY_PLUGIN_SCOPE, isFirstPartyPackage } from './first-party.js';
+
+describe('isFirstPartyPackage (third-party detection)', () => {
+  it('accepts packages under the @moxxy scope', () => {
+    expect(isFirstPartyPackage('@moxxy/plugin-channel-slack')).toBe(true);
+    expect(isFirstPartyPackage('@moxxy/sdk')).toBe(true);
+  });
+
+  it('rejects bare (unscoped) packages', () => {
+    expect(isFirstPartyPackage('left-pad')).toBe(false);
+    expect(isFirstPartyPackage('moxxy-plugin-evil')).toBe(false);
+  });
+
+  it('rejects other scopes, including lookalikes', () => {
+    expect(isFirstPartyPackage('@moxxyy/plugin-x')).toBe(false);
+    expect(isFirstPartyPackage('@moxxy-plugins/x')).toBe(false);
+    expect(isFirstPartyPackage('@evil/moxxy')).toBe(false);
+  });
+
+  it('rejects a scope-only prefix trick (@moxxy without the slash)', () => {
+    // `@moxxy` alone is not under the scope: the slash is part of the prefix.
+    expect(FIRST_PARTY_PLUGIN_SCOPE.endsWith('/')).toBe(true);
+    expect(isFirstPartyPackage('@moxxy')).toBe(false);
+  });
+});

package/src/first-party.ts

@@ -0,0 +1,19 @@
+/**
+ * The npm scope every first-party moxxy package lives under. First-party
+ * packages are the trusted, co-versioned set (published together via the
+ * fixed changeset group); anything outside this scope is third-party code
+ * the user pulled in from the registry and gets stricter treatment:
+ * post-install capability consent and the `thirdPartyRequireDeclaration`
+ * ratchet in `@moxxy/plugin-security`.
+ */
+export const FIRST_PARTY_PLUGIN_SCOPE = '@moxxy/';
+
+/**
+ * Whether a package name belongs to the trusted first-party scope. The input
+ * is a bare npm package name (`@moxxy/plugin-x`, `some-plugin`) — pass names,
+ * not install specs (`name@1.2.3` would still work, but git/path specs are
+ * not names and should be resolved to one first).
+ */
+export function isFirstPartyPackage(packageName: string): boolean {
+  return packageName.startsWith(FIRST_PARTY_PLUGIN_SCOPE);
+}

package/src/index.ts

@@ -117,7 +117,9 @@ export type {
   Isolator,
   HandlerModuleRef,
 } from './isolation.js';
-export { ISOLATION_RANK } from './isolation.js';
+export { ISOLATION_RANK, aggregateCapabilitySpecs } from './isolation.js';
+
+export { FIRST_PARTY_PLUGIN_SCOPE, isFirstPartyPackage } from './first-party.js';
 
 export type {
   SubagentSpec,
@@ -190,6 +192,12 @@ export type {
   SessionMeta,
   SessionSource,
 } from './event-store.js';
+export { SESSION_SOURCES } from './event-store.js';
+export type {
+  ReflectorDef,
+  ReflectContext,
+  ReflectionProposal,
+} from './reflector.js';
 // Node-runtime helpers (writeFileAtomic*, moxxyHome/moxxyPath,
 // readRequestBody/bearerTokenMatches, channel-auth) are exported from the
 // './server' subpath, NOT the main barrel — they statically reach node:*
@@ -228,6 +236,11 @@ export {
   type MoxxyErrorCode,
   type MoxxyErrorInit,
 } from './errors.js';
+// Shared retry primitives: a leak-safe, abort-aware sleep + the exponential
+// back-off schedule. General-purpose — not mode-loop internals: the runner's
+// connect retry and the desktop supervisor's restart wait use them too, so
+// don't reimplement an ad-hoc `new Promise(setTimeout)` back-off elsewhere.
+export { sleepWithAbort, nextBackoffMs } from './mode/abort-backoff.js';
 export {
   collectProviderStream,
   runSingleShotTurn,
@@ -236,8 +249,6 @@ export {
   buildSystemPromptWithSkills,
   createStuckLoopDetector,
   stableHash,
-  sleepWithAbort,
-  nextBackoffMs,
   type CollectedToolUse,
   type StreamResult,
   type ProjectMessagesOptions,
@@ -367,7 +378,7 @@ export type {
   ResolvedPluginManifest,
 } from './plugin.js';
 
-export { startChannelWith } from './channel.js';
+export { startChannelWith, EXIT_AFTER_PAIR_FLAG, exitAfterPairRequested } from './channel.js';
 export type {
   Channel,
   ChannelHandle,
@@ -458,10 +469,14 @@ export {
   skillFrontmatterSchema,
   pluginManifestSchema,
   moxxyPackageSchema,
+  pluginSetupFieldSchema,
+  pluginSetupSchema,
   requirementSchema,
   type SkillFrontmatterInput,
   type PluginManifestInput,
   type MoxxyPackageInput,
+  type PluginSetupField,
+  type PluginSetupSpec,
 } from './schemas.js';
 
 export {

package/src/isolation-aggregate.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { aggregateCapabilitySpecs, type CapabilitySpec } from './isolation.js';
+
+describe('aggregateCapabilitySpecs', () => {
+  it('empty / all-undefined input aggregates to an empty surface', () => {
+    expect(aggregateCapabilitySpecs([])).toEqual({});
+    expect(aggregateCapabilitySpecs([undefined, undefined])).toEqual({});
+  });
+
+  it('unions fs globs, env, and commands (sorted, deduped)', () => {
+    const a: CapabilitySpec = {
+      fs: { read: ['$cwd/**', '/tmp/**'], write: ['/tmp/**'] },
+      env: ['PATH', 'HOME'],
+      subprocess: true,
+      commands: ['npm'],
+    };
+    const b: CapabilitySpec = {
+      fs: { read: ['/tmp/**'] },
+      env: ['PATH'],
+      subprocess: true,
+      commands: ['git', 'npm'],
+    };
+    expect(aggregateCapabilitySpecs([a, b])).toEqual({
+      fs: { read: ['$cwd/**', '/tmp/**'], write: ['/tmp/**'] },
+      env: ['HOME', 'PATH'],
+      subprocess: true,
+      commands: ['git', 'npm'],
+    });
+  });
+
+  it('net takes the strongest mode: any > allowlist > none', () => {
+    const none: CapabilitySpec = { net: { mode: 'none' } };
+    const list: CapabilitySpec = { net: { mode: 'allowlist', hosts: ['b.com', 'a.com'] } };
+    const any: CapabilitySpec = { net: { mode: 'any' } };
+
+    expect(aggregateCapabilitySpecs([none])).toEqual({ net: { mode: 'none' } });
+    expect(aggregateCapabilitySpecs([none, list])).toEqual({
+      net: { mode: 'allowlist', hosts: ['a.com', 'b.com'] },
+    });
+    expect(aggregateCapabilitySpecs([list, any, none])).toEqual({ net: { mode: 'any' } });
+  });
+
+  it('merges allowlist hosts across specs', () => {
+    const a: CapabilitySpec = { net: { mode: 'allowlist', hosts: ['registry.npmjs.org'] } };
+    const b: CapabilitySpec = { net: { mode: 'allowlist', hosts: ['api.slack.com'] } };
+    expect(aggregateCapabilitySpecs([a, b])).toEqual({
+      net: { mode: 'allowlist', hosts: ['api.slack.com', 'registry.npmjs.org'] },
+    });
+  });
+
+  it('timeMs and memMb take the max; undeclared entries contribute nothing', () => {
+    const a: CapabilitySpec = { timeMs: 30_000, memMb: 128 };
+    const b: CapabilitySpec = { timeMs: 600_000 };
+    expect(aggregateCapabilitySpecs([a, undefined, b])).toEqual({
+      timeMs: 600_000,
+      memMb: 128,
+    });
+  });
+
+  it('an "any" net dropped into a wide union does not resurrect allowlist hosts', () => {
+    // Regression guard: once mode is 'any', collected hosts must not leak
+    // back into the result as a misleading narrower-looking allowlist.
+    const spec = aggregateCapabilitySpecs([
+      { net: { mode: 'allowlist', hosts: ['a.com'] } },
+      { net: { mode: 'any' } },
+    ]);
+    expect(spec.net).toEqual({ mode: 'any' });
+  });
+});

package/src/isolation.ts

@@ -146,3 +146,70 @@ export const ISOLATION_RANK: Readonly<Record<IsolationStrength, number>> = Objec
   wasm: 5,
   docker: 6,
 });
+
+/**
+ * Widest-wins union of capability declarations — the combined blast radius
+ * if every contributing tool exercised its full declared surface. Used for
+ * package-level views: `moxxy security audit --package`, the install-time
+ * capability report, and (later) signed-index capability manifests.
+ *
+ * Union semantics per axis: fs globs / env vars / commands are set-unions
+ * (sorted, deduped); net takes the strongest mode (`any` > `allowlist` with
+ * merged hosts > `none`); `subprocess` is an OR; `timeMs` / `memMb` take the
+ * max. `undefined` entries (undeclared tools) contribute nothing — callers
+ * report their count separately so a wide-open undeclared tool is never
+ * hidden behind a tidy aggregate.
+ */
+export function aggregateCapabilitySpecs(
+  specs: ReadonlyArray<CapabilitySpec | undefined>,
+): CapabilitySpec {
+  const read = new Set<string>();
+  const write = new Set<string>();
+  const env = new Set<string>();
+  const commands = new Set<string>();
+  const hosts = new Set<string>();
+  let netMode: NetCapability['mode'] | undefined;
+  let subprocess = false;
+  let timeMs: number | undefined;
+  let memMb: number | undefined;
+
+  for (const spec of specs) {
+    if (!spec) continue;
+    for (const g of spec.fs?.read ?? []) read.add(g);
+    for (const g of spec.fs?.write ?? []) write.add(g);
+    if (spec.net) {
+      if (spec.net.mode === 'any') netMode = 'any';
+      else if (spec.net.mode === 'allowlist') {
+        if (netMode !== 'any') netMode = 'allowlist';
+        for (const h of spec.net.hosts) hosts.add(h);
+      } else netMode ??= 'none';
+    }
+    for (const e of spec.env ?? []) env.add(e);
+    if (spec.subprocess) subprocess = true;
+    for (const c of spec.commands ?? []) commands.add(c);
+    if (spec.timeMs !== undefined) timeMs = Math.max(timeMs ?? 0, spec.timeMs);
+    if (spec.memMb !== undefined) memMb = Math.max(memMb ?? 0, spec.memMb);
+  }
+
+  const sorted = (s: Set<string>): string[] => [...s].sort();
+  return {
+    ...(read.size || write.size
+      ? {
+          fs: {
+            ...(read.size ? { read: sorted(read) } : {}),
+            ...(write.size ? { write: sorted(write) } : {}),
+          },
+        }
+      : {}),
+    ...(netMode === 'allowlist'
+      ? { net: { mode: 'allowlist' as const, hosts: sorted(hosts) } }
+      : netMode
+        ? { net: { mode: netMode } }
+        : {}),
+    ...(env.size ? { env: sorted(env) } : {}),
+    ...(timeMs !== undefined ? { timeMs } : {}),
+    ...(memMb !== undefined ? { memMb } : {}),
+    ...(subprocess ? { subprocess: true } : {}),
+    ...(commands.size ? { commands: sorted(commands) } : {}),
+  };
+}

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;
 }
 
 /**

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>;
+    }>;
+  };
 }