Files
Netcatty/docs/plugin-platform/terminal-providers.md
T
13fa68a720 feat(plugins): add sync providers and encrypted sidecar sync (#2713)
* feat(plugins): add sync providers and encrypted sidecar sync

Implement PR 8 of the plugin platform (#2269): namespaced sync Providers
with provider.sync, encrypted-object storage operations, WebDAV through the
shared storage surface, dynamic cloud provider IDs, and non-cascade sidecars
for sync:true plugin settings plus account/CRDT baselines.

Related to #2269

* fix(plugins): wire sync providers and sidecars into production paths

Close PR 8 integration gaps: dynamic plugin provider registry and
getConnectedAdapter createPluginStorage, WebDAV through EncryptedObjectStorage,
cloud payload collect/apply for pluginSidecars, and IPC/preload bridges.

Related to #2269

* fix(plugins): preserve WebDAV auth reuse and resourceId through EOS wrap

encryptedObjectStorageAsCloudAdapter now reports initiallyAuthenticated when
config exists (matching raw WebDAVAdapter) so getConnectedAdapter reuses the
cached instance, and preserves/refreshes resourceId from the backing adapter
instead of always forcing the default object key.

Related to #2269

* fix(plugins): address Codex PR 8 review findings

Carry pluginSidecars through merge/convergent uploads, lazy-connect before
object I/O with revision-aware writes, fail closed on sidecar collect errors,
expose connectPluginProvider, preserve remote timestamps, and drop deleted
installed-plugin settings from collection.

Related to #2269

* fix(plugins): close remaining Codex P1/P2 sync issues

Lazy stream cancel for inline sync reads, must-not-exist conditional writes,
three-way sidecar merge for local resets, validated apply path for settings,
and merge remote sidecars into convergent uploads.

Related to #2269

* fix(plugins): harden sidecar collect/apply and write verification

Preserve last-known sidecars when the host is offline, apply remote
deletions for installed plugins, force convergent upload on sidecar
divergence, verify plugin object writes, and pick plugin providers in
auto-sync startup checks.

Related to #2269

* fix(plugins): close remaining Codex sidecar/sync path gaps

Include sidecars in auto-sync payload and hash, keep explicit empty bundles,
fail apply when host is offline, require getCapabilities, and carry merged
sidecars into convergent local apply/upload decisions.

Related to #2269

* fix(plugins): close Codex P1 sidecar collect/apply/merge gaps

Treat null host responses as unavailable, persist collected settings into
the non-cascade table, retain decoded convergent payloads, use three-way
sidecar merge for deletions, and fail apply only on operational errors.
Also treat non-empty plugin sidecars as meaningful sync data and re-run
auto-sync when plugin contributions change.

Related to #2269

* fix(plugins): close remaining Codex P1 sidecar and provider gaps

Replay offline-cached sidecars before collect, keep explicit empty
sidecar fields after three-way merge, thread sidecars through convergent
conflict/downgrade materialization, keep gated-off plugin providers from
joining sync as connected, and rebind plugin EOS sessions after runtime
replacement.

Related to #2269

* fix(plugins): separate pending remote sidecars from last-known cache

Replay only host-offline remote applies into the DB, keep last-known as
upload fallback, use contribution reset for deleted settings, probe real
plugin host readiness, rebind storage events for plugin providers, clear
plugin bases on reset, and swallow disconnect rejections.

Related to #2269

* fix(plugins): hydrate retained sidecars and gate missing providers

Materialize installed-plugin settings from retained sidecars before
collect pruning, clear sidecars on setting reset, fail closed when
pending remote replay fails, and only restore plugin providers that are
contribution-available. Also initialize dynamic provider counters on
connect.

Related to #2269

* fix(plugins): surface plugin sync providers and preserve conflict sidecars

Collect live sidecars before convergent conflict apply/upload, include
dynamic providers in status and disconnect paths, and list plugin sync
providers in Cloud Sync settings for connect/disconnect.

Related to #2269

* fix(plugins): per-provider sidecar baselines and safer collect/UI

Merge convergent sidecars against each provider's own baseline, keep
retained settings in sidecars without unvalidated plugin_settings writes,
guard isConnectDisabled for never-connected plugins, and fall back plugin
provider labels/icons in the status popup.

Related to #2269

* fix(plugins): correct plugin provider discovery and sidecar reverify

Read nested contribution metadata for sync provider cards, gate empty-config
connects, enforce single-provider disconnect for plugins, and re-verify after
sidecar-only convergent uploads so baselines track the post-write payload.

Related to #2269

* fix(plugins): refresh sync provider availability from live contributions

Replace the contribution-available provider ID set when plugins change so
disabled or uninstalled sync providers leave the auto-sync ready set and
drop to disconnected with config retained.

Related to #2269

* fix(plugins): preserve sidecars in backups, pending queue, and migration

Attach last-known plugin sidecars to protective local vault backups, fail
operationally when pending/last-known storage writes are rejected, carry
sidecars through convergent migration publish, and reject trailing garbage
on encrypted object parse.

Related to #2269

* fix(plugins): abort conflict collect failures and merge migration sidecars

Rethrow operational sidecar collection errors during convergent conflict
resolution, LWW-union all local/provider sidecars during convergent
migration, re-collect last-known after apply, and prefer live host collect
for protective local vault backups.

Related to #2269

* fix(plugins): restore pluginBridge tests, fix import path, union downgrade sidecars

Correct SettingsSyncTab dynamic import path so production builds resolve,
add ipcMain.on to the plugin bridge test double, union all provider
sidecars on convergent downgrade, keep empty last-known resets, and skip
force-delete when contribution reset validation rejects.

Related to #2269

* fix(plugins): abort backup collect failures and honor empty remote wipes

Only fall back to last-known sidecars when the host is unavailable during
protective backups, treat explicit empty remote sidecar bundles as
authoritative wipes, remove lint-blocking anys from harness tests, and
use a stable equal-timestamp sidecar tie-break.

Related to #2269

* fix(plugins): include sidecars in equality, preserve merge base on reconnect

Compare pluginSidecars in cloudSyncPayloadsEqual for migration freshness,
clear plugin merge state only when account/resource changes on reconnect,
cancel accepted sync read streams on failure, and stop re-connecting the
plugin EOS adapter on every I/O.

Related to #2269

* fix(plugins): drop cached adapters on contribution refresh

Invalidate plugin sync adapters when live contributions change so a
restarted runtime gets a fresh connect, take offline any non-disconnected
missing providers, and latch version-change backups only after cancellation
checks pass.

Related to #2269

* fix(plugins): preserve omitted sidecars and hydrate on plugin enable

Treat missing pluginSidecars as legacy/unsupported in three-way merge
(only explicit empty is a wipe), hydrate retained settings when a plugin
enables, and re-enable retained provider configs when contributions return.

Related to #2269

* fix(plugins): keep newer retained sidecars over older stored settings

When collection merges existing sidecars with plugin_settings rows, prefer
the newer updatedAt so a schema-rejected remote value retained only in
the sidecar table is not overwritten by a stale local setting.

Related to #2269

* fix(plugins): seal plugin provider config and clear base on config change

Encrypt opaque plugin provider configuration before persistence, clear
merge state when reconnect configuration changes, and stream sync objects
below a base64-safe inline threshold so control-plane JSON stays in budget.

Related to #2269

* fix(plugins): seal plugin configs by provider id and hydrate before start

Encrypt plugin provider configuration only for non-builtin provider IDs
so field-name collisions cannot skip sealing, hydrate retained sidecars
before plugin enable starts the runtime, and stop tearing down live
adapters on no-op availability refreshes.

Related to #2269

* fix(plugins): seal scalar configs, safe inline reads, stable config fingerprint

Encrypt any non-builtin plugin configuration JSON shape, enforce the
base64-safe inline read cutoff, and compare reconnect configurations with
order-independent fingerprints so merge bases are not cleared spuriously.

Related to #2269

* fix(plugins): thread sync credentials and harden availability checks

Pass SyncConnectPayload.credential through the object-storage and IPC host
path, treat only null/undefined config as missing, and avoid wiping the
plugin provider availability catalog on transient discovery failures.

Related to #2269

* fix(plugins): unblock schema-required sync connect and scalar configs

Add a JSON config dialog for plugin sync providers that declare a
required configurationSchema, reuse retained configs on reconnect, and
treat falsy scalar configs as present in readiness and adapter lookup.

Related to #2269

* fix(plugins): rebind sync adapters on contribution refresh

Drop cached plugin sync adapters when live contributions still include
the provider so replaced runtimes get a fresh connect, and seal falsy
scalar plugin configs with nullish presence checks end-to-end.

Related to #2269

* fix(plugins): apply sidecars under current declared setting scopes

When a plugin update changes a syncable setting scope, write under the
live declaration and drop the obsolete scope row so collection does not
republish duplicates.

Related to #2269

* fix(plugins): seal config envelopes and stabilize provider counters

Use an unambiguous host-owned sealed-config envelope, initialize
dynamic-provider sequence counters before cross-window decrypt, keep
three-way sidecar deletions during convergent migration, and create the
sidecar table for existing schema-1 plugin databases.

Related to #2269

* fix(plugins): avoid mid-sync adapter drops and sidecar resurrection

Keep plugin adapters across setting-only contribution refreshes and
rebind sessions on ensureConnected; stop preserving local-only missing
plugin sidecars when remote already mentions the plugin; compare configs
with nullish semantics across windows; swallow quick-connect failures
after toasting.

Related to #2269

* fix(plugins): restore remoteKeys for installed sidecar resets

Reintroduce the remote key set used when dropping installed-plugin
settings the remote no longer carries so applyFromSync cannot throw
after replacing the sidecar table.

Related to #2269

* fix(plugins): honor conflict policy and re-key scoped sidecars

Pass preferCloud/preferLocal into three-way sidecar merge, use
per-provider baselines on convergent downgrade so local resets are not
resurrected, and re-key applied settings under the current declared
scope coordinates.

Related to #2269

* fix(plugins): keep strategy on final sidecar merge and block dual legacy

Pass preferCloud/preferLocal through the final verified sidecar merge,
avoid auto-reactivating a retained plugin while another legacy provider
is already connected, cache plugin adapters only after initializeSync,
and preserve explicit null configuration values.

Related to #2269

* fix(plugins): strip plugin avatars and protect last-known sidecars

Do not load plugin-supplied avatar URLs in the main renderer, and avoid
overwriting last-known sidecars with an unmerged remote bundle when the
post-apply collect fails or is non-authoritative.

Related to #2269

* fix(plugins): strip top-bar plugin avatars and stop always-rebind

Hide plugin avatar URLs in the sync status popover, drop always-on
rebindSession for plugin adapters, and read convergent mode from the
local config module when deciding whether to auto-reactivate providers.

Related to #2269

* fix(plugins): use window.netcatty for sync IPC and allow null configs

Read plugin sync and sidecar APIs from the production preload global,
and treat an explicit config property (including JSON null) as present
for readiness and adapter lookup.

Related to #2269

* fix(plugins): close residual Codex P2 sync edge cases

Three-way merge sidecars during v2 convergent migration so local
resets are not resurrected, preserve explicit null plugin configs on
adapter rebuild, rebind EOS sessions after I/O failure for replaced
runtimes, and accept the public inlineObjectBytes limit on readObject.

Related to #2269

* fix(plugins): keep inline read cutoff under control-plane budget

Restore the base64-safe inline cutoff so advertised-size reads cannot
overflow the 128 KiB provider JSON envelope; providers near the public
inlineObjectBytes limit must stream.

Related to #2269

* fix(plugins): harden sidecar empty-vault, hydrate LWW, and credential seals

Close remaining Codex/review gaps for PR8: keep empty sidecar shells from
bypassing upload guards, skip startup hydrate when local settings are newer,
seal/validate durable plugin credential refs, and cover schema 1→2 migration.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): rebind plugin sync sessions and keep null configs

Address Codex P2 on 8ae52c54: re-issue connect after runtime replacement,
and treat stored config:null as present in the dashboard reconnect path.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): defer empty sidecar last-known until sync succeeds

