@moxxy/sdk 0.1.0 → 0.1.3

package/src/mode-helpers.ts

@@ -12,6 +12,9 @@ import {
   toolResultStubbed,
 } from './elision-state.js';
 import { applyLazyTools } from './tool-gating.js';
+import { runCompactionIfNeeded } from './compactor-helpers.js';
+import { runElisionIfNeeded } from './elision-helpers.js';
+import { usageEventFields } from './token-accounting.js';
 
 /**
  * Shared bits used by every loop strategy: a typed tool-use struct and a
@@ -481,3 +484,169 @@ export async function collectProviderStream(
   }
   return { text, toolUses: finalToolUses, stopReason, error, ...(usage ? { usage } : {}) };
 }
+
+/**
+ * Run a single-shot (no-tools) provider turn — the shape every planner /
+ * synthesis phase shares. Runs context management (compaction + elision),
+ * emits the `provider_request` bookend, streams the response with tools
+ * disabled, then emits either an `error` event (returning `null`) or the
+ * `provider_response` bookend (returning the collected text).
+ *
+ * Replaces the ~40-line block each mode phase used to inline; centralizing it
+ * keeps event emission uniform and means a fix here (e.g. always running
+ * elision) lands for every loop strategy at once.
+ */
+export async function runSingleShotTurn(
+  ctx: ModeContext,
+  messages: ReadonlyArray<ProviderMessage>,
+  opts: { maxTokens?: number } = {},
+): Promise<string | null> {
+  await runCompactionIfNeeded(ctx);
+  await runElisionIfNeeded(ctx);
+
+  await ctx.emit({
+    type: 'provider_request',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    provider: ctx.provider.name,
+    model: ctx.model,
+  });
+
+  const { text, usage, error } = await collectProviderStream(ctx, messages, {
+    includeTools: false,
+    ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+  });
+  if (error) {
+    await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: error.retryable ? 'retryable' : 'fatal',
+      message: error.message,
+    });
+    return null;
+  }
+
+  await ctx.emit({
+    type: 'provider_response',
+    sessionId: ctx.sessionId,
+    turnId: ctx.turnId,
+    source: 'system',
+    provider: ctx.provider.name,
+    model: ctx.model,
+    ...usageEventFields(usage),
+  });
+
+  return text;
+}
+
+/**
+ * Sliding-window detector for "model keeps making the same tool call".
+ *
+ * When the same `(toolName, input)` pair appears `repeatThreshold` times in
+ * the last `windowSize` calls, the model is almost certainly stuck — polling a
+ * tool that returns the same thing, mis-handling an error, etc. Bail early
+ * instead of burning through the iteration cap.
+ *
+ * Shared across every loop strategy so detection is uniform — previously each
+ * mode re-rolled this, and one copy used a non-canonical `JSON.stringify`
+ * signature that silently missed key-reordered repeats.
+ */
+export interface StuckSignal {
+  /** True when the loop guard should trip. */
+  readonly stuck: boolean;
+  /** Repeat count behind the trip — for the error message. */
+  readonly count: number;
+  /**
+   * `exact` = the same (tool, full-input) repeated `repeatThreshold` times.
+   * `near`  = the same (tool, identity arg — url / file_path / command / …)
+   *           repeated `nearThreshold` times while only volatile args (maxBytes,
+   *           timeoutMs) varied. Catches the "refetch the same URL with a bigger
+   *           maxBytes over and over" loop the exact check sails past.
+   */
+  readonly kind: 'exact' | 'near';
+}
+
+export interface StuckLoopDetector {
+  readonly windowSize: number;
+  readonly repeatThreshold: number;
+  /** Record the call and report whether the loop guard should trip. */
+  record(toolName: string, input: unknown): StuckSignal;
+}
+
+/** 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'];
+
+function identityArg(input: unknown): string | null {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const o = input as Record<string, unknown>;
+  for (const k of IDENTITY_ARG_KEYS) {
+    const v = o[k];
+    if (typeof v === 'string' && v.trim().length > 0) return `${k}=${v}`;
+  }
+  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;
+  // 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 nearThreshold = opts.nearThreshold ?? Math.max(repeatThreshold + 2, 5);
+  const recent: string[] = [];
+  const recentNear: string[] = [];
+  return {
+    windowSize,
+    repeatThreshold,
+    record(toolName, input): StuckSignal {
+      const key = `${toolName}|${stableHash(input)}`;
+      recent.push(key);
+      if (recent.length > windowSize) recent.shift();
+      const exactCount = recent.filter((k) => k === key).length;
+      if (exactCount >= repeatThreshold) return { stuck: true, count: exactCount, kind: 'exact' };
+
+      let nearCount = 0;
+      const id = identityArg(input);
+      if (id !== null) {
+        const nearKey = `${toolName}|${id}`;
+        recentNear.push(nearKey);
+        if (recentNear.length > nearWindowSize) recentNear.shift();
+        nearCount = recentNear.filter((k) => k === nearKey).length;
+        if (nearCount >= nearThreshold) return { stuck: true, count: nearCount, kind: 'near' };
+      }
+      return { stuck: false, count: Math.max(exactCount, nearCount), kind: 'exact' };
+    },
+  };
+}
+
+/**
+ * Stable, key-order-canonical hash of a tool call's input, so `{a:1,b:2}` and
+ * `{b:2,a:1}` produce the same key. Use for any "have I seen this call before"
+ * comparison — a raw `JSON.stringify` is NOT order-stable.
+ */
+export function stableHash(input: unknown): string {
+  return canonicalize(input);
+}
+
+function canonicalize(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalize).join(',') + ']';
+  }
+  const entries = Object.entries(value as Record<string, unknown>).sort(
+    ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+  );
+  return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + canonicalize(v)).join(',') + '}';
+}

