sliccy 5.37.0 → 5.38.0

package/dist/node-server/_shared/tray-sync-protocol.d.ts

@@ -0,0 +1,436 @@
+/**
+ * Typed sync protocol for tray WebRTC data channels — canonical wire format.
+ *
+ * Leader → Follower: chat snapshots (single + chunked), streamed agent events,
+ *   user-message echoes, scoop list, sprinkle list / content / updates,
+ *   federated CDP (request + response + event), federated tab.open and its
+ *   reply pair, federated FS (request + response), liveness (ping/pong/status/error).
+ *
+ * Follower → Leader: user input, abort, snapshot/scoop selection requests,
+ *   sprinkle refresh + content fetch + lick, target advertisement, federated
+ *   CDP (request + response + event), federated tab.open and its reply pair,
+ *   federated FS (request + response), ping/pong.
+ *
+ * The iOS follower (`packages/ios-app/SliccFollower/Models/SyncProtocol.swift`)
+ * mirrors a **subset** of this file: federated `fs.*` in both directions is
+ * TS-only; iOS responds to leader-initiated `cdp.request` / `tab.open` (and
+ * sends back `cdp.response` / `cdp.event` / `tab.opened`) but does NOT
+ * originate either, so the follower-initiated CDP/tab.open paths are also
+ * TS-only. The per-variant iOS decision is MECHANICALLY enforced by the
+ * golden-fixture corpus
+ * (`packages/webapp/src/scoops/tray-sync-protocol-corpus.ts` →
+ * `packages/ios-app/.../Fixtures/tray-sync-corpus.json`, decoded by both the
+ * vitest and XCTest suites) — adding a variant here fails typecheck there
+ * until it gets a fixture + explicit iOS expectation. See
+ * `packages/ios-app/CLAUDE.md` "Protocol Mirror Invariant".
+ *
+ * This module holds the message unions and their payload-adjacent types
+ * (types + pure guards only — platform-agnostic by construction). The
+ * `TraySyncChannel` wrapper, chunking helpers, and typed factories live in
+ * `@slicc/webapp` `scoops/tray-sync-protocol.ts` (they depend on
+ * `TrayDataChannelLike` and the webapp logger), which re-exports everything
+ * here for webapp-internal importers.
+ */
+import type { AgentEvent, ChatMessage, LickEvent, MessageAttachment } from './agent-wire-types.js';
+/**
+ * Runtime tag a cherry follower connects with (`StartPageFollowerTrayOptions.runtime`).
+ * It is the advertisement-independent signal the leader uses to keep a cooperative
+ * cherry host page out of flows it cannot satisfy (teleport selection) — see
+ * `tray-leader-sync.ts:getBestFollowerForTeleport`. Kept here, next to the wire
+ * format, because both the follower boot (`ui/`) and the leader (`scoops/`) must
+ * agree on the exact string without one layer importing the other.
+ */
+export declare const CHERRY_RUNTIME_TAG = "slicc-cherry";
+/**
+ * Tray sync protocol version, exchanged via the additive `hello` message both
+ * sides send on channel open. A peer that never sends `hello` is a legacy
+ * build (pre-versioning); a peer with a HIGHER version than ours means this
+ * build is outdated — both cases log loudly instead of surfacing as silently
+ * missing features. Bump when the wire format changes incompatibly.
+ */
+export declare const TRAY_SYNC_PROTOCOL_VERSION = 1;
+/**
+ * Additive version handshake, sent by BOTH sides as their first message on
+ * channel open. Legacy peers drop it harmlessly (TS: unknown-message warn;
+ * iOS: `.unknown`), so it is backward and forward compatible.
+ */
+export interface TraySyncHelloMessage {
+    type: 'hello';
+    protocolVersion: number;
+    /** Optional runtime tag of the sender (e.g. 'slicc-standalone'). */
+    runtime?: string;
+}
+export type LeaderToFollowerMessage = {
+    type: 'snapshot';
+    messages: ChatMessage[];
+    scoopJid: string;
+} | {
+    type: 'snapshot_chunk';
+    chunkData: string;
+    chunkIndex: number;
+    totalChunks: number;
+    scoopJid: string;
+} | {
+    type: 'agent_event';
+    event: AgentEvent;
+    scoopJid: string;
+} | {
+    type: 'user_message_echo';
+    text: string;
+    messageId: string;
+    scoopJid: string;
+    attachments?: MessageAttachment[];
+} | {
+    type: 'status';
+    scoopStatus: string;
+} | {
+    type: 'error';
+    error: string;
+} | {
+    type: 'scoops.list';
+    scoops: ScoopSummary[];
+    activeScoopJid: string;
+} | {
+    type: 'sprinkles.list';
+    sprinkles: SprinkleSummary[];
+} | {
+    type: 'sprinkle.content';
+    requestId: string;
+    sprinkleName: string;
+    content: string;
+    chunkIndex?: number;
+    totalChunks?: number;
+    error?: string;
+} | {
+    type: 'sprinkle.update';
+    sprinkleName: string;
+    data: unknown;
+} | {
+    type: 'sprinkle.reloaded';
+    sprinkleName: string;
+} | {
+    type: 'targets.registry';
+    targets: TrayTargetEntry[];
+} | {
+    type: 'cdp.request';
+    requestId: string;
+    localTargetId: string;
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+} | {
+    type: 'cdp.response';
+    requestId: string;
+    result?: Record<string, unknown>;
+    error?: string;
+    chunkData?: string;
+    chunkIndex?: number;
+    totalChunks?: number;
+} | {
+    type: 'cdp.event';
+    method: string;
+    params: Record<string, unknown>;
+    sessionId?: string;
+} | {
+    type: 'tab.open';
+    requestId: string;
+    url: string;
+} | {
+    type: 'tab.opened';
+    requestId: string;
+    targetId: string;
+} | {
+    type: 'tab.open.error';
+    requestId: string;
+    error: string;
+} | {
+    type: 'preview.open';
+    requestId: string;
+    url: string;
+} | {
+    type: 'fs.request';
+    requestId: string;
+    request: TrayFsRequest;
+} | {
+    type: 'fs.response';
+    requestId: string;
+    response: TrayFsResponse;
+} | CherrySliccEventMessage | {
+    type: 'theme.apply';
+    themeJson: string | null;
+} | TraySyncHelloMessage | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+export type FollowerToLeaderMessage = {
+    type: 'user_message';
+    text: string;
+    messageId: string;
+    attachments?: MessageAttachment[];
+} | {
+    type: 'abort';
+} | {
+    type: 'request_snapshot';
+    scoopJid?: string;
+} | {
+    type: 'scoops.select';
+    scoopJid: string;
+} | {
+    type: 'sprinkles.refresh';
+} | {
+    type: 'sprinkle.fetch';
+    requestId: string;
+    sprinkleName: string;
+} | {
+    type: 'sprinkle.lick';
+    sprinkleName: string;
+    body: unknown;
+    targetScoop?: string;
+} | {
+    type: 'lick';
+    event: Omit<LickEvent, 'originFollowerId' | 'originLabel'>;
+} | {
+    type: 'targets.advertise';
+    targets: RemoteTargetInfo[];
+    runtimeId: string;
+} | {
+    type: 'cdp.request';
+    requestId: string;
+    targetRuntimeId: string;
+    localTargetId: string;
+    method: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+} | {
+    type: 'cdp.response';
+    requestId: string;
+    result?: Record<string, unknown>;
+    error?: string;
+    chunkData?: string;
+    chunkIndex?: number;
+    totalChunks?: number;
+} | {
+    type: 'cdp.event';
+    method: string;
+    params: Record<string, unknown>;
+    sessionId?: string;
+} | {
+    type: 'tab.open';
+    requestId: string;
+    targetRuntimeId: string;
+    url: string;
+} | {
+    type: 'tab.opened';
+    requestId: string;
+    targetId: string;
+} | {
+    type: 'tab.open.error';
+    requestId: string;
+    error: string;
+} | {
+    type: 'fs.request';
+    requestId: string;
+    targetRuntimeId: string;
+    request: TrayFsRequest;
+} | {
+    type: 'fs.response';
+    requestId: string;
+    response: TrayFsResponse;
+} | CherryHostEventMessage | TraySyncHelloMessage | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+export interface RemoteTargetInfo {
+    targetId: string;
+    title: string;
+    url: string;
+    /** Distinguishes a real browser page from a cooperative cherry host page. */
+    kind?: 'browser' | 'cherry' | 'preview';
+    /**
+     * Only present for kind === 'cherry'. What the host page lends to the leader,
+     * expressed in the vocabulary this tray/teleport layer cares about: `network`
+     * gates whether the target may serve `Network.*` CDP for teleport-pool
+     * selection. NOTE: intentionally a DIFFERENT shape from the SDK handshake
+     * `CherryHandshakeHello.capabilities` (`{ navigate; screenshot; openUrl }` in
+     * cdp/cherry-host-protocol.ts) — `openUrl` is a sandbox-escape concern at the
+     * host SDK boundary, whereas `network` is a teleport-routing concern here.
+     * They are mapped, not equal.
+     */
+    capabilities?: {
+        navigate: boolean;
+        network: boolean;
+        screenshot: boolean;
+    };
+}
+/** Host page → cone: a named event emitted by the cherry host page. */
+export interface CherryHostEventMessage {
+    type: 'cherry.host_event';
+    targetId: string;
+    name: string;
+    detail?: unknown;
+}
+/** Cone → host page: a named event sent to the cherry host page. */
+export interface CherrySliccEventMessage {
+    type: 'cherry.slicc_event';
+    targetId: string;
+    name: string;
+    detail?: unknown;
+}
+export declare function isCherryHostEventMessage(m: unknown): m is CherryHostEventMessage;
+export declare function isCherrySliccEventMessage(m: unknown): m is CherrySliccEventMessage;
+/** Lightweight scoop description sent to followers for their scoop picker / swipe view. */
+export interface ScoopSummary {
+    jid: string;
+    name: string;
+    folder: string;
+    isCone: boolean;
+    assistantLabel: string;
+    trigger?: string;
+}
+/** Lightweight sprinkle description sent to followers for the sprinkle sidebar. */
+export interface SprinkleSummary {
+    /** Sprinkle name (basename without .shtml). */
+    name: string;
+    /** Display title. */
+    title: string;
+    /** VFS path (used for chunked content fetch). */
+    path: string;
+    /** Whether this sprinkle is currently open in the leader's UI. */
+    open: boolean;
+    /** Whether this sprinkle should auto-open. */
+    autoOpen: boolean;
+}
+export interface TrayTargetEntry {
+    targetId: string;
+    localTargetId: string;
+    runtimeId: string;
+    title: string;
+    url: string;
+    isLocal: boolean;
+    /** Distinguishes a real browser page from a cooperative cherry host page. */
+    kind?: 'browser' | 'cherry' | 'preview';
+    /**
+     * Only present for kind === 'cherry'. What the host page lends to the leader,
+     * expressed in the vocabulary this tray/teleport layer cares about: `network`
+     * gates whether the target may serve `Network.*` CDP for teleport-pool
+     * selection. NOTE: intentionally a DIFFERENT shape from the SDK handshake
+     * `CherryHandshakeHello.capabilities` (`{ navigate; screenshot; openUrl }` in
+     * cdp/cherry-host-protocol.ts) — `openUrl` is a sandbox-escape concern at the
+     * host SDK boundary, whereas `network` is a teleport-routing concern here.
+     * They are mapped, not equal.
+     */
+    capabilities?: {
+        navigate: boolean;
+        network: boolean;
+        screenshot: boolean;
+    };
+}
+/** Chrome CDP Network.Cookie shape used for teleporting cookies between runtimes. */
+export interface CookieTeleportCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    size: number;
+    httpOnly: boolean;
+    secure: boolean;
+    session: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    priority?: 'Low' | 'Medium' | 'High';
+    sameParty?: boolean;
+    sourceScheme?: 'Unset' | 'NonSecure' | 'Secure';
+    sourcePort?: number;
+    partitionKey?: string;
+}
+/** A single FS operation request sent over the data channel. */
+export type TrayFsRequest = {
+    op: 'readFile';
+    path: string;
+    encoding?: 'utf-8' | 'binary';
+} | {
+    op: 'writeFile';
+    path: string;
+    content: string;
+    encoding: 'utf-8' | 'base64';
+} | {
+    op: 'stat';
+    path: string;
+} | {
+    op: 'readDir';
+    path: string;
+} | {
+    op: 'mkdir';
+    path: string;
+    recursive?: boolean;
+} | {
+    op: 'rm';
+    path: string;
+    recursive?: boolean;
+} | {
+    op: 'exists';
+    path: string;
+} | {
+    op: 'walk';
+    path: string;
+};
+/** A single FS operation response. Chunked responses use chunkIndex/totalChunks for large file content. */
+export type TrayFsResponse = {
+    ok: true;
+    data: TrayFsResponseData;
+    chunkIndex?: number;
+    totalChunks?: number;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/** Possible data payloads for successful FS responses. */
+export type TrayFsResponseData = {
+    type: 'file';
+    content: string;
+    encoding: 'utf-8' | 'base64';
+} | {
+    type: 'stat';
+    stat: {
+        type: 'file' | 'directory' | 'symlink';
+        size: number;
+        mtime: number;
+        ctime: number;
+    };
+} | {
+    type: 'dirEntries';
+    entries: Array<{
+        name: string;
+        type: 'file' | 'directory' | 'symlink';
+    }>;
+} | {
+    type: 'exists';
+    exists: boolean;
+} | {
+    type: 'paths';
+    paths: string[];
+} | {
+    type: 'void';
+};
+export type TraySyncMessage = LeaderToFollowerMessage | FollowerToLeaderMessage;
+/**
+ * Compile-time exhaustiveness guard for protocol dispatchers.
+ *
+ * Call this from the `default:` branch of a `switch (message.type)` over a
+ * protocol union. Because the parameter is `never`, adding a new message
+ * variant to the union fails compile in every dispatcher until that
+ * dispatcher makes an explicit decision — a documented no-op `case` is
+ * allowed, silence is not.
+ *
+ * Unlike a classic `assertNever` this must NOT throw: at runtime a
+ * version-skewed peer (shipped iOS binary, older hosted UI, cherry embed)
+ * can legitimately deliver a message type this build doesn't know. It
+ * returns the loosely-typed message so the caller can log it loudly.
+ */
+export declare function unhandledProtocolMessage(message: never): {
+    type?: string;
+};
+//# sourceMappingURL=tray-sync-protocol.d.ts.map

package/dist/node-server/_shared/tray-sync-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tray-sync-protocol.d.ts","sourceRoot":"","sources":["../src/tray-sync-protocol.ts"],"names":[],"mappings":"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"}

package/dist/node-server/_shared/tray-sync-protocol.js

@@ -0,0 +1,74 @@
+/**
+ * Typed sync protocol for tray WebRTC data channels — canonical wire format.
+ *
+ * Leader → Follower: chat snapshots (single + chunked), streamed agent events,
+ *   user-message echoes, scoop list, sprinkle list / content / updates,
+ *   federated CDP (request + response + event), federated tab.open and its
+ *   reply pair, federated FS (request + response), liveness (ping/pong/status/error).
+ *
+ * Follower → Leader: user input, abort, snapshot/scoop selection requests,
+ *   sprinkle refresh + content fetch + lick, target advertisement, federated
+ *   CDP (request + response + event), federated tab.open and its reply pair,
+ *   federated FS (request + response), ping/pong.
+ *
+ * The iOS follower (`packages/ios-app/SliccFollower/Models/SyncProtocol.swift`)
+ * mirrors a **subset** of this file: federated `fs.*` in both directions is
+ * TS-only; iOS responds to leader-initiated `cdp.request` / `tab.open` (and
+ * sends back `cdp.response` / `cdp.event` / `tab.opened`) but does NOT
+ * originate either, so the follower-initiated CDP/tab.open paths are also
+ * TS-only. The per-variant iOS decision is MECHANICALLY enforced by the
+ * golden-fixture corpus
+ * (`packages/webapp/src/scoops/tray-sync-protocol-corpus.ts` →
+ * `packages/ios-app/.../Fixtures/tray-sync-corpus.json`, decoded by both the
+ * vitest and XCTest suites) — adding a variant here fails typecheck there
+ * until it gets a fixture + explicit iOS expectation. See
+ * `packages/ios-app/CLAUDE.md` "Protocol Mirror Invariant".
+ *
+ * This module holds the message unions and their payload-adjacent types
+ * (types + pure guards only — platform-agnostic by construction). The
+ * `TraySyncChannel` wrapper, chunking helpers, and typed factories live in
+ * `@slicc/webapp` `scoops/tray-sync-protocol.ts` (they depend on
+ * `TrayDataChannelLike` and the webapp logger), which re-exports everything
+ * here for webapp-internal importers.
+ */
+/**
+ * Runtime tag a cherry follower connects with (`StartPageFollowerTrayOptions.runtime`).
+ * It is the advertisement-independent signal the leader uses to keep a cooperative
+ * cherry host page out of flows it cannot satisfy (teleport selection) — see
+ * `tray-leader-sync.ts:getBestFollowerForTeleport`. Kept here, next to the wire
+ * format, because both the follower boot (`ui/`) and the leader (`scoops/`) must
+ * agree on the exact string without one layer importing the other.
+ */
+export const CHERRY_RUNTIME_TAG = 'slicc-cherry';
+/**
+ * Tray sync protocol version, exchanged via the additive `hello` message both
+ * sides send on channel open. A peer that never sends `hello` is a legacy
+ * build (pre-versioning); a peer with a HIGHER version than ours means this
+ * build is outdated — both cases log loudly instead of surfacing as silently
+ * missing features. Bump when the wire format changes incompatibly.
+ */
+export const TRAY_SYNC_PROTOCOL_VERSION = 1;
+export function isCherryHostEventMessage(m) {
+    return (typeof m === 'object' && m !== null && m.type === 'cherry.host_event');
+}
+export function isCherrySliccEventMessage(m) {
+    return (typeof m === 'object' && m !== null && m.type === 'cherry.slicc_event');
+}
+/**
+ * Compile-time exhaustiveness guard for protocol dispatchers.
+ *
+ * Call this from the `default:` branch of a `switch (message.type)` over a
+ * protocol union. Because the parameter is `never`, adding a new message
+ * variant to the union fails compile in every dispatcher until that
+ * dispatcher makes an explicit decision — a documented no-op `case` is
+ * allowed, silence is not.
+ *
+ * Unlike a classic `assertNever` this must NOT throw: at runtime a
+ * version-skewed peer (shipped iOS binary, older hosted UI, cherry embed)
+ * can legitimately deliver a message type this build doesn't know. It
+ * returns the loosely-typed message so the caller can log it loudly.
+ */
+export function unhandledProtocolMessage(message) {
+    return message;
+}
+//# sourceMappingURL=tray-sync-protocol.js.map

package/dist/node-server/_shared/tray-sync-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tray-sync-protocol.js","sourceRoot":"","sources":["../src/tray-sync-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAwK5C,MAAM,UAAU,wBAAwB,CAAC,CAAU;IACjD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAuB,CAAC,IAAI,KAAK,mBAAmB,CAC7F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,CAAU;IAClD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAuB,CAAC,IAAI,KAAK,oBAAoB,CAC9F,CAAC;AACJ,CAAC;AAqHD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAc;IACrD,OAAO,OAA4B,CAAC;AACtC,CAAC"}