Keep prior non-empty last-known across an authoritative empty collect so the
empty-vault guard can still recognize a plugin-only reset, then commit the
empty cache after a successful upload.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): avoid restricted localStorage global in sidecar test

Bind the mock to a local binding so eslint no-restricted-globals stays clean.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): commit applied sidecar cache and reset orphan settings

Prefer merged payload sidecars when updating last-known after sync, and clear
syncable plugin_settings that lack sidecar rows on authoritative remote deletes.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): reseal marker-shaped plugin configs instead of skipping

Exact __netcatty_plugin_config_v1 collisions no longer bypass encryption; trusted
host envelopes are unwrapped then resealed, and false collisions are sealed whole.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): keep merged sidecars in last-known after apply collect fails

Return applyFromSync entries from IPC and use them when follow-up collect fails,
so preserved missing-plugin rows are not dropped from the offline upload cache.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): delete stale-scope settings at stored coordinates on reset

After resetSetting against the current declared scope, also remove the row at
the sidecar's stored scope so scope migrations cannot republish remote deletes.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): close sync-provider credential, stream, and sidecar gaps

Make SecretRef usable end-to-end via lease-bound network.request, keep
renderer/main transfers abortable and bounded, and stop sidecar
last-known/pending from corrupting backups and conflict apply.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): harden single-provider, secret schema, and conditional conflicts

