@nexrall/code-core 1.4.76 → 1.4.78

package/dist/share/sessionChannel.d.ts

@@ -0,0 +1,136 @@
+import type { ShareIoFactory, ShareStatus } from './sessionShare';
+/** One pushed message, as it came off the wire (already shape-checked). */
+export interface ChannelMessage {
+    nonce: string;
+    source: string;
+    text: string;
+    ts: number;
+}
+/** `ask` holds pushes for a human verdict; `auto` delivers them on arrival. */
+export type ChannelPolicy = 'ask' | 'auto';
+/** What the module reports for the terminal to render — data, not prose. */
+export type ChannelNotice = {
+    kind: 'queued';
+    msg: ChannelMessage;
+    position: number;
+} | {
+    kind: 'delivered';
+    msg: ChannelMessage;
+    auto: boolean;
+    folded: boolean;
+} | {
+    kind: 'discarded';
+    msg: ChannelMessage;
+} | {
+    kind: 'dropped';
+    msg: ChannelMessage;
+    reason: 'queue_full';
+};
+export interface SessionChannelDeps {
+    /** Origin of the platform API — the Socket.IO server shares the host. */
+    url: string;
+    sessionId: string;
+    /** Called before EVERY (re)connect attempt, so a rotated token is picked up. */
+    tokenProvider: () => string | null;
+    /** Called once after an auth-shaped connect error, like the share half. */
+    refreshToken?: () => Promise<boolean>;
+    ioFactory?: ShareIoFactory;
+    onStatus?: (s: ShareStatus) => void;
+    onNotice?: (n: ChannelNotice) => void;
+    /**
+     * Deliver an accepted (or auto) message: `formatted` is what the model sees.
+     * Returns `queued` when the message was folded into a running turn instead
+     * of starting one (the REPL's busy path) — reported to watchers verbatim.
+     */
+    onDeliver?: (formatted: string, msg: ChannelMessage) => 'accepted' | 'queued' | void;
+    /** Test seam — the only reason a token is not always crypto-random. */
+    mintToken?: () => string;
+}
+/** Token shape the CLI mints and the relay/route only ever hash. */
+export declare const CHANNEL_TOKEN_PREFIX = "nxch_";
+/** More undecided pushes than this and new ones are refused, not queued — an
+ *  external source must not be able to bury the one message a human needs. */
+export declare const CHANNEL_QUEUE_CAP = 10;
+/** Matches the relay's and the route's own cap (defense in depth). */
+export declare const CHANNEL_TEXT_MAX_CHARS = 8192;
+/** S13c: what a source may read back — one turn's closing text, same bound. */
+export declare const CHANNEL_REPLY_MAX_CHARS = 8192;
+export declare function hashChannelToken(token: string): string;
+/**
+ * The push endpoint for a session. Built here so the CLI prints exactly the
+ * URL the route serves — one string, one place.
+ */
+export declare function channelPushUrl(id: string, url: string): string;
+/**
+ * Escape `<` so a hostile push cannot close the wrapper tag early; `&` and
+ * `>` stay readable because CI URLs are the common case and the model reads
+ * this text, not an XML parser.
+ */
+export declare function escapeChannelText(text: string): string;
+/**
+ * What the conversation receives. Same `<channel source=…>` shape Claude Code
+ * documents for its own channels, so prompts and habits built for one read
+ * the same here — and it can never parse as a slash command.
+ */
+export declare function formatChannelEvent(msg: ChannelMessage): string;
+export declare class SessionChannel {
+    private readonly deps;
+    private socket;
+    private id;
+    private status;
+    private stopped;
+    private refreshing;
+    private policy;
+    private queue;
+    private seenNonces;
+    /** S13c: nonces delivered but not yet answered by a finished turn. */
+    private awaitingReply;
+    /** Minted once per open; rotated by a re-open after /channel close. */
+    private token;
+    private tokenHash;
+    constructor(deps: SessionChannelDeps);
+    get sessionId(): string;
+    get state(): ShareStatus;
+    get activePolicy(): ChannelPolicy;
+    /** The push URL a human pastes into CI; the token is NOT part of it. */
+    get pushUrl(): string;
+    /** Shown once by `/channel open` — memory only, never persisted anywhere. */
+    get rawToken(): string | null;
+    /** Pending pushes, oldest first. A copy: callers cannot mutate the queue. */
+    pending(): ChannelMessage[];
+    start(policy?: ChannelPolicy): this;
+    /** Switch policy — `auto` drains whatever is already queued, oldest first. */
+    setPolicy(policy: ChannelPolicy): ChannelPolicy;
+    /** Accept (deliver) one pending push — 1-based `index`, default the oldest. */
+    accept(index?: number): ChannelMessage | null;
+    /** Refuse one pending push — same indexing as accept. */
+    discard(index?: number): ChannelMessage | null;
+    /** /clear and /fork: a rebind reuses the token for the new session id. */
+    rebind(id: string): void;
+    stop(reason?: string): void;
+    private take;
+    private deliver;
+    /**
+     * S13c — close the loop: hand every delivered-but-unanswered push the
+     * closing text of the turn that consumed it (chat.ts calls this when a turn
+     * ends; `null`/blank means the turn said nothing useful, which is reported
+     * as an EXPLICIT no-text marker rather than silence). Frames are keyed by
+     * nonce and stored by the relay, readable only with the channel token.
+     * Returns how many nonces were answered.
+     */
+    publishReplies(reply: string | null, opts?: {
+        interrupted?: boolean;
+    }): number;
+    /** Shape-check a pushed frame — the relay is a pipe, delivery trusts nothing. */
+    private validateMessage;
+    private ack;
+    private notice;
+    private emitOpen;
+    private emitTo;
+    private setStatus;
+}
+export declare function startSessionChannel(deps: SessionChannelDeps, policy?: ChannelPolicy): SessionChannel;
+export declare function activeSessionChannel(): SessionChannel | null;
+export declare function rebindSessionChannel(id: string): void;
+export declare function stopSessionChannel(reason?: string): void;
+//# sourceMappingURL=sessionChannel.d.ts.map

