@moxxy/sdk 0.11.0 → 0.12.0

package/dist/tool-display.js

@@ -0,0 +1,66 @@
+/**
+ * Channel-agnostic "rich tool result" payloads.
+ *
+ * A tool whose result is more than a line of text (a file diff, eventually a
+ * table or chart) returns a `ToolDisplayResult`: a short `forModel` string the
+ * model sees, plus a structured `display` every channel can render natively.
+ * The projection layer (see `mode-helpers.ts`) sends ONLY `forModel` to the
+ * model, so the rich payload never bloats the context window.
+ *
+ * The first (and currently only) display kind is `file-diff`, emitted by the
+ * built-in Write/Edit tools. It carries the changed slices of a file (a few
+ * lines of context around each edit) — never the whole file — so the payload
+ * stays bounded regardless of file size. Channels render it as a classic diff:
+ * line numbers, +/- markers, green/red line backgrounds.
+ */
+export function isToolDisplayResult(x) {
+    return (typeof x === 'object' &&
+        x !== null &&
+        typeof x.forModel === 'string' &&
+        isToolDisplay(x.display));
+}
+export function isToolDisplay(x) {
+    return isFileDiffDisplay(x);
+}
+export function isFileDiffDisplay(x) {
+    return (typeof x === 'object' &&
+        x !== null &&
+        x.kind === 'file-diff' &&
+        Array.isArray(x.hunks));
+}
+/** Human summary, e.g. "Added 10 lines, removed 1 line". */
+export function fileDiffSummary(d) {
+    const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+    const parts = [];
+    if (d.added > 0 || d.removed === 0)
+        parts.push(`Added ${plural(d.added, 'line')}`);
+    if (d.removed > 0)
+        parts.push(`${parts.length ? 'removed' : 'Removed'} ${plural(d.removed, 'line')}`);
+    let summary = parts.join(', ');
+    if (d.truncated)
+        summary += ' (diff truncated)';
+    return summary;
+}
+/** Verb for the diff header — "Create" for new files, else "Update". */
+export function fileDiffVerb(d) {
+    return d.mode === 'create' ? 'Create' : 'Update';
+}
+/** Gutter number a renderer should show for a line (new number, or old for deletions). */
+export function diffGutterNo(line) {
+    return line.kind === 'del' ? line.oldNo : line.newNo;
+}
+/**
+ * Flatten a file diff's hunks into a single row list, inserting a `gap` marker
+ * between non-contiguous hunks (channels render it as a `⋯` separator).
+ */
+export function toDiffRows(d) {
+    const rows = [];
+    d.hunks.forEach((hunk, i) => {
+        if (i > 0)
+            rows.push({ kind: 'gap' });
+        for (const line of hunk.lines)
+            rows.push(line);
+    });
+    return rows;
+}
+//# sourceMappingURL=tool-display.js.map

