pi-note 0.28.0 → 0.29.1

package/remote/client.ts

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { pinoteToken } from '../token.ts';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { McpError, ResourceListChangedNotificationSchema, type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { ActionResultSchema, ChangedSchema, StaleActionDataSchema, UI_STALE_ACTION } from './protocol.ts';
+
+export interface RemoteConfig { url: URL; token: string; scope: string }
+/** PINOTE_ALLOW_HTTP=1 explicitly permits plaintext on a trusted private VPN. */
+export function remoteConfig(env: NodeJS.ProcessEnv = process.env): RemoteConfig {
+  const token = pinoteToken(env);
+  let url: URL;
+  try { url = new URL(env.PINOTE_URL ?? 'http://127.0.0.1:8765/mcp'); }
+  catch { throw new Error('Invalid PINOTE_URL'); }
+  if (url.username || url.password || url.search || url.hash) throw new Error('PINOTE_URL must not contain credentials, query, or fragment');
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && (local || env.PINOTE_ALLOW_HTTP === '1'))) {
+    throw new Error('Remote Pinote requires HTTPS; PINOTE_ALLOW_HTTP=1 permits a trusted private VPN');
+  }
+  return { url, token, scope: createHash('sha256').update(url.href).digest('hex') };
+}
+export class RemoteFailure extends Error {
+  readonly uncertain: boolean;
+  readonly stale: boolean;
+  constructor(uncertain = false, stale = false) {
+    super(stale ? 'Action not applied: state changed. Refresh and review before retrying.' :
+      `Pinote request failed.${uncertain ? ' The write may have committed; refresh before retrying.' : ' Context unavailable; retry an explicit call to reconnect.'}`);
+    this.uncertain = uncertain && !stale; this.stale = stale;
+  }
+}
+export interface Peer {
+  read(uri: string, meta: Record<string, unknown>, signal: AbortSignal): Promise<{ contents: Array<{ text?: string; mimeType?: string }> }>;
+  tool(name: string, args: Record<string, unknown>, meta: Record<string, unknown>, signal: AbortSignal): Promise<CallToolResult>;
+  action(params: Record<string, unknown>, signal: AbortSignal): Promise<ReturnType<typeof ActionResultSchema.parse>>;
+  close(): Promise<void>;
+}
+export type PeerFactory = (config: RemoteConfig, signal: AbortSignal, changed: () => void, disconnected: () => void) => Promise<Peer>;
+export const connectPeer: PeerFactory = async (config, signal, changed, disconnected) => {
+  const client = new Client({ name: 'pinote-pi', version: '1' }, { capabilities: {} });
+  const transport = new StreamableHTTPClientTransport(config.url, {
+    requestInit: { headers: { Authorization: `Bearer ${config.token}` }, redirect: 'error' },
+    // Never replay POSTs, resume streams, or reconnect behind the caller's epoch.
+    reconnectionOptions: { maxRetries: 0, initialReconnectionDelay: 1000, maxReconnectionDelay: 1000, reconnectionDelayGrowFactor: 1 },
+    fetch: (url, init) => fetch(url, { ...init, redirect: 'error', signal: init?.method === 'DELETE'
+      ? AbortSignal.timeout(1000) // Bounded session cleanup remains possible after operation cancellation.
+      : AbortSignal.any([signal, ...(init?.signal ? [init.signal] : [])]) }),
+  });
+  let closing = false;
+  // Losing the notification stream must clear the idle UI, not silently leave a stale view.
+  // SDK errors can contain response bodies/URLs; expose only our stable failure messages.
+  client.onerror = () => {
+    if (closing) return;
+    closing = true; disconnected();
+    void client.close().catch(() => {});
+  };
+  client.onclose = () => { closing = true; disconnected(); };
+  client.setNotificationHandler(ChangedSchema, changed);
+  client.setNotificationHandler(ResourceListChangedNotificationSchema, changed);
+  const abort = () => { void client.close().catch(() => {}); };
+  signal.addEventListener('abort', abort, { once: true });
+  try {
+    signal.throwIfAborted();
+    await client.connect(transport, { signal, timeout: 10_000 });
+    signal.throwIfAborted();
+  } catch {
+    signal.removeEventListener('abort', abort);
+    await client.close().catch(() => {});
+    throw new RemoteFailure();
+  }
+  const options = (operation: AbortSignal) => ({ signal: AbortSignal.any([signal, operation]), timeout: 20_000 });
+  return {
+    read: (uri, meta, operation) => client.readResource({ uri, _meta: meta }, options(operation)),
+    tool: (name, args, meta, operation) => client.callTool({ name, arguments: args, _meta: meta }, undefined, options(operation)) as Promise<CallToolResult>,
+    action: (params, operation) => client.request({ method: 'native-ui/action', params }, ActionResultSchema, options(operation)),
+    async close() {
+      closing = true;
+      signal.removeEventListener('abort', abort);
+      // Pinote owns no detached jobs: release the HTTP session rather than waiting for idle expiry.
+      try { await transport.terminateSession(); } catch { /* A dropped server may already have discarded it. */ }
+      await client.close();
+    },
+  };
+};
+/** Stable errors only: neither env credentials nor transport/server error bodies escape. */
+export function remoteFailure(error: unknown, mutation: boolean): RemoteFailure {
+  return new RemoteFailure(mutation, error instanceof McpError && error.code === UI_STALE_ACTION && StaleActionDataSchema.safeParse(error.data).success);
+}