package/src/mode.ts

@@ -88,6 +88,14 @@ export interface ModeContext {
    * Absent in synthetic test contexts that don't model a full Session.
    */
   readonly subagents?: SubagentSpawner;
+  /**
+   * 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.
+   */
+  readonly requestModeSwitch?: (modeName: string) => void;
   emit(event: EmittedEvent): Promise<MoxxyEvent>;
 }
 

package/src/mutex.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { createMutex } from './mutex.js';
+
+const tick = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe('createMutex', () => {
+  it('serializes overlapping runs (no interleave)', async () => {
+    const mutex = createMutex();
+    const order: string[] = [];
+    const slow = mutex.run(async () => {
+      order.push('a:start');
+      await tick(20);
+      order.push('a:end');
+    });
+    const fast = mutex.run(async () => {
+      order.push('b:start');
+      await tick(1);
+      order.push('b:end');
+    });
+    await Promise.all([slow, fast]);
+    expect(order).toEqual(['a:start', 'a:end', 'b:start', 'b:end']);
+  });
+
+  it('returns the callback result', async () => {
+    const mutex = createMutex();
+    await expect(mutex.run(() => 42)).resolves.toBe(42);
+    await expect(mutex.run(async () => 'x')).resolves.toBe('x');
+  });
+
+  it('keeps the lock alive after a rejection', async () => {
+    const mutex = createMutex();
+    await expect(mutex.run(() => Promise.reject(new Error('boom')))).rejects.toThrow('boom');
+    // Next run must still execute — the chain isn't poisoned.
+    await expect(mutex.run(() => 'recovered')).resolves.toBe('recovered');
+  });
+});

package/src/mutex.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-instance write mutex: a promise chain that serializes async mutators so
+ * two overlapping read-modify-write cycles can't both read the same snapshot
+ * and clobber each other.
+ *
+ * The single home for the framework's "serialize file-state mutators"
+ * invariant. Stores (vault, memory, permissions, scheduler, webhooks, …) hold
+ * one `Mutex` instance and run every mutation through {@link Mutex.run}.
+ */
+export interface Mutex {
+  /** Run `fn` after all previously-queued runs settle. */
+  run<T>(fn: () => Promise<T> | T): Promise<T>;
+}
+
+export function createMutex(): Mutex {
+  let chain: Promise<unknown> = Promise.resolve();
+  return {
+    run<T>(fn: () => Promise<T> | T): Promise<T> {
+      // `.then(fn, fn)` runs `fn` whether the previous run resolved or
+      // rejected, so one failed mutation doesn't deadlock the queue.
+      const next = chain.then(fn as () => T, fn as () => T);
+      // Keep the chain alive across rejections — never let a rejected link
+      // permanently poison the lock.
+      chain = next.then(
+        () => undefined,
+        () => undefined,
+      );
+      return next;
+    },
+  };
+}

