@jait/gateway 0.1.0

package/dist/surfaces/contracts.d.ts

@@ -0,0 +1,34 @@
+export type SurfaceState = "idle" | "starting" | "running" | "stopping" | "stopped" | "error";
+export interface SurfaceStartInput {
+    sessionId: string;
+    workspaceRoot: string;
+}
+export interface SurfaceStopInput {
+    reason?: string;
+}
+export interface SurfaceSnapshot {
+    id: string;
+    type: string;
+    state: SurfaceState;
+    sessionId: string;
+    startedAt?: string;
+    metadata: Record<string, string | number | boolean | null>;
+}
+export interface Surface {
+    readonly id: string;
+    readonly type: string;
+    readonly state: SurfaceState;
+    readonly sessionId: string | null;
+    start(input: SurfaceStartInput): Promise<void>;
+    stop(input?: SurfaceStopInput): Promise<void>;
+    snapshot(): SurfaceSnapshot;
+    /** Event callback — fired when output arrives (terminal stdout, etc.) */
+    onOutput?: (data: string) => void;
+    /** Event callback — fired on state change */
+    onStateChange?: (state: SurfaceState) => void;
+}
+export interface SurfaceFactory {
+    type: string;
+    create(id: string): Surface;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/surfaces/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/surfaces/contracts.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9F,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,IAAI,eAAe,CAAC;IAE5B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B"}

package/dist/surfaces/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/surfaces/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/surfaces/contracts.ts"],"names":[],"mappings":""}

package/dist/surfaces/filesystem.d.ts

@@ -0,0 +1,76 @@
+/**
+ * File System Surface — Sprint 3.4
+ *
+ * file.read, file.write, file.patch with path boundary enforcement
+ * via PathGuard. Tracks operations for audit.
+ */
+import { type PathGuardOptions } from "../security/path-guard.js";
+import type { Surface, SurfaceStartInput, SurfaceStopInput, SurfaceSnapshot, SurfaceState } from "./contracts.js";
+export declare class FileSystemSurface implements Surface {
+    readonly id: string;
+    private guardOpts?;
+    readonly type: "filesystem";
+    private _state;
+    private _sessionId;
+    private _startedAt;
+    private guard;
+    private _opCount;
+    /**
+     * Backup map: absolute path → original file content.
+     * Stored before the first write/patch so that undo can restore the original.
+     * Only the *first* version is kept (subsequent edits don't overwrite the backup).
+     */
+    private _backups;
+    onOutput?: (data: string) => void;
+    onStateChange?: (state: SurfaceState) => void;
+    constructor(id: string, guardOpts?: Partial<PathGuardOptions> | undefined);
+    get state(): SurfaceState;
+    get sessionId(): string | null;
+    start(input: SurfaceStartInput): Promise<void>;
+    stop(_input?: SurfaceStopInput): Promise<void>;
+    snapshot(): SurfaceSnapshot;
+    read(filePath: string): Promise<string>;
+    write(filePath: string, content: string): Promise<void>;
+    patch(filePath: string, search: string, replace: string): Promise<{
+        matched: boolean;
+    }>;
+    exists(filePath: string): Promise<boolean>;
+    list(dirPath: string): Promise<string[]>;
+    statFile(filePath: string): Promise<{
+        size: number;
+        isDirectory: boolean;
+        modified: string;
+    }>;
+    /** Check if a path is within workspace boundary */
+    isPathAllowed(filePath: string): boolean;
+    /**
+     * Restore a file to its pre-modification state.
+     * Returns true if a backup existed and was restored, false otherwise.
+     */
+    restore(filePath: string): Promise<boolean>;
+    /** Check whether we have a backup for a given file path */
+    hasBackup(filePath: string): boolean;
+    /**
+     * Get the backup (original) content for a file.
+     * Returns the original string, null if the file was newly created, or undefined if no backup exists.
+     */
+    getBackup(filePath: string): string | null | undefined;
+    /** Clear the backup for a file (e.g. after user accepts changes). */
+    clearBackup(filePath: string): void;
+    /**
+     * Save a backup of the current file content for an external change.
+     * Used when CLI providers (e.g. Codex) modify files directly, bypassing
+     * the surface's own write/patch methods.
+     * Only saves the *first* backup — won't overwrite existing entries.
+     */
+    saveExternalBackup(filePath: string): Promise<void>;
+    private ensureRunning;
+    private _setState;
+}
+export declare class FileSystemSurfaceFactory {
+    private guardOpts?;
+    readonly type: "filesystem";
+    constructor(guardOpts?: Partial<PathGuardOptions> | undefined);
+    create(id: string): FileSystemSurface;
+}
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/surfaces/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/surfaces/filesystem.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,KAAK,EACV,OAAO,EACP,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACb,MAAM,gBAAgB,CAAC;AAExB,qBAAa,iBAAkB,YAAW,OAAO;aAoB7B,EAAE,EAAE,MAAM;IAC1B,OAAO,CAAC,SAAS,CAAC;IApBpB,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IAEtC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAK;IAErB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAoC;IAEpD,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;gBAG5B,EAAE,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,YAAA;IAG/C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAEK,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9C,IAAI,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,QAAQ,IAAI,eAAe;IAgBrB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASvC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBvD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAqBvF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW1C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAWnG,mDAAmD;IACnD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIxC;;;OAGG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBjD,2DAA2D;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAUpC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS;IAWtD,qEAAqE;IACrE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQnC;;;;;OAKG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAazD,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,SAAS;CAIlB;AAED,qBAAa,wBAAwB;IAEvB,OAAO,CAAC,SAAS,CAAC;IAD9B,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;gBAClB,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,YAAA;IAEzD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB;CAGtC"}

package/dist/surfaces/filesystem.js

@@ -0,0 +1,245 @@
+/**
+ * File System Surface — Sprint 3.4
+ *
+ * file.read, file.write, file.patch with path boundary enforcement
+ * via PathGuard. Tracks operations for audit.
+ */
+import { readFile, writeFile, mkdir, stat, readdir } from "node:fs/promises";
+import { dirname, relative } from "node:path";
+import { PathGuard } from "../security/path-guard.js";
+export class FileSystemSurface {
+    id;
+    guardOpts;
+    type = "filesystem";
+    _state = "idle";
+    _sessionId = null;
+    _startedAt = null;
+    guard = null;
+    _opCount = 0;
+    /**
+     * Backup map: absolute path → original file content.
+     * Stored before the first write/patch so that undo can restore the original.
+     * Only the *first* version is kept (subsequent edits don't overwrite the backup).
+     */
+    _backups = new Map();
+    onOutput;
+    onStateChange;
+    constructor(id, guardOpts) {
+        this.id = id;
+        this.guardOpts = guardOpts;
+    }
+    get state() {
+        return this._state;
+    }
+    get sessionId() {
+        return this._sessionId;
+    }
+    async start(input) {
+        this._sessionId = input.sessionId;
+        this._startedAt = new Date().toISOString();
+        this.guard = new PathGuard({
+            workspaceRoot: input.workspaceRoot,
+            ...this.guardOpts,
+        });
+        this._setState("running");
+    }
+    async stop(_input) {
+        this._setState("stopped");
+        this.guard = null;
+    }
+    snapshot() {
+        return {
+            id: this.id,
+            type: this.type,
+            state: this._state,
+            sessionId: this._sessionId ?? "",
+            startedAt: this._startedAt ?? undefined,
+            metadata: {
+                workspaceRoot: this.guard?.workspaceRoot ?? null,
+                operationCount: this._opCount,
+            },
+        };
+    }
+    // ── File Operations ────────────────────────────────────────────
+    async read(filePath) {
+        this.ensureRunning();
+        const abs = await this.guard.validateWithSymlinkCheck(filePath);
+        this._opCount++;
+        const content = await readFile(abs, "utf-8");
+        this.onOutput?.(`read ${relative(this.guard.workspaceRoot, abs)} (${content.length} bytes)`);
+        return content;
+    }
+    async write(filePath, content) {
+        this.ensureRunning();
+        const abs = await this.guard.validateWithSymlinkCheck(filePath);
+        this._opCount++;
+        // Save backup of original content (only on first modification)
+        if (!this._backups.has(abs)) {
+            try {
+                const original = await readFile(abs, "utf-8");
+                this._backups.set(abs, original);
+            }
+            catch {
+                // File didn't exist before — backup is null (undo = delete)
+                this._backups.set(abs, null);
+            }
+        }
+        // Ensure parent directory exists
+        await mkdir(dirname(abs), { recursive: true });
+        await writeFile(abs, content, "utf-8");
+        this.onOutput?.(`wrote ${relative(this.guard.workspaceRoot, abs)} (${content.length} bytes)`);
+    }
+    async patch(filePath, search, replace) {
+        this.ensureRunning();
+        const abs = await this.guard.validateWithSymlinkCheck(filePath);
+        this._opCount++;
+        const original = await readFile(abs, "utf-8");
+        if (!original.includes(search)) {
+            return { matched: false };
+        }
+        // Save backup of original content (only on first modification)
+        if (!this._backups.has(abs)) {
+            this._backups.set(abs, original);
+        }
+        const patched = original.replace(search, replace);
+        await writeFile(abs, patched, "utf-8");
+        this.onOutput?.(`patched ${relative(this.guard.workspaceRoot, abs)}`);
+        return { matched: true };
+    }
+    async exists(filePath) {
+        this.ensureRunning();
+        const abs = this.guard.validate(filePath);
+        try {
+            await stat(abs);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async list(dirPath) {
+        this.ensureRunning();
+        const abs = this.guard.validate(dirPath);
+        this._opCount++;
+        const entries = await readdir(abs, { withFileTypes: true });
+        return entries.map((e) => (e.isDirectory() ? e.name + "/" : e.name));
+    }
+    async statFile(filePath) {
+        this.ensureRunning();
+        const abs = this.guard.validate(filePath);
+        const s = await stat(abs);
+        return {
+            size: s.size,
+            isDirectory: s.isDirectory(),
+            modified: s.mtime.toISOString(),
+        };
+    }
+    /** Check if a path is within workspace boundary */
+    isPathAllowed(filePath) {
+        return this.guard?.isAllowed(filePath) ?? false;
+    }
+    /**
+     * Restore a file to its pre-modification state.
+     * Returns true if a backup existed and was restored, false otherwise.
+     */
+    async restore(filePath) {
+        this.ensureRunning();
+        const abs = await this.guard.validateWithSymlinkCheck(filePath);
+        if (!this._backups.has(abs))
+            return false;
+        const backup = this._backups.get(abs);
+        if (backup === null) {
+            // File was newly created — remove it
+            const { unlink } = await import("node:fs/promises");
+            try {
+                await unlink(abs);
+            }
+            catch { /* already gone */ }
+        }
+        else {
+            await writeFile(abs, backup, "utf-8");
+        }
+        this._backups.delete(abs);
+        this.onOutput?.(`restored ${relative(this.guard.workspaceRoot, abs)}`);
+        return true;
+    }
+    /** Check whether we have a backup for a given file path */
+    hasBackup(filePath) {
+        if (!this.guard)
+            return false;
+        try {
+            const abs = this.guard.validate(filePath);
+            return this._backups.has(abs);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the backup (original) content for a file.
+     * Returns the original string, null if the file was newly created, or undefined if no backup exists.
+     */
+    getBackup(filePath) {
+        if (!this.guard)
+            return undefined;
+        try {
+            const abs = this.guard.validate(filePath);
+            if (!this._backups.has(abs))
+                return undefined;
+            return this._backups.get(abs) ?? null;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Clear the backup for a file (e.g. after user accepts changes). */
+    clearBackup(filePath) {
+        if (!this.guard)
+            return;
+        try {
+            const abs = this.guard.validate(filePath);
+            this._backups.delete(abs);
+        }
+        catch { /* ignore */ }
+    }
+    /**
+     * Save a backup of the current file content for an external change.
+     * Used when CLI providers (e.g. Codex) modify files directly, bypassing
+     * the surface's own write/patch methods.
+     * Only saves the *first* backup — won't overwrite existing entries.
+     */
+    async saveExternalBackup(filePath) {
+        this.ensureRunning();
+        const abs = await this.guard.validateWithSymlinkCheck(filePath);
+        if (this._backups.has(abs))
+            return;
+        try {
+            const original = await readFile(abs, "utf-8");
+            this._backups.set(abs, original);
+        }
+        catch {
+            // File doesn't exist yet — backup is null (undo = delete the new file)
+            this._backups.set(abs, null);
+        }
+    }
+    ensureRunning() {
+        if (this._state !== "running" || !this.guard) {
+            throw new Error("FileSystem surface is not running");
+        }
+    }
+    _setState(s) {
+        this._state = s;
+        this.onStateChange?.(s);
+    }
+}
+export class FileSystemSurfaceFactory {
+    guardOpts;
+    type = "filesystem";
+    constructor(guardOpts) {
+        this.guardOpts = guardOpts;
+    }
+    create(id) {
+        return new FileSystemSurface(id, this.guardOpts);
+    }
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/surfaces/filesystem.js.map

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

package/dist/surfaces/index.d.ts

@@ -0,0 +1,6 @@
+export type { Surface, SurfaceFactory, SurfaceSnapshot, SurfaceStartInput, SurfaceStopInput, SurfaceState, } from "./contracts.js";
+export { SurfaceRegistry } from "./registry.js";
+export { TerminalSurface, TerminalSurfaceFactory } from "./terminal.js";
+export { FileSystemSurface, FileSystemSurfaceFactory } from "./filesystem.js";
+export { BrowserSurface, BrowserSurfaceFactory, type BrowserDriver, type BrowserPageSnapshot, type BrowserInteractiveElement, } from "./browser.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/surfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/surfaces/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,OAAO,EACP,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,cAAc,CAAC"}

package/dist/surfaces/index.js

@@ -0,0 +1,5 @@
+export { SurfaceRegistry } from "./registry.js";
+export { TerminalSurface, TerminalSurfaceFactory } from "./terminal.js";
+export { FileSystemSurface, FileSystemSurfaceFactory } from "./filesystem.js";
+export { BrowserSurface, BrowserSurfaceFactory, } from "./browser.js";
+//# sourceMappingURL=index.js.map

package/dist/surfaces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/surfaces/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,EACL,cAAc,EACd,qBAAqB,GAItB,MAAM,cAAc,CAAC"}

package/dist/surfaces/registry.d.ts

@@ -0,0 +1,24 @@
+import type { Surface, SurfaceFactory, SurfaceSnapshot, SurfaceStartInput } from "./contracts.js";
+export declare class SurfaceRegistry {
+    private readonly factories;
+    private readonly surfaces;
+    /** Called after every surface is started (regardless of creation path) */
+    onSurfaceStarted?: (id: string, surface: Surface) => void;
+    /** Called just before a surface is removed after stopping */
+    onSurfaceStopped?: (id: string, surface: Surface) => void;
+    register(factory: SurfaceFactory): void;
+    /** Create + start a surface in one call */
+    startSurface(type: string, id: string, input: SurfaceStartInput): Promise<Surface>;
+    /** Stop + remove a surface */
+    stopSurface(id: string, reason?: string): Promise<boolean>;
+    getSurface(id: string): Surface | undefined;
+    listSurfaces(): Surface[];
+    listSnapshots(): SurfaceSnapshot[];
+    /** Get surfaces belonging to a specific session */
+    getBySession(sessionId: string): Surface[];
+    unregister(id: string): boolean;
+    /** Stop all surfaces (used during shutdown) */
+    stopAll(reason?: string): Promise<void>;
+    get registeredTypes(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/surfaces/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/surfaces/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAElG,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1D,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAE1D,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAIvC,2CAA2C;IACrC,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,OAAO,CAAC;IAanB,8BAA8B;IACxB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUhE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI3C,YAAY,IAAI,OAAO,EAAE;IAIzB,aAAa,IAAI,eAAe,EAAE;IAIlC,mDAAmD;IACnD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EAAE;IAI1C,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,+CAA+C;IACzC,OAAO,CAAC,MAAM,SAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,IAAI,eAAe,IAAI,MAAM,EAAE,CAE9B;CACF"}

package/dist/surfaces/registry.js

@@ -0,0 +1,59 @@
+export class SurfaceRegistry {
+    factories = new Map();
+    surfaces = new Map();
+    /** Called after every surface is started (regardless of creation path) */
+    onSurfaceStarted;
+    /** Called just before a surface is removed after stopping */
+    onSurfaceStopped;
+    register(factory) {
+        this.factories.set(factory.type, factory);
+    }
+    /** Create + start a surface in one call */
+    async startSurface(type, id, input) {
+        const factory = this.factories.get(type);
+        if (!factory) {
+            throw new Error(`Surface factory '${type}' is not registered`);
+        }
+        const instance = factory.create(id);
+        this.surfaces.set(id, instance);
+        await instance.start(input);
+        this.onSurfaceStarted?.(id, instance);
+        return instance;
+    }
+    /** Stop + remove a surface */
+    async stopSurface(id, reason) {
+        const surface = this.surfaces.get(id);
+        if (!surface)
+            return false;
+        const snap = surface.snapshot();
+        await surface.stop({ reason });
+        this.onSurfaceStopped?.(id, { ...surface, snapshot: () => snap });
+        this.surfaces.delete(id);
+        return true;
+    }
+    getSurface(id) {
+        return this.surfaces.get(id);
+    }
+    listSurfaces() {
+        return [...this.surfaces.values()];
+    }
+    listSnapshots() {
+        return this.listSurfaces().map((s) => s.snapshot());
+    }
+    /** Get surfaces belonging to a specific session */
+    getBySession(sessionId) {
+        return this.listSurfaces().filter((s) => s.sessionId === sessionId);
+    }
+    unregister(id) {
+        return this.surfaces.delete(id);
+    }
+    /** Stop all surfaces (used during shutdown) */
+    async stopAll(reason = "shutdown") {
+        const ids = [...this.surfaces.keys()];
+        await Promise.allSettled(ids.map((id) => this.stopSurface(id, reason)));
+    }
+    get registeredTypes() {
+        return [...this.factories.keys()];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/surfaces/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/surfaces/registry.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,eAAe;IACT,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEvD,0EAA0E;IAC1E,gBAAgB,CAA0C;IAC1D,6DAA6D;IAC7D,gBAAgB,CAA0C;IAE1D,QAAQ,CAAC,OAAuB;QAC9B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED,2CAA2C;IAC3C,KAAK,CAAC,YAAY,CAChB,IAAY,EACZ,EAAU,EACV,KAAwB;QAExB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,qBAAqB,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QAChC,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,CAAC,gBAAgB,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACtC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,8BAA8B;IAC9B,KAAK,CAAC,WAAW,CAAC,EAAU,EAAE,MAAe;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,EAAa,CAAC,CAAC;QAC7E,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,mDAAmD;IACnD,YAAY,CAAC,SAAiB;QAC5B,OAAO,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACtE,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,+CAA+C;IAC/C,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,UAAU;QAC/B,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACtC,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,eAAe;QACjB,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/surfaces/terminal.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Terminal Surface — uses bun-pty directly.
+ *
+ * Each TerminalSurface owns a persistent interactive PTY shell process
+ * (viewable in the frontend via xterm.js + WebSocket).
+ *
+ * Shell integration:
+ * On start, sources an integration script that hooks into the shell's
+ * prompt lifecycle and emits OSC 633 escape sequences (same protocol as
+ * VS Code's terminal shell integration).  This lets us detect command
+ * boundaries, exit codes, and CWD changes without wrapping commands.
+ */
+import type { Surface, SurfaceStartInput, SurfaceStopInput, SurfaceSnapshot, SurfaceState } from "./contracts.js";
+export interface TerminalSurfaceOptions {
+    shell?: string;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+}
+export interface TerminalExecutionResult {
+    output: string;
+    exitCode: number | null;
+    timedOut: boolean;
+}
+export declare class TerminalSurface implements Surface {
+    readonly id: string;
+    readonly type: "terminal";
+    private _state;
+    private _sessionId;
+    private _startedAt;
+    private _cwd;
+    private _pid;
+    private _pty;
+    private _outputBuffer;
+    private _cols;
+    private _rows;
+    private readonly shell;
+    private readonly extraEnv;
+    private _outputListeners;
+    /** Whether the OSC 633 shell integration has emitted its first prompt (B marker) */
+    private _shellIntegrationReady;
+    private _shellIntegrationReadyResolve?;
+    private _shellIntegrationReadyPromise;
+    /** External callbacks (wired by index.ts / routes) */
+    onOutput?: (data: string) => void;
+    onStateChange?: (state: SurfaceState) => void;
+    onExit?: (exitCode: number, signal?: number) => void;
+    constructor(id: string, opts?: TerminalSurfaceOptions);
+    get state(): SurfaceState;
+    get sessionId(): string | null;
+    get pid(): number | undefined;
+    /** True once the shell has emitted at least one OSC 633;B prompt-end marker */
+    get shellIntegrationReady(): boolean;
+    /** Resolves when the shell integration prompt is first ready (or after a timeout fallback) */
+    waitForPrompt(timeoutMs?: number): Promise<void>;
+    start(input: SurfaceStartInput): Promise<void>;
+    stop(_input?: SurfaceStopInput): Promise<void>;
+    /** Write raw data to the PTY (user keyboard input from frontend) */
+    write(data: string): void;
+    /** Resize the PTY */
+    resize(cols: number, rows: number): void;
+    /** Add an output listener (used by terminal.run to mirror output) */
+    addOutputListener(listener: (data: string) => void): void;
+    /** Remove an output listener */
+    removeOutputListener(listener: (data: string) => void): void;
+    snapshot(): SurfaceSnapshot;
+    getRecentOutput(lines?: number): string;
+    private _setState;
+}
+export declare class TerminalSurfaceFactory {
+    readonly type: "terminal";
+    private opts;
+    constructor(opts?: TerminalSurfaceOptions);
+    create(id: string): TerminalSurface;
+}
+//# sourceMappingURL=terminal.d.ts.map

package/dist/surfaces/terminal.d.ts.map

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