package/remote/exit.ts

@@ -0,0 +1,84 @@
+import { CustomEditor, type ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import { clean } from './protocol.ts';
+import type { RemoteSession } from './session.ts';
+
+const leave = 'Exit without completing';
+const complete = 'Complete task and exit';
+
+/** Default remote companion. /quit and nonempty-editor input remain Pi-owned. */
+export function registerRemoteExit(pi: ExtensionAPI, getSession: () => RemoteSession | undefined): void {
+  let invalidate: (() => void) | undefined;
+  let stop: (() => void) | undefined;
+  pi.on('session_start', (_event, ctx) => {
+    stop?.();
+    if (ctx.mode !== 'tui' || !ctx.hasUI) return;
+    const previous = ctx.ui.getEditorComponent();
+    let alive = true, pending = false, epoch = 0;
+    let controller: AbortController | undefined;
+    invalidate = () => { epoch++; controller?.abort(); };
+    const exit = async () => {
+      if (!alive || pending) return;
+      pending = true;
+      const generation = epoch, session = getSession();
+      const operation = controller = new AbortController();
+      const sessionId = ctx.sessionManager.getSessionId();
+      const validSession = session?.current();
+      const current = () => alive && generation === epoch && !operation.signal.aborted &&
+        session === getSession() && !!validSession?.() &&
+        ctx.sessionManager.getSessionId() === sessionId && ctx.ui.getEditorText().length === 0;
+      const shutdown = () => { if (!ctx.isIdle()) ctx.abort(); ctx.shutdown(); };
+      try {
+        if (!session) throw new Error('unavailable');
+        await session.refresh(true);
+        if (!current()) return;
+        const view = session.view;
+        if (!view) throw new Error('unavailable');
+        if (view.state.selectedId == null) { shutdown(); return; }
+        const branch = ctx.sessionManager.getLeafId();
+        const done = view.controls.find((c) => c.id === 'done' && c.kind === 'action');
+        const title = truncateToWidth(clean((view.body ?? view.title).split('\n', 1)[0]), 70);
+        const choice = await ctx.ui.select(`Pinote · ${title}`, ['Cancel', leave, complete], {
+          signal: AbortSignal.any([operation.signal, session.signal]),
+        });
+        if (!current()) return;
+        if (choice === leave) { shutdown(); return; }
+        if (choice !== complete) return;
+        const latest = session.view;
+        if (!ctx.isIdle() || ctx.sessionManager.getLeafId() !== branch || !done ||
+            !latest || latest.state.selectedId !== view.state.selectedId || latest.revision !== view.revision ||
+            !latest.controls.some((c) => c.id === done.id && c.kind === done.kind && c.revision === done.revision)) {
+          throw new Error('changed');
+        }
+        // Approval belongs to this exact displayed view, never to a refreshed revision.
+        await session.action(view, done, undefined, () => ctx.isIdle());
+        if (!current()) return;
+        if (session.view && session.view.state.selectedId == null) ctx.shutdown();
+        else ctx.ui.notify('Pinote: Pi stayed open because the selection was not cleared. Refresh /pinote before retrying.', 'warning');
+      } catch {
+        if (alive && generation === epoch) ctx.ui.notify('Pinote: Pi stayed open. Completion was not confirmed and may have committed; refresh /pinote before retrying. /quit exits without completing.', 'warning');
+      } finally { pending = false; }
+    };
+    const factory: NonNullable<ReturnType<typeof ctx.ui.getEditorComponent>> = (tui, theme, keybindings) => {
+      const editor = previous ? previous(tui, theme, keybindings) : new CustomEditor(tui, theme, keybindings);
+      const handleInput = editor.handleInput.bind(editor);
+      editor.handleInput = (data) => {
+        if (alive && keybindings.matches(data, 'app.exit') && editor.getText().length === 0) { void exit(); return; }
+        handleInput(data);
+      };
+      return editor;
+    };
+    ctx.ui.setEditorComponent(factory);
+    stop = () => {
+      alive = false;
+      invalidate?.();
+      if (ctx.ui.getEditorComponent() === factory) ctx.ui.setEditorComponent(previous);
+    };
+  });
+  pi.on('session_shutdown', () => { stop?.(); stop = invalidate = undefined; });
+  const interrupted = () => { invalidate?.(); };
+  pi.on('agent_start', interrupted);
+  pi.on('session_before_switch', interrupted);
+  pi.on('session_before_fork', interrupted);
+  pi.on('session_before_tree', interrupted);
+}

package/remote/footer.ts

@@ -0,0 +1,129 @@
+// Vendored native footer primitive from mcp-session-gateway; no gateway runtime dependency.
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth, visibleWidth, type Component, type TuiMouseEvent, type TuiMouseEventResult } from '@earendil-works/pi-tui';
+import { clean, footerText, type NativeView } from './protocol.ts';
+
+type Item = NonNullable<NativeView['footer']>[number];
+type Row = { uri: string; view: NativeView };
+type Hit = Row & { item: Item; x: number; end: number; y: number };
+const line = (text: string) => clean(text).replace(/\n/g, ' ');
+
+/** Fullscreen-only click regions: no action hyperlinks, pointer changes, or keyboard focus. */
+export class NativeFooter implements Component {
+  private hits: Hit[] = [];
+  private hover?: Hit;
+  private armed?: string;
+  private singleClick?: ReturnType<typeof setTimeout>;
+  private pending = 0;
+  private queue = Promise.resolve();
+  private disposed = false;
+
+  private rows: () => Row[];
+  private theme: Theme;
+  private invoke: (hit: Row, item: Item, action?: string) => Promise<boolean>;
+  private repaint: () => void;
+  constructor(rows: () => Row[], theme: Theme,
+    invoke: (hit: Row, item: Item, action?: string) => Promise<boolean>, repaint: () => void) {
+    this.rows = rows; this.theme = theme; this.invoke = invoke; this.repaint = repaint;
+  }
+
+  private doubleKey(hit: Hit): string | undefined {
+    const action = hit.item.doubleAction;
+    return action ? JSON.stringify([hit.uri, action,
+      hit.view.controls.find((control) => control.id === action)?.revision ?? hit.view.revision]) : undefined;
+  }
+
+  render(width: number): string[] {
+    this.hits = [];
+    return this.rows().filter(({ view }) => view.footer?.length).map(({ uri, view }, y) => {
+      let rendered = '', x = 0;
+      for (const item of view.footer ?? []) {
+        if (x >= width) break;
+        const text = footerText({ ...view, footer: [item] },
+          (value, budget) => truncateToWidth(value, Math.max(0, Math.min(budget, width - x))),
+          (value, style) => {
+            const colored = style.color ? this.theme.fg(style.color, value) : value;
+            return style.italic ? this.theme.italic(colored) : colored;
+          });
+        const end = x + visibleWidth(text);
+        if (end > x && (item.openApp || item.action || item.doubleAction || item.secondaryAction)) {
+          this.hits.push({ uri, view, item, x, end, y });
+        }
+        rendered += text;
+        x = end;
+      }
+      const hovered = this.hits.find((hit) => hit.uri === uri && hit.uri === this.hover?.uri && hit.item === this.hover.item);
+      if (hovered || this.pending) {
+        const label = (id: string) => line(view.controls.find((control) => control.id === id)?.label ?? id);
+        const hint = this.pending ? 'Working…' : hovered!.item.openApp ? `Open ${line(view.title)}`
+          : [hovered!.item.action ? `Click: ${label(hovered!.item.action)}` : '',
+            hovered!.item.doubleAction ? `Double-click: ${label(hovered!.item.doubleAction)}` : ''].filter(Boolean).join(' · ');
+        const remaining = width - x - 3;
+        if (remaining >= 12) rendered += this.theme.fg('muted', ` · ${truncateToWidth(hint, remaining)}`);
+      }
+      return rendered;
+    });
+  }
+
+  private cancelSingleClick(): void {
+    clearTimeout(this.singleClick);
+    this.singleClick = undefined;
+    this.armed = undefined;
+  }
+
+  private dispatch(hit: Hit, action?: string, open = false): void {
+    if (!action && !open) return;
+    this.pending++;
+    this.repaint();
+    this.queue = this.queue.then(async () => {
+      if (!this.disposed) await this.invoke(hit, hit.item, action);
+    }).catch(() => {}).finally(() => {
+      this.pending--;
+      if (!this.disposed) this.repaint();
+    });
+  }
+
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+    const hit = this.hits.find((item) => item.y === event.y && event.x >= item.x && event.x < item.end);
+    if (event.type === 'move') {
+      const changed = hit?.item !== this.hover?.item;
+      this.hover = hit;
+      return changed ? { handled: true, render: true } : undefined;
+    }
+    if (!hit || event.ctrl || event.alt || event.shift || event.type === 'wheel' || event.type === 'drag') return;
+    if (event.type !== 'click') return { handled: true, render: false };
+    let action: string | undefined;
+    let open = false;
+    if (event.button === 'right') {
+      this.cancelSingleClick();
+      if (this.pending) return { handled: true, render: false };
+      action = hit.item.secondaryAction;
+    } else if (event.button === 'left') {
+      const count = event.clickCount ?? 1;
+      if (count === 1 && !this.pending) {
+        this.cancelSingleClick();
+        this.armed = this.doubleKey(hit);
+        action = hit.item.action;
+        open = Boolean(hit.item.openApp);
+        if (this.armed) {
+          // Match Pi TUI's 500ms component double-click window (measured on release).
+          this.singleClick = setTimeout(() => {
+            this.cancelSingleClick();
+            this.dispatch(hit, action, open);
+          }, 500);
+          return { handled: true, render: false };
+        }
+      } else if (count === 2 && this.armed && this.armed === this.doubleKey(hit)) {
+        this.cancelSingleClick();
+        action = hit.item.doubleAction;
+      } else {
+        this.cancelSingleClick();
+      }
+    }
+    this.dispatch(hit, action, open);
+    return { handled: true, render: false };
+  }
+
+  invalidate(): void { this.hits = []; this.hover = undefined; }
+  dispose(): void { this.disposed = true; this.hits = []; this.cancelSingleClick(); }
+}

