@termfleet/core 0.1.0

package/dist/terminal-client.d.ts

@@ -0,0 +1,49 @@
+import { type ProviderUrlResolver } from "./provider-url-resolver.js";
+export type TerminalHelloMessage = {
+    type: "hello";
+    cols: number;
+    rows: number;
+};
+export type TerminalOutputMessage = {
+    type: "output";
+    data: string;
+};
+export type TerminalExitMessage = {
+    type: "exit";
+    exitCode: number;
+    signal?: number;
+};
+export type TerminalErrorMessage = {
+    type: "error";
+    message: string;
+};
+export type TerminalInputRejectedMessage = {
+    type: "input-rejected";
+    message: string;
+};
+export type TerminalMessage = TerminalHelloMessage | TerminalOutputMessage | TerminalExitMessage | TerminalErrorMessage | TerminalInputRejectedMessage;
+export type TerminalClientOptions = {
+    authToken?: () => string | undefined;
+    baseUrl: string;
+    cols: number;
+    rows: number;
+    terminalId: string;
+    urlResolver?: ProviderUrlResolver;
+};
+export declare class TerminalClient {
+    readonly cols: number;
+    readonly rows: number;
+    readonly terminalId: string;
+    private readonly authToken?;
+    private socket?;
+    private readonly baseUrl;
+    private readonly urls;
+    constructor({ authToken, baseUrl, cols, rows, terminalId, urlResolver }: TerminalClientOptions);
+    connect(): WebSocket;
+    write(data: string): void;
+    close(): void;
+    parse(raw: string): TerminalMessage;
+    private requireOpenSocket;
+    private url;
+}
+export declare function webSocketBaseUrl(baseUrl: string): string;

package/dist/terminal-client.js

@@ -0,0 +1,89 @@
+import { directProviderUrlResolver } from "./provider-url-resolver.js";
+export class TerminalClient {
+    cols;
+    rows;
+    terminalId;
+    authToken;
+    socket;
+    baseUrl;
+    urls;
+    constructor({ authToken, baseUrl, cols, rows, terminalId, urlResolver }) {
+        this.authToken = authToken;
+        this.baseUrl = baseUrl;
+        this.cols = cols;
+        this.rows = rows;
+        this.terminalId = terminalId;
+        this.urls = urlResolver ?? directProviderUrlResolver;
+    }
+    connect() {
+        if (this.socket && this.socket.readyState !== WebSocket.CLOSED && this.socket.readyState !== WebSocket.CLOSING) {
+            return this.socket;
+        }
+        this.socket = new WebSocket(this.url());
+        return this.socket;
+    }
+    write(data) {
+        const socket = this.requireOpenSocket();
+        socket.send(JSON.stringify({ data, type: "input" }));
+    }
+    close() {
+        this.socket?.close();
+    }
+    parse(raw) {
+        const message = JSON.parse(raw);
+        if (message.type === "hello") {
+            const cols = message.cols;
+            const rows = message.rows;
+            if (cols === undefined || rows === undefined || !Number.isInteger(cols) || !Number.isInteger(rows)) {
+                throw new Error(`Hello message for ${this.terminalId} did not include cols and rows.`);
+            }
+            return { cols, rows, type: "hello" };
+        }
+        if (message.type === "output") {
+            if (typeof message.data !== "string") {
+                throw new Error(`Output message for ${this.terminalId} did not include data.`);
+            }
+            return { data: message.data, type: "output" };
+        }
+        if (message.type === "exit") {
+            const exitCode = message.exitCode;
+            if (exitCode === undefined || !Number.isInteger(exitCode)) {
+                throw new Error(`Exit message for ${this.terminalId} did not include an exit code.`);
+            }
+            return { exitCode, signal: message.signal, type: "exit" };
+        }
+        if (message.type === "error") {
+            return { message: message.message ?? `WebSocket error for ${this.terminalId}.`, type: "error" };
+        }
+        if (message.type === "input-rejected") {
+            return { message: message.message ?? `Input rejected for ${this.terminalId}.`, type: "input-rejected" };
+        }
+        throw new Error(`Unsupported message type: ${String(message.type)}`);
+    }
+    requireOpenSocket() {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            throw new Error(`Terminal socket for ${this.terminalId} is not open.`);
+        }
+        return socket;
+    }
+    url() {
+        const url = new URL(`${this.urls.wsBase(this.baseUrl)}/ws`);
+        url.searchParams.set("terminalId", this.terminalId);
+        url.searchParams.set("cols", String(this.cols));
+        url.searchParams.set("rows", String(this.rows));
+        const token = this.authToken?.();
+        if (token) {
+            url.searchParams.set("token", token);
+        }
+        for (const [name, value] of Object.entries(this.urls.wsAuthQuery())) {
+            url.searchParams.set(name, value);
+        }
+        return url.href;
+    }
+}
+export function webSocketBaseUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    return url.origin;
+}

package/dist/types.d.ts

