@prismshadow/penguin-server 0.2.6 → 0.2.8

package/dist/extension/index.d.ts

@@ -0,0 +1,212 @@
+import { Resources } from '@prismshadow/penguin-core/kernel';
+export { Disposable, Extension, ExtensionContext, ExtensionEvents, PenguinContext, PenguinInterface, ToolFactory, WorkflowFactory, WorkflowInstance, WorkflowInstances } from '@prismshadow/penguin-core/extension';
+
+/**
+ * Screen snapshot -> ANSI restore stream, plus plain-text capture.
+ *
+ * This is what makes a browser refresh (or a reconnect from a second device) show the
+ * terminal exactly as it was: the daemon keeps an authoritative headless xterm per pty, and
+ * on attach it *re-renders* that grid as an escape-sequence stream the client's real xterm
+ * replays into an identical screen. That beats the two obvious alternatives:
+ *
+ * - Replaying the raw pty byte log: unbounded, and full-screen programs (vim, top) replay
+ *   as a flicker of stale frames.
+ * - Sending a JSON cell grid: a 200k-object payload per attach, parsed on the UI thread.
+ *
+ * Cursor alignment is the subtle part. The restore writes `scrollback + rows` lines, so the
+ * client's viewport ends up holding exactly the server's viewport, and only then is the
+ * cursor placed with a viewport-relative CUP. Trailing blank rows are therefore written on
+ * purpose — dropping them would shift every subsequent row and land the cursor in the wrong
+ * place.
+ */
+
+interface CaptureLinesOptions {
+    /** Line index into scrollback+viewport; negative counts from the end (-1 = last line). */
+    start?: number;
+    end?: number;
+}
+interface CaptureLinesResult {
+    lines: string[];
+    totalLines: number;
+}
+
+interface TerminalExitInfo {
+    exitCode: number;
+    signal: number | null;
+    lastOutputLines: string[];
+}
+interface CreateTerminalSessionOptions {
+    id?: string;
+    /** Absolute working directory (already resolved and validated by the manager). */
+    cwd: string;
+    /** Owning user id — a shell is the most privileged thing this server hands out. */
+    ownerUserId: string;
+    /**
+     * Stable per-user display number (tmux-style), assigned by the manager at creation. It
+     * travels with the terminal for its whole life — UI numbering must never depend on list
+     * position, which changes under user-reordered tabs.
+     */
+    seq?: number;
+    name?: string;
+    shell?: string;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+    /**
+     * Where a pushed bundle's node-pty assets live (the hmr capability's assetsDir);
+     * absent falls back to the packaged require (see pty-module.ts).
+     */
+    assets?: () => string | null;
+}
+interface TerminalSessionInfo {
+    id: string;
+    seq: number;
+    name: string;
+    cwd: string;
+    ownerUserId: string;
+    title: string | null;
+    cols: number;
+    rows: number;
+    pid: number;
+    createdAt: string;
+    alive: boolean;
+    exit: TerminalExitInfo | null;
+}
+type TerminalOutputListener = (data: string) => void;
+type TerminalExitListener = (info: TerminalExitInfo) => void;
+type TerminalTitleListener = (title: string | null) => void;
+declare class TerminalSession {
+    readonly id: string;
+    readonly seq: number;
+    readonly cwd: string;
+    readonly ownerUserId: string;
+    readonly createdAt: Date;
+    private name;
+    private readonly terminal;
+    private readonly ptyProcess;
+    private readonly inputMode;
+    private readonly outputListeners;
+    private readonly exitListeners;
+    private readonly titleListeners;
+    private title;
+    private pendingTitle;
+    private titleTimer;
+    private sizeState;
+    private exitInfo;
+    private disposed;
+    constructor(options: CreateTerminalSessionOptions);
+    /** DA1 / DSR / OSC colour queries — see OSC_COLOR_QUERY_RESPONSES. */
+    private registerCapabilityResponders;
+    get alive(): boolean;
+    get exit(): TerminalExitInfo | null;
+    info(): TerminalSessionInfo;
+    rename(name: string): void;
+    write(data: string): void;
+    /**
+     * Applies a size request under the claim/update ownership rule, resizing both the pty and
+     * the daemon's emulator so snapshots keep matching what the shell laid out.
+     */
+    resize(request: {
+        connectionId: string;
+        cols: number;
+        rows: number;
+        intent: "claim" | "update";
+    }): boolean;
+    releaseSize(connectionId: string): void;
+    get size(): {
+        cols: number;
+        rows: number;
+    };
+    /** The attach payload: the whole screen as an ANSI stream (see snapshot.ts). */
+    restoreStream(options?: {
+        scrollbackLines?: number;
+    }): string;
+    capture(options?: CaptureLinesOptions): CaptureLinesResult;
+    onOutput(listener: TerminalOutputListener): () => void;
+    onExit(listener: TerminalExitListener): () => void;
+    onTitleChange(listener: TerminalTitleListener): () => void;
+    kill(signal?: string): void;
+    dispose(): void;
+}
+
+interface CreateTerminalRequest {
+    cwd: string;
+    ownerUserId: string;
+    name?: string;
+    cols?: number;
+    rows?: number;
+    shell?: string;
+}
+declare class TerminalManager {
+    private readonly resources;
+    private readonly opts;
+    /**
+     * The kernel's resource registry, threaded to every session it creates: a native module
+     * reaches the platform through it (pty-module.ts), and live ptys are registered in it so
+     * a hot swap hands them to the next platform instead of killing them.
+     */
+    constructor(resources: Resources, opts?: {
+        graceMs?: number;
+        /** Where a pushed bundle's node-pty assets live (hmr.assetsDir); absent falls back to the packaged require. */
+        assets?: () => string | null;
+    });
+    private get graceMs();
+    private readonly sessions;
+    private readonly reapTimers;
+    /** Exit-listener unsubscribers, so quiesce() can detach this manager from delivered ptys. */
+    private readonly exitUnsubs;
+    /** Paired unregister per pty (register's return): the only way an entry leaves the registry. */
+    private readonly unregisters;
+    create(request: CreateTerminalRequest): Promise<TerminalSession>;
+    /**
+     * Takes a session into this manager AND into the runtime's resource registry. The
+     * registry is what makes a pty outlive a platform swap: it sits outside the reloadable
+     * tree, so the shell keeps running and the next instance claims it back (see
+     * hmr/resources.ts). The parked context carries only these ids.
+     */
+    private track;
+    /**
+     * Reclaims the sessions a previous instance parked. An id the registry no longer knows
+     * is simply dropped: its shell died with the process that owned it, and a manager
+     * holding a handle to nothing would only fail later, further from the cause.
+     */
+    adopt(ids: readonly string[]): void;
+    /**
+     * Park-side detach (hot swap only — never process exit): the ptys are DELIVERED to the
+     * next App through the registry, so this manager must stop acting on them. Exit
+     * listeners are unsubscribed (the successor adopts and re-listens), and every pending
+     * reap — each targeting an already-dead session that was therefore NOT parked for
+     * adoption — runs immediately instead of firing later from a dead generation, where it
+     * would release a registry id out from under whoever owns it next.
+     */
+    quiesce(): void;
+    /** Handle ids for the parked context document — live sessions only. */
+    handleIds(): string[];
+    /** Looks up a session, enforcing ownership. Unknown and not-yours are both 404 — no probing. */
+    require(id: string, userId: string): TerminalSession;
+    get(id: string): TerminalSession | undefined;
+    list(userId: string): TerminalSession[];
+    listInfo(userId: string): TerminalSessionInfo[];
+    kill(id: string, userId: string): void;
+    /** Drops the session once nothing can usefully be read from it any more. */
+    private scheduleReap;
+    /** Server shutdown: every pty is a child process and must not outlive us. */
+    disposeAll(): void;
+}
+
+/**
+ * The harness's extension surface — the `@prismshadow/penguin-server/extension` subpath.
+ *
+ * The contract itself lives in `@prismshadow/penguin-core/extension`; what this module adds
+ * is the harness's own members, contributed by AUGMENTING that contract rather than by
+ * redeclaring it. Core names nothing it cannot reach, this layer names what it owns, and
+ * an extension sees one `PenguinContext` either way.
+ *
+ * Re-exported here so an extension package has one import site for both halves.
+ */
+
+declare module "@prismshadow/penguin-core/extension" {
+    interface PenguinContext {
+        terminals: TerminalManager;
+    }
+}

package/dist/extension/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/extension/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}