Keep legacy restart from dual-connecting providers, extract writeOnly schema
secrets into OS storage, and surface conditional-write precondition failures
as conflict UI instead of a generic sync error.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): dedupe sync type imports for lint

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: address Codex review on PR #2713

* fix(plugins): wait for sidecar host before version backup latch

Defer the one-shot upgrade snapshot until the plugin sidecar host is ready (or a short grace), and catch getDataHash failures so pending/baseline paths do not reject unhandled.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(plugins): require sidecar grace before version backup

Always wait for contributions/grace tick before the upgrade snapshot, and only latch after a non-cancelled attempt so cleanup cannot suppress retries.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: netcatty-bot <308658023+netcatty-bot@users.noreply.github.com>
2026-08-05 18:43:10 +08:00

17 KiB

Terminal Provider API

PR 5 adds the host-owned terminal Provider registry on top of the isolated runtime and permission boundary. Provider declarations remain immutable manifest data. Listing Providers never starts a plugin; first invocation uses the existing idempotent onProvider:<id> activation seam and revalidates the active plugin version and runtime identity after the response.

Runtime registration

An activated plugin registers only contributions owned by its exact plugin ID:

context.subscriptions.add(context.providers.register(
  "com.example.shell.completion",
  "terminal.completion",
  async ({ payload, cancellationToken }) => {
    if (cancellationToken.isCancellationRequested) return { items: [] };
    return { items: [{ text: "git status", displayText: "git status", score: 100 }] };
  },
));

