Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

38.1 KB
Raw Blame
// Graceful non-terminal stub surface for the browser (Server Edition) build.
//
// The real namespaces (`pty`, `workspace`, `settings`, `speech`, the fs/git/files/context group
// from `buildFilesApi`, and `dialog` from the in-app `dialog-picker`) are provided by the
// ws-bridge; everything else here degrades benignly so the renderer boots without a full
// Electron preload.
// The exact per-member behavior is the boot-path contract encoded in the Task 7 brief (derived
// from a full renderer-boot audit): every `on*` subscription MUST return a callable no-op
// unsubscribe (the renderer uses the return value as a React effect cleanup — a missing member or
// a non-function return is a mount crash), promise members that the boot path awaits resolve to a
// benign value, and everything else rejects with a coded error.
//
// The object is `satisfies Omit<NodeTerminalApi, 'pty' | 'workspace' | 'settings' | 'fs' | 'git'
// | 'files' | 'context' | 'boardLog' | 'logs' | 'dialog'>`, so the TypeScript compiler is the completeness test: if
// `NodeTerminalApi` gains a member, this file fails to typecheck until the stub is declared.

import {
  UNKNOWN_CLAUDE_CLI_CAPS,
  UNKNOWN_GROK_CLI_CAPS,
  UNKNOWN_CURSOR_CLI_CAPS,
  UNKNOWN_CODEX_IDENTITY_CAPS,
  UNKNOWN_CODEX_CLI_CAPS,
  type ClaudeUsage,
  type ClipboardWriteOptions,
  type NodeTerminalApi,
  type NotifyPayload,
  type UpdatePolicy
} from '../../shared/types'
import { E_UNSUPPORTED } from '../../shared/rpc'
import { INACTIVE_PROJECT_LIMIT, type ClaimResult, type ProjectLimitState } from '../../shared/project-limit'
import { isMacPlatform } from '../../shared/platform-utils'
import { effectiveBindings, terminalShortcutPolicy } from '../lib/keybindingOverrides'
import type { ContextElement } from '../lib/keyContext'
import { createMarkdownToggleSource } from './markdown-toggle-key'

/** Reject with a coded error the RPC layer + renderer recognize (renderer degrades silently). */
export function unsupported(name: string): Promise<never> {
  return Promise.reject(
    Object.assign(new Error(`${name} is not supported in the browser build`), {
      code: E_UNSUPPORTED
    })
  )
}

/** A subscription stub: ignores its listener, returns a no-op unsubscribe. */
export const noopUnsub: () => () => void = () => () => {}

// Per-member helpers. Each returned function ignores its arguments, so it is assignable to the
// real (more-specific) member signature while `satisfies` still enforces the member exists.
/** Promise member that is unavailable on the server. */
const U = (name: string) => (): Promise<never> => unsupported(name)
/** Void (fire-and-forget) member: a synchronous no-op. */
const noop = (): void => {}
/** Promise<void> member: a resolved no-op. */
const pnoop = (): Promise<void> => Promise.resolve()

/** Copy without the Clipboard API (non-secure context): a hidden textarea + execCommand('copy').
 *  Browsers only honor it inside a user gesture. That holds for the copy shortcut and the click-
 *  driven copy buttons, but NOT for the OSC 52 path (`TerminalNode.tsx` — driven by terminal
 *  OUTPUT, e.g. `vim "+y`, with no user activation): over plain http that one always fails and
 *  lands in the error banner below. Returns false when the copy fails, so the caller surfaces it
 *  rather than swallowing it — never silent.
 *
 *  Cleanup is in a `finally` on purpose: `select()`/`execCommand()` CAN throw (Firefox has thrown
 *  NS_ERROR_FAILURE on execCommand('copy')), and a leaked scratch textarea would be invisible,
 *  focused and `position:fixed` — i.e. it would swallow every subsequent keystroke. `select()` also
 *  steals focus from xterm's helper textarea, so the previously-focused element is restored too
 *  (the terminal's *selection* survives on its own — xterm paints it, it is not a DOM Selection). */