package/dist/tool-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-display.js","sourceRoot":"","sources":["../src/tool-display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA8CH,MAAM,UAAU,mBAAmB,CAAC,CAAU;IAC5C,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,OAAQ,CAA4B,CAAC,QAAQ,KAAK,QAAQ;QAC1D,aAAa,CAAE,CAA2B,CAAC,OAAO,CAAC,CACpD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,CAAU;IAC1C,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAwB,CAAC,IAAI,KAAK,WAAW;QAC9C,KAAK,CAAC,OAAO,CAAE,CAAyB,CAAC,KAAK,CAAC,CAChD,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,eAAe,CAAC,CAAkB;IAChD,MAAM,MAAM,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IAClF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACnF,IAAI,CAAC,CAAC,OAAO,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACtG,IAAI,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,IAAI,mBAAmB,CAAC;IAChD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAAC,CAAkB;IAC7C,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnD,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,OAAO,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;AACvD,CAAC;AAKD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,CAAkB;IAC3C,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QAC1B,IAAI,CAAC,GAAG,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/sdk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
   "keywords": [
     "moxxy",
@@ -44,6 +44,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./tool-display": {
+      "types": "./dist/tool-display.d.ts",
+      "import": "./dist/tool-display.js"
     }
   },
   "files": [

package/src/elision-state.ts

@@ -1,4 +1,5 @@
 import type { MoxxyEvent } from './events.js';
+import { isToolDisplayResult } from './tool-display.js';
 
 /**
  * Shared elision decision logic — the single source of truth for "is this event
@@ -16,6 +17,10 @@ export const TINY_TURN_CHARS = 200;
 export function toolResultBytes(output: unknown, errorMessage?: string): number {
   if (errorMessage !== undefined) return errorMessage.length;
   if (typeof output === 'string') return output.length;
+  // Rich results (e.g. file diffs) only ever send their short `forModel`
+  // string to the model — measure THAT so the estimate matches projection
+  // and the bulky `display` payload never trips elision.
+  if (isToolDisplayResult(output)) return output.forModel.length;
   try {
     return JSON.stringify(output ?? '').length;
   } catch {

package/src/events.ts

@@ -49,6 +49,40 @@ export interface AssistantMessageEvent extends EventBase {
   readonly stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error';
 }
 
+/**
+ * A live reasoning/thinking delta. Parallels {@link AssistantChunkEvent}: it is
+ * streamed for the UI's live "thinking…" preview and is NOT retained in the
+ * display log (renderers accumulate it ephemerally, clearing on the matching
+ * {@link ReasoningMessageEvent} or the turn's `assistant_message`). Only
+ * emitted when the active provider+model supports reasoning AND it is enabled
+ * in that provider's config.
+ */
+export interface ReasoningChunkEvent extends EventBase {
+  readonly type: 'reasoning_chunk';
+  readonly delta: string;
+}
+
+/**
+ * A finalized reasoning summary for ONE provider call. Parallels
+ * {@link AssistantMessageEvent}: it is persisted + replayed, and because
+ * `collectProviderStream` runs once per loop round these land between tool
+ * batches (the "summary of the work done between calls" behavior). The
+ * `signature`/`redacted`/`encrypted` fields exist purely for history
+ * round-trip — Anthropic requires the signed `thinking` block be replayed
+ * first on a tool-use continuation; Codex/Anthropic redacted thinking carries
+ * an opaque blob replayed verbatim and never shown.
+ */
+export interface ReasoningMessageEvent extends EventBase {
+  readonly type: 'reasoning_message';
+  readonly content: string;
+  /** Anthropic thinking-block signature; absent for providers that don't sign. */
+  readonly signature?: string;
+  /** True when the reasoning is redacted/encrypted and must not be displayed. */
+  readonly redacted?: boolean;
+  /** Opaque provider blob (Anthropic redacted_thinking data / Codex encrypted_content) replayed as-is. */
+  readonly encrypted?: string;
+}
+
 export interface ToolCallRequestedEvent extends EventBase {
   readonly type: 'tool_call_requested';
   readonly callId: ToolCallId;
@@ -226,6 +260,8 @@ export type MoxxyEvent =
   | UserPromptEvent
   | AssistantChunkEvent
   | AssistantMessageEvent
+  | ReasoningChunkEvent
+  | ReasoningMessageEvent
   | ToolCallRequestedEvent
   | ToolCallApprovedEvent
   | ToolCallDeniedEvent

package/src/index.ts

@@ -19,6 +19,8 @@ export type {
   UserPromptAttachment,
   AssistantChunkEvent,
   AssistantMessageEvent,
+  ReasoningChunkEvent,
+  ReasoningMessageEvent,
   ToolCallRequestedEvent,
   ToolCallApprovedEvent,
   ToolCallDeniedEvent,
@@ -136,7 +138,30 @@ export type {
   ProviderOAuthStatus,
   ProviderAuthDescriptor,
 } from './provider.js';
+export {
+  encodeLoginPrompt,
+  decodeLoginPrompt,
+  createLoginStreamScanner,
+} from './provider-login-bridge.js';
+export type { LoginPromptRequest, LoginStreamItem } from './provider-login-bridge.js';
 export type { CacheStrategyDef, CacheStrategyContext } from './cache-strategy.js';
+export type {
+  DiffLine,
+  DiffHunk,
+  DiffRow,
+  FileDiffDisplay,
+  ToolDisplay,
+  ToolDisplayResult,
+} from './tool-display.js';
+export {
+  isToolDisplayResult,
+  isToolDisplay,
+  isFileDiffDisplay,
+  fileDiffSummary,
+  fileDiffVerb,
+  diffGutterNo,
+  toDiffRows,
+} from './tool-display.js';
 export type {
   ViewNode,
   ViewAction,
@@ -334,6 +359,22 @@ export type {
 export type { EmbeddingProvider, EmbedderDef } from './embedding.js';
 export { CachedEmbeddingProvider } from './embedding-cache.js';
 
+export { defineSurface } from './surface.js';
+export type {
+  SurfaceKind,
+  SurfaceDataMessage,
+  SurfaceInputMessage,
+  SurfaceSize,
+  SurfaceInstance,
+  SurfaceAvailability,
+  SurfaceContext,
+  SurfaceDef,
+  SurfaceRegistry,
+  SurfaceInfo,
+  OpenSurfaceResult,
+  SurfaceHost,
+} from './surface.js';
+
 export type {
   RequirementKind,
   RequirementState,

package/src/loop-helpers.test.ts

@@ -151,6 +151,46 @@ describe('projectMessagesFromLog', () => {
       content: [{ type: 'text', text: 'running it now' }],
     });
   });
+
+  it('projects only `forModel` for a rich tool result (file diff), never the display payload', () => {
+    // A Write/Edit returns { forModel, display:{kind:'file-diff', hunks:[…]} }.
+    // The model must see ONLY the short summary — the bulky hunks stay
+    // channel-side, so the context window never carries the full diff.
+    const display = {
+      forModel: 'edited /repo/a.ts — added 1 line, removed 1 line',
+      display: {
+        kind: 'file-diff' as const,
+        path: 'a.ts',
+        mode: 'update' as const,
+        added: 1,
+        removed: 1,
+        hunks: [
+          {
+            oldStart: 1,
+            oldLines: 1,
+            newStart: 1,
+            newLines: 1,
+            lines: [{ kind: 'del' as const, text: 'before', oldNo: 1 }, { kind: 'add' as const, text: 'after', newNo: 1 }],
+          },
+        ],
+      },
+    };
+    const log = reader([
+      event(0, { type: 'user_prompt', turnId: t1, source: 'user', text: 'edit it' }),
+      event(1, { type: 'tool_call_requested', turnId: t1, source: 'model', callId: 'c1', name: 'Edit', input: {} }),
+      event(2, { type: 'tool_result', turnId: t1, source: 'tool', callId: 'c1', ok: true, output: display }),
+    ]);
+
+    const messages = projectMessagesFromLog({ log });
+    const toolResult = messages.find((m) => m.role === 'tool_result');
+    const block = toolResult!.content[0]!;
+    expect(block).toMatchObject({ type: 'tool_result', content: display.forModel });
+    // The hunks / file content must NOT leak into the projected text.
+    if (block.type === 'tool_result') {
+      expect(block.content).not.toContain('hunks');
+      expect(block.content).not.toContain('before');
+    }
+  });
 });
 
 function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {

package/src/mode-helpers.ts

@@ -11,6 +11,7 @@ import {
   toolResultStub,
   toolResultStubbed,
 } from './elision-state.js';
+import { isToolDisplayResult } from './tool-display.js';
 import { applyLazyTools } from './tool-gating.js';
 import { runCompactionIfNeeded } from './compactor-helpers.js';
 import { runElisionIfNeeded } from './elision-helpers.js';
@@ -196,6 +197,14 @@ export function projectMessages(
 
   let pendingAssistant: ProviderMessage | null = null;
   let pendingAssistantMaxSeq = -1;
+  // Reasoning block awaiting attachment to the current assistant turn. Only set
+  // for REPLAYABLE reasoning (Anthropic signature / redacted-or-Codex encrypted
+  // blob) — render-only reasoning is never sent back. Attached as content[0] of
+  // the turn's assistant message (Anthropic requires the signed thinking block
+  // first on an interleaved-thinking tool-use continuation; a missing/unsigned
+  // one is a hard 400). Dropped at any turn/compaction boundary it doesn't reach.
+  let pendingReasoning: Extract<ContentBlock, { type: 'reasoning' }> | null = null;
+  let pendingReasoningSeq = -1;
   const flush = (): void => {
     if (!pendingAssistant) return;
     const flushed = pendingAssistant;
@@ -237,6 +246,7 @@ export function projectMessages(
       if (!emittedCompactions.has(compaction)) {
         emittedCompactions.add(compaction);
         flush();
+        pendingReasoning = null;
         messages.push({
           role: 'user',
           content: [{ type: 'text', text: `[summary of earlier turns]\n${compaction.summary}` }],
@@ -249,6 +259,7 @@ export function projectMessages(
     switch (e.type) {
       case 'user_prompt': {
         flush();
+        pendingReasoning = null;
         // Elided + conversational: collapse to a stub (anchor/tiny kept full).
         if (conversationalStubbed(e, el)) {
           messages.push({
@@ -286,9 +297,26 @@ export function projectMessages(
         recordStable(e.seq);
         break;
       }
+      case 'reasoning_message': {
+        // Render-only reasoning (no signature/encrypted) is never replayed —
+        // it exists only for the live/scrollback "Thinking" view. Replayable
+        // reasoning is stashed for content[0] of this turn's assistant message.
+        if (e.signature || e.encrypted) {
+          pendingReasoning = {
+            type: 'reasoning',
+            text: e.content,
+            ...(e.signature ? { signature: e.signature } : {}),
+            ...(e.redacted ? { redacted: true } : {}),
+            ...(e.encrypted ? { encrypted: e.encrypted } : {}),
+          };
+          pendingReasoningSeq = e.seq;
+        }
+        break;
+      }
       case 'assistant_message':
         flush();
         if (conversationalStubbed(e, el)) {
+          pendingReasoning = null;
           messages.push({
             role: 'assistant',
             content: [{ type: 'text', text: conversationalStub('assistant', e.seq) }],
@@ -303,14 +331,31 @@ export function projectMessages(
         // tool_use blocks are projected from tool_call_requested events —
         // which also un-wedges historical logs that already contain one.
         if (e.content.trim().length === 0) {
+          pendingReasoning = null;
           recordStable(e.seq);
           break;
         }
-        messages.push({ role: 'assistant', content: [{ type: 'text', text: e.content }] });
+        {
+          const content: Array<ProviderMessage['content'][number]> = [];
+          if (pendingReasoning) {
+            content.push(pendingReasoning);
+            pendingReasoning = null;
+          }
+          content.push({ type: 'text', text: e.content });
+          messages.push({ role: 'assistant', content });
+        }
         recordStable(e.seq);
         break;
       case 'tool_call_requested': {
-        pendingAssistant ??= { role: 'assistant', content: [] };
+        if (!pendingAssistant) {
+          // Seed the assistant turn so the signed reasoning block is content[0],
+          // ahead of every tool_use (Anthropic's interleaved-thinking ordering).
+          pendingAssistant = { role: 'assistant', content: pendingReasoning ? [pendingReasoning] : [] };
+          if (pendingReasoning) {
+            pendingAssistantMaxSeq = Math.max(pendingAssistantMaxSeq, pendingReasoningSeq);
+            pendingReasoning = null;
+          }
+        }
         pendingAssistantMaxSeq = Math.max(pendingAssistantMaxSeq, e.seq);
         (pendingAssistant.content as Array<ProviderMessage['content'][number]>).push({
           type: 'tool_use',
@@ -330,6 +375,10 @@ export function projectMessages(
           text = toolResultStub(e.callId, toolResultBytes(e.output), recalled);
         } else if (e.error) {
           text = `[error:${e.error.kind}] ${e.error.message}`;
+        } else if (isToolDisplayResult(e.output)) {
+          // Rich result (e.g. a file diff): the model only needs the short
+          // `forModel` summary — the structured `display` is for channels.
+          text = e.output.forModel;
         } else {
           text = typeof e.output === 'string' ? e.output : JSON.stringify(e.output ?? '');
         }
@@ -361,6 +410,18 @@ export interface StreamResult {
   readonly error: { readonly message: string; readonly retryable: boolean } | null;
   /** Token usage reported by the provider on `message_end`, including cache hits/writes. */
   readonly usage?: TokenUsage;
+  /**
+   * Reasoning/thinking summary for this provider call, when the model emitted
+   * any. The mode emits it as a `reasoning_message` event (so it persists and
+   * round-trips). `signature`/`encrypted` carry Anthropic's signed thinking
+   * block / redacted blob; `redacted` marks display-suppressed reasoning.
+   */
+  readonly reasoning?: {
+    readonly text: string;
+    readonly signature?: string;
+    readonly redacted?: boolean;
+    readonly encrypted?: string;
+  };
 }
 
 /**
@@ -431,12 +492,17 @@ export async function collectProviderStream(
   // message-derived system text. Prefilling it would duplicate the prompt.
   // It stays as the side channel `onBeforeProviderCall` hooks use to inject
   // per-request system text (e.g. the memory consolidation nudge).
+  // Forward the per-provider reasoning preference, but only when THIS model
+  // advertises `supportsReasoning` — providers ignore the knob otherwise, but
+  // gating here keeps requests clean and avoids unsupported-param errors.
+  const reqReasoning = descriptor?.supportsReasoning ? ctx.reasoning : undefined;
   const req = {
     model: ctx.model,
     messages: effectiveMessages,
     ...(toolList ? { tools: toolList } : {}),
     ...(cacheHints && cacheHints.length > 0 ? { cacheHints } : {}),
     ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+    ...(reqReasoning ? { reasoning: reqReasoning } : {}),
     signal: ctx.signal,
   };
   const transformed = await ctx.hooks.dispatchBeforeProviderCall(req, {
@@ -453,6 +519,14 @@ export async function collectProviderStream(
   let stopReason: StopReason = 'end_turn';
   let error: StreamResult['error'] = null;
   let usage: TokenUsage | undefined;
+  // Reasoning/thinking accumulation for this single provider call. Emitted as a
+  // finalized `reasoning_message` by the mode (turn-iterator / goal-loop) so it
+  // persists and round-trips; `signature`/`encrypted` carry Anthropic's signed
+  // thinking block / redacted blob for replay.
+  let reasoningText = '';
+  let reasoningSignature: string | undefined;
+  let reasoningRedacted = false;
+  let reasoningEncrypted: string | undefined;
 
   let stream: AsyncIterable<ProviderEvent>;
   try {
@@ -498,6 +572,25 @@ export async function collectProviderStream(
           error = { message: event.message, retryable: event.retryable };
           break;
         }
+        case 'reasoning_delta': {
+          reasoningText += event.delta;
+          // Live preview only — parallels `assistant_chunk`; renderers
+          // accumulate ephemerally and clear on the finalized reasoning_message.
+          await ctx.emit({
+            type: 'reasoning_chunk',
+            sessionId: ctx.sessionId,
+            turnId: ctx.turnId,
+            source: 'model',
+            delta: event.delta,
+          });
+          break;
+        }
+        case 'reasoning_signature': {
+          if (event.signature) reasoningSignature = event.signature;
+          if (event.encrypted) reasoningEncrypted = event.encrypted;
+          if (event.redacted) reasoningRedacted = true;
+          break;
+        }
         case 'message_start':
         case 'tool_use_delta':
         default:
@@ -516,7 +609,25 @@ export async function collectProviderStream(
     if (!partial.name) continue;
     finalToolUses.push({ id, name: partial.name, input: partial.input ?? {} });
   }
-  return { text, toolUses: finalToolUses, stopReason, error, ...(usage ? { usage } : {}) };
+  // Surface reasoning when there's visible text OR an opaque blob to replay
+  // (a redacted_thinking block has no text but must still round-trip).
+  const reasoning =
+    reasoningText.trim().length > 0 || reasoningEncrypted
+      ? {
+          text: reasoningText,
+          ...(reasoningSignature ? { signature: reasoningSignature } : {}),
+          ...(reasoningRedacted ? { redacted: true } : {}),
+          ...(reasoningEncrypted ? { encrypted: reasoningEncrypted } : {}),
+        }
+      : undefined;
+  return {
+    text,
+    toolUses: finalToolUses,
+    stopReason,
+    error,
+    ...(usage ? { usage } : {}),
+    ...(reasoning ? { reasoning } : {}),
+  };
 }
 
 /**

package/src/mode.ts

@@ -77,6 +77,13 @@ export interface ModeContext {
   readonly elision?: ElisionSettings;
   /** When true, send only always-on + loaded tool schemas; index the rest. */
   readonly lazyTools?: boolean;
+  /**
+   * Per-provider reasoning/thinking preference, resolved from the active
+   * provider's config at session build. Forwarded to the provider as
+   * `ProviderRequest.reasoning` by {@link collectProviderStream}, gated on the
+   * active model's `supportsReasoning`. Absent/false → reasoning off.
+   */
+  readonly reasoning?: { readonly effort?: 'low' | 'medium' | 'high' } | boolean;
   readonly permissions: PermissionResolver;
   /**
    * Optional generic "ask the user a question" gate. Any loop strategy can

package/src/plugin.ts

@@ -9,6 +9,7 @@ import type { LifecycleHooks } from './hooks.js';
 import type { ModeDef } from './mode.js';
 import type { ProviderDef } from './provider.js';
 import type { MoxxyRequirement } from './requirements.js';
+import type { SurfaceDef } from './surface.js';
 import type { ToolDef } from './tool.js';
 import type { TranscriberDef } from './transcriber.js';
 import type { SynthesizerDef } from './synthesizer.js';
@@ -16,7 +17,7 @@ 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' | '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';
 
 export interface PluginSpec {
   readonly name: string;
@@ -44,6 +45,14 @@ export interface PluginSpec {
    */
   readonly tunnelProviders?: ReadonlyArray<TunnelProviderDef>;
   readonly channels?: ReadonlyArray<ChannelDef>;
+  /**
+   * Interactive surfaces contributed by the plugin — long-lived panes a human
+   * and the agent drive together (an embedded terminal, an in-window browser).
+   * Registered into the session's `SurfaceRegistry`; the runner exposes them to
+   * thin clients over the `surface.*` protocol family. The plugin's own tools
+   * reach the same underlying resource through module state. See {@link SurfaceDef}.
+   */
+  readonly surfaces?: ReadonlyArray<SurfaceDef>;
   /**
    * Speech-to-text backends contributed by the plugin. Selected by name via
    * `session.transcribers.setActive(name)`; channels with audio input use

package/src/provider-login-bridge.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createLoginStreamScanner,
+  decodeLoginPrompt,
+  encodeLoginPrompt,
+  type LoginStreamItem,
+} from './provider-login-bridge.js';
+
+describe('encode/decode login prompt', () => {
+  it('round-trips a request', () => {
+    const marker = encodeLoginPrompt({ question: 'Paste token:', mask: true });
+    // NUL-bracketed.
+    expect(marker.startsWith('\u0000')).toBe(true);
+    expect(marker.endsWith('\u0000')).toBe(true);
+    const inner = marker.slice(1, -1);
+    expect(decodeLoginPrompt(inner)).toEqual({ question: 'Paste token:', mask: true });
+  });
+
+  it('rejects non-marker segments', () => {
+    expect(decodeLoginPrompt('just text')).toBeNull();
+    expect(decodeLoginPrompt('{"tag":"other","question":"x"}')).toBeNull();
+    expect(decodeLoginPrompt('{not json')).toBeNull();
+  });
+});
+
+/** Drain a scanner across the given chunks into a flat item list. */
+function scanAll(chunks: string[]): LoginStreamItem[] {
+  const scanner = createLoginStreamScanner();
+  return chunks.flatMap((c) => [...scanner.push(c)]);
+}
+
+describe('createLoginStreamScanner', () => {
+  it('passes plain output straight through', () => {
+    expect(scanAll(['hello world'])).toEqual([{ type: 'output', text: 'hello world' }]);
+  });
+
+  it('extracts a marker with surrounding output', () => {
+    const stream = 'opening browser\n' + encodeLoginPrompt({ question: 'Paste code:', mask: false }) + 'done\n';
+    expect(scanAll([stream])).toEqual([
+      { type: 'output', text: 'opening browser\n' },
+      { type: 'prompt', prompt: { question: 'Paste code:', mask: false } },
+      { type: 'output', text: 'done\n' },
+    ]);
+  });
+
+  it('reassembles a marker split across chunks', () => {
+    const marker = encodeLoginPrompt({ question: 'Paste token:', mask: true });
+    const mid = Math.floor(marker.length / 2);
+    const items = scanAll(['prefix', marker.slice(0, mid), marker.slice(mid), 'suffix']);
+    expect(items).toEqual([
+      { type: 'output', text: 'prefix' },
+      { type: 'prompt', prompt: { question: 'Paste token:', mask: true } },
+      { type: 'output', text: 'suffix' },
+    ]);
+  });
+
+  it('handles two prompts in sequence', () => {
+    const a = encodeLoginPrompt({ question: 'first', mask: false });
+    const b = encodeLoginPrompt({ question: 'second', mask: true });
+    expect(scanAll([a + b])).toEqual([
+      { type: 'prompt', prompt: { question: 'first', mask: false } },
+      { type: 'prompt', prompt: { question: 'second', mask: true } },
+    ]);
+  });
+
+  it('holds back a lone opening NUL until its partner arrives', () => {
+    const scanner = createLoginStreamScanner();
+    const marker = encodeLoginPrompt({ question: 'q', mask: false });
+    // Feed everything except the closing NUL: nothing should surface yet.
+    expect([...scanner.push('text' + marker.slice(0, -1))]).toEqual([
+      { type: 'output', text: 'text' },
+    ]);
+    // Closing NUL completes the marker.
+    expect([...scanner.push('\u0000')]).toEqual([
+      { type: 'prompt', prompt: { question: 'q', mask: false } },
+    ]);
+  });
+});