@av-pi-studio/client 0.0.1

package/dist/file-transfer-client.js

@@ -0,0 +1,83 @@
+import {} from "@av-pi-studio/protocol";
+function concat(chunks) {
+    const total = chunks.reduce((sum, c) => sum + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+export class FileTransferClient {
+    daemon;
+    pending = new Map();
+    nextStream = 1;
+    detach = null;
+    constructor(daemon) {
+        this.daemon = daemon;
+    }
+    /** Begin routing inbound file-transfer frames. Idempotent. */
+    start() {
+        if (this.detach)
+            return;
+        this.detach = this.daemon.onFileTransferFrame((frame) => this.dispatch(frame));
+    }
+    /** Stop routing inbound frames. Any downloads still pending are rejected. */
+    stop() {
+        this.detach?.();
+        this.detach = null;
+        for (const [stream, pending] of this.pending) {
+            pending.reject(new Error("file transfer router stopped"));
+            this.pending.delete(stream);
+        }
+    }
+    /**
+     * Download the file at `path`: requests a single-use token, then requests the chunked
+     * transfer, assembling `Begin → Chunk* → End` frames into one buffer.
+     */
+    async download(path) {
+        const tokenResponse = await this.daemon.request("file_download_token_request", { path });
+        if (!tokenResponse.ok || !tokenResponse.token) {
+            throw new Error(tokenResponse.error ?? "failed to issue download token");
+        }
+        const stream = this.nextStream++;
+        const result = new Promise((resolve, reject) => {
+            this.pending.set(stream, { chunks: [], meta: {}, resolve, reject });
+        });
+        const requestResponse = await this.daemon.request("file_download_request", { token: tokenResponse.token, stream });
+        if (!requestResponse.ok) {
+            this.pending.delete(stream);
+            throw new Error(requestResponse.error ?? "download request failed");
+        }
+        return result;
+    }
+    dispatch(frame) {
+        const pending = this.pending.get(frame.stream);
+        if (!pending)
+            return; // not a download stream we're tracking (e.g. an upload) — ignore
+        switch (frame.opcode) {
+            case "Begin":
+                pending.meta.fileName = frame.meta.fileName;
+                pending.meta.mimeType = frame.meta.mimeType;
+                return;
+            case "Chunk":
+                pending.chunks.push(frame.data);
+                return;
+            case "End":
+                this.pending.delete(frame.stream);
+                if (frame.ok) {
+                    pending.resolve({ bytes: concat(pending.chunks), ...pending.meta });
+                }
+                else {
+                    pending.reject(new Error("download failed"));
+                }
+                return;
+            case "Error":
+                this.pending.delete(frame.stream);
+                pending.reject(new Error(frame.message));
+                return;
+        }
+    }
+}
+//# sourceMappingURL=file-transfer-client.js.map

package/dist/file-transfer-client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export declare const CLIENT_PACKAGE: "@av-pi-studio/client";
+/** Proves the client consumes protocol's emitted declarations. */
+export declare const PROTOCOL_DEP: "@av-pi-studio/protocol";
+export * from "./transport.js";
+export * from "./daemon-client.js";
+export * from "./pistudio-client.js";
+export * from "./terminal-stream-router.js";
+export * from "./file-transfer-client.js";
+export * from "./reconnect.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc,EAAG,sBAA+B,CAAC;AAE9D,kEAAkE;AAClE,eAAO,MAAM,YAAY,0BAAmB,CAAC;AAG7C,cAAc,gBAAgB,CAAC;AAG/B,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,6BAA6B,CAAC;AAG5C,cAAc,2BAA2B,CAAC;AAG1C,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+// @av-pi-studio/client — low-level daemon WS driver + Pi-StudioClient SDK facade.
+import { PROTOCOL_PACKAGE } from "@av-pi-studio/protocol";
+export const CLIENT_PACKAGE = "@av-pi-studio/client";
+/** Proves the client consumes protocol's emitted declarations. */
+export const PROTOCOL_DEP = PROTOCOL_PACKAGE;
+// Transport abstraction (direct WS; relay rides the same API).
+export * from "./transport.js";
+// Low-level daemon WebSocket driver.
+export * from "./daemon-client.js";
+// High-level PiStudioClient SDK facade + handles.
+export * from "./pistudio-client.js";
+// Terminal-stream router (binary frame demux per slot).
+export * from "./terminal-stream-router.js";
+// File-transfer client (binary download frame demux + assembly).
+export * from "./file-transfer-client.js";
+// Reconnection + capability-rehydrate driver.
+export * from "./reconnect.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,CAAC,MAAM,cAAc,GAAG,sBAA+B,CAAC;AAE9D,kEAAkE;AAClE,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAE7C,+DAA+D;AAC/D,cAAc,gBAAgB,CAAC;AAE/B,qCAAqC;AACrC,cAAc,oBAAoB,CAAC;AAEnC,kDAAkD;AAClD,cAAc,sBAAsB,CAAC;AAErC,wDAAwD;AACxD,cAAc,6BAA6B,CAAC;AAE5C,iEAAiE;AACjE,cAAc,2BAA2B,CAAC;AAE1C,8CAA8C;AAC9C,cAAc,gBAAgB,CAAC"}

package/dist/pistudio-client.d.ts

@@ -0,0 +1,122 @@
+import type { AgentStreamEvent, CreateAgentRequest, FetchAgentTimelineResponse, SessionMessage, TimelineDirection } from "@av-pi-studio/protocol";
+import type { DaemonClient } from "./daemon-client.js";
+/**
+ * High-level `PiStudioClient` SDK facade over the low-level `DaemonClient` driver.
+ *
+ * Exposes workspace/agent/provider handles plus update handler registration, mirroring the
+ * scope's `Pi-StudioClient` surface (architecture/client-app-runtime.md § Layered client library /
+ * Facade and features/agent-sessions.md § Public Contract). Method names follow the server RPC
+ * type names (`create_agent_request`, `send_agent_prompt`, `interrupt_agent`, `update_agent`,
+ * `resume_agent`, `import_agent_session`, `fetch_agent_timeline_request`).
+ *
+ * Out of scope: app runtime controller (sprint-012), terminal router (task-003).
+ */
+export type PiStudioAgentUpdateHandler = (update: AgentUpdateMessage) => void;
+export type PiStudioWorkspaceUpdateHandler = (update: WorkspaceUpdateMessage) => void;
+export type PiStudioAgentStreamHandler = (event: AgentStreamEvent) => void;
+/** Shape of an inbound `agent_update` session message (append-only; passthrough). */
+export interface AgentUpdateMessage {
+    type: "agent_update";
+    agentId: string;
+    status?: string;
+    title?: string;
+    labels?: Record<string, string>;
+    [key: string]: unknown;
+}
+/** Shape of an inbound `workspace_update` session message. */
+export interface WorkspaceUpdateMessage {
+    type: "workspace_update";
+    workspaceId: string;
+    [key: string]: unknown;
+}
+export interface PiStudioAgentTimelineHandle {
+    /** Fetch a bounded page of authoritative timeline history. */
+    fetch(opts?: {
+        cursor?: string;
+        direction?: TimelineDirection;
+        limit?: number;
+    }): Promise<FetchAgentTimelineResponse>;
+    /** Subscribe to live `agent_stream` events for this agent. Returns an unsubscribe fn. */
+    subscribe(handler: PiStudioAgentStreamHandler): () => void;
+}
+export interface PiStudioAgentActions {
+    readonly agentId: string;
+    readonly timeline: PiStudioAgentTimelineHandle;
+    /** Send a follow-up prompt to the running/idle agent. */
+    send(prompt: string, opts?: {
+        clientMessageId?: string;
+        images?: unknown[];
+    }): Promise<unknown>;
+    /** Alias for `send` reflecting the scope's "run a turn" verb. */
+    run(prompt: string, opts?: {
+        clientMessageId?: string;
+        images?: unknown[];
+    }): Promise<unknown>;
+    /** Interrupt the current turn. */
+    interrupt(): Promise<unknown>;
+    /** Update model/mode/thinking/features/title/labels without recreating the session. */
+    update(patch: {
+        modeId?: string;
+        model?: string;
+        thinkingOptionId?: string;
+        featureValues?: Record<string, unknown>;
+        title?: string;
+        labels?: Record<string, string>;
+    }): Promise<unknown>;
+    /** Resume a closed session via its persistence handle. */
+    resume(): Promise<unknown>;
+    /** Archive (soft-delete) the agent — closes the runtime, keeps the record for resume. */
+    archive(): Promise<unknown>;
+    /** Permanently delete the agent's persisted record (hard delete — no trace, cannot resume). */
+    delete(): Promise<unknown>;
+    /** Subscribe to `agent_update` events scoped to this agent. */
+    onUpdate(handler: PiStudioAgentUpdateHandler): () => void;
+}
+export interface PiStudioWorkspaceActions {
+    readonly workspaceId: string;
+    /** Subscribe to `workspace_update` events scoped to this workspace. */
+    onUpdate(handler: PiStudioWorkspaceUpdateHandler): () => void;
+}
+export interface PiStudioProviderActions {
+    /** List available providers. */
+    listProviders(): Promise<unknown>;
+    /** List models for a provider. */
+    listModels(provider: string): Promise<unknown>;
+    /** List modes for a provider. */
+    listModes(provider: string): Promise<unknown>;
+    /** Trigger an explicit provider snapshot refresh (no hidden revalidation). */
+    refreshSnapshot(): Promise<unknown>;
+}
+export declare class PiStudioClient {
+    private readonly daemon;
+    constructor(daemon: DaemonClient);
+    get connection(): DaemonClient;
+    /**
+     * Create a new agent session. Returns the response payload (includes `agentId`). When
+     * `initialPrompt` is set, the daemon runs the first turn and streams events to subscribers.
+     */
+    createAgent(req: Omit<CreateAgentRequest, "type" | "requestId"> & {
+        requestId?: string;
+    }): Promise<{
+        agentId: string;
+        [key: string]: unknown;
+    }>;
+    /** Get an agent handle for an existing agentId. */
+    agent(agentId: string): PiStudioAgentActions;
+    /** Get a workspace handle for an existing workspaceId. */
+    workspace(workspaceId: string): PiStudioWorkspaceActions;
+    /** Provider actions (list providers/models/modes, refresh snapshot). */
+    get providers(): PiStudioProviderActions;
+    /** Subscribe to ALL `agent_update` events (any agent). */
+    onAgentUpdate(handler: PiStudioAgentUpdateHandler): () => void;
+    /** Subscribe to ALL `workspace_update` events (any workspace). */
+    onWorkspaceUpdate(handler: PiStudioWorkspaceUpdateHandler): () => void;
+}
+/** Convenience re-export of the import operation (not agent-scoped). */
+export declare function importAgentSession(daemon: DaemonClient, args: {
+    provider: string;
+    cwd: string;
+    providerHandleId: string;
+}): Promise<unknown>;
+export type { SessionMessage };
+//# sourceMappingURL=pistudio-client.d.ts.map

package/dist/pistudio-client.d.ts.map

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

package/dist/pistudio-client.js

@@ -0,0 +1,155 @@
+// ─── Facade implementation ──────────────────────────────────────────────────────
+export class PiStudioClient {
+    daemon;
+    constructor(daemon) {
+        this.daemon = daemon;
+    }
+    get connection() {
+        return this.daemon;
+    }
+    /**
+     * Create a new agent session. Returns the response payload (includes `agentId`). When
+     * `initialPrompt` is set, the daemon runs the first turn and streams events to subscribers.
+     */
+    async createAgent(req) {
+        const payload = await this.daemon.request("create_agent_request", {
+            ...req,
+        });
+        return payload;
+    }
+    /** Get an agent handle for an existing agentId. */
+    agent(agentId) {
+        return new AgentHandle(this.daemon, agentId);
+    }
+    /** Get a workspace handle for an existing workspaceId. */
+    workspace(workspaceId) {
+        return new WorkspaceHandle(this.daemon, workspaceId);
+    }
+    /** Provider actions (list providers/models/modes, refresh snapshot). */
+    get providers() {
+        return new ProviderHandle(this.daemon);
+    }
+    /** Subscribe to ALL `agent_update` events (any agent). */
+    onAgentUpdate(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            if (msg.type === "agent_update") {
+                handler(msg);
+            }
+        });
+    }
+    /** Subscribe to ALL `workspace_update` events (any workspace). */
+    onWorkspaceUpdate(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            if (msg.type === "workspace_update") {
+                handler(msg);
+            }
+        });
+    }
+}
+// ─── Handle classes ──────────────────────────────────────────────────────────────
+class TimelineHandle {
+    daemon;
+    agentId;
+    constructor(daemon, agentId) {
+        this.daemon = daemon;
+        this.agentId = agentId;
+    }
+    fetch(opts = {}) {
+        return this.daemon.request("fetch_agent_timeline_request", {
+            agentId: this.agentId,
+            cursor: opts.cursor,
+            direction: opts.direction,
+            limit: opts.limit,
+        });
+    }
+    subscribe(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            const m = msg;
+            if (m.type === "agent_stream" && m.agentId === this.agentId && m.event) {
+                handler(m.event);
+            }
+        });
+    }
+}
+class AgentHandle {
+    daemon;
+    agentId;
+    timeline;
+    constructor(daemon, agentId) {
+        this.daemon = daemon;
+        this.agentId = agentId;
+        this.timeline = new TimelineHandle(daemon, agentId);
+    }
+    send(prompt, opts = {}) {
+        return this.daemon.request("send_agent_prompt", {
+            agentId: this.agentId,
+            prompt,
+            clientMessageId: opts.clientMessageId,
+            images: opts.images,
+        });
+    }
+    run(prompt, opts) {
+        return this.send(prompt, opts);
+    }
+    interrupt() {
+        return this.daemon.request("interrupt_agent", { agentId: this.agentId });
+    }
+    update(patch) {
+        return this.daemon.request("update_agent", { agentId: this.agentId, ...patch });
+    }
+    resume() {
+        return this.daemon.request("resume_agent", { agentId: this.agentId });
+    }
+    archive() {
+        return this.daemon.request("archive_agent", { agentId: this.agentId });
+    }
+    delete() {
+        return this.daemon.request("delete_agent", { agentId: this.agentId });
+    }
+    onUpdate(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            const m = msg;
+            if (m.type === "agent_update" && m.agentId === this.agentId)
+                handler(m);
+        });
+    }
+}
+class WorkspaceHandle {
+    daemon;
+    workspaceId;
+    constructor(daemon, workspaceId) {
+        this.daemon = daemon;
+        this.workspaceId = workspaceId;
+    }
+    onUpdate(handler) {
+        return this.daemon.onSessionMessage((msg) => {
+            const m = msg;
+            if (m.type === "workspace_update" && m.workspaceId === this.workspaceId)
+                handler(m);
+        });
+    }
+}
+class ProviderHandle {
+    daemon;
+    constructor(daemon) {
+        this.daemon = daemon;
+    }
+    listProviders() {
+        return this.daemon.request("list_providers", {});
+    }
+    listModels(provider) {
+        return this.daemon.request("list_provider_models", { provider });
+    }
+    listModes(provider) {
+        return this.daemon.request("list_provider_modes", { provider });
+    }
+    refreshSnapshot() {
+        // Dotted-namespace RPC per the protocol convention.
+        return this.daemon.request("providers.snapshot.refresh.request", {});
+    }
+}
+/** Convenience re-export of the import operation (not agent-scoped). */
+export function importAgentSession(daemon, args) {
+    return daemon.request("import_agent_session", args);
+}
+//# sourceMappingURL=pistudio-client.js.map

