@moxxy/sdk 0.11.0 → 0.12.0

package/dist/plugin.d.ts

@@ -9,13 +9,14 @@ 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';
 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;
     readonly version?: string;
@@ -42,6 +43,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/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/provider-login-bridge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+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 declare function encodeLoginPrompt(req: LoginPromptRequest): string;
+/**
+ * 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 declare function decodeLoginPrompt(segment: string): LoginPromptRequest | 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 declare function createLoginStreamScanner(): {
+    push(chunk: string): ReadonlyArray<LoginStreamItem>;
+};
+//# sourceMappingURL=provider-login-bridge.d.ts.map

package/dist/provider-login-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-login-bridge.d.ts","sourceRoot":"","sources":["../src/provider-login-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAEjE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAS5E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC;CACrD,CAmCA"}

package/dist/provider-login-bridge.js

@@ -0,0 +1,95 @@
+/**
+ * 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';
+/**
+ * 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) {
+    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) {
+    if (!segment.startsWith('{'))
+        return null;
+    try {
+        const o = JSON.parse(segment);
+        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() {
+    let buf = '';
+    return {
+        push(chunk) {
+            buf += chunk;
+            const out = [];
+            // 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;
+        },
+    };
+}
+//# sourceMappingURL=provider-login-bridge.js.map

package/dist/provider-login-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-login-bridge.js","sourceRoot":"","sources":["../src/provider-login-bridge.ts"],"names":[],"mappings":"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"}

package/dist/provider.d.ts

@@ -38,6 +38,23 @@ export type ContentBlock = {
     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
@@ -75,6 +92,17 @@ 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 = {
     readonly type: 'message_start';
@@ -102,6 +130,24 @@ export type ProviderEvent = {
     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;
@@ -136,6 +182,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 {
     readonly name: string;

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/subagent.d.ts

@@ -24,6 +24,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/dist/subagent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subagent.d.ts","sourceRoot":"","sources":["../src/subagent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IACrF,oFAAoF;IACpF,QAAQ,CAAC,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/D,qDAAqD;IACrD,OAAO,CAAC,CAAC,cAAc,EAAE,SAAS,GAAG,IAAI,CAAC;CAC3C"}
+{"version":3,"file":"subagent.d.ts","sourceRoot":"","sources":["../src/subagent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IACnC,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IACrF,oFAAoF;IACpF,QAAQ,CAAC,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC/D,qDAAqD;IACrD,OAAO,CAAC,CAAC,cAAc,EAAE,SAAS,GAAG,IAAI,CAAC;CAC3C"}

package/dist/surface.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 declare function defineSurface(def: SurfaceDef): SurfaceDef;
+/**
+ * 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>;
+}
+//# sourceMappingURL=surface.d.ts.map

package/dist/surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEjE,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,oEAAoE;IACpE,KAAK,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,4DAA4D;IAC5D,MAAM,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;;OAIG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QAC1D,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC3D,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;IACtE,yDAAyD;IACzD,WAAW,CAAC,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;CACvF;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAEzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC;IAClC,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/C,GAAG,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;CACjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5C,0DAA0D;IAC1D,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpD,0EAA0E;IAC1E,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,2EAA2E;IAC3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,+BAA+B;IAC/B,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC1D,oDAAoD;IACpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B"}

package/dist/surface.js

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/** Identity helper mirroring `defineTool` / `defineChannel`. */
+export function defineSurface(def) {
+    return def;
+}
+//# sourceMappingURL=surface.js.map

package/dist/surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../src/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA+FH,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/tool-display.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 declare function isToolDisplayResult(x: unknown): x is ToolDisplayResult;
+export declare function isToolDisplay(x: unknown): x is ToolDisplay;
+export declare function isFileDiffDisplay(x: unknown): x is FileDiffDisplay;
+/** Human summary, e.g. "Added 10 lines, removed 1 line". */
+export declare function fileDiffSummary(d: FileDiffDisplay): string;
+/** Verb for the diff header — "Create" for new files, else "Update". */
+export declare function fileDiffVerb(d: FileDiffDisplay): string;
+/** Gutter number a renderer should show for a line (new number, or old for deletions). */
+export declare function diffGutterNo(line: DiffLine): number | undefined;
+/** 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 declare function toDiffRows(d: FileDiffDisplay): DiffRow[];
+//# sourceMappingURL=tool-display.d.ts.map

package/dist/tool-display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-display.d.ts","sourceRoot":"","sources":["../src/tool-display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mCAAmC;AACnC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,GAAG,KAAK,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,iBAAiB,CAOtE;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAOlE;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAQ1D;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAEvD;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,eAAe,GAAG,OAAO,EAAE,CAOxD"}