WebSocket subscriptions need cursor, from=now, and path-scoped catch-up

[kjgbot]

Problem

Pear issue AgentWorkforce/pear#82 exposed an upstream Relayfile event-subscription contract gap. The detailed finding is in AgentWorkforce/pear#82 (comment).

The current /fs/ws subscription flow replays recent workspace events as fresh events on subscribe/reconnect because the server unconditionally runs GetRecentEvents(workspaceID, 100) catch-up with no client cursor, no from=now / no-backfill mode, and no server-side path scope.

Consumers such as Pear need to subscribe to live integration events without receiving historical provider records as new notifications, and they need reconnect catch-up to honor the same semantics.

Required contract

• New WebSocket subscriptions default to from=now, meaning no historical catch-up unless explicitly requested.
• The SDK/server accept either from=now or an exclusive cursor for resume/catch-up.
• Reconnect catch-up honors the selected no-backfill/cursor behavior and must not replay recent workspace history by default.
• Subscriptions can pass exact path filters so the server only sends matching file events instead of forcing clients to receive workspace-wide events and filter locally.
• Backward-compatible API support is needed so older clients can keep their existing behavior while updated clients can opt into the fixed contract.

Pear impact

Pear currently pins @relayfile/sdk@0.7.23. Once this is fixed and released, Pear should bump the SDK to the first version containing this contract and use the WebSocket from=now + path filter options for Track C in AgentWorkforce/pear#82.

[kjgbot]

Pear Track C disposition from AgentWorkforce/pear#103:

Pear is temporarily subscribing only to exact selected mount paths. For Slack, that means a selected alias path like /slack/channels/<id>__<slug> is not expanded to the raw /slack/channels/<id> fallback in the client stopgap, because the live repro showed Relayfile emitting the same record under both raw and alias paths and Pear double-injecting it.

Accepted temporary gap until this upstream contract lands: if Relayfile/adapter-slack materializes only the raw <channelId> directory for a selected alias path, Pear can under-deliver that event. Fast-follow option after server-side path filters/from=now are available: support exact alias delivery upstream, or let Pear re-add the raw fallback with dedupe normalization such as <id>__<slug> -> <id> in injectionDeduplicationKey so raw+alias events map to one logical injection.

[kjgbot]

Fix PR opened: https://github.com/AgentWorkforce/relayfile/pull/239\n\nScope: /fs/ws now supports live-only from=now, exclusive cursor catch-up, and repeated path filters applied server-side to both catch-up and live fanout. TypeScript SDK transports default to from=now and expose cursor/path options. PR body includes the Pear SDK bump note for consumers pinned to @relayfile/sdk@0.7.23.

[kjgbot]

Fixed by #239, merged at main commit 3d9f08d.\n\nDelivered: /fs/ws supports from=now, exclusive cursor catch-up, and repeated path filters; server applies filters before catch-up/live frame writes; TypeScript SDK WebSocket transports default to from=now; WS frames include eventId/origin/provider/correlationId. Legacy no-query WebSocket clients keep the previous recent-events catch-up behavior.