package/dist/pistudio-client.js.map

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

package/dist/reconnect.d.ts

@@ -0,0 +1,68 @@
+import type { DaemonClient } from "./daemon-client.js";
+/**
+ * Reconnection + capability-rehydrate driver (architecture/client-app-runtime.md § Connection,
+ * § Error Handling; architecture/websocket-protocol.md § Behavior / on reconnect).
+ *
+ * On socket drop, backoff-reconnect, re-`hello` (the `DaemonClient.connect()` resends the same
+ * capabilities), and rehydrate the recorded `serverId`/`features`. Timeline resume planning lives
+ * in sprint-012; this driver exposes the hooks (`onReconnected`) the planner rides on.
+ *
+ * Reconnection backoff parameters are TODO(verify) — defaults below are conservative.
+ */
+export interface ReconnectionOptions {
+    /** Initial backoff delay (ms). Default 500. */
+    initialDelayMs?: number;
+    /** Maximum backoff delay (ms). Default 30_000. */
+    maxDelayMs?: number;
+    /** Exponential growth factor. Default 2. */
+    factor?: number;
+    /** Random jitter ratio [0..1] applied to each delay. Default 0.2. */
+    jitter?: number;
+    /** Max reconnect attempts before giving up (Infinity = never). Default Infinity. */
+    maxAttempts?: number;
+    /** Injected timer scheduler (tests). Defaults to setTimeout. */
+    setTimer?: (cb: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    /** Injected RNG in [0,1) (tests). Defaults to Math.random. */
+    random?: () => number;
+}
+export type ReconnectedHandler = (info: {
+    attempt: number;
+    serverId: string | null;
+}) => void;
+export type ReconnectFailedHandler = (error: unknown, attempt: number) => void;
+export declare class ReconnectionManager {
+    private readonly daemon;
+    private readonly initialDelayMs;
+    private readonly maxDelayMs;
+    private readonly factor;
+    private readonly jitter;
+    private readonly maxAttempts;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly random;
+    private attempt;
+    private timer;
+    private active;
+    private detachState;
+    private readonly reconnectedHandlers;
+    private readonly failedHandlers;
+    constructor(daemon: DaemonClient, options?: ReconnectionOptions);
+    /** Compute the backoff delay for a given attempt number (1-based), with jitter. */
+    delayForAttempt(attempt: number): number;
+    /** Subscribe to successful reconnections (after re-handshake + rehydrate). */
+    onReconnected(handler: ReconnectedHandler): () => void;
+    /** Subscribe to reconnect attempt failures. */
+    onReconnectFailed(handler: ReconnectFailedHandler): () => void;
+    /**
+     * Start watching the daemon connection. On a `closed` transition, schedule a backoff reconnect.
+     */
+    start(): void;
+    /** Stop watching and cancel any pending reconnect. */
+    stop(): void;
+    /** Number of reconnect attempts made since the last healthy open. */
+    get attemptCount(): number;
+    private scheduleReconnect;
+    private tryReconnect;
+}
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../src/reconnect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;GASG;AAEH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,KAAK,IAAI,CAAC;AAC9F,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/E,qBAAa,mBAAmB;IAmB5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAlBzB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAA6B;IAEhD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAiC;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqC;gBAGjD,MAAM,EAAE,YAAY,EACrC,OAAO,GAAE,mBAAwB;IAanC,mFAAmF;IACnF,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAMxC,8EAA8E;IAC9E,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAKtD,+CAA+C;IAC/C,iBAAiB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAK9D;;OAEG;IACH,KAAK,IAAI,IAAI;IASb,sDAAsD;IACtD,IAAI,IAAI,IAAI;IAQZ,qEAAqE;IACrE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,OAAO,CAAC,iBAAiB;YAWX,YAAY;CAe3B"}

package/dist/reconnect.js

@@ -0,0 +1,103 @@
+export class ReconnectionManager {
+    daemon;
+    initialDelayMs;
+    maxDelayMs;
+    factor;
+    jitter;
+    maxAttempts;
+    setTimer;
+    clearTimer;
+    random;
+    attempt = 0;
+    timer = null;
+    active = false;
+    detachState = null;
+    reconnectedHandlers = new Set();
+    failedHandlers = new Set();
+    constructor(daemon, options = {}) {
+        this.daemon = daemon;
+        this.initialDelayMs = options.initialDelayMs ?? 500;
+        this.maxDelayMs = options.maxDelayMs ?? 30_000;
+        this.factor = options.factor ?? 2;
+        this.jitter = options.jitter ?? 0.2;
+        this.maxAttempts = options.maxAttempts ?? Number.POSITIVE_INFINITY;
+        this.setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+        this.clearTimer =
+            options.clearTimer ?? ((h) => clearTimeout(h));
+        this.random = options.random ?? Math.random;
+    }
+    /** Compute the backoff delay for a given attempt number (1-based), with jitter. */
+    delayForAttempt(attempt) {
+        const base = Math.min(this.maxDelayMs, this.initialDelayMs * this.factor ** (attempt - 1));
+        const jitterAmount = base * this.jitter * (this.random() * 2 - 1);
+        return Math.max(0, Math.round(base + jitterAmount));
+    }
+    /** Subscribe to successful reconnections (after re-handshake + rehydrate). */
+    onReconnected(handler) {
+        this.reconnectedHandlers.add(handler);
+        return () => this.reconnectedHandlers.delete(handler);
+    }
+    /** Subscribe to reconnect attempt failures. */
+    onReconnectFailed(handler) {
+        this.failedHandlers.add(handler);
+        return () => this.failedHandlers.delete(handler);
+    }
+    /**
+     * Start watching the daemon connection. On a `closed` transition, schedule a backoff reconnect.
+     */
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.detachState = this.daemon.onStateChange((state) => {
+            if (state === "closed" && this.active)
+                this.scheduleReconnect();
+            if (state === "open")
+                this.attempt = 0; // reset backoff on a healthy connection
+        });
+    }
+    /** Stop watching and cancel any pending reconnect. */
+    stop() {
+        this.active = false;
+        if (this.timer)
+            this.clearTimer(this.timer);
+        this.timer = null;
+        this.detachState?.();
+        this.detachState = null;
+    }
+    /** Number of reconnect attempts made since the last healthy open. */
+    get attemptCount() {
+        return this.attempt;
+    }
+    scheduleReconnect() {
+        if (!this.active)
+            return;
+        if (this.attempt >= this.maxAttempts)
+            return;
+        this.attempt += 1;
+        const delay = this.delayForAttempt(this.attempt);
+        this.timer = this.setTimer(() => {
+            this.timer = null;
+            void this.tryReconnect();
+        }, delay);
+    }
+    async tryReconnect() {
+        if (!this.active)
+            return;
+        const attempt = this.attempt;
+        try {
+            // connect() re-sends hello with the same capabilities → daemon rehydrates them, and the
+            // client re-records serverId + features from the fresh server_info.
+            await this.daemon.connect();
+            for (const handler of this.reconnectedHandlers) {
+                handler({ attempt, serverId: this.daemon.serverId });
+            }
+        }
+        catch (error) {
+            for (const handler of this.failedHandlers)
+                handler(error, attempt);
+            this.scheduleReconnect(); // back off and retry
+        }
+    }
+}
+//# sourceMappingURL=reconnect.js.map