package/src/plugin.ts

@@ -3,6 +3,8 @@ import type { CacheStrategyDef } from './cache-strategy.js';
 import type { ChannelDef } from './channel.js';
 import type { CommandDef } from './command.js';
 import type { CompactorDef } from './compactor.js';
+import type { EmbedderDef } from './embedding.js';
+import type { Isolator } from './isolation.js';
 import type { LifecycleHooks } from './hooks.js';
 import type { ModeDef } from './mode.js';
 import type { ProviderDef } from './provider.js';
@@ -11,8 +13,9 @@ import type { ToolDef } from './tool.js';
 import type { TranscriberDef } from './transcriber.js';
 import type { ViewRendererDef } from './view-renderer.js';
 import type { TunnelProviderDef } from './tunnel.js';
+import type { WorkflowExecutorDef } from './workflow.js';
 
-export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'hooks' | 'agent' | 'command' | 'transcriber';
+export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'hooks' | 'agent' | 'command' | 'transcriber' | 'embedder' | 'isolator' | 'workflow-executor';
 
 export interface PluginSpec {
   readonly name: string;
@@ -47,6 +50,22 @@ export interface PluginSpec {
    * the active provider does not advertise `supportsAudio`.
    */
   readonly transcribers?: ReadonlyArray<TranscriberDef>;
+  /**
+   * Text-embedding backends contributed by the plugin. Selected by name via
+   * `session.embedders.setActive(name, config)`; @moxxy/plugin-memory uses the
+   * active embedder for semantic recall. `createClient` is lazy so a discovered
+   * embedder plugin never pulls its (often heavy) runtime in until selected.
+   */
+  readonly embedders?: ReadonlyArray<EmbedderDef>;
+  /**
+   * Capability isolators contributed by the plugin (worker_threads, subprocess,
+   * wasm, …). Registered into the active security layer's `IsolatorRegistry`
+   * and selected by name via `security.isolator` config. Registration alone is
+   * inert — a contributed isolator is NEVER auto-activated as the sandbox
+   * boundary; the user must opt in by name (so a rogue plugin can't silently
+   * weaken isolation).
+   */
+  readonly isolators?: ReadonlyArray<Isolator>;
   /**
    * Typed subagent kinds the plugin contributes. Each becomes
    * dispatchable as `dispatch_agent({ agentType: <name>, ... })`.
@@ -64,6 +83,13 @@ export interface PluginSpec {
    * pickers, raw-mode toggles) inside the channel itself.
    */
   readonly commands?: ReadonlyArray<CommandDef>;
+  /**
+   * Workflow-execution strategies contributed by the plugin. One is active per
+   * session (selected via `session.workflowExecutors.setActive(name)`); the
+   * active executor runs a workflow DAG. `@moxxy/plugin-workflows` ships the
+   * default `dag` executor.
+   */
+  readonly workflowExecutors?: ReadonlyArray<WorkflowExecutorDef>;
   readonly hooks?: LifecycleHooks;
   readonly skillsDir?: string;
 }

package/src/provider-utils.ts

@@ -8,6 +8,15 @@ import { classifyNetworkError } from './errors.js';
 /** Canonical stop reasons emitted on `message_end` events. */
 export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error';
 
+/**
+ * Rough token estimate for a blob of text: ~4 chars per token. The shared
+ * fallback for a provider's `countTokens` when no native tokenizer is wired —
+ * previously each provider hardcoded `Math.ceil(text.length / 4)` independently.
+ */
+export function estimateTextTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
 /**
  * Heuristic: should a provider request retry on this error? Used by stream
  * modes to attach a `retryable: boolean` flag to the `error` event so callers

package/src/resolvers.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateToolRule } from './resolvers.js';
+import type { PendingToolCall, PermissionRule } from './permission.js';
+
+function call(name: string, input: unknown = {}): PendingToolCall {
+  return { callId: 'c1', name, input } as unknown as PendingToolCall;
+}
+
+describe('evaluateToolRule', () => {
+  it('returns null when the tool declares no rule (defer to resolver)', () => {
+    expect(evaluateToolRule(undefined, call('reload_skills'))).toBeNull();
+  });
+
+  it('allows a tool that declares action allow', () => {
+    const rule: PermissionRule = { action: 'allow' };
+    expect(evaluateToolRule(rule, call('reload_skills'))).toEqual({
+      mode: 'allow',
+      reason: 'tool-declared allow',
+    });
+  });
+
+  it('denies a tool that declares action deny', () => {
+    const rule: PermissionRule = { action: 'deny', reason: 'nope' };
+    expect(evaluateToolRule(rule, call('danger'))).toEqual({ mode: 'deny', reason: 'nope' });
+  });
+
+  it('defers (null) for action prompt so the interactive resolver decides', () => {
+    expect(evaluateToolRule({ action: 'prompt' }, call('self_update_verify'))).toBeNull();
+  });
+
+  it('only applies when the name pattern matches', () => {
+    const rule: PermissionRule = { action: 'allow', pattern: { name: 'reload_skills' } };
+    expect(evaluateToolRule(rule, call('reload_skills'))).not.toBeNull();
+    expect(evaluateToolRule(rule, call('other_tool'))).toBeNull();
+  });
+
+  it('matches on inputMatches (string + RegExp)', () => {
+    const rule: PermissionRule = {
+      action: 'allow',
+      pattern: { inputMatches: { path: /^\/tmp\// } },
+    };
+    expect(evaluateToolRule(rule, call('write', { path: '/tmp/ok.txt' }))).not.toBeNull();
+    expect(evaluateToolRule(rule, call('write', { path: '/etc/passwd' }))).toBeNull();
+  });
+});

package/src/resolvers.ts

@@ -0,0 +1,164 @@
+import type {
+  PendingToolCall,
+  PermissionContext,
+  PermissionDecision,
+  PermissionResolver,
+  PermissionRule,
+} from './permission.js';
+
+export const autoAllowResolver: PermissionResolver = {
+  name: 'auto-allow',
+  async check(): Promise<PermissionDecision> {
+    return { mode: 'allow', reason: 'auto-allow resolver (test mode)' };
+  },
+};
+
+export const denyByDefaultResolver: PermissionResolver = {
+  name: 'deny-by-default',
+  async check(): Promise<PermissionDecision> {
+    return { mode: 'deny', reason: 'No interactive resolver available in headless mode. Use --allow-tools or permissions.json.' };
+  },
+};
+
+export interface CallbackResolverOptions {
+  readonly name?: string;
+  readonly callback: (call: PendingToolCall, ctx: PermissionContext) => Promise<PermissionDecision>;
+}
+
+export function createCallbackResolver(opts: CallbackResolverOptions): PermissionResolver {
+  return {
+    name: opts.name ?? 'callback',
+    check: opts.callback,
+  };
+}
+
+export function createAllowListResolver(toolNames: ReadonlyArray<string>): PermissionResolver {
+  const allowed = new Set(toolNames);
+  return {
+    name: 'allow-list',
+    async check(call) {
+      if (allowed.has(call.name)) return { mode: 'allow_session', reason: 'allow-list' };
+      return { mode: 'deny', reason: `Tool '${call.name}' not in allow-list` };
+    },
+  };
+}
+
+export type PermissionPromptHandler = (
+  call: PendingToolCall,
+  ctx: PermissionContext,
+) => Promise<PermissionDecision>;
+
+export interface DeferredPermissionResolverOptions {
+  readonly prompt: PermissionPromptHandler;
+  readonly name?: string;
+  readonly sessionAllows?: Set<string>;
+}
+
+export interface DeferredPermissionResolver extends PermissionResolver {
+  /**
+   * Resolve all in-flight prompts with `deny`. Call from a channel's `stop`
+   * so a pending permission prompt doesn't hang forever when the host UI
+   * unmounts (the TUI bug the audit flagged).
+   */
+  abortAll(reason?: string): void;
+}
+
+/**
+ * Resolver for channels that defer permission decisions to an external UI
+ * (Ink dialog, Telegram inline keyboard, web form). Wraps a `prompt`
+ * callback with:
+ *   - sessionAllows shortcut — `allow_session` decisions skip subsequent
+ *     prompts for the same tool name.
+ *   - in-flight tracking — `abortAll()` resolves pending prompts with
+ *     `deny`, so the channel can shut down cleanly without hangs.
+ */
+export function createDeferredPermissionResolver(
+  opts: DeferredPermissionResolverOptions,
+): DeferredPermissionResolver {
+  const sessionAllows = opts.sessionAllows ?? new Set<string>();
+  const pending = new Set<(d: PermissionDecision) => void>();
+  return {
+    name: opts.name ?? 'deferred',
+    async check(call, ctx) {
+      if (sessionAllows.has(call.name)) {
+        return { mode: 'allow_session', reason: 'allow_session previously granted' };
+      }
+      const decision = await new Promise<PermissionDecision>((resolve) => {
+        pending.add(resolve);
+        opts.prompt(call, ctx).then(
+          (d) => {
+            pending.delete(resolve);
+            resolve(d);
+          },
+          (err) => {
+            pending.delete(resolve);
+            resolve({ mode: 'deny', reason: err instanceof Error ? err.message : String(err) });
+          },
+        );
+      });
+      // Both allow_session and allow_always should skip future prompts for
+      // the same tool within this resolver instance. allow_always
+      // additionally signals to the caller (via the decision flag) that
+      // the rule should be persisted to ~/.moxxy/permissions.json — but
+      // that persistence isn't our job; the channel does it when wiring
+      // up the dialog.
+      if (decision.mode === 'allow_session' || decision.mode === 'allow_always') {
+        sessionAllows.add(call.name);
+      }
+      return decision;
+    },
+    abortAll(reason = 'channel closed') {
+      for (const r of pending) r({ mode: 'deny', reason });
+      pending.clear();
+    },
+  };
+}
+
+/**
+ * Evaluate a tool's OWN declared {@link PermissionRule} against a call.
+ *
+ * Tools can ship a `permission` rule to express their author's policy — e.g.
+ * `reload_skills` / `load_tool` declare `{ action: 'allow' }` because they're
+ * safe, internal, idempotent operations that should never prompt. That rule
+ * was previously stored on the ToolDef but never consulted, so in headless
+ * runs (where the channel resolver denies by default) even these safe tools
+ * were blocked. The session resolver now consults this BETWEEN the user's
+ * `permissions.json` policy and the channel resolver, so:
+ *
+ *   user policy (deny/allow)  >  tool-declared rule  >  channel resolver
+ *
+ * Returns a decision for a matching `allow`/`deny` rule, or `null` to defer
+ * (no rule, pattern didn't match, or `action: 'prompt'` — the interactive
+ * resolver should handle those).
+ */
+export function evaluateToolRule(
+  rule: PermissionRule | undefined,
+  call: PendingToolCall,
+): PermissionDecision | null {
+  if (!rule || !toolRuleMatches(rule, call)) return null;
+  switch (rule.action) {
+    case 'allow':
+      return { mode: 'allow', reason: rule.reason ?? 'tool-declared allow' };
+    case 'deny':
+      return { mode: 'deny', reason: rule.reason ?? 'tool-declared deny' };
+    case 'prompt':
+      return null; // defer to the interactive resolver
+  }
+}
+
+function toolRuleMatches(rule: PermissionRule, call: PendingToolCall): boolean {
+  const p = rule.pattern;
+  if (!p) return true; // no pattern → applies to every call of this tool
+  if (p.name !== undefined && !patternMatch(p.name, call.name)) return false;
+  if (p.inputMatches) {
+    const input = (call.input ?? {}) as Record<string, unknown>;
+    for (const [key, matcher] of Object.entries(p.inputMatches)) {
+      if (!patternMatch(matcher, String(input[key] ?? ''))) return false;
+    }
+  }
+  return true;
+}
+
+function patternMatch(pattern: string | RegExp, candidate: string): boolean {
+  return pattern instanceof RegExp ? pattern.test(candidate) : pattern === candidate;
+}