package/remote/menu.ts

@@ -0,0 +1,106 @@
+import { DynamicBorder, getSettingsListTheme, keyText, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Input, Key, matchesKey, SelectList, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type Container, type TUI } from '@earendil-works/pi-tui';
+import { clean, type NativeView } from './protocol.ts';
+
+export interface MenuState { search: string; selected?: string }
+export interface MenuChoice { id: string; value?: string }
+const line = (text: string) => clean(text).replace(/\n/g, ' ');
+
+/** Reserve the native dock (including footer/widgets), not just the terminal's last row. */
+export function inlineHeight(tui: TUI, width: number, component: Component): number {
+  const children = tui.children ?? [];
+  const owner = children.find((child) => (child as Partial<Container>).children?.includes(component));
+  const reserved = owner ? children.slice(1).filter((child) => child !== owner)
+    .reduce((height, child) => height + child.render(width).length, 0) : 0;
+  return Math.max(1, Math.min(tui.terminal.rows - 6, tui.terminal.rows - 1 - reserved));
+}
+
+/** Public Input/SelectList APIs only; state belongs to this navigation session. */
+export function remoteMenu(ctx: ExtensionContext, view: NativeView, state: MenuState, signal: AbortSignal,
+  watch: (changed: () => void) => () => void): Promise<MenuChoice | undefined> {
+  return ctx.ui.custom<MenuChoice | undefined>((tui, theme, keys, done) => {
+    const input = new Input(); input.setValue(state.search);
+    const settings = getSettingsListTheme();
+    const items = view.controls.map((c) => {
+      const values = c.kind === 'toggle' ? ['false', 'true'] : c.kind === 'select' && (c.options?.length ?? 0) < 5
+        ? c.options?.map((o, i) => `${i + 1}. ${line(o.label)}`) : undefined;
+      const index = c.options?.findIndex((o) => o.value === c.value) ?? -1;
+      return { id: c.id, label: `${c.icon ? `${line(c.icon)} ` : ''}${line(c.label)}`, description: line(c.description ?? ''), values,
+        value: c.kind === 'action' ? 'Open' : c.kind === 'select' ? values?.[index] ?? line(c.options?.find((o) => o.value === c.value)?.label ?? String(c.value ?? '')) : line(String(c.value ?? '')) };
+    });
+    items.push({ id: '__refresh', label: 'Refresh', description: '', value: '', values: undefined });
+    let filtered = items, list: SelectList | undefined, layout = '', geometry = '', usable = false, listTop = 0, listRows = 0;
+    const cancel = () => done(undefined);
+    const changed = () => done({ id: '__changed' });
+    const unwatch = watch(changed);
+    signal.addEventListener('abort', cancel, { once: true });
+    const activate = () => {
+      if (signal.aborted || !usable || !layout || geometry !== `${tui.terminal.columns}:${tui.terminal.rows}`) return;
+      const item = filtered.find((item) => item.id === list?.getSelectedItem()?.value);
+      if (item) done({ id: item.id, value: item.values?.[(item.values.indexOf(item.value) + 1) % item.values.length] });
+    };
+    const component: Component & { dispose(): void; focused: boolean } = {
+      get focused() { return input.focused; },
+      set focused(value) { input.focused = value; },
+      render(width) {
+        const height = inlineHeight(tui, width, component);
+        geometry = `${width}:${tui.terminal.rows}`;
+        usable = width >= 28 && height >= 10;
+        if (!usable) { layout = ''; return [truncateToWidth('Enlarge terminal · Esc back', width)]; }
+        const compact = height < 16;
+        const border = new DynamicBorder((s) => theme.fg('border', s)).render(width);
+        const hints = wrapTextWithAnsi(`${keyText('tui.select.up')}/${keyText('tui.select.down')} move · ${keyText('tui.select.confirm')}/Space change · ${keyText('tui.select.cancel')} back · Ctrl+R refresh`, width);
+        const header = [...border, truncateToWidth(theme.fg('accent', line(view.title)), width),
+          ...(!compact && view.body ? wrapTextWithAnsi(line(view.body), width).slice(0, 2) : []), ...input.render(width), ''];
+        const detailRows = compact ? 1 : 2;
+        // SelectList may append a scroll indicator. Reserve that row even at the ends.
+        const capacity = Math.min(10, height - header.length - detailRows - hints.length - border.length - 2);
+        if (capacity < 1) { usable = false; layout = ''; return [truncateToWidth('Enlarge terminal · Esc back', width)]; }
+        filtered = items.filter((item) => state.search.toLowerCase().split(/\s+/).every((term) => item.label.toLowerCase().includes(term)));
+        const signature = `${width}:${capacity}:${state.search}`;
+        if (layout !== signature) {
+          layout = signature;
+          const labelWidth = Math.min(36, Math.floor((width - 6) * 0.6), Math.max(1, ...items.map((item) => visibleWidth(item.label))));
+          const row = (item: typeof items[number], selected: boolean) => {
+            const label = truncateToWidth(item.label, labelWidth, '');
+            return settings.label(label + ' '.repeat(Math.max(0, labelWidth - visibleWidth(label))), selected) + '  '
+              + settings.value(truncateToWidth(item.value, Math.max(1, width - labelWidth - 6), ''), selected);
+          };
+          list = new SelectList(filtered.map((item) => ({ value: item.id, label: row(item, false) })), capacity, {
+            selectedPrefix: () => '', selectedText: () => settings.cursor + row(filtered.find((item) => item.id === list?.getSelectedItem()?.value)!, true),
+            description: settings.description, scrollInfo: settings.hint, noMatch: () => settings.hint('  No matching settings'),
+          });
+          list.setSelectedIndex(Math.max(0, filtered.findIndex((item) => item.id === state.selected)));
+          list.onSelectionChange = (item) => { state.selected = item.value; };
+          list.onSelect = activate; list.onCancel = cancel;
+          if (list.getSelectedItem()) state.selected = list.getSelectedItem()!.value;
+        }
+        const selected = filtered.find((item) => item.id === list?.getSelectedItem()?.value);
+        const wrapped = wrapTextWithAnsi(selected?.description ?? '', width - 4);
+        const description = wrapped.slice(0, detailRows);
+        if (wrapped.length > detailRows) description[detailRows - 1] = truncateToWidth(description[detailRows - 1], width - 5, '') + '…';
+        while (description.length < detailRows) description.push('');
+        const rows = list!.render(width); listTop = header.length; listRows = Math.min(capacity, filtered.length);
+        return [...header, ...rows, '', ...description.map((s) => settings.description(`  ${s}`)), ...hints.map(settings.hint), ...border]
+          .map((s) => truncateToWidth(s, width));
+      },
+      handleInput(data) {
+        if (keys.matches(data, 'tui.select.cancel') || matchesKey(data, Key.ctrl('c'))) cancel();
+        else if (usable && geometry === `${tui.terminal.columns}:${tui.terminal.rows}`) {
+          if (matchesKey(data, Key.ctrl('r'))) done({ id: '__refresh' });
+          else if (data === ' ' && !state.search) activate();
+          else if ((['tui.select.up', 'tui.select.down', 'tui.select.pageUp', 'tui.select.pageDown', 'tui.select.confirm'] as const).some((key) => keys.matches(data, key))) { if (layout) list?.handleInput(data); }
+          else { input.handleInput(data); if (state.search !== input.getValue()) { state.search = input.getValue(); layout = ''; } }
+        }
+        tui.requestRender();
+      },
+      handleMouse(event) {
+        if (!usable || !layout || geometry !== `${tui.terminal.columns}:${tui.terminal.rows}` || event.y < listTop || event.y >= listTop + listRows) return;
+        return list?.handleMouse({ ...event, y: event.y - listTop });
+      },
+      invalidate() { layout = ''; input.invalidate(); list?.invalidate(); },
+      dispose() { unwatch(); signal.removeEventListener('abort', cancel); },
+    };
+    return component;
+  });
+}

