@moxxy/sdk 0.25.0 → 0.27.0

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 } from './provider.js';
+import type { ModelDescriptor, ProviderKeyValidation } from './provider.js';
+import type { PluginSetupSpec } from './schemas.js';
 import type { ToolCompactPresentation } from './tool.js';
 
 /**
@@ -281,6 +283,9 @@ export interface InstallablePluginView {
   readonly installSpec: string;
   readonly kind?: string;
   readonly startCommand?: string;
+  /** Registry contributions the package provides (category + name) — lets
+   *  surfaces offer install-on-first-use for a missing capability. */
+  readonly provides?: ReadonlyArray<{ readonly category: string; readonly name: string }>;
 }
 
 /** One loaded plugin in {@link PluginsAdminView.loaded}, grouped by `kinds`. */
@@ -350,6 +355,100 @@ export interface PluginsAdminView {
    * (`setActive`). Rejects an unknown category or an unregistered name.
    */
   setCategoryDefault(category: string, name: string): Promise<void>;
+  /**
+   * Install a plugin (npm into `~/.moxxy/plugins`), persist its enable, and
+   * hot-reload the plugin host so its contributions register live. Accepts a
+   * catalog id, a package name, or a full npm spec. Resolves with the spec
+   * that installed plus the diff of contribution names that registered,
+   * keyed by kind (`tools`, `providers`, `modes`, …). Optional capability
+   * per the seam convention: a `RemoteSession` leaves it undefined and the
+   * picker falls back to printing the `moxxy plugins install` command.
+   */
+  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
+ *  UI — mirrors `ProviderAuthContext` minus vault/headless (the host adds
+ *  those). `write` receives the flow's progress lines (sign-in URL, status);
+ *  `prompt` renders a single-line input (paste-back codes), masked for
+ *  secrets. */
+export interface ProviderConnectIo {
+  readonly write: (chunk: string) => void;
+  readonly prompt?: (question: string, opts?: { readonly mask?: boolean }) => Promise<string>;
+}
+
+/**
+ * The slice of provider onboarding a channel needs to connect a provider
+ * WITHOUT leaving the session: install it if it's catalog-only, collect +
+ * validate + store an API key, or drive an OAuth sign-in. Present on a local
+ * Session (wired by the CLI, which owns vault + catalog); a `RemoteSession`
+ * leaves {@link SessionLike.providerSetup} undefined and the UI falls back
+ * to pointing at `moxxy init` / `moxxy login`.
+ */
+export interface ProviderSetupView {
+  /**
+   * How this provider authenticates: from its registered def, else the
+   * first-party catalog; null when the id is unknown to both.
+   */
+  authKind(providerId: string): 'apiKey' | 'oauth' | 'none' | null;
+  /**
+   * Ensure the provider's package is registered — a catalog-only provider is
+   * npm-installed + enabled + hot-reloaded. Resolves false when the provider
+   * still isn't registered afterwards (unknown id, bad install).
+   */
+  ensureInstalled(providerId: string): Promise<boolean>;
+  /** Validate a key against the provider's own `validateKey` (if it has one). */
+  testKey(providerId: string, key: string): Promise<ProviderKeyValidation>;
+  /** Store the key in the vault under the provider's canonical key name and
+   *  mark the provider ready for this session. */
+  saveKey(providerId: string, key: string): Promise<void>;
+  /**
+   * Drive the provider's OAuth flow. `io` routes the flow's output/prompts
+   * into the calling channel's UI; when omitted the host's default terminal
+   * prompting applies (the clack path `moxxy init`/`moxxy login` use).
+   */
+  loginOAuth(
+    providerId: string,
+    io?: ProviderConnectIo,
+  ): Promise<{ readonly accountId?: string | null; readonly expiresAt?: number }>;
 }
 
 /**
@@ -406,4 +505,18 @@ export interface SessionLike {
   workflows?: WorkflowsView;
   /** Plugin-management slice backing the `/plugins` picker. */
   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>;
+    }>;
+  };
 }