Registration is activation-owned and disposable. A stale disposable cannot remove a replacement registration. Invocation carries the declared Provider ID/kind, an operation, a host-generated request ID, a bounded JSON payload, the deadline, and a cooperative cancellation token. Results use the canonical ok/cancelled/failed Provider result union and are validated again by the main process before renderer use.

Each invocation reauthorizes the Provider kind's least-privilege permission set against the current runtime identity before sending a session snapshot or request payload. Required grants are reused; optional declarations prompt at first use and denial/cancellation returns no terminal data to the runtime.

Terminal snapshots and lifecycle

Providers receive immutable metadata snapshots containing only stable session identity and presentation context: session/host/workspace IDs, protocol, connection status, cwd, title, shell type, dimensions, and alternate-screen state. Active runtimes can subscribe with context.terminals.onDidChange(). Protocol values preserve the actual built-in transport (ssh, mosh, et, telnet, local, or serial) and accept bounded namespaced identifiers for future connection Providers instead of collapsing non-SSH transports to SSH. Immediately before an invocation, a lazily activated Provider receives a snapshot event for the current session so it does not depend on lifecycle events that occurred before activation. Lifecycle events cover creation, connection/reconnection, cwd/title/resize/ alternate-screen changes, command submission, host-detected command completion, disconnect, and disposal. Completion events contain no command text or raw output and are emitted from OSC 133 completion markers when available, with a conservative next-prompt fallback for shells without integration markers. Connection-scoped cwd, title, and alternate-screen metadata is cleared before disconnect and reconnect publication; viewport dimensions remain available. Ongoing lifecycle delivery begins only after a successful invocation with a non-once provider.terminal grant. Each event rechecks that grant without opening a new prompt and remains bound to the exact plugin version, runtime ID, runtime kind, and security principal that received the authorized invocation. One-use grants receive only the invocation snapshot and payload.

