mirror of
https://github.com/getpaseo/paseo.git
synced 2026-11-02 22:52:58 +00:00
Mohamed Boudra
d4ac64f335
* feat(plugins): stream events and bytes between plugins and the app
Plugins can declare a subscription with defineSubscription, handle it with
server.handle(contract, (input, { push, signal })), and listen from a surface
with useSubscription or client.subscribe. A top-level Uint8Array in an event,
an RPC output, or an RPC input crosses the wire as a binary frame (opcodes
0x20-0x2f) without JSON or base64; a nested one fails validation on the sender.
Each subscriber runs its own handler, owned by the session that subscribed,
so release, disconnect, plugin stop and reload need no plugin code. The
runtime buffers pushes until the subscribe response has gone out, so a client
never sees an event for a subscription it does not know yet.
Gated on server_info.features.pluginSubscriptions; binary outputs reach only
clients that advertise plugin_binary_payloads.
* fix(plugins): close subscription gaps found in review
- Losing daemon.manage now releases the session's plugin subscriptions;
binary events bypass the outbound permission check, so streams would
otherwise outlive the revocation.
- A subscribe that times out sends unsubscribe, since the plugin may
still start the handler after the daemon gave up.
- The byte limit leaves room for the largest frame header and routing,
and lives in assertPluginWireValue so events, outputs and inputs share it.
- A release right after the host accepted keeps `ready` resolved, so a
handler that returns at once reports closed rather than an error.
- Session trace logging tolerates loggers without isLevelEnabled.
* fix(plugins): withhold binary plugin results after plugin access is revoked
A binary RPC output or event skipped the outbound permission check its
JSON form passes, so an RPC in flight when daemon.manage was revoked still
delivered its bytes. Each frame now checks the permission of the JSON
message it stands in for.
* test(plugins): cover subscriptions in a real browser instead of JSDOM
The app subscription tests mounted hooks in JSDOM, which docs/testing.md
rules out. The adapter and contract behavior is now a plain unit test,
and a Playwright spec drives the diff-watch and media-stream examples:
JSON events following file changes, streamed bytes, and an upload.
* test(plugins): add the plain subscription unit test and the browser spec
* fix(plugins): apply subscription schema transforms once
Both ends parsed each subscription value, and the sender sent its parse
output, so the receiver parsed a schema's output as fresh input. An event
schema like z.string().transform((s) => s.length) closed the stream as
invalid. The sender now validates and sends the value as given; the
receiver's parse produces what the handler or callback sees.
* fix(plugins): parse a subscription's input once in the plugin process
server.handle wrapped subscription handlers in a second input parse, so a
transforming input schema rejected its own parsed output before the
handler ran.
58 lines
3.7 KiB
TypeScript
58 lines
3.7 KiB
TypeScript
export const CLIENT_CAPS = {
|
|
terminalChunkedReplay: "terminal_chunked_replay",
|
|
binaryChunkingV1: "binary_chunking_v1",
|
|
helloRejection: "hello_rejection",
|
|
// COMPAT(ownedSubscriptions): added in v0.8.0, remove legacy ownership after 2027-03-09.
|
|
ownedSubscriptions: "owned_subscriptions",
|
|
// Clients outside the Paseo app version series can explicitly accept provider IDs.
|
|
// COMPAT(explicitEventSubscriptions): added in v0.8.0, remove legacy broadcasts after 2027-03-08.
|
|
explicitEventSubscriptions: "explicit_event_subscriptions",
|
|
allProviders: "all_providers",
|
|
// COMPAT(selectiveAgentTimeline): added in v0.1.106. Capable clients receive
|
|
// agent streams only for their explicit viewed set. Remove after 2027-01-12
|
|
// once the supported client floor is >= v0.1.106.
|
|
selectiveAgentTimeline: "selective_agent_timeline",
|
|
reasoningMergeEnum: "reasoning_merge_enum",
|
|
// COMPAT(customModeIcons): added in v0.1.84. Old clients pin AgentModeIcon to
|
|
// a closed enum and crash rendering unknown values; daemon downgrades icons
|
|
// outside the legacy set to "ShieldCheck" when this cap is absent. Drop the
|
|
// gate when floor >= v0.1.84.
|
|
customModeIcons: "custom_mode_icons",
|
|
// COMPAT(terminalReflowableSnapshot): added in v0.1.88. The daemon attaches
|
|
// per-row soft-wrap flags (gridWrapped/scrollbackWrapped) to terminal snapshots
|
|
// only when the client advertises this, so restored content can reflow on resize.
|
|
// Old clients use a strict TerminalState schema and would reject the extra fields.
|
|
// Drop the gate (always send the flags) when floor >= v0.1.88.
|
|
terminalReflowableSnapshot: "terminal_reflowable_snapshot",
|
|
// COMPAT(providerSubagents): added in v0.1.107. The daemon emits provider-owned
|
|
// child descriptors and timelines only to clients that understand the new messages.
|
|
providerSubagents: "provider_subagents",
|
|
// COMPAT(projectedSubagentTimeline): added after v0.8.0, remove gates after 2027-03-14; retain wire capability.
|
|
projectedSubagentTimeline: "projected_subagent_timeline",
|
|
// COMPAT(projectUpdates): added in v0.1.109, remove gate after 2027-01-15.
|
|
projectUpdates: "project_updates",
|
|
// COMPAT(compactProviderSnapshots): added in v0.2.X. Capable clients receive
|
|
// provider catalogs with shared thinking sets and may revalidate by content hash.
|
|
// Remove the legacy snapshot encoding after 2027-02-04.
|
|
compactProviderSnapshots: "compact_provider_snapshots",
|
|
providerSnapshotReferences: "provider_snapshot_references",
|
|
// COMPAT(timelineReplacementInvalidation): added in v0.5.0, remove legacy
|
|
// reconstructed timeline replay after 2027-02-21 once the client floor supports invalidation.
|
|
timelineReplacementInvalidation: "timeline_replacement_invalidation",
|
|
// COMPAT(timelineNotifications): added in v0.7.2. The daemon omits notification
|
|
// timeline items for older clients whose strict timeline union rejects them.
|
|
// Remove after 2027-03-03 once the supported client floor is >= v0.7.2.
|
|
timelineNotifications: "timeline_notifications",
|
|
// COMPAT(pluginTimelineItems): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
|
|
pluginTimelineItems: "plugin_timeline_items",
|
|
workspaceSetupObservation: "workspace_setup_observation",
|
|
// COMPAT(pluginBinaryPayloads): added in v0.15.0, remove after 2027-05-02 once client floor >= v0.15.0.
|
|
// The daemon sends plugin RPC outputs as binary opcode 0x21 only to clients that decode it.
|
|
pluginBinaryPayloads: "plugin_binary_payloads",
|
|
// COMPAT(workspaceSetupBlocked): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
|
|
workspaceSetupBlocked: "workspace_setup_blocked",
|
|
browserHost: "browser_host",
|
|
} as const;
|
|
|
|
export type ClientCapability = (typeof CLIENT_CAPS)[keyof typeof CLIENT_CAPS];
|