package/src/session-like.ts

@@ -40,10 +40,23 @@ export interface SessionLogReader extends EventLogReader {
   subscribe(fn: (event: MoxxyEvent) => void | Promise<void>): () => void;
 }
 
-/** Serializable provider metadata (models + context windows) for display. */
+/** How a provider authenticates. UIs use this to decide whether to
+ *  show an API-key field or kick off an OAuth flow. */
+export type ProviderAuthKind = 'api-key' | 'oauth';
+
+/** Serializable provider metadata (models + context windows + auth)
+ *  for display. */
 export interface ProviderInfo {
   readonly name: string;
   readonly models: ReadonlyArray<ModelDescriptor>;
+  /** 'oauth' when the provider declares an oauth login on its plugin
+   *  definition, 'api-key' otherwise. Defaults to 'api-key' for
+   *  providers that don't declare. */
+  readonly authKind: ProviderAuthKind;
+  /** True when the provider's plugin can list its models live (e.g.
+   *  via /v1/models). Lets the desktop's model picker show a
+   *  "Fetch live" affordance only where it makes sense. */
+  readonly supportsLiveModelDiscovery: boolean;
 }
 
 /** Serializable tool metadata for status lines / slash menus / compact rendering. */
@@ -94,6 +107,64 @@ export interface SessionInfo {
   readonly activeTranscriber: string | null;
 }
 
