@moxxy/sdk 0.11.0 → 0.12.0

package/src/provider-login-bridge.ts

@@ -0,0 +1,105 @@
+/**
+ * Cross-process bridge for relaying a provider login's interactive prompts —
+ * the out-of-band token / authorization-code paste that `claude-code` needs —
+ * from a spawned `moxxy login --stdin-prompts` subprocess to a GUI host that
+ * has no TTY (the desktop app).
+ *
+ * The subprocess emits each `ctx.prompt(question)` call as a NUL-bracketed
+ * JSON marker on stdout. NUL never appears in normal terminal output, so the
+ * host can scan the byte stream for these markers, render the prompt, and
+ * write the user's answer back as one stdin line. Loopback flows that never
+ * call `ctx.prompt` (e.g. openai-codex, which captures the code via a local
+ * callback server) emit no markers — the host just streams their output and
+ * waits for the process to exit.
+ *
+ * Living here (not in the CLI or the desktop contract) keeps the one wire
+ * format in a package both the CLI producer and the desktop consumer already
+ * depend on, so the two ends can never drift.
+ */
+
+/** The byte that brackets a prompt marker. Absent from normal CLI output. */
+const NUL = '\u0000';
+
+/** Tag distinguishing a login-prompt marker from any other NUL-bracketed run. */
+const PROMPT_TAG = 'moxxy.login.prompt';
+
+export interface LoginPromptRequest {
+  /** The question to show the user, verbatim from `ctx.prompt`. */
+  readonly question: string;
+  /** True for secrets — the host should mask the input field. */
+  readonly mask: boolean;
+}
+
+/** One decoded item from a login subprocess's stdout stream. */
+export type LoginStreamItem =
+  | { readonly type: 'output'; readonly text: string }
+  | { readonly type: 'prompt'; readonly prompt: LoginPromptRequest };
+
+/**
+ * Serialize a prompt request as a NUL-bracketed marker for stdout. The
+ * leading NUL also delimits it from any partial preceding `ctx.write` output
+ * the host scanner has buffered.
+ */
+export function encodeLoginPrompt(req: LoginPromptRequest): string {
+  return NUL + JSON.stringify({ tag: PROMPT_TAG, question: req.question, mask: req.mask }) + NUL;
+}
+
+/**
+ * Try to parse a single inter-NUL segment as a prompt marker. Returns null
+ * when it isn't one, so the host can pass the segment through as output.
+ */
+export function decodeLoginPrompt(segment: string): LoginPromptRequest | null {
+  if (!segment.startsWith('{')) return null;
+  try {
+    const o = JSON.parse(segment) as Record<string, unknown>;
+    if (o.tag !== PROMPT_TAG || typeof o.question !== 'string') return null;
+    return { question: o.question, mask: o.mask === true };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Streaming scanner for a login subprocess's stdout. Feed it chunks; it
+ * returns the ordered output / prompt items decoded so far, holding back any
+ * incomplete trailing marker (an opening NUL with no closing NUL yet) until
+ * the rest of it arrives in a later chunk.
+ */
+export function createLoginStreamScanner(): {
+  push(chunk: string): ReadonlyArray<LoginStreamItem>;
+} {
+  let buf = '';
+  return {
+    push(chunk: string): ReadonlyArray<LoginStreamItem> {
+      buf += chunk;
+      const out: LoginStreamItem[] = [];
+      // Consume every COMPLETE marker (NUL <json> NUL), emitting the plain
+      // text before each as output. Stop at the first NUL with no closing
+      // partner — that's a marker still mid-flight, kept for the next chunk.
+      for (;;) {
+        const open = buf.indexOf(NUL);
+        if (open === -1) break;
+        const close = buf.indexOf(NUL, open + 1);
+        if (close === -1) break;
+        if (open > 0) out.push({ type: 'output', text: buf.slice(0, open) });
+        const segment = buf.slice(open + 1, close);
+        const prompt = decodeLoginPrompt(segment);
+        // A NUL-bracketed run that isn't a valid marker is anomalous; surface
+        // its inner text as output rather than swallowing it.
+        out.push(prompt ? { type: 'prompt', prompt } : { type: 'output', text: segment });
+        buf = buf.slice(close + 1);
+      }
+      // Flush any plain text that precedes a still-incomplete marker (or all
+      // of it when no NUL is pending), keeping only the partial marker.
+      const pending = buf.indexOf(NUL);
+      if (pending === -1) {
+        if (buf) out.push({ type: 'output', text: buf });
+        buf = '';
+      } else if (pending > 0) {
+        out.push({ type: 'output', text: buf.slice(0, pending) });
+        buf = buf.slice(pending);
+      }
+      return out;
+    },
+  };
+}

package/src/provider.ts

@@ -19,7 +19,24 @@ export type ContentBlock =
    * to a text placeholder. Text/Office files are inlined as `text` instead — only
    * formats a model ingests as bytes become `document` blocks.
    */
-  | { readonly type: 'document'; readonly mediaType: string; readonly data: string; readonly name?: string };
+  | { readonly type: 'document'; readonly mediaType: string; readonly data: string; readonly name?: string }
+  /**
+   * A model reasoning/thinking block, preserved in conversation history so it
+   * can be replayed on the next request. Anthropic REQUIRES the signed
+   * `thinking` block be sent back (as the first block of an assistant turn that
+   * also carries tool_use) on an interleaved-thinking continuation — a missing
+   * or unsigned block is a hard 400, so the loop drops unsigned reasoning from
+   * what it replays. `redacted` blocks carry only `encrypted` (the opaque blob)
+   * and `text: ''`; they are replayed verbatim, never shown. Providers without
+   * reasoning ignore this block.
+   */
+  | {
+      readonly type: 'reasoning';
+      readonly text: string;
+      readonly signature?: string;
+      readonly redacted?: boolean;
+      readonly encrypted?: string;
+    };
 
 /**
  * Provider-neutral instruction for where a prompt-cache breakpoint should be
@@ -56,6 +73,15 @@ export interface ProviderRequest {
   readonly signal?: AbortSignal;
   /** Where to place prompt-cache breakpoints. Set by the active CacheStrategy. */
   readonly cacheHints?: ReadonlyArray<CacheHint>;
+  /**
+   * Request reasoning/thinking from the model. `false`/absent = off. Providers
+   * gate on this AND the model descriptor's `supportsReasoning`; unsupported
+   * providers/models ignore it. The loop sets it from the active provider's
+   * reasoning config (see the per-provider reasoning setting). `effort` maps to
+   * each provider's native knob (Anthropic thinking budget, OpenAI/Codex
+   * `reasoning.effort`).
+   */
+  readonly reasoning?: { readonly effort?: 'low' | 'medium' | 'high' } | boolean;
 }
 
 export type ProviderEvent =
@@ -65,7 +91,17 @@ export type ProviderEvent =
   | { readonly type: 'tool_use_delta'; readonly id: string; readonly partialInput: string }
   | { readonly type: 'tool_use_end'; readonly id: string; readonly input: unknown }
   | { readonly type: 'message_end'; readonly stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error'; readonly usage?: TokenUsage }
-  | { readonly type: 'error'; readonly message: string; readonly retryable: boolean };
+  | { readonly type: 'error'; readonly message: string; readonly retryable: boolean }
+  /** A streamed reasoning/thinking text delta (visible summary). */
+  | { readonly type: 'reasoning_delta'; readonly delta: string }
+  /**
+   * End-of-reasoning-block metadata for history round-trip, emitted once per
+   * reasoning block. `signature` is Anthropic's thinking-block signature;
+   * `encrypted` carries an opaque blob (Anthropic redacted_thinking data /
+   * Codex reasoning encrypted_content) that must be replayed verbatim;
+   * `redacted` marks reasoning that must never be displayed.
+   */
+  | { readonly type: 'reasoning_signature'; readonly signature?: string; readonly redacted?: boolean; readonly encrypted?: string };
 
 export interface TokenUsage {
   readonly inputTokens: number;
@@ -101,6 +137,13 @@ export interface ModelDescriptor {
    * the transcript as text instead.
    */
   readonly supportsAudio?: boolean;
+  /**
+   * Whether this model can emit reasoning/thinking summaries (Anthropic
+   * extended thinking, OpenAI o-series / Codex reasoning). Gates the
+   * per-provider reasoning config UI and whether the loop requests reasoning
+   * for this model. When false, `ProviderRequest.reasoning` is ignored.
+   */
+  readonly supportsReasoning?: boolean;
 }
 
 export interface LLMProvider {

package/src/subagent.ts

@@ -26,6 +26,12 @@ export interface SubagentSpec {
   readonly allowedTools?: ReadonlyArray<string>;
   /** Human-readable label surfaced in `subagent_*` event payloads. */
   readonly label?: string;
+  /**
+   * Named kind this child was spawned as (e.g. `'Explore'`, `'code-reviewer'`).
+   * Surfaced in `subagent_*` payloads so sibling agents of the same kind group
+   * under one collapsible header. Defaults to `'default'`.
+   */
+  readonly agentType?: string;
   /**
    * When true, the child session stays alive after the first turn for
    * {@link SubagentSpawner.continue}. `subagent_completed` is deferred until

package/src/surface.ts

@@ -0,0 +1,173 @@
+/**
+ * A Surface is a long-lived, interactive pane that BOTH a human viewer (a
+ * desktop panel) and the agent drive together: an embedded terminal (a shared
+ * PTY) or an in-window browser (a shared page). Unlike a {@link Channel} — which
+ * is a whole conversation transport — a Surface is a single resource attached to
+ * an existing Session, streaming opaque output frames out and accepting opaque
+ * input messages in.
+ *
+ * Surfaces are RUNNER-OWNED: the underlying resource (PTY, Playwright page) lives
+ * in the same process as the agent's tools, so the agent reads/writes the exact
+ * same instance the user watches. A thin client (the desktop) renders the
+ * streamed frames and relays the user's input back over the runner protocol —
+ * there is no reverse RPC. Plugins contribute surfaces via
+ * `definePlugin({ surfaces: [defineSurface(...)] })`; the plugin's own tools
+ * (e.g. `terminal`, `browser_session`) share the resource through module state.
+ *
+ * The payloads (`SurfaceDataMessage.payload`, `SurfaceInputMessage`) are
+ * deliberately opaque (`unknown` / open record): they cross the JSON-RPC wire
+ * verbatim and each surface kind defines its own shape (PTY bytes, a base64
+ * frame, a navigate request). Keeping them untyped here means a new surface kind
+ * never has to touch this file or the protocol.
+ */
+
+/**
+ * Surface kind discriminator. Open string union so plugins add kinds without
+ * editing the SDK; the built-ins are `'terminal'` and `'browser'`.
+ */
+export type SurfaceKind = 'terminal' | 'browser' | (string & {});
+
+/** One outbound frame from a surface instance to its viewers. */
+export interface SurfaceDataMessage {
+  /** The instance this frame belongs to (a viewer may watch several). */
+  readonly surfaceId: string;
+  readonly kind: SurfaceKind;
+  /** Surface-specific payload (PTY text, a base64 frame, a url/title update). */
+  readonly payload: unknown;
+}
+
+/**
+ * One inbound message from a viewer to a surface instance — a keystroke, a
+ * mouse event, a navigate request, a resize. `type` discriminates; the rest is
+ * surface-specific.
+ */
+export interface SurfaceInputMessage {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** Viewport hint for a resize (terminal cols/rows or pixel width/height). */
+export interface SurfaceSize {
+  readonly cols?: number;
+  readonly rows?: number;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/**
+ * A live, attached surface instance — the running PTY or browser page. Opening
+ * the same kind twice returns the SAME instance (surfaces are shared), so a
+ * viewer that joins late gets the existing resource plus its {@link snapshot}.
+ */
+export interface SurfaceInstance {
+  readonly id: string;
+  readonly kind: SurfaceKind;
+  /** Subscribe to outbound frames. Returns an unsubscribe fn. */
+  onData(cb: (payload: unknown) => void): () => void;
+  /**
+   * A catch-up payload for a late-joining viewer (terminal scrollback, the last
+   * browser frame, the current url). Optional — a surface with no replayable
+   * state omits it.
+   */
+  snapshot?(): unknown;
+  /** Apply an inbound message from a viewer (or the agent's tool). */
+  input(msg: SurfaceInputMessage): void | Promise<void>;
+  /** Re-size the viewport, when the surface is size-aware. */
+  resize?(size: SurfaceSize): void | Promise<void>;
+  /**
+   * Detach this instance. The underlying shared resource MAY persist (the
+   * agent's tool can still use the PTY/page); `close` just tears down streaming
+   * + viewer state. A surface that owns its resource exclusively disposes it.
+   */
+  close(): void | Promise<void>;
+}
+
+/** Whether a surface kind can run right now (e.g. node-pty present). */
+export interface SurfaceAvailability {
+  readonly ok: boolean;
+  /** Human-readable explanation when `ok` is false (shown in the empty pane). */
+  readonly reason?: string;
+}
+
+/** Context handed to a surface when it opens. */
+export interface SurfaceContext {
+  /** Working directory of the owning Session. */
+  readonly cwd: string;
+  readonly logger?: {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+    error?(msg: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+/**
+ * A registered, named factory for a Surface. `open` is idempotent per kind: a
+ * second `open` attaches to the resource the first one created (the host
+ * enforces this), so the agent's tool and the user's pane share one instance.
+ */
+export interface SurfaceDef {
+  readonly kind: SurfaceKind;
+  readonly description?: string;
+  open(ctx: SurfaceContext): Promise<SurfaceInstance> | SurfaceInstance;
+  /** Optional runtime gate (default: always available). */
+  isAvailable?(ctx: SurfaceContext): Promise<SurfaceAvailability> | SurfaceAvailability;
+}
+
+/** Identity helper mirroring `defineTool` / `defineChannel`. */
+export function defineSurface(def: SurfaceDef): SurfaceDef {
+  return def;
+}
+
+/**
+ * Read-only registry of surface defs contributed by plugins. Implementation
+ * lives in @moxxy/core.
+ */
+export interface SurfaceRegistry {
+  list(): ReadonlyArray<SurfaceDef>;
+  get(kind: SurfaceKind): SurfaceDef | undefined;
+  has(kind: SurfaceKind): boolean;
+}
+
+/** Wire-friendly surface descriptor for `surface.list` (no functions). */
+export interface SurfaceInfo {
+  readonly kind: SurfaceKind;
+  readonly description?: string;
+  readonly available: boolean;
+  /** Why it is unavailable, when `available` is false. */
+  readonly reason?: string;
+}
+
+/** Result of opening a surface — its id + a catch-up snapshot for the viewer. */
+export interface OpenSurfaceResult {
+  readonly surfaceId: string;
+  readonly kind: SurfaceKind;
+  readonly snapshot?: unknown;
+}
+
+/**
+ * The runtime manager of open surface instances, present on an in-process
+ * `Session`. The runner server drives it on behalf of attached clients; the
+ * agent's tools reach the SAME underlying resources through plugin module state.
+ * Output from every open instance is multiplexed through {@link onData}.
+ */
+export interface SurfaceHost {
+  /** Available surface kinds with their current availability. */
+  list(): Promise<ReadonlyArray<SurfaceInfo>>;
+  /** Open (or attach to the shared) instance for a kind. */
+  open(kind: SurfaceKind): Promise<OpenSurfaceResult>;
+  /** Route a viewer message to an open instance. No-op if it isn't open. */
+  input(surfaceId: string, msg: SurfaceInputMessage): Promise<void>;
+  /** Resize an open instance. No-op if it isn't open or isn't size-aware. */
+  resize(surfaceId: string, size: SurfaceSize): Promise<void>;
+  /** Close one open instance. */
+  close(surfaceId: string): Promise<void>;
+  /**
+   * Subscribe to outbound frames from EVERY open instance (multiplexed by
+   * `surfaceId`). Returns an unsubscribe fn. The runner subscribes once and
+   * broadcasts each frame as a `surface.data` notification.
+   */
+  onData(cb: (msg: SurfaceDataMessage) => void): () => void;
+  /** Close every open instance (session teardown). */
+  closeAll(): Promise<void>;
+}

package/src/tool-display.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  diffGutterNo,
+  fileDiffSummary,
+  fileDiffVerb,
+  isFileDiffDisplay,
+  isToolDisplayResult,
+  toDiffRows,
+  type FileDiffDisplay,
+} from './tool-display.js';
+
+const diff = (over: Partial<FileDiffDisplay> = {}): FileDiffDisplay => ({
+  kind: 'file-diff',
+  path: 'src/a.ts',
+  mode: 'update',
+  added: 10,
+  removed: 1,
+  hunks: [],
+  ...over,
+});
+
+describe('fileDiffSummary', () => {
+  it('pluralizes and joins', () => {
+    expect(fileDiffSummary(diff())).toBe('Added 10 lines, removed 1 line');
+  });
+  it('handles add-only / remove-only', () => {
+    expect(fileDiffSummary(diff({ removed: 0 }))).toBe('Added 10 lines');
+    expect(fileDiffSummary(diff({ added: 0, removed: 3 }))).toBe('Removed 3 lines');
+  });
+  it('notes truncation', () => {
+    expect(fileDiffSummary(diff({ truncated: true }))).toContain('truncated');
+  });
+});
+
+describe('fileDiffVerb', () => {
+  it('maps mode to verb', () => {
+    expect(fileDiffVerb(diff({ mode: 'create' }))).toBe('Create');
+    expect(fileDiffVerb(diff({ mode: 'update' }))).toBe('Update');
+  });
+});
+
+describe('diffGutterNo', () => {
+  it('uses old number for deletions, new otherwise', () => {
+    expect(diffGutterNo({ kind: 'del', text: '', oldNo: 5, newNo: undefined })).toBe(5);
+    expect(diffGutterNo({ kind: 'add', text: '', newNo: 7 })).toBe(7);
+    expect(diffGutterNo({ kind: 'context', text: '', oldNo: 3, newNo: 4 })).toBe(4);
+  });
+});
+
+describe('toDiffRows', () => {
+  it('inserts a gap marker between hunks', () => {
+    const d = diff({
+      hunks: [
+        { oldStart: 1, oldLines: 1, newStart: 1, newLines: 1, lines: [{ kind: 'context', text: 'a' }] },
+        { oldStart: 9, oldLines: 1, newStart: 9, newLines: 1, lines: [{ kind: 'context', text: 'b' }] },
+      ],
+    });
+    const rows = toDiffRows(d);
+    expect(rows.map((r) => r.kind)).toEqual(['context', 'gap', 'context']);
+  });
+});
+
+describe('guards', () => {
+  it('isFileDiffDisplay / isToolDisplayResult', () => {
+    expect(isFileDiffDisplay(diff())).toBe(true);
+    expect(isFileDiffDisplay({ kind: 'other' })).toBe(false);
+    expect(isToolDisplayResult({ forModel: 'x', display: diff() })).toBe(true);
+    expect(isToolDisplayResult({ forModel: 'x' })).toBe(false);
+    expect(isToolDisplayResult('wrote 12 chars')).toBe(false);
+  });
+});

package/src/tool-display.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+
+/** One rendered line of a diff. */
+export interface DiffLine {
+  readonly kind: 'context' | 'add' | 'del';
+  readonly text: string;
+  /** 1-based line number in the OLD file (del + context lines). */
+  readonly oldNo?: number;
+  /** 1-based line number in the NEW file (add + context lines). */
+  readonly newNo?: number;
+}
+
+/** A contiguous changed region plus its surrounding context lines. */
+export interface DiffHunk {
+  readonly oldStart: number;
+  readonly oldLines: number;
+  readonly newStart: number;
+  readonly newLines: number;
+  readonly lines: ReadonlyArray<DiffLine>;
+}
+
+/** Structured diff for a single file write/edit. */
+export interface FileDiffDisplay {
+  readonly kind: 'file-diff';
+  /** Display path — relative to cwd when possible, else absolute. */
+  readonly path: string;
+  readonly mode: 'create' | 'update';
+  readonly added: number;
+  readonly removed: number;
+  readonly hunks: ReadonlyArray<DiffHunk>;
+  /** Set when a very large diff was capped (some hunks/lines dropped). */
+  readonly truncated?: boolean;
+}
+
+/** Extensible union of structured tool-result payloads. */
+export type ToolDisplay = FileDiffDisplay;
+
+/**
+ * The shape a tool returns when it wants a rich, channel-rendered result.
+ * `forModel` is the only thing the model sees; `display` is for channels.
+ */
+export interface ToolDisplayResult {
+  readonly forModel: string;
+  readonly display: ToolDisplay;
+}
+
+export function isToolDisplayResult(x: unknown): x is ToolDisplayResult {
+  return (
+    typeof x === 'object' &&
+    x !== null &&
+    typeof (x as { forModel?: unknown }).forModel === 'string' &&
+    isToolDisplay((x as { display?: unknown }).display)
+  );
+}
+
+export function isToolDisplay(x: unknown): x is ToolDisplay {
+  return isFileDiffDisplay(x);
+}
+
+export function isFileDiffDisplay(x: unknown): x is FileDiffDisplay {
+  return (
+    typeof x === 'object' &&
+    x !== null &&
+    (x as { kind?: unknown }).kind === 'file-diff' &&
+    Array.isArray((x as { hunks?: unknown }).hunks)
+  );
+}
+
+/** Human summary, e.g. "Added 10 lines, removed 1 line". */
+export function fileDiffSummary(d: FileDiffDisplay): string {
+  const plural = (n: number, w: string): string => `${n} ${w}${n === 1 ? '' : 's'}`;
+  const parts: string[] = [];
+  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: FileDiffDisplay): string {
+  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: DiffLine): number | undefined {
+  return line.kind === 'del' ? line.oldNo : line.newNo;
+}
+
+/** A renderable row: either a diff line or a gap marker between hunks. */
+export type DiffRow = DiffLine | { readonly kind: 'gap' };
+
+/**
+ * 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: FileDiffDisplay): DiffRow[] {
+  const rows: DiffRow[] = [];
+  d.hunks.forEach((hunk, i) => {
+    if (i > 0) rows.push({ kind: 'gap' });
+    for (const line of hunk.lines) rows.push(line);
+  });
+  return rows;
+}