@@ -0,0 +1,155 @@
+import type { LifecycleSnapshot, PaneLifecycle } from "./session-lifecycle.js";
+export type Bounds = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+export type TerminalArea = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export type TerminalSize = {
+    columns: number;
+    rows: number;
+};
+export type ChromeRect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export type WindowChrome = {
+    id: number;
+    title: string;
+    titlebar: ChromeRect;
+    closeButton: ChromeRect;
+    minimizeButton: ChromeRect;
+    fullscreenButton: ChromeRect;
+    terminalViewport: ChromeRect;
+    textArea: TerminalArea;
+    scrollbar: ChromeRect;
+};
+export type ProviderWindow = {
+    id: number;
+    name: string;
+    displayId?: string;
+    folder?: {
+        filesystemId?: string;
+        path: string;
+    };
+    file?: {
+        filesystemId?: string;
+        path: string;
+        terminalId: string;
+    };
+    iframe?: {
+        resolvedSrc?: string;
+        src: string;
+    };
+    filesystemId?: string;
+    provider?: string;
+    terminalId?: string;
+    terminalBackend?: "tmux" | "iterm";
+    managed?: boolean;
+    windowKind?: "terminal" | "folder" | "file" | "iframe";
+    bounds: Bounds;
+    chrome: WindowChrome;
+    terminalArea: TerminalArea;
+    terminalSize: TerminalSize;
+    contents?: string;
+    effect?: TerminalEffect;
+    lifecycle?: PaneLifecycle;
+    launchError?: WindowLaunchFailure;
+};
+export type WindowLaunchFailure = {
+    agent?: string;
+    agentSessionId?: string;
+    code: string;
+    failedAt: string;
+    message: string;
+    stage: string;
+};
+export type TerminalEffectKind = "dim" | "flash" | "highlight";
+export type TerminalEffect = {
+    expiresAt: number;
+    kind: TerminalEffectKind;
+};
+export type ProviderDisplay = {
+    id: string;
+    name: string;
+    bounds: Bounds;
+    windows: ProviderWindow[];
+};
+export type ProviderFilesystem = {
+    id: string;
+    kind: "container" | "host" | "volume";
+    name: string;
+    root?: string;
+};
+export type ProviderObservationStatus = {
+    status: "ok";
+    observedAt: string;
+    consecutiveFailures?: 0;
+    lastFailure?: {
+        error: string;
+        failedAt: string;
+    };
+} | {
+    status: "failed";
+    error: string;
+    failedAt: string;
+    consecutiveFailures: number;
+    lastSuccessObservedAt?: string;
+};
+export type ProviderSnapshot = {
+    build?: ProviderBuildInfo;
+    epoch: string;
+    instanceId?: string;
+    provider: ProviderKind;
+    terminalThemeProfile?: TerminalThemeProfile;
+    revision: number;
+    observedAt: string;
+    observation?: ProviderObservationStatus;
+    displayBounds: Bounds;
+    displays?: ProviderDisplay[];
+    filesystems?: ProviderFilesystem[];
+    lifecycle: LifecycleSnapshot;
+    spaces?: ProviderDisplay[];
+    windows: ProviderWindow[];
+};
+export declare const terminalThemeProfiles: readonly ["termfleet-dark", "github-dark", "solarized-dark", "dracula", "nord", "light"];
+export type TerminalThemeProfile = (typeof terminalThemeProfiles)[number];
+export declare function isTerminalThemeProfile(value: unknown): value is TerminalThemeProfile;
+export declare function parseTerminalThemeProfile(value: unknown): TerminalThemeProfile | undefined;
+export type ProviderHealth = {
+    build?: ProviderBuildInfo;
+    instanceId?: string;
+    ok: true;
+    provider: string;
+};
+export type ProviderBuildInfo = {
+    buildSha?: string;
+    version: string;
+};
+export type OrphanSessionPruneResult = {
+    discovered: string[];
+    errors: {
+        message: string;
+        session: string;
+    }[];
+    kept: string[];
+    pruned: string[];
+    tracked: string[];
+};
+export type ProviderKind = "iterm" | "virtual-tmux" | "wezterm";
+export type ProviderRef = {
+    baseUrl: string;
+    id: string;
+    label: string;
+};
+export declare function addBoundsSize(bounds: Omit<Bounds, "width" | "height">): Bounds;

package/dist/types.js

@@ -0,0 +1,21 @@
+// The one source of truth for terminal color-scheme profiles: the runtime list
+// (in display order), the type derived from it, and the parsers every layer shares.
+// Kept here so the CLI, console, provider, persisted-layout reader, and the frontend
+// appearance picker can't drift out of sync.
+export const terminalThemeProfiles = ["termfleet-dark", "github-dark", "solarized-dark", "dracula", "nord", "light"];
+export function isTerminalThemeProfile(value) {
+    return typeof value === "string" && terminalThemeProfiles.includes(value);
+}
+// Lenient parse: returns the profile or undefined (for reading persisted/optional data
+// where an unknown value should drop, not throw). Callers that must reject an explicit
+// bad value throw at the call site after this returns undefined.
+export function parseTerminalThemeProfile(value) {
+    return isTerminalThemeProfile(value) ? value : undefined;
+}
+export function addBoundsSize(bounds) {
+    return {
+        ...bounds,
+        height: bounds.bottom - bounds.top,
+        width: bounds.right - bounds.left
+    };
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@termfleet/core",
+  "version": "0.1.0",
+  "description": "Termfleet core: contracts, the provider SDK, and the agent-transcript/session library (Claude Code / Codex / Gemini). The reusable layer, usable beyond the console.",
+  "license": "Apache-2.0",
+  "author": "Volter AI",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3",
+    "yjs": "^13.6.31"
+  }
+}