+/**
+ * Resolves a provider's stored credentials (vault tokens / API keys) into the
+ * config object `providers.setActive` needs. The host installs one on a local
+ * Session at boot; it is undefined across a `RemoteSession` transport (a closure
+ * can't cross the wire — the runner side resolves credentials there instead).
+ */
+export type CredentialResolver = (providerName: string) => Promise<Record<string, unknown>>;
+
+/** One server's status in {@link McpAdminView.listServers}. */
+export interface McpServerStatusView {
+  readonly name: string;
+  readonly enabled: boolean;
+  readonly connected: boolean;
+}
+
+/**
+ * The slice of the MCP admin API a channel needs to drive the MCP picker and
+ * status line. Present on a local Session when the MCP admin plugin is wired;
+ * a `RemoteSession` leaves {@link SessionLike.mcpAdmin} undefined and the UI
+ * degrades gracefully.
+ */
+export interface McpAdminView {
+  enableAndAttach(name: string): Promise<{ toolNames: ReadonlyArray<string> } | null>;
+  detach(name: string): Promise<boolean>;
+  listServers(): Promise<ReadonlyArray<McpServerStatusView>>;
+}
+
+/** One workflow's summary for the `/workflows` modal. */
+export interface WorkflowSummaryView {
+  readonly name: string;
+  readonly description: string;
+  readonly enabled: boolean;
+  readonly scope: string;
+  readonly steps: number;
+  /** Human-readable trigger summary, e.g. `cron(0 8 * * *)` or `on-demand`. */
+  readonly triggers: string;
+}
+
+/** Result of running a workflow from the modal. */
+export interface WorkflowRunView {
+  readonly ok: boolean;
+  readonly output: string;
+  readonly error?: string;
+  readonly steps: ReadonlyArray<{ readonly id: string; readonly status: string; readonly error?: string }>;
+}
+
+/**
+ * The slice of the workflows API a channel needs to drive the `/workflows`
+ * modal (list, enable/disable toggle, run). Present on a local Session when
+ * `@moxxy/plugin-workflows` is wired; a `RemoteSession` leaves
+ * {@link SessionLike.workflows} undefined and the UI degrades gracefully.
+ */
+export interface WorkflowsView {
+  list(): Promise<ReadonlyArray<WorkflowSummaryView>>;
+  setEnabled(name: string, enabled: boolean): Promise<void>;
+  run(name: string): Promise<WorkflowRunView>;
+}
+
 /**
  * The session surface a `Channel` depends on, decoupled from whether the
  * session runs in-process (`@moxxy/core`'s `Session`) or is a thin-client
@@ -115,4 +186,19 @@ export interface SessionLike {
   /** Wire-friendly registry snapshot for rendering. */
   getInfo(): SessionInfo;
   close(reason?: string): Promise<void>;
+
+  /**
+   * Live runtime capabilities present only on an in-process Session; a
+   * `RemoteSession` thin client leaves them undefined, so callers MUST guard.
+   * For plain display prefer the serializable {@link getInfo} snapshot — these
+   * are for the mutate/guard paths a channel drives (provider switch, MCP picker).
+   */
+  /** Providers whose credentials resolved this session (live, mutable). */
+  readyProviders?: Set<string>;
+  /** Re-resolves a provider's credentials before `providers.setActive`. */
+  credentialResolver?: CredentialResolver;
+  /** MCP admin slice backing the MCP picker / status line. */
+  mcpAdmin?: McpAdminView;
+  /** Workflows slice backing the `/workflows` modal. */
+  workflows?: WorkflowsView;
 }