package/remote/protocol.ts

@@ -0,0 +1,77 @@
+// Vendored native-ui v1 wire primitives from mcp-session-gateway; independently hosted here.
+import { z } from 'zod';
+
+// Private, versioned terminal UI protocol, not the HTML MCP Apps extension.
+export const UI_MIME = 'application/vnd.mcp-native-ui+json';
+export const UI_CONTEXT = 'native-ui/context';
+export const UI_STATE = 'native-ui/state';
+export const UI_FEATURES = 'native-ui/features';
+export const UI_STALE_ACTION = -33003;
+export const StaleActionDataSchema = z.object({ 'native-ui/action': z.object({ status: z.literal('not-applied'), reason: z.literal('stale-view') }) });
+const text = z.string().max(20_000);
+const scalar = z.union([text, z.number().finite(), z.boolean(), z.null()]);
+export const StateSchema = z.record(z.string(), z.unknown()).refine((state) => JSON.stringify(state).length <= 8192, 'UI state exceeds 8 KiB');
+const control = z.object({
+  id: z.string().min(1).max(256), label: text, icon: z.string().max(8).optional(), description: text.optional(),
+  kind: z.enum(['action', 'text', 'number', 'toggle', 'select']),
+  value: scalar.optional(), multiline: z.boolean().optional(),
+  options: z.array(z.object({ label: text, value: scalar })).max(256).optional(),
+  confirm: text.optional(), revision: z.string().min(1).max(256).optional(),
+}).strict();
+export const ViewSchema = z.object({
+  version: z.literal(1), title: text, revision: z.string().min(1).max(256),
+  state: StateSchema, body: text.optional(), retainOnNew: z.boolean().optional(),
+  controls: z.array(control).max(256),
+  footer: z.array(z.object({ text, openApp: z.literal(true).optional(), url: z.string().max(2048).optional(), action: z.string().min(1).max(256).optional(), secondaryAction: z.string().min(1).max(256).optional(), doubleAction: z.string().min(1).max(256).optional(), style: z.object({ italic: z.boolean().optional(), color: z.enum(['accent', 'muted', 'text']).optional() }).strict().optional(), width: z.number().int().min(3).max(1000).optional() }).strict()).max(128).optional(),
+}).strict().superRefine((view, ctx) => {
+  if (new Set(view.controls.map((c) => c.id)).size !== view.controls.length) ctx.addIssue({ code: 'custom', message: 'Duplicate control IDs' });
+  for (const item of view.footer ?? []) {
+    if (item.openApp && (item.url !== undefined || item.action || item.secondaryAction || item.doubleAction)) {
+      ctx.addIssue({ code: 'custom', message: 'App launchers cannot also contain URLs or server actions' });
+    }
+    if (item.secondaryAction && (!item.action || !view.controls.some((c) => c.id === item.secondaryAction && c.kind === 'action'))) {
+      ctx.addIssue({ code: 'custom', message: 'Secondary footer actions require a primary action and an action control' });
+    }
+    if (item.doubleAction && (item.url !== undefined || !view.controls.some((c) => c.id === item.doubleAction && c.kind === 'action'))) {
+      ctx.addIssue({ code: 'custom', message: 'Double footer actions must reference an action control and cannot have a URL' });
+    }
+    if (item.action && (item.url !== undefined || !view.controls.some((c) => c.id === item.action && c.kind === 'action'))) {
+      ctx.addIssue({ code: 'custom', message: 'Footer actions must reference an action control and cannot have a URL' });
+    }
+  }
+});
+export const ActionResultSchema = z.object({ view: ViewSchema, draft: text.optional(), preview: text.optional() });
+export const ChangedSchema = z.object({ method: z.literal('notifications/native-ui/changed'), params: z.object({ uri: z.string().max(4096) }) });
+export type NativeView = z.infer<typeof ViewSchema>;
+export type NativeControl = z.infer<typeof control>;
+
+export function clean(text: string): string {
+  return cleanUnbounded(text).slice(0, 20_000);
+}
+
+/** Preserve long generated preview lines while still stripping terminal controls. */
+export function cleanUnbounded(text: string): string {
+  return text.replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+    .replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, '');
+}
+/** Make significant whitespace and controls explicit in operator disclosures. */
+export const literal = (value: unknown) => (JSON.stringify(value) ?? '(unset)')
+  .replace(/[^\x21-\x7e]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
+
+// Editors render their contents literally; do not silently alter editable data.
+export function editorText(text: string): string {
+  if (/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u.test(text)) throw new Error('Unsupported terminal controls in editor text');
+  return text;
+}
+export function footerText(view: NativeView, clip: (text: string, width: number) => string = (text) => text, styleText: (text: string, style: NonNullable<NonNullable<NativeView['footer']>[number]['style']>) => string = (text) => text): string {
+  return (view.footer ?? []).map(({ text, url, style, width }) => {
+    const clipped = clip(clean(text).replace(/\n/g, ' '), width ?? 60);
+    const label = style ? styleText(clipped, style) : clipped;
+    if (!url || /[\s\u0000-\u001f\u007f-\u009f]/u.test(url)) return label;
+    try {
+      const target = new URL(url);
+      if (!['https:', 'http:'].includes(target.protocol) || target.username || target.password) return label;
+      return `\x1b]8;;${target.href}\x1b\\${label}\x1b]8;;\x1b\\`;
+    } catch { return label; }
+  }).join('');
+}