package/dist/share/sessionChannel.d.ts.map

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

package/dist/share/sessionChannel.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionChannel = exports.CHANNEL_REPLY_MAX_CHARS = exports.CHANNEL_TEXT_MAX_CHARS = exports.CHANNEL_QUEUE_CAP = exports.CHANNEL_TOKEN_PREFIX = void 0;
+exports.hashChannelToken = hashChannelToken;
+exports.channelPushUrl = channelPushUrl;
+exports.escapeChannelText = escapeChannelText;
+exports.formatChannelEvent = formatChannelEvent;
+exports.startSessionChannel = startSessionChannel;
+exports.activeSessionChannel = activeSessionChannel;
+exports.rebindSessionChannel = rebindSessionChannel;
+exports.stopSessionChannel = stopSessionChannel;
+// Lives in core (moved from the CLI's ui/sessionChannel.ts, 2026-10-05) so the
+// VS Code panel opens the same inbound door with the same policy rules; the CLI
+// module is a re-export shim. The singleton helpers are for the one-REPL CLI;
+// the panel instantiates SessionChannel directly, one per chat tab.
+// S13 — channels: the INBOUND door into a live session. An external source
+// (CI, a webhook, a script, a chat bridge) pushes a message through the
+// platform relay (POST /api/cli-sessions/<id>/push on the api-server) and this
+// module is the terminal half: it opens the door when asked, receives pushed
+// frames, and LEAVES THE POLICY TO THE TERMINAL — default `ask`, where a push
+// waits for the person at the keyboard to accept it; `auto` for hands-off
+// monitoring, an explicit per-session choice.
+//
+// Invariants, mirroring sessionShare.ts:
+//   · never throws and never breaks the REPL — a malformed frame is dropped.
+//   · default OFF: nothing is reachable until `/channel open` mints a token.
+//   · the raw token NEVER leaves the process — only its sha256 goes to the
+//     relay (relay: cli:channel-open), and the push route re-hashes the header
+//     it receives; a leaked relay store therefore leaks nothing usable.
+//   · a received message can never run a command or answer a prompt BY ITSELF:
+//     delivery is the caller's job (chat.ts injects a wrapped <channel> line),
+//     and the relay/route never inject anything.
+//   · the door dies with the process: stop() and disconnect both make the
+//     server-side mapping vanish, and the push route 404s from that moment.
+const node_crypto_1 = require("node:crypto");
+const socket_io_client_1 = require("socket.io-client");
+/** Token shape the CLI mints and the relay/route only ever hash. */
+exports.CHANNEL_TOKEN_PREFIX = 'nxch_';
+/** More undecided pushes than this and new ones are refused, not queued — an
+ *  external source must not be able to bury the one message a human needs. */
+exports.CHANNEL_QUEUE_CAP = 10;
+/** Matches the relay's and the route's own cap (defense in depth). */
+exports.CHANNEL_TEXT_MAX_CHARS = 8192;
+/** S13c: what a source may read back — one turn's closing text, same bound. */
+exports.CHANNEL_REPLY_MAX_CHARS = 8192;
+/** Bounded nonce memory for duplicate suppression across reconnects. */
+const SEEN_NONCE_CAP = 512;
+/** Delivered pushes awaiting a reply; past this the oldest stop being tracked
+ *  (they are not owed an answer forever — the door answers what it can). */
+const AWAITING_REPLY_CAP = 64;
+const NONCE_RE = /^[a-f0-9]{16}$/;
+const SOURCE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+function defaultMintToken() {
+    return exports.CHANNEL_TOKEN_PREFIX + (0, node_crypto_1.randomBytes)(24).toString('base64url');
+}
+function hashChannelToken(token) {
+    return (0, node_crypto_1.createHash)('sha256').update(token).digest('hex');
+}
+/**
+ * The push endpoint for a session. Built here so the CLI prints exactly the
+ * URL the route serves — one string, one place.
+ */
+function channelPushUrl(id, url) {
+    return `${url.replace(/\/+$/, '')}/api/cli-sessions/${encodeURIComponent(id)}/push`;
+}
+/**
+ * Escape `<` so a hostile push cannot close the wrapper tag early; `&` and
+ * `>` stay readable because CI URLs are the common case and the model reads
+ * this text, not an XML parser.
+ */
+function escapeChannelText(text) {
+    return text.replace(/</g, '&lt;');
+}
+/**
+ * What the conversation receives. Same `<channel source=…>` shape Claude Code
+ * documents for its own channels, so prompts and habits built for one read
+ * the same here — and it can never parse as a slash command.
+ */
+function formatChannelEvent(msg) {
+    return `<channel source="${msg.source}" ts="${new Date(msg.ts).toISOString()}">\n${escapeChannelText(msg.text)}\n</channel>`;
+}
+const defaultFactory = (url, opts) => (0, socket_io_client_1.io)(url, opts);
+class SessionChannel {
+    constructor(deps) {
+        this.deps = deps;
+        this.socket = null;
+        this.status = { state: 'connecting' };
+        this.stopped = false;
+        this.refreshing = false;
+        this.policy = 'ask';
+        this.queue = [];
+        this.seenNonces = new Set();
+        /** S13c: nonces delivered but not yet answered by a finished turn. */
+        this.awaitingReply = new Set();
+        /** Minted once per open; rotated by a re-open after /channel close. */
+        this.token = null;
+        this.tokenHash = null;
+        this.id = deps.sessionId;
+    }
+    get sessionId() {
+        return this.id;
+    }
+    get state() {
+        return this.status;
+    }
+    get activePolicy() {
+        return this.policy;
+    }
+    /** The push URL a human pastes into CI; the token is NOT part of it. */
+    get pushUrl() {
+        return channelPushUrl(this.id, this.deps.url);
+    }
+    /** Shown once by `/channel open` — memory only, never persisted anywhere. */
+    get rawToken() {
+        return this.token;
+    }
+    /** Pending pushes, oldest first. A copy: callers cannot mutate the queue. */
+    pending() {
+        return [...this.queue];
+    }
+    start(policy = 'ask') {
+        const mint = this.deps.mintToken ?? defaultMintToken;
+        this.token = mint();
+        this.tokenHash = hashChannelToken(this.token);
+        this.policy = policy;
+        const factory = this.deps.ioFactory ?? defaultFactory;
+        const socket = factory(this.deps.url, {
+            path: '/socket.io',
+            transports: ['websocket'],
+            autoUnref: true,
+            reconnection: true,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 15000,
+            timeout: 10000,
+            auth: (cb) => {
+                cb({ token: this.deps.tokenProvider() ?? '' });
+            },
+        });
+        this.socket = socket;
+        socket.on('connect', () => {
+            if (this.stopped)
+                return; // a late reconnect after stop must not resurrect the door
+            this.setStatus({ state: 'live' });
+            // Re-sent on every (re)connect: the mapping is refreshed, and after a
+            // blip the door re-opens without the user doing anything.
+            this.emitOpen();
+        });
+        socket.on('disconnect', (reason) => {
+            if (!this.stopped)
+                this.setStatus({ state: 'offline', detail: String(reason ?? 'disconnected') });
+        });
+        socket.on('connect_error', (err) => {
+            const detail = err?.message ?? 'connect error';
+            this.setStatus({ state: 'offline', detail });
+            if (this.deps.refreshToken && !this.refreshing && /invalid|expired/i.test(detail)) {
+                this.refreshing = true;
+                void this.deps
+                    .refreshToken()
+                    .catch(() => { })
+                    .finally(() => {
+                    this.refreshing = false;
+                });
+            }
+        });
+        socket.on('cli:channel-message', (payload) => {
+            if (this.stopped)
+                return; // an in-flight frame between emit(close) and disconnect
+            const msg = this.validateMessage(payload);
+            if (!msg)
+                return;
+            if (this.seenNonces.has(msg.nonce))
+                return; // reconnect overlap: one delivery
+            if (this.seenNonces.size >= SEEN_NONCE_CAP) {
+                this.seenNonces.delete(this.seenNonces.values().next().value);
+            }
+            this.seenNonces.add(msg.nonce);
+            if (this.policy === 'auto') {
+                this.deliver(msg, true);
+                return;
+            }
+            if (this.queue.length >= exports.CHANNEL_QUEUE_CAP) {
+                this.notice({ kind: 'dropped', msg, reason: 'queue_full' });
+                this.ack(msg, 'discarded');
+                return;
+            }
+            this.queue.push(msg);
+            this.notice({ kind: 'queued', msg, position: this.queue.length });
+            this.ack(msg, 'queued');
+        });
+        return this;
+    }
+    /** Switch policy — `auto` drains whatever is already queued, oldest first. */
+    setPolicy(policy) {
+        if (this.stopped)
+            return this.policy;
+        this.policy = policy;
+        if (policy === 'auto') {
+            const queued = this.queue.splice(0);
+            for (const msg of queued)
+                this.deliver(msg, true);
+        }
+        return this.policy;
+    }
+    /** Accept (deliver) one pending push — 1-based `index`, default the oldest. */
+    accept(index) {
+        const msg = this.take(index);
+        if (!msg)
+            return null;
+        this.deliver(msg, false);
+        return msg;
+    }
+    /** Refuse one pending push — same indexing as accept. */
+    discard(index) {
+        const msg = this.take(index);
+        if (!msg)
+            return null;
+        this.notice({ kind: 'discarded', msg });
+        this.ack(msg, 'discarded');
+        return msg;
+    }
+    /** /clear and /fork: a rebind reuses the token for the new session id. */
+    rebind(id) {
+        if (this.stopped || !id || id === this.id)
+            return;
+        this.id = id;
+        // The relay stores the SAME hash under the new session id (one mapping
+        // key), so a push for the old id starts 404ing and the new id works.
+        if (this.socket?.connected)
+            this.emitOpen();
+    }
+    stop(reason = 'closed') {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.queue = [];
+        // S13c: unanswered pushes die with the door — the token that could read
+        // the results is being revoked in the same breath.
+        this.awaitingReply.clear();
+        if (this.socket?.connected)
+            this.emitTo('cli:channel-close', { id: this.id, reason });
+        this.token = null;
+        this.tokenHash = null;
+        try {
+            this.socket?.disconnect();
+        }
+        catch {
+            /* closing anyway */
+        }
+        this.setStatus({ state: 'stopped' });
+    }
+    take(index) {
+        if (this.stopped || this.queue.length === 0)
+            return null;
+        const at = index === undefined ? 0 : Math.min(Math.max(1, index), this.queue.length) - 1;
+        const [msg] = this.queue.splice(at, 1);
+        return msg ?? null;
+    }
+    deliver(msg, auto) {
+        let verdict = 'accepted';
+        try {
+            verdict = this.deps.onDeliver?.(formatChannelEvent(msg), msg) ?? 'accepted';
+        }
+        catch {
+            /* the REPL survives any frame */
+        }
+        this.notice({ kind: 'delivered', msg, auto, folded: verdict === 'queued' });
+        this.ack(msg, verdict);
+        // S13c: the message is now the conversation's problem — whatever the turn
+        // that consumed it ends up saying is owed back to the source.
+        if (this.awaitingReply.size >= AWAITING_REPLY_CAP) {
+            this.awaitingReply.delete(this.awaitingReply.values().next().value);
+        }
+        this.awaitingReply.add(msg.nonce);
+    }
+    /**
+     * S13c — close the loop: hand every delivered-but-unanswered push the
+     * closing text of the turn that consumed it (chat.ts calls this when a turn
+     * ends; `null`/blank means the turn said nothing useful, which is reported
+     * as an EXPLICIT no-text marker rather than silence). Frames are keyed by
+     * nonce and stored by the relay, readable only with the channel token.
+     * Returns how many nonces were answered.
+     */
+    publishReplies(reply, opts = {}) {
+        if (this.stopped || this.awaitingReply.size === 0)
+            return 0;
+        const text = (reply ?? '').trim();
+        let body;
+        if (!text)
+            body = { noText: true };
+        else if (text.length > exports.CHANNEL_REPLY_MAX_CHARS) {
+            body = { reply: text.slice(0, exports.CHANNEL_REPLY_MAX_CHARS), truncated: true };
+        }
+        else
+            body = { reply: text };
+        if (opts.interrupted)
+            body.interrupted = true;
+        let answered = 0;
+        for (const nonce of this.awaitingReply) {
+            this.emitTo('cli:channel-result', { id: this.id, nonce, ...body });
+            answered += 1;
+        }
+        this.awaitingReply.clear();
+        return answered;
+    }
+    /** Shape-check a pushed frame — the relay is a pipe, delivery trusts nothing. */
+    validateMessage(payload) {
+        const p = payload;
+        if (!p || typeof p !== 'object' || p.id !== this.id)
+            return null;
+        if (typeof p.nonce !== 'string' || !NONCE_RE.test(p.nonce))
+            return null;
+        if (typeof p.text !== 'string' || !p.text.trim() || p.text.length > exports.CHANNEL_TEXT_MAX_CHARS)
+            return null;
+        const source = typeof p.source === 'string' && SOURCE_RE.test(p.source) ? p.source : 'channel';
+        const ts = typeof p.ts === 'number' && Number.isFinite(p.ts) ? p.ts : Date.now();
+        return { nonce: p.nonce, source, text: p.text, ts };
+    }
+    ack(msg, status) {
+        this.emitTo('cli:channel-ack', { id: this.id, nonce: msg.nonce, status });
+    }
+    notice(n) {
+        try {
+            this.deps.onNotice?.(n);
+        }
+        catch {
+            /* notices are cosmetic */
+        }
+    }
+    emitOpen() {
+        if (!this.tokenHash)
+            return;
+        this.emitTo('cli:channel-open', { id: this.id, tokenHash: this.tokenHash });
+    }
+    emitTo(event, payload) {
+        try {
+            this.socket?.emit(event, payload);
+        }
+        catch {
+            /* the door must never break the REPL */
+        }
+    }
+    setStatus(next) {
+        const same = next.state === this.status.state && next.detail === this.status.detail;
+        this.status = next;
+        if (!same) {
+            try {
+                this.deps.onStatus?.(next);
+            }
+            catch {
+                /* status is cosmetic */
+            }
+        }
+    }
+}
+exports.SessionChannel = SessionChannel;
+// ─── The one channel a REPL can have ──────────────────────────────────────────
+let current = null;
+function startSessionChannel(deps, policy = 'ask') {
+    current?.stop('replaced');
+    current = new SessionChannel(deps).start(policy);
+    return current;
+}
+function activeSessionChannel() {
+    return current;
+}
+function rebindSessionChannel(id) {
+    current?.rebind(id);
+}
+function stopSessionChannel(reason = 'closed') {
+    current?.stop(reason);
+    current = null;
+}
+//# sourceMappingURL=sessionChannel.js.map