PR 5 intentionally omits command text, password/prompt content, raw terminal output, xterm objects, backend handles, and terminal-worker ports. The ordinary JSON-RPC Provider path is not suitable for hot interception. PR 6 owns the separate permission-gated MessagePort fast path for input/output interceptors, sensitive-input bypass, circuit breaking, and the 4 ms interceptor budget.

Privileged terminal data pipeline

PR 6 implements the two declared raw kinds without exposing xterm, Electron IPC, backend streams, or the general plugin control plane. Only an advanced utility runtime with provider.terminal and the matching terminal.intercept.input or terminal.intercept.output grant can be attached. Authorization is bound to the exact plugin version, runtime ID, runtime kind, security principal, terminal session, direction, and declared Provider. Because the transferred port is a long-lived capability, both permissions must resolve to a session, application, or persistent grant; a one-use grant is rejected before either port endpoint is published. Browser runtimes are rejected before a port is transferred. Publisher signature eligibility remains a distribution-policy decision owned by PR 9; the advanced runtime and explicit high-risk permission boundary is already enforced here.

An activated utility plugin uses the same registration owner and receives a specialized SDK invocation:

context.subscriptions.add(context.providers.register(
  "com.example.filter.input",
  "terminal.interceptor.input",
  async ({ data, session, sequence }) => {
    // The transferred UTF-8 Uint8Array is owned by this invocation.
    return data;
  },
));

For each terminal session, Netcatty permits at most one arbitrary interceptor per direction. A single candidate can be selected automatically; competing candidates require an explicit host-owned user choice and "No interceptor" is the default/cancel action. The choice is session-local and is discarded on session disposal, contribution withdrawal, runtime replacement, crash, or quarantine. The requesting renderer must own the terminal session before any authorization or activation work occurs.

The main process transfers the two ends of one MessageChannelMain directly to the terminal worker and selected plugin utility process. The utility-side attachment is established by a transfer-aware PluginRpcRouter request, so the existing router owns correlation, deadline, cancellation, validation, late-response retirement, close cleanup, and protocol-failure containment. Only the accepted long-lived byte path leaves the control plane. Data messages contain a monotonic sequence, direction, bounded credit information, and one transferable ArrayBuffer; the main process never copies terminal payloads. Ready, chunk, successful-result, and failed-result metadata use the canonical TerminalInterceptorFrame union. Both worker and utility peers validate it from the generated contract bundle, and the shared MessagePort envelope rejects missing, unexpected, detached, oversized, or byte-length-mismatched transfers. The worker serializes chunks, caps each transfer at 64 KiB, and limits queued output to a 256 KiB credit window. Output remains ordered and host output taps retain the original data. Renderer flow acknowledgements use the original ingress count even when a plugin expands, contracts, or completely suppresses visible output. Host-bypassed sensitive input and protocol replies still wait behind earlier ordinary input so bypass cannot reorder the terminal stream.

Input requests have a 4 ms worker-owned deadline. Output requests have a bounded 50 ms deadline and a 256 KiB queued-output window. A timeout, malformed response, invalid UTF-8 result, closed port, runtime exit, or credit-window overflow trips the circuit breaker immediately: the original chunk fails open, the interceptor is disabled for that session/direction, and Netcatty displays a host-owned warning. An interceptor cannot suppress that warning or re-enable itself without a fresh host authorization path.