function copyViaExecCommand(text: string, quiet = false): boolean {
  const prev = document.activeElement as HTMLElement | null
  let ta: HTMLTextAreaElement | undefined
  try {
    ta = document.createElement('textarea')
    ta.value = text
    ta.setAttribute('readonly', '')
    ta.style.position = 'fixed'
    ta.style.opacity = '0'
    document.body.appendChild(ta)
    ta.select()
    if (!document.execCommand('copy')) throw new Error('execCommand returned false')
    return true
  } catch {
    // A QUIET write (copy-on-select, issue #759) ends here: it fires on every drag, and a banner
    // per drag would be unusable. The explicit copy chord still toasts, so a user on plain http
    // learns the clipboard is blocked the first time they copy deliberately.
    if (quiet) return false
    // Surfacing beats silence: the user needs to know why nothing landed in their clipboard. The
    // diagnosis differs — plain http has no Clipboard API at all, while in a secure context we got
    // here because the API rejected (permission denied / document not focused) AND the fallback
    // failed too. Canvas listens for this event and shows a banner.
    // This module only ever runs in a browser (it IS the browser shim), so `window` is there —
    // guarded consistently rather than half-guarded.
    const secure = window.isSecureContext
    window.dispatchEvent(
      new CustomEvent('nodeterm:toast', {
        detail: {
          kind: 'error',
          message: secure
            ? 'Copy failed — the browser denied clipboard access. Click the page and try again.'
            : 'Copy failed — the browser blocks clipboard access over plain http. Use https or localhost.'
        }
      })
    )
    return false
  } finally {
    // A throw in here would ESCAPE the function and replace the return value (a `finally` outranks
    // both the `return true` and the `return false` above) — so cleanup can never be allowed to
    // throw: `prev.focus()` on an exotic element is out of our control.
    try {
      ta?.remove()
      prev?.focus?.()
    } catch {
      // Cleanup is best-effort; the copy's outcome is what the caller must see.
    }
  }
}

export function buildStubApi(): Omit<
  NodeTerminalApi,
  | 'pty'
  | 'workspace'
  | 'settings'
  | 'integrations'
  | 'fs'
  | 'git'
  | 'files'
  | 'context'
  | 'boardLog'
  | 'logs'
  | 'githubIssues'
  | 'githubControl'
  | 'canvas'
  | 'dialog'
  | 'onAgentStatus'
  | 'agentStatusSnapshot'
  | 'onSubagentActivity'
  | 'onUnreadClear'
  | 'answerPermission'
  | 'ackDone'
  | 'reportHibernated'
  | 'seedAgentIdentity'
  | 'onAgentWake'
  | 'onRemoteViewers'
  | 'onAgentRefreshNode'
  | 'onAgentRenameNode'
  // Real over the bridge (IPC.appUserDataDir): the worktree dialog's default path is derived from
  // it, and a '' stub would propose `/worktrees/…` at the filesystem root.
  | 'userDataDir'
  | 'presence'
  | 'speech'