package/dist/share/sessionShare.d.ts

@@ -0,0 +1,104 @@
+import { type SessionEvent } from '../events/sessionEvents';
+/** The slice of a Socket.IO socket this module uses — small enough to fake in tests. */
+export interface ShareSocket {
+    readonly connected: boolean;
+    on(event: string, handler: (...args: unknown[]) => void): unknown;
+    emit(event: string, payload?: unknown): void;
+    disconnect(): void;
+}
+export type ShareIoFactory = (url: string, opts: Record<string, unknown>) => ShareSocket;
+export interface ShareStatus {
+    state: 'connecting' | 'live' | 'offline' | 'stopped';
+    detail?: string;
+}
+export interface SessionShareDeps {
+    /** Origin of the platform API — the Socket.IO server shares the host, path /socket.io. */
+    url: string;
+    sessionId: string;
+    /** Computed fresh at every hello: the model (and branch) can change mid-session. */
+    meta: () => Record<string, unknown>;
+    /** Called before EVERY (re)connect attempt, so a rotated token is picked up. */
+    tokenProvider: () => string | null;
+    /** Called once after an auth-shaped connect error (an access token that expired mid-session). */
+    refreshToken?: () => Promise<boolean>;
+    /** Tail of the local JSONL, oldest → newest. Defaults to readEvents(id, {last: PULL_LIMIT}). */
+    recent?: (id: string) => SessionEvent[];
+    ioFactory?: ShareIoFactory;
+    onStatus?: (s: ShareStatus) => void;
+    /** §93 S12b: a line the WEB typed, delivered only while drive is on. */
+    onRemoteText?: (text: string) => void;
+    /** §93 S12b: the web's answer to the pending permission prompt (drive on only). */
+    onRemoteAnswer?: (requestId: string, answer: 'y' | 'n') => void;
+}
+/** Frames pushed when a viewer attaches — enough context to see what the session has been doing. */
+export declare const PULL_LIMIT = 200;
+/** Frames re-pushed after a reconnect, to fill the hole the outage left in watching clients. */
+export declare const RECONNECT_FILL = 50;
+/** Bound on a remote input line; matches the relay's own cap (defense in depth). */
+export declare const MAX_REMOTE_INPUT_CHARS = 8192;
+/** §93 S12b: the web's feedback line for one remote frame (accepted / queued / refused / stale). */
+export interface RemoteNoteFrame {
+    kind: 'input' | 'answer';
+    status: 'accepted' | 'queued' | 'refused' | 'stale';
+    reason?: string;
+    text?: string;
+    requestId?: string;
+}
+/** Where the relay lives. Overridable so a dev stack never needs production. */
+export declare function shareServerUrl(env?: NodeJS.ProcessEnv): string;
+/** The link a human opens to watch — the CLI prints this, nothing else constructs it. */
+export declare function webLiveUrl(id: string, env?: NodeJS.ProcessEnv): string;
+export declare class SessionShare {
+    private readonly deps;
+    private socket;
+    private id;
+    private status;
+    /** A second connect means the first one dropped: heal the hole for watchers. */
+    private everConnected;
+    private refreshing;
+    private stopped;
+    /** §93 S12b: remote driving — the terminal's switch, off until /share drive on. */
+    private drive;
+    /** §93 S12b: the permission prompt currently open in this terminal (null: none). */
+    private pendingPermission;
+    constructor(deps: SessionShareDeps);
+    get sessionId(): string;
+    get state(): ShareStatus;
+    start(): this;
+    /**
+     * §93 S12b — turn remote driving on/off (returning the state now in effect).
+     * Off by default: a watch link is read-only until the person AT the terminal
+     * says otherwise, and the value is re-announced by every hello so a viewer
+     * that missed the toggle frame sees the truth after any reconnect. The
+     * terminal keeps every gate — drive can be revoked at any moment with
+     * /share drive off, and the destructive confirm stays terminal-only regardless.
+     */
+    setDrive(on: boolean): boolean;
+    isDriveOn(): boolean;
+    /**
+     * §93 S12b — the permission prompt currently open here, or null when none is.
+     * Kept so a viewer attaching MID-prompt is handed it again by the pull (the
+     * same healing rule the event tail follows); cleared by the gate when the
+     * prompt is done. Like every publish, a frame while disconnected is dropped
+     * rather than buffered — the pull replays the current one.
+     */
+    publishPermission(frame: unknown | null): void;
+    /** §93 S12b — tell the web what this terminal did with a remote frame. */
+    publishRemoteNote(note: RemoteNoteFrame): void;
+    publish(ev: SessionEvent): void;
+    /** /clear and /fork move the session to a new id; watching follows it. */
+    rebind(id: string): void;
+    stop(reason?: string): void;
+    private emitTo;
+    /** One shape for every hello, so the two call sites cannot drift. */
+    private emitHello;
+    private pushTail;
+    private setStatus;
+}
+export declare function startSessionShare(deps: SessionShareDeps): SessionShare;
+export declare function activeSessionShare(): SessionShare | null;
+/** Called from the event funnel; free when sharing is off. */
+export declare function publishSharedEvent(ev: SessionEvent | null | undefined): void;
+export declare function rebindSessionShare(id: string): void;
+export declare function stopSessionShare(reason?: string): void;
+//# sourceMappingURL=sessionShare.d.ts.map