package/dist/reconnect.js.map

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

package/dist/terminal-stream-router.d.ts

@@ -0,0 +1,38 @@
+import type { DaemonClient } from "./daemon-client.js";
+/**
+ * Client-side demux of binary terminal frames to per-slot subscribers, plus outbound input/resize
+ * encoding (architecture/client-app-runtime.md § Router; features/terminals.md § Binary stream
+ * protocol).
+ *
+ * Inbound `Output`/`Snapshot`/`Restore` frames are dispatched to the subscriber registered for that
+ * `slot`. Outbound `Input`/`Resize` are encoded with the right opcode + slot and sent on the data
+ * path.
+ */
+export interface TerminalSlotSubscriber {
+    /** Live terminal output bytes. */
+    onOutput?: (data: Uint8Array) => void;
+    /** Full-screen snapshot bytes (sent on (re)subscribe). */
+    onSnapshot?: (data: Uint8Array) => void;
+    /** Restore snapshot bytes (reflowable/mode-gated). */
+    onRestore?: (data: Uint8Array) => void;
+}
+export declare class TerminalStreamRouter {
+    private readonly daemon;
+    private readonly subscribers;
+    private detach;
+    constructor(daemon: DaemonClient);
+    /** Begin routing inbound terminal frames. Idempotent. */
+    start(): void;
+    /** Stop routing inbound frames (subscribers retained). */
+    stop(): void;
+    /** Register (or replace) the subscriber for a slot. Returns an unsubscribe fn. */
+    subscribeSlot(slot: number, subscriber: TerminalSlotSubscriber): () => void;
+    /** True iff a subscriber is registered for the slot. */
+    hasSlot(slot: number): boolean;
+    /** Send raw input bytes to a slot's PTY (opcode `Input = 0x02`). */
+    sendInput(slot: number, data: Uint8Array): void;
+    /** Send a resize (opcode `Resize = 0x03`, JSON `{ rows, cols }` payload). */
+    sendResize(slot: number, rows: number, cols: number): void;
+    private dispatch;
+}
+//# sourceMappingURL=terminal-stream-router.d.ts.map

package/dist/terminal-stream-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-stream-router.d.ts","sourceRoot":"","sources":["../src/terminal-stream-router.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;GAQG;AAEH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACtC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACxC;AAED,qBAAa,oBAAoB;IAInB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6C;IACzE,OAAO,CAAC,MAAM,CAA6B;gBAEd,MAAM,EAAE,YAAY;IAEjD,yDAAyD;IACzD,KAAK,IAAI,IAAI;IAKb,0DAA0D;IAC1D,IAAI,IAAI,IAAI;IAKZ,kFAAkF;IAClF,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAO3E,wDAAwD;IACxD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAM9B,oEAAoE;IACpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAI/C,6EAA6E;IAC7E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAM1D,OAAO,CAAC,QAAQ;CAkBjB"}