> {
  const api = {
    ssh: {
      list: U('ssh.list'),
      save: U('ssh.save'),
      remove: U('ssh.remove'),
      importCandidates: U('ssh.importCandidates')
    },
    sshProject: {
      connect: U('sshProject.connect'),
      disconnect: U('sshProject.disconnect'),
      killSessions: U('sshProject.killSessions'),
      listDir: U('sshProject.listDir'),
      mkdir: U('sshProject.mkdir'),
      uploadFile: U('sshProject.uploadFile'),
      downloadFile: U('sshProject.downloadFile'),
      onStatus: noopUnsub,
      submitPassphrase: U('sshProject.submitPassphrase'),
      onPassphraseRequest: noopUnsub,
      onPassphraseDismiss: noopUnsub
    },
    // Desktop only: the Server Edition has no SSH projects, and a relay tab must never drive the
    // host's ssh (relay-api.ts takes this stub rather than the local preload's member).
    shareTeam: {
      probe: U('shareTeam.probe'),
      install: U('shareTeam.install'),
      cancelInstall: U('shareTeam.cancelInstall'),
      onInstallOutput: noopUnsub,
      flushMirror: U('shareTeam.flushMirror'),
      bootstrap: U('shareTeam.bootstrap'),
      killSessions: U('shareTeam.killSessions'),
      resume: U('shareTeam.resume'),
      seedBookmark: U('shareTeam.seedBookmark')
    },
    sshFs: {
      list: U('sshFs.list'),
      read: U('sshFs.read'),
      readBinary: U('sshFs.readBinary'),
      write: U('sshFs.write'),
      mkdir: U('sshFs.mkdir'),
      exists: U('sshFs.exists'),
      quickOpen: U('sshFs.quickOpen')
    },
    clipboard: {
      // Clipboard API → execCommand → visible error. `navigator.clipboard` only exists in a SECURE
      // context (https or localhost); over plain http on a LAN it is undefined, and the old
      // optional-chained call copied nothing and told nobody. execCommand('copy') is deprecated but
      // is the only thing that works there.
      writeText: (text: string, opts?: ClipboardWriteOptions): void => {
        const quiet = opts?.quiet === true
        if (typeof navigator !== 'undefined' && navigator.clipboard) {
          void navigator.clipboard.writeText(text).catch(() => copyViaExecCommand(text, quiet))
          return
        }
        copyViaExecCommand(text, quiet)
      },
      // A browser cannot place host-local file references on the viewer's OS clipboard.
      writeFiles: async (): Promise<boolean> => false
    },
    shell: {
      // no filesystem-reveal in a browser; intentionally inert (see docs/SERVER.md)
      reveal: noop,
      // no OS default-app open in a browser; intentionally inert (see docs/SERVER.md)
      openPath: noop,
      // The one browser-native member: open the URL in a new tab.
      openExternal: (url: string): void => {
        window.open(url, '_blank', 'noopener')
      },
      // Picking + re-encoding an icon needs the main process (native dialog + sharp); a browser
      // client has neither, so this degrades to "cancelled" rather than opening anything.
      pickProjectIcon: async () => null
    },
    media: {
      allow: U('media.allow'),
      // Deliberate graceful degrade: the remote-media cache lives on the DESKTOP shell (scp over
      // the project's ControlMaster). Resolve a typed refusal instead of rejecting so the
      // VideoNode shows the reason rather than a generic load failure.
      allowSsh: (): Promise<{ ok: false; error: string }> =>
        Promise.resolve({ ok: false, error: 'Playing media from an SSH host is not available in the browser.' }),
      writeHtml: U('media.writeHtml')
    },
    browser: {
      register: noop,
      unregister: noop,
      onBrowserNewWindow: noopUnsub,
      // Browser control does not exist off the desktop shell (no <webview>, no CDP), so there is no
      // lease to push and nothing to stop — the chip simply never appears.
      onLeaseChanged: noopUnsub,
      stop: noop,
      stopAll: noop,
      stopProject: noop
    },
    updates: {
      onAvailable: noopUnsub,
      onDownloaded: noopUnsub,
      onProgress: noopUnsub,
      onError: noopUnsub,
      onNotAvailable: noopUnsub,
      // Server Edition has no updater at all (initUpdater runs only in src/main) and a browser
      // tab cannot self-install, so there is no channel state to report either way.
      onNoChannel: noopUnsub,
      // No self-install in a browser, so there is never an install in progress to report.
      onInstalling: noopUnsub,
      // Nothing is ever staged in a browser.
      getStaged: () => Promise.resolve(null),
      check: noop,
      getVersion: U('updates.getVersion'),
      // Boot path awaits this and reads `p.mandatory` UNGUARDED (UpdateCard.tsx), so the old
      // `null as unknown as UpdatePolicy` — a cast that also defeats this file's `satisfies`
      // completeness gate — threw a TypeError on every Server Edition page load. There is no
      // server handler for the update policy (the browser cannot self-install anyway), so the
      // honest answer is the shape's own "no policy" value: nothing mandatory, no minimum.
      getPolicy: (): Promise<UpdatePolicy> => Promise.resolve({ minSupported: null, mandatory: false }),
      restart: noop,
      // Prepare-for-update is a Windows session-host concern (issue #829). The Server Edition runs
      // on Linux with tmux, has no installer to unblock, and a browser tab must never be able to
      // end every session on the server. Documented degrade: `unsupported`, so the entry points
      // never render.
      prepareInspect: () => Promise.resolve({ kind: 'unsupported' as const }),
      prepareShutdownHost: () => Promise.resolve({ kind: 'unsupported' as const }),
      prepareQuit: noop
    },
    announcements: {
      fetch: () => Promise.resolve([]),
      // The Server Edition does not read the check feed, so there is never a popup to show.
      popups: () => Promise.resolve([]),
      popupImage: () => Promise.resolve(null)
    },
    license: {
      upgrade: U('license.upgrade'),
      activate: U('license.activate'),
      deactivate: U('license.deactivate'),
      // Renderer has no catch here and silently degrades to the free tier on rejection.
      getStatus: U('license.getStatus'),
      // Server Edition has no license layer at all (initLicense runs only in src/main), so these
      // reject rather than answer a fabricated "0 devices" — the same degrade as getStatus above.
      detail: U('license.detail'),
      releaseOthers: U('license.releaseOthers'),
      onChange: noopUnsub
    },
    projectLimit: {
      // The Server Edition has no open-project gate (docs/project-limit.md), so it answers the
      // dormant state and every open stays synchronous. Resolved, not rejected: unlike
      // `license.getStatus`, this is read on the open path, and "inactive" is the true answer here
      // rather than "unknown". `claim` answers `disabled` (this shell never talks to the license
      // server) for the same reason: a refusal `ClaimResult` names, where an E_UNSUPPORTED throw is
      // outside the contract.
      state: (): Promise<ProjectLimitState> => Promise.resolve(INACTIVE_PROJECT_LIMIT),
      claim: (): Promise<ClaimResult> =>
        Promise.resolve({ ok: false, error: 'disabled', state: INACTIVE_PROJECT_LIMIT }),
      onChange: noopUnsub
    },
    contextLink: {
      setLinks: pnoop,
      info: U('contextLink.info')
    },
    usage: {
      // Superseded by the real WS-backed namespace in ws-bridge (the core usage service runs in
      // the server shell too), so nothing reaches these in a live browser session. Kept only to
      // satisfy `satisfies NodeTerminalApi`.
      //
      // The `null as unknown as ClaudeUsage` cast is retained on purpose: the boot path awaits
      // `fetch`, and UsageIndicator treats a null snapshot as "nothing to show" and renders
      // nothing. It still lies about its type — the honest fix is widening `UsageApi.fetch` to
      // `Promise<ClaudeUsage | null>`, a public-API change tracked separately.
      fetch: (): Promise<ClaudeUsage> => Promise.resolve(null as unknown as ClaudeUsage),
      refresh: U('usage.refresh'),
      // Empty, not a reject: "no providers configured" is a real answer and the popover
      // renders it as nothing. This one needs no cast — the honest type already fits.
      providers: () => Promise.resolve([]),
      // Same reasoning as `providers`: "no connected SSH hosts" is a real answer, and it is the
      // permanently correct one on a shell with no SSH projects.
      remote: () => Promise.resolve([]),
      setProviderCookie: U('usage.setProviderCookie'),
      cookieProviders: () => Promise.resolve({}),
      onUpdate: noopUnsub
    },
    devPorts: {
      // Deliberately NOT superseded by a WS namespace: the Server Edition does not serve dev ports
      // (its browser tab has no <webview> browser node, and a page the viewer opened would load on
      // the viewer's machine, where the server's port is not). A relay tab shares this surface for
      // the other reason — its sessions live on the host. `unsupported` is the honest answer on
      // both, and the chip is not drawn.
      scan: () => Promise.resolve({ ok: false, reason: 'unsupported', nodes: {} }),
      forward: () =>
        Promise.resolve({ ok: false, reason: 'unsupported', message: 'Port forwarding is not available here.' }),
      unforward: () => Promise.resolve(false)
    },
    // Real in the browser (ws-bridge `buildRecentConversationsApi`). Where this stub stays in force
    // — nowhere today — `unsupported` is the honest answer: "could not look", never "no history".
    recentConversations: {
      list: () => Promise.resolve({ ok: false as const, reason: 'unsupported' as const })
    },
    sessionMemory: {
      // Superseded by the real WS-backed namespace in ws-bridge (the core session-memory service
      // runs in the server shell too), so nothing reaches these in a live browser session. Kept
      // only to satisfy `satisfies NodeTerminalApi`.
      //
      // Where it DOES stay in force is the relay tab, which shares this stub surface: there the
      // renderer runs on the guest while the sessions live on the host, so answering at all would
      // describe the wrong machine. `ok:false` / `null` are the service's own words for "could not
      // measure" — the one honest answer, and never mistakable for "nothing is using memory".
      read: () => Promise.resolve({ ok: false, rows: [], mem: null }),
      host: () => Promise.resolve(null)
    },
    wallpaper: {
      // Superseded by the real WS-backed namespace in ws-bridge (registerWallpaperIpc runs in the
      // server shell). A RELAY tab keeps this: the wallpaper is this window's own appearance, and
      // the peer's disk has nothing to say about it. No stills, nothing to load (gradient presets
      // are pure CSS and need no bridge), and import refuses.
      listStills: () => Promise.resolve([]),
      load: () => Promise.resolve(null),
      importImage: U('wallpaper.importImage'),
      listAerials: () => Promise.resolve([]),
      aerialClips: () => Promise.resolve([])
    },
    simulator: {
      devices: () => Promise.resolve({ devices: [] }),
      boot: () => Promise.resolve({ ok: false as const, error: 'Simulator views are only available in the desktop app.' }),
      // DESKTOP only, deliberately not bridged: the helper talks to the simulator frameworks
      // of the machine it runs on, and a Server Edition / relay tab's canvas is on another one. The
      // node is not offered there; these say why if reached anyway.
      start: () => Promise.resolve({ ok: false as const, error: 'Simulator views are only available in the desktop app.' }),
      stop: () => Promise.resolve(),
      input: () => Promise.resolve(false),
      shutdown: () => Promise.resolve(false),
      action: () => Promise.resolve({ ok: false as const, error: 'Simulator views are only available in the desktop app.' }),
      state: () => Promise.resolve({}),
      screenshot: () => Promise.resolve({ ok: false as const, error: 'Simulator views are only available in the desktop app.' }),
      startRecording: () => Promise.resolve({ ok: false as const, error: 'Simulator views are only available in the desktop app.' }),
      stopRecording: () => Promise.resolve({ ok: false as const, error: 'Not recording.' }),
      isRecording: () => Promise.resolve(false),
      onFrame: () => () => {},
      onStatus: () => () => {}
    },
    runConfig: {
      // Superseded by the real WS-backed namespace in ws-bridge (registerRunConfigIpc runs in the
      // server shell). A RELAY tab keeps this: its terminals run on the PEER, so this machine's
      // folders, devices and processes would describe the wrong computer — the run node is not
      // offered there, and these answer "nothing" rather than guess.
      entries: () => Promise.resolve({ found: false, entries: [], isFlutterProject: false }),
      devices: () => Promise.resolve({ devices: [], error: 'Runs are managed on the host' }),
      bootDevice: () => Promise.resolve(false),
      discoverProjects: () => Promise.resolve([]),
      start: () => Promise.resolve({ ok: false as const, error: 'Runs are managed on the host' }),
      status: () => Promise.resolve({ running: false, exitCode: null }),
      stop: () => Promise.resolve(false),
      signal: () => Promise.resolve(false),
      watch: () => Promise.resolve()
    },
    triggers: {
      // Superseded by the real WS-backed namespace in ws-bridge (startTriggerService registers the
      // handlers in the server shell). On the RELAY tab this stub stays in force and REFUSES: the
      // arm store, the scheduler and the sessions all live on the host — arming from the guest
      // would write another machine's execution consent. The card catches the rejection and says
      // triggers are managed on the host machine.
      arm: U('triggers.arm'),
      disarm: U('triggers.disarm'),
      status: U('triggers.status'),
      runNow: U('triggers.runNow')
    },
    codex: {
      // Overridden by the real WS-backed namespace in ws-bridge. The stub's answer is the same
      // one the Server Edition gives on purpose (see server/handlers/index.ts): no shared
      // identity, so every Codex launch line stays the bare `codex`.
      identityCaps: () => Promise.resolve(UNKNOWN_CODEX_IDENTITY_CAPS),
      // A RELAY tab keeps this stub: its sessions run on the GUEST's machine, whose codex is a
      // different binary from the one this probe could reach, and applying our vocabulary to their
      // launch line is precisely the cross-machine guess this gate exists to stop. Unknown ⇒ the
      // baseline vocabulary ⇒ the two values every measured codex accepts; "Ask each time" is
      // reported as unsupported there rather than gambling `untrusted` on someone else's CLI.
      // Overridden by the real WS-backed namespace in ws-bridge for the Server Edition.
      cliCaps: () => Promise.resolve(UNKNOWN_CODEX_CLI_CAPS),
      onIdentity: noopUnsub
    },
    claude: {
      // Overridden by the real WS-backed namespace in ws-bridge; the stub still answers with the
      // fail-open caps (never rejects) because the permission-mode gate reads it on the boot path.
      cliCaps: () => Promise.resolve(UNKNOWN_CLAUDE_CLI_CAPS),
      readTranscript: U('claude.readTranscript')
    },
    grok: {
      // Same shape and same reason as claude's above: the launch path reads this synchronously, so
      // it must resolve rather than reject. Unprobed ⇒ no `--session-id` ⇒ today's command line.
      cliCaps: () => Promise.resolve(UNKNOWN_GROK_CLI_CAPS),
      // Nothing taken is the honest answer where no shell can look, and it degrades to today's
      // behaviour: mint freely. Overridden by the real WS-backed namespace in ws-bridge.
      takenSessionIds: () => Promise.resolve([])
    },
    cursor: {
      // Overridden by the real WS-backed namespace in ws-bridge. Never rejects: empty = no picker.
      cliCaps: () => Promise.resolve(UNKNOWN_CURSOR_CLI_CAPS)
    },
    agent: {
      // No env snapshot outside the desktop window: the stub (and ws-bridge, identically) answers
      // an empty env, so `${env:VAR}` expansion reports every referenced var as missing and the
      // launch/preview paths degrade to the missing-env refusal instead of a host-env dump.
      envSnapshot: () => Promise.resolve({}),
      discoverModels: () => Promise.resolve({ models: [], error: 'Model discovery is unavailable.' }),
      gatewayCredentialStatus: () =>
        Promise.resolve({ hasStoredKey: false, storage: 'unavailable' }),
      saveGatewayCredential: U('agent.saveGatewayCredential'),
      clearGatewayCredential: U('agent.clearGatewayCredential')
    },
    projectSettings: {
      // Overridden by the real WS-backed namespace in ws-bridge (same registerIpc() call as
      // `workspace`); this fallback only matters if some future assembly spreads the stub alone.
      // Fail-closed rather than reject: an unknown/unreachable project reads as "no settings" and
      // a write/update as "did not happen", matching the real handlers' contract for an unknown id.
      read: () => Promise.resolve(null),
      writeShared: () => Promise.resolve(false),
      updateLocal: () => Promise.resolve(false),
      launchInfo: () => Promise.resolve(null),
      onTrustChanged: noopUnsub
    },
    projectSetup: {
      // Same fallback story as `projectSettings` above — real over the bridge
      // (`buildRealApi`'s `projectSetup`); this only matters if some future assembly spreads the
      // stub alone. `run` fails closed with the SAME shape a real "nothing to run" answer uses, so
      // a caller needs no extra branch to handle the stub differently from the real thing.
      run: () => Promise.resolve({ status: 'skipped', reason: 'unavailable' }),
      cancel: () => Promise.resolve(false),
      consent: pnoop,
      // Fails closed, like `run`: no bridge means no way to ask a human, and an unasked question
      // is never an approval.
      requestTrust: () => Promise.resolve(false),
      onConsentRequest: noopUnsub,
      onConsentDismiss: noopUnsub,
      onEvent: noopUnsub
    },
    worktree: {
      // Real over the bridge (`buildRealApi`'s `worktree`); this fallback only matters if some
      // future assembly spreads the stub alone. Fails closed with the SAME empty-result shape a
      // real "nothing was linked" answer uses, so a caller needs no extra branch.
      materializeShared: () => Promise.resolve([])
    },
    chat: {
      readTranscript: U('chat.readTranscript'),
      // Resolves rather than rejects, like the two `cliCaps` above and for the same reason: cold
      // restore awaits this on the boot path, and its whole contract is that anything it cannot
      // judge is `unknown` ⇒ resume exactly as before. A rejection here would be a second way of
      // saying the same thing that every caller would have to remember to catch.
      transcriptExists: () => Promise.resolve('unknown' as const),
      // Rejects: a surface with no catalog reader (relay tabs) falls back to the shared built-in
      // table in the composer, which is the honest subset — never another machine's files.
      catalog: U('chat.catalog')
    },
    claudeAccounts: {
      add: U('claudeAccounts.add'),
      waitLogin: U('claudeAccounts.waitLogin'),
      cancelWaitLogin: U('claudeAccounts.cancelWaitLogin'),
      remove: U('claudeAccounts.remove'),
      link: U('claudeAccounts.link'),
      setSkillSharing: U('claudeAccounts.setSkillSharing'),
      copySession: U('claudeAccounts.copySession')
    },
    codexAccounts: {
      add: U('codexAccounts.add'),
      waitLogin: U('codexAccounts.waitLogin'),
      cancelWaitLogin: U('codexAccounts.cancelWaitLogin'),
      identity: U('codexAccounts.identity'),
      systemIdentity: U('codexAccounts.systemIdentity'),
      remove: U('codexAccounts.remove'),
      switchThread: U('codexAccounts.switchThread'),
      commitSwitch: U('codexAccounts.commitSwitch'),
      finishSwitch: U('codexAccounts.finishSwitch'),
      rollbackSwitch: U('codexAccounts.rollbackSwitch'),
      switchThreadRemote: U('codexAccounts.switchThreadRemote'),
      transferThreadToSsh: U('codexAccounts.transferThreadToSsh')
    },
    transcripts: {
      search: U('transcripts.search')
    },
    remoteHost: {
      start: U('remoteHost.start'),
      stop: U('remoteHost.stop'),
      sendCanvasState: noop,
      onApplyMutation: noopUnsub,
      onPeerPending: noopUnsub,
      onPeerPendingCleared: noopUnsub,
      // Standing phone hosting is Desktop-only; never pretend that a browser pinned a phone.
      approvePhone: U('remoteHost.approvePhone'),
      approve: (_id: string) => {},
      reject: (_id: string) => {},
      setPhoneAccess: noop
    },
    // New relay tunnel (Stage 4). Hosting/connecting a peer-to-peer relay is a desktop-only
    // (Electron) capability — the Server Edition is itself the remote host, reached over its own WS
    // bridge — so the entry points (`start`/`connect`) reject with E_UNSUPPORTED and the UI hides
    // the affordance. Because those never yield a live connection, the gate/frame void members are
    // inert no-ops (there is no connectionId to act on) and the subscriptions are no-op unsubscribes.
    relayHost: {
      start: U('relayHost.start'),
      invite: U('relayHost.invite'),
      stop: U('relayHost.stop'),
      // Nothing can be hosted here (start/invite are unsupported), so nothing is refused either.
      scopeProblems: async () => ({}),
      revoke: noop,
      onPeerPending: noopUnsub,
      confirm: noop,
      onOpen: noopUnsub,
      onClosed: noopUnsub
    },
    relayClient: {
      connect: U('relayClient.connect'),
      onSas: noopUnsub,
      confirm: noop,
      onApproved: noopUnsub,
      send: noop,
      onFrame: noopUnsub,
      onClosed: noopUnsub,
      disconnect: noop
    },
    // A browser cannot join a relay host (only the desktop's main process holds a relay client),
    // so it has joined no hosted team: an empty list is the true answer, not a degrade.
    relayHosted: {
      bookmarks: async () => [],
      removeBookmark: async () => {}
    },
    handoff: {
      build: U('handoff.build')
    },
    pairing: {
      start: U('pairing.start'),
      stop: U('pairing.stop'),
      onDone: noopUnsub,
      probeSsh: U('pairing.probeSsh'),
      openRemoteLoginSettings: U('pairing.openRemoteLoginSettings'),
      listDevices: U('pairing.listDevices'),
      revokeDevice: U('pairing.revokeDevice'),
      // The Server Edition has no relay host key and no paired-phone registry, so it cannot own a
      // push webhook (same degrade as push-notify). The Settings row is hidden in the browser.
      webhookStatus: U('pairing.webhookStatus'),
      webhookMint: U('pairing.webhookMint'),
      webhookRevoke: U('pairing.webhookRevoke'),
      webhookEndpoint: U('pairing.webhookEndpoint')
    },
    shortcuts: {
      // Deliberate no-op (not a gap): the recording bit exists to stand the DESKTOP's
      // `before-input-event` intercepts down, and a browser tab has no application menu to steal
      // ⌘W/⌘M/⌘0 back from — nothing intercepts here, so there is nothing to suspend. The
      // recorder's own preventDefault/stopPropagation is the whole path in this shell; that also
      // covers the ⌘M window listener below, which is bubble-phase and skips a prevented event.
      setRecording: noop,
      // Deliberate no-op for the same reason, one step further: the mirror exists so the DESKTOP's
      // intercepts can stand down under `terminal-first`, and there are no intercepts here to
      // stand down. The policy itself still works in the browser — it is enforced by the
      // renderer's own dispatcher (`keyDispatchContextFor`), which reads focus directly.
      setTerminalFocused: noop
    },
    // Deliberate degrade: `nodeterm://` links are an OS URL-scheme registration, which only the
    // desktop app has. Nothing ever fires here; accept refuses.
    openLink: {
      ready: noop,
      onRequest: noopUnsub,
      onPair: noopUnsub,
      onNotice: noopUnsub,
      accept: U('openLink.accept'),
      cancel: noop
    },
    // REAL, not a stub: a browser tab has no main process to intercept ⌘/Ctrl+M, so the chord is
    // matched by a window keydown listener here (bindings, terminal-first stand-down and focus all
    // read live — see markdown-toggle-key.ts, including why macOS Chrome never delivers ⌘M).
    // Node-env tests have no window: they get the inert unsubscribe the boot contract requires.
    onMarkdownToggle:
      typeof window === 'undefined'
        ? noopUnsub
        : createMarkdownToggleSource({
            target: window,
            bindings: () => effectiveBindings('node.toggleMarkdown'),
            isMac: isMacPlatform,
            policy: terminalShortcutPolicy,
            activeElement: () => document.activeElement as unknown as ContextElement | null
          }),
    onCloseNode: noopUnsub,
    // Deliberate no-op (not a gap): a browser tab has no application menu to steal ⌘0, so the
    // renderer's own keydown handler is the whole path there.
    onZoomActualSize: noopUnsub,
    // Native app-menu events (desktop-only — the Server Edition has no native menu). Stubs so the
    // bridge satisfies NodeTerminalApi; the canvas only wires real listeners on desktop.
    onToggleAutoAlign: noopUnsub,
    onFitView: noopUnsub,
    onToggleKanban: noopUnsub,
    onOpenSettings: noopUnsub,
    closeWindow: noop,
    // Best-effort: a browser tab can't force itself frontmost the way the desktop BrowserWindow
    // can, but `window.focus()` still helps when the page is merely blurred (not another OS app).
    focusWindow: () => {
      try {
        window.focus()
      } catch {
        /* focus is a no-op in some embeddings — never throw into a drop handler */
      }
    },
    setBadgeCount: noop,
    // UI scale is page zoom, and a browser page cannot set its own — the browser already owns the
    // identical mechanism (Cmd/Ctrl+±, persisted per site). Intentionally inert; the Settings row
    // is disabled with this reason on the Server Edition (AppearanceSection's browser branch).
    setUiZoomFactor: noop,
    getPathForFile: (): string => '',
    notify: async (payload: NotifyPayload): Promise<'shown' | 'failed' | 'skipped'> => {
      if (typeof Notification !== 'undefined' && Notification.permission === 'granted') {
        try {
          new Notification(payload.title, { body: payload.body })
          return 'shown'
        } catch {
          return 'skipped'
        }
      }
      return 'skipped'
    },
    openNotificationSettings: pnoop,
    onFocusNode: noopUnsub,
    // Server Edition v1: the memory-pressure levers run HOST-side only (the session reaper, driven
    // by the same core monitor in src/server/index.ts). A browser tab's own memory — its WebGL
    // contexts and parked terminals — belongs to the browser, which already discards and reclaims
    // on its own terms; pushing our levers over the wire would fight it, not help it. Deliberate
    // no-op, not an oversight.
    onMemoryPressure: noopUnsub,
    // Deliberate no-op, not an oversight. The desktop signal means "the user put the app away"
    // (tray / hide / minimize). The browser's nearest analogue, `visibilitychange`, fires on every
    // tab switch AND on occlusion — wiring it here would release every terminal of a user who
    // glanced at another tab for two minutes. The browser throttles and discards a hidden tab on
    // its own terms; the viewport-driven levers keep working unchanged.
    onWindowVisibility: noopUnsub,
    // Same asymmetry, one step further: the desktop's pty-pressure banner exists to offer "Fix
    // automatically…", which ends in macOS's admin-password dialog on the HOST's physical display.
    // A browser tab cannot answer that prompt, so the host keeps the reaper leg and says nothing
    // here (see the note beside createPtyPressureMonitor in src/server/index.ts). The fix itself
    // rejects rather than pretending, so a stray call can never look like it worked.
    onPtyPressure: noopUnsub,
    // A browser tab has no raw input stream to classify — trackpad-vs-mouse ground truth exists
    // only under the Electron shell (main/trackpad-gesture.ts). Never fires here; the canvas
    // wheel router is constructed WITHOUT gesture reporting in this runtime and keeps its
    // delta-shape heuristics, so the degrade is a kept behavior, not a silent gap.
    onCanvasTrackpadGesture: noopUnsub,
    raisePtyDeviceLimit: async () => ({
      ok: false as const,
      error: 'Raising the terminal limit must be done on the machine running the server.'
    }),
    onAgentControl: noopUnsub,
    sendAgentControlResult: noop,
    // Browser control is desktop-only (no <webview>, no CDP on the Server Edition / relay), so the
    // resolve round-trip is inert here — the verb is refused by name before it reaches a handler.
    onBrowserControlResolve: noopUnsub,
    sendBrowserControlResolveResult: noop,
    // The phone Chat verbs are served by the phone relay host, which lives only in the desktop
    // main process — the Server Edition serves no phone relay, so nothing asks this renderer.
    onHostChatQuery: noopUnsub,
    sendHostChatReply: noop,
    // Messaging never runs in the browser: `onAgentControl` above is inert here, so no dispatch
    // can ever reach this. It answers the honest terminal refusal all the same, so a stray call
    // can never look like it delivered.
    agentMessage: {
      deliver: async () => ({
        ok: false as const,
        error: 'Agent messaging is only available in the desktop app. Do not retry.'
      }),
      // A board comment typed here — in a browser tab, or in a relay tab onto another machine — is
      // display-only on purpose: it never types into a pane. The typed outcome lets the comment row
      // say so instead of showing nothing.
      deliverBoardComment: async () => ({
        ok: false as const,
        error: 'Board comments reach agents only in the desktop app.',
        result: { kind: 'notPermitted', reason: 'unsupported-edition' }
      })
    },
    // Board-dispatch report: the Server Edition's `buildStationNoticeApi` carries the real one, and a
    // relay tab keeps this no-op (its board is the host's).
    boardDispatch: { report: noop },
    // Inert by default: the Server Edition overrides it with the real bridge
    // (`buildStationNoticeApi`), and a relay tab keeps this — its stations belong to the host's core.
    stationNotice: {
      list: async () => [],
      onChanged: noopUnsub,
      reportDropped: noop
    },
    // Same split: the Server Edition overrides it (`buildStationOutcomeApi`); a relay tab keeps this.
    stationOutcome: {
      list: async () => [],
      onChanged: noopUnsub
    },
    // Same split again: the Server Edition overrides it (`buildStationHandoverApi`).
    stationHandover: {
      list: async () => [],
      onChanged: noopUnsub
    },
    // Governs nothing by default. The Server Edition overrides it with the real bridge
    // (`buildCanvasAuthorityApi`); a relay tab answers from its own connection (relay-api.ts).
    canvasAuthority: {
      assumeAllUntilAnswered: false,
      governed: async () => [],
      onChanged: noopUnsub
    }
  } satisfies Omit<
    NodeTerminalApi,
    | 'pty'
    | 'workspace'
    | 'settings'
    | 'integrations'
    | 'fs'
    | 'git'
    | 'files'
    | 'context'
    | 'boardLog'
    | 'logs'
    | 'githubIssues'
    | 'githubControl'
    | 'canvas'
    | 'dialog'
    | 'onAgentStatus'
    | 'agentStatusSnapshot'
    | 'onSubagentActivity'
    | 'onUnreadClear'
    | 'answerPermission'
  | 'ackDone'
  | 'reportHibernated'
  | 'seedAgentIdentity'
  | 'onAgentWake'
  | 'onRemoteViewers'
  | 'onAgentRefreshNode'
  | 'onAgentRenameNode'
    | 'userDataDir'
    | 'presence'
    | 'speech'
  >

  return api
}