package/dist/share/sessionShare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionShare.d.ts","sourceRoot":"","sources":["../../src/share/sessionShare.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAExE,wFAAwF;AACxF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC;IAClE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,WAAW,CAAC;AAEzF,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,0FAA0F;IAC1F,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,IAAI,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,gFAAgF;IAChF,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACnC,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,YAAY,EAAE,CAAC;IACxC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,wEAAwE;IACxE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,mFAAmF;IACnF,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,IAAI,CAAC;CACjE;AAED,oGAAoG;AACpG,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,gGAAgG;AAChG,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAI3C,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG3E;AAED,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGnF;AAKD,qBAAa,YAAY;IAaX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAZjC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,MAAM,CAAwC;IACtD,gFAAgF;IAChF,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,mFAAmF;IACnF,OAAO,CAAC,KAAK,CAAS;IACtB,oFAAoF;IACpF,OAAO,CAAC,iBAAiB,CAAiB;gBAEb,IAAI,EAAE,gBAAgB;IAInD,IAAI,SAAS,IAAI,MAAM,CAEtB;IACD,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,KAAK,IAAI,IAAI;IAsGb;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO;IAU9B,SAAS,IAAI,OAAO;IAIpB;;;;;;OAMG;IACH,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI;IAM9C,0EAA0E;IAC1E,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAY9C,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI;IAK/B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IASxB,IAAI,CAAC,MAAM,SAAW,GAAG,IAAI;IAgB7B,OAAO,CAAC,MAAM;IAQd,qEAAqE;IACrE,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,SAAS;CAWlB;AAMD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAItE;AAED,wBAAgB,kBAAkB,IAAI,YAAY,GAAG,IAAI,CAExD;AAED,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAG5E;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,SAAW,GAAG,IAAI,CAGxD"}