These budgets are containment limits, not production performance acceptance evidence. PR 9 owns the reproducible benchmark harness, supported hardware and operating-system matrix, and release gate proving no more than 1% no-plugin throughput regression plus approximately 4 ms p95 / 8 ms p99 added input latency before the development gate can be removed.

Credential protection is outside plugin control. Input that the host marks as sensitive/no-echo bypasses the port before buffer creation, including every character entered while the password-prompt state is active and confirmed sudo/su credential autofill. Recorded automation credentials use a password dialog, remain redacted from script activity/logs, and carry the same sensitive marker through the script bridge. The terminal worker also recognizes authentication challenges from bounded original-output tails before output interception, so an output plugin cannot expose a password by hiding or rewriting its prompt. Generic PTY protocols do not expose an authoritative live echo-mode signal. Consequently, a custom or promptless program that disables echo may not be recognized by the host classifier. The native permission dialog states this limit before granting input interception, and public enablement remains blocked until PR 9 restricts the capability to explicitly approved signed advanced plugins. This is a deliberate limitation of the first terminal data path, not an absolute no-echo confidentiality guarantee. Sensitive input is also excluded from terminal broadcast. Terminal protocol replies, urgent interrupts, transfer input gates, transport encoding, Telnet IAC escaping, host logs, renderer flow accounting, and marker/safety parsing remain host-owned. Output interceptors may create or suppress visible byte sequences that affect output-derived lifecycle signals such as OSC 133. Netcatty owns the parser, marker objects, validation, and cleanup, but deliberately derives those signals from the transformed visible stream; credential-prompt classification remains based on bounded original host output before interception. With no active interceptor, the worker uses the existing synchronous output path and performs no interceptor Promise, transfer, or payload allocation.

Host adapters

Netcatty's built-in autocomplete engine and keyword highlighter use the same application Provider adapters as plugins:

  • completion requests run built-in and plugin Providers concurrently;
  • one active request exists per session and Provider kind; a newer request cancels and suppresses the older result;
  • Provider ordering is deterministic and can honor a host-owned preference list; completion items are score-ranked and text-deduplicated;
  • one Provider failure is contained and does not suppress other Providers;
  • plugin completion responses are capped and normalized before rendering;
  • completion insertion/display text rejects control and bidirectional override characters before it can reach terminal input or suggestion UI. The host always renders the exact insertion text for third-party completions, so a friendly label cannot conceal a different command on previewless terminals;
  • decoration Providers return declarative rules only. Rule IDs are namespaced, counts and strings are bounded, colors must be explicit hex values, and unsupported expressions are rejected before reaching the highlighter, and accepted plugin patterns are compiled and executed by the linear-time RE2JS engine with global, case-insensitive matching;
  • decoration results are capped again after Provider fan-out at 16 active rules and 32 total patterns. Plugin matching examines at most the first 4096 characters and retains at most 256 plugin matches for one logical line. A wrapped logical line is matched only once per refresh before ranges are projected onto its physical rows; plugin decoration is omitted for oversized wrapped blocks that cannot be assembled safely. Patterns that can match an empty string are rejected because they cannot produce a visible highlight. Normal boot and hibernate wake share the same CWD-triggered decoration refresh path;
  • link and hover Providers receive one bounded physical xterm line and return exact zero-based ranges. Links are restricted to credential-free HTTP(S) URLs, reuse the host link-modifier policy, and render hover text with host DOM nodes rather than plugin HTML. UTF-16 result boundaries are mapped back to xterm cells so wide and combining characters cannot shift activation or decoration ranges. Requests pause while the terminal is hidden or disconnected, and in-flight results are aborted and invalidated on either transition;
  • matcher Providers receive at most the latest 32 parsed logical normal-buffer lines in one batch. Wrapped physical rows are joined before invocation and exact logical ranges are split back across host-owned xterm decorations. Each result identifies a host-provided lineId; ranges are validated against that exact line, the combined request text is capped below the 128 KiB Provider envelope, and at most 64 logical matches remain visible. Alternate-screen output is excluded;
  • semantic Providers receive only a bounded command submitted from a positively confirmed shell prompt (or an explicitly identified network device prompt) and require terminal.input. Authentication challenges, REPL input, and other untrusted prompt-shaped input never reach ordinary Providers. Prompt Providers receive no command or raw output. Their bounded annotations are rendered at host-detected command completion. A prompt line is included only when the shared host detector confirms an empty shell prompt, so the last output line is never mislabeled as prompt context;
  • background Providers return at most four solid-color presentation layers. Per-layer opacity and the combined host overlay are capped at 0.35, plugin HTML/CSS/images are never accepted, and the request includes the current terminal background color for contrast-aware results. An omitted layer opacity uses the host-owned safe default of 0.15. Providers may request a 250-60000 ms host refresh cadence; refresh pauses while the terminal is hidden or disconnected and is disabled when reduced motion is requested;
  • theme Providers receive the complete current host palette and may return a bounded partial palette of explicit colors. Providers are merged in the same deterministic preference order as enumeration, with the first value for each color winning; host colors remain authoritative for omitted values;
  • every ordinary visual adapter applies a renderer-owned end-to-end wait bound around lazy activation, authorization, and runtime work. Stale generations, disconnects, contribution changes, runtime replacement, and terminal disposal cannot reapply old visual results. Provider availability is cached from immutable enumeration without activation, stale enumeration generations cannot overwrite newer contribution state, and enumeration errors fail closed. Autocomplete, decoration, link, hover, matcher, and background paths therefore perform no plugin RPC work when those contribution kinds are absent or the development-gated host is disabled.

The operation payload/result shapes for the ordinary adapters are intentionally declarative. Every payload also contains the immutable session snapshot for the exact invocation:

  • terminal.completion/provideCompletions: bounded input, cursor, host OS, CWD source, and result limit -> bounded completion items;
  • terminal.decoration/provideDecorations: a host refresh reason -> bounded declarative highlight rules;
  • terminal.link/provideLinks: { line, bufferLineNumber } -> { links: [{ start, length, uri, label? }] };
  • terminal.hover/provideHovers: { line, bufferLineNumber } -> { hovers: [{ start, length, contents }] };
  • terminal.matcher/provideMatches: { lines: [{ lineId, line, bufferLineNumber }] } -> { matches: [{ lineId, start, length, label, severity?, color? }] };
  • terminal.semantic/provideSemantics: { command } -> classification, destructive/idempotent flags, and bounded annotations;
  • terminal.prompt/provideAnnotations: a host reason -> bounded annotations;
  • terminal.background/provideBackgrounds: a host reason and optional current terminal background -> bounded solid-color layers plus optional refreshAfterMs.
  • terminal.theme/provideTheme: a host reason and complete current host palette -> a validated partial terminal palette.

The SDK exports and infers the matching payload, item, operation, and result interfaces for all nine ordinary Provider kinds, including the immutable host session snapshot attached to every invocation. The generic registration overload remains available for later Provider kinds, so plugins do not need application-internal renderer types and PRs 6-9 can add their own typed maps.

The control-plane JSON budget remains 1 MiB, while each terminal Provider payload and result is additionally limited to 128 KiB. Default terminal Provider requests have a 1.5 second deadline; autocomplete uses a shorter 750 ms runtime deadline plus an 800 ms renderer-owned end-to-end wait bound that also covers lazy activation and first-use authorization. Built-in suggestions therefore remain available when a plugin prompt is unanswered. Renderer request cancellation is owned by the requesting WebContents and all outstanding work is aborted when that sender is destroyed. A single renderer may retain at most 64 active terminal requests, and one fan-out invokes at most the first 32 deterministically ranked Providers.

Downstream compatibility

The registry uses the existing generic Provider request/result envelopes, runtime identity, cancellation, progress, permission names, and stream protocol. PR 6 added its direct interceptor transport without changing the ordinary registry. PR 7 reused that registration and runtime lifecycle for connection, authentication, and importer Providers, with operation-specific result validators and bounded stream consumers. PR 8 sync Providers (implemented) and PR 9 rollout can reuse the same boundaries.