@nimbus-sh/sdk 0.1.4 → 0.2.0

package/README.md

@@ -72,6 +72,15 @@ export default createNimbusHandler({
 });
 ```
 
+The bundled session UI includes an Agent surface in the editor workspace.
+Configure it with Worker vars
+`NIMBUS_CF_OAUTH_CLIENT_ID`, `NIMBUS_CF_OAUTH_SCOPES`,
+`NIMBUS_AGENT_MODEL`, `NIMBUS_AGENT_GATEWAY_ID`, and the secrets
+`NIMBUS_AGENT_COOKIE_SECRET` or `NIMBUS_CLOUDFLARE_API_TOKEN` when you want
+Cloudflare OAuth or owner-token Workers AI access. User OAuth uses
+Authorization Code + PKCE and encrypted browser cookies; Nimbus does not store
+user OAuth tokens in Durable Object storage.
+
 ## Programmatic sandbox quickstart
 
 The same sandbox handle API works in two modes:
@@ -152,6 +161,32 @@ Worker verifies the JWT, enforces `sid` pins and `sandbox:use` scope, applies
 the configured runtime policy, and delegates to the same `NimbusSession` RPC
 methods used by `Nimbus.fromEnv()`.
 
+Sandbox destruction is a separate lifecycle operation. Tokens that call
+`box.destroy()` must include `session:destroy` or `session:admin` in addition
+to the normal sandbox scope.
+
+## Flue connector
+
+Use `@nimbus-sh/sdk/flue` when an agent runtime expects Flue's sandbox
+provider contract:
+
+```ts
+import { Nimbus } from '@nimbus-sh/sdk/sandbox';
+import { nimbusFlue } from '@nimbus-sh/sdk/flue';
+
+const box = Nimbus.fromEnv(env, nimbusConfig).sandbox('job-123');
+await box.ready();
+
+const factory = nimbusFlue(box);
+const sessionEnv = await factory.createSessionEnv({
+  id: 'job-123',
+  cwd: '/home/user',
+});
+
+await sessionEnv.writeFile('/home/user/main.py', 'print(2 + 2)\n');
+const result = await sessionEnv.exec('python /home/user/main.py');
+```
+
 ## Sandbox handle API
 
 ```ts
@@ -168,13 +203,20 @@ const box = nimbus.sandbox('session-or-job-id', {
 
 await box.ready();
 await box.exec('node -e "console.log(2 + 2)"');
-await box.startProcess('node --watch /home/user/app/server.js');
+const proc = await box.startProcess('node --watch /home/user/app/server.js');
+// returns immediately with proc.pid; poll box.processes.logs(proc.pid) for
+// output and the exit record, or box.processes.kill(proc.pid) to stop it
 await box.runCode('print(2 + 2)', { language: 'python', install: 'ifMissing' });
 
 await box.files.write('/home/user/app/a.txt', 'hello');
 await box.files.read('/home/user/app/a.txt');
 await box.files.list('/home/user/app');
-await box.files.delete('/home/user/app/a.txt');
+await box.files.stat('/home/user/app/a.txt');
+await box.files.lstat('/home/user/app/link');
+await box.files.rename('/home/user/app/a.txt', '/home/user/app/b.txt');
+await box.files.chmod('/home/user/app/b.txt', 0o755);
+await box.files.readRange('/home/user/app/b.txt', 0, 64);
+await box.files.delete('/home/user/app/b.txt');
 
 await box.runtimes.available();
 await box.runtimes.installed();
@@ -208,7 +250,7 @@ object with `tools.exec.execute`, `runCode`, `readFile`, `writeFile`,
 `provider.capabilities` is intentionally honest: Nimbus claims shell,
 JavaScript/TypeScript, npm, git, owned filesystem, outbound fetch, inbound
 HTTP-like port routing, process spawn/long-running processes, Python/Ruby
-when allowed, and clang as WASI-native. It does not claim Docker, apt, GPU,
+when allowed, and clang-backed WASI/WebAssembly execution. It does not claim Docker, apt, GPU,
 custom Linux images, native Linux ELF execution, or raw TCP listeners.
 
 ## Quickstart — mint a session token

package/dist/flue.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @nimbus-sh/sdk/flue - Flue sandbox connector for Nimbus sandboxes.
+ *
+ * Flue owns the agent harness. Nimbus owns the sandbox. This adapter maps a
+ * `NimbusSandbox` handle to Flue's `SandboxFactory`/`SandboxApi` contract
+ * without making `@flue/runtime` a hard dependency of the core SDK.
+ */
+import type { NimbusSandbox } from './sandbox.js';
+export interface NimbusFlueFileStat {
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    size: number;
+    mtime: Date;
+}
+export interface NimbusFlueSessionEnv {
+    exec(command: string, options?: NimbusFlueExecOptions): Promise<NimbusFlueShellResult>;
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    stat(path: string): Promise<NimbusFlueFileStat>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    cwd: string;
+    resolvePath(path: string): string;
+}
+export interface NimbusFlueShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface NimbusFlueExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+export interface NimbusFlueSandboxApi {
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    stat(path: string): Promise<NimbusFlueFileStat>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    exec(command: string, options?: NimbusFlueExecOptions): Promise<NimbusFlueShellResult>;
+}
+export interface NimbusFlueRuntime<SessionEnv = NimbusFlueSessionEnv> {
+    createSandboxSessionEnv(api: NimbusFlueSandboxApi, cwd: string): SessionEnv;
+}
+export interface NimbusFlueFactory<SessionEnv = NimbusFlueSessionEnv> {
+    createSessionEnv(options: {
+        id: string;
+        cwd?: string;
+    }): Promise<SessionEnv>;
+}
+export interface NimbusFlueOptions<SessionEnv = NimbusFlueSessionEnv> {
+    cwd?: string;
+    runtime?: NimbusFlueRuntime<SessionEnv>;
+}
+export declare function nimbusFlue<SessionEnv = NimbusFlueSessionEnv>(sandbox: NimbusSandbox, options?: NimbusFlueOptions<SessionEnv>): NimbusFlueFactory<SessionEnv>;
+export declare class NimbusFlueApi implements NimbusFlueSandboxApi {
+    private readonly sandbox;
+    constructor(sandbox: NimbusSandbox);
+    readFile(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    stat(path: string): Promise<NimbusFlueFileStat>;
+    readdir(path: string): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+    mkdir(path: string, _options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    exec(command: string, options?: NimbusFlueExecOptions): Promise<NimbusFlueShellResult>;
+}
+//# sourceMappingURL=flue.d.ts.map

package/dist/flue.d.ts.map

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

package/dist/flue.js

@@ -0,0 +1,112 @@
+/**
+ * @nimbus-sh/sdk/flue - Flue sandbox connector for Nimbus sandboxes.
+ *
+ * Flue owns the agent harness. Nimbus owns the sandbox. This adapter maps a
+ * `NimbusSandbox` handle to Flue's `SandboxFactory`/`SandboxApi` contract
+ * without making `@flue/runtime` a hard dependency of the core SDK.
+ */
+export function nimbusFlue(sandbox, options = {}) {
+    return {
+        async createSessionEnv({ cwd }) {
+            const runtime = options.runtime ?? await loadFlueRuntime();
+            return runtime.createSandboxSessionEnv(new NimbusFlueApi(sandbox), cwd ?? options.cwd ?? '/home/user');
+        },
+    };
+}
+export class NimbusFlueApi {
+    sandbox;
+    constructor(sandbox) {
+        this.sandbox = sandbox;
+    }
+    async readFile(path) {
+        const content = await this.sandbox.files.read(path);
+        if (content == null)
+            throw enoent(path);
+        return content;
+    }
+    async readFileBuffer(path) {
+        const content = await this.sandbox.files.readBytes(path);
+        if (content == null)
+            throw enoent(path);
+        return content;
+    }
+    async writeFile(path, content) {
+        await this.sandbox.files.write(path, content);
+    }
+    async stat(path) {
+        const stat = await this.sandbox.files.stat(path);
+        if (!stat)
+            throw enoent(path);
+        return toFlueStat(stat);
+    }
+    async readdir(path) {
+        const entries = await this.sandbox.files.list(path);
+        return entries.map((entry) => entry.name);
+    }
+    async exists(path) {
+        return this.sandbox.files.exists(path);
+    }
+    async mkdir(path, _options = {}) {
+        await this.sandbox.files.mkdir(path);
+    }
+    async rm(path, options = {}) {
+        if (options.force && !(await this.sandbox.files.exists(path)))
+            return;
+        await this.sandbox.files.delete(path, { recursive: options.recursive });
+    }
+    async exec(command, options = {}) {
+        const result = await this.sandbox.exec(command, {
+            cwd: options.cwd,
+            env: options.env,
+            timeoutMs: secondsToMilliseconds(options.timeout),
+        });
+        if (options.signal?.aborted)
+            throw abortError(options.signal);
+        return toShellResult(result);
+    }
+}
+async function loadFlueRuntime() {
+    try {
+        const specifier = '@flue/runtime';
+        const runtime = await import(specifier);
+        if (typeof runtime.createSandboxSessionEnv === 'function') {
+            return runtime;
+        }
+    }
+    catch {
+        // Error below gives callers the exact integration action.
+    }
+    throw new Error('nimbusFlue requires @flue/runtime. Install Flue or pass { runtime: { createSandboxSessionEnv } }.');
+}
+function toFlueStat(stat) {
+    const type = String(stat.type);
+    return {
+        isFile: type === 'file',
+        isDirectory: type === 'directory',
+        isSymbolicLink: false,
+        size: Number(stat.size) || 0,
+        mtime: new Date(Number(stat.mtime) || Date.now()),
+    };
+}
+function toShellResult(result) {
+    return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+    };
+}
+function secondsToMilliseconds(timeout) {
+    if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0)
+        return undefined;
+    return Math.max(1, Math.round(timeout * 1000));
+}
+function enoent(path) {
+    const error = new Error(`ENOENT: no such file or directory, '${path}'`);
+    error.code = 'ENOENT';
+    return error;
+}
+function abortError(signal) {
+    return signal.reason instanceof Error
+        ? signal.reason
+        : new DOMException('The operation was aborted', 'AbortError');
+}

package/dist/index.d.ts

@@ -26,4 +26,5 @@ export * from './token.js';
 export * from './errors.js';
 export * from './session.js';
 export * from './sandbox.js';
+export * from './flue.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -26,3 +26,4 @@ export * from './token.js';
 export * from './errors.js';
 export * from './session.js';
 export * from './sandbox.js';
+export * from './flue.js';

package/dist/sandbox.d.ts

@@ -22,6 +22,14 @@ export interface NimbusSandboxProfile {
 }
 export interface NimbusConfig {
     endpoint?: string;
+    /**
+     * The deployment's `NIMBUS_PREVIEW_HOST_SUFFIX`, enabling the
+     * `<port>--<sid>.<suffix>` preview origin. `Nimbus.fromEnv` reads it off
+     * the bindings, so in-Worker callers never restate it; remote clients
+     * (`Nimbus.connect`) have no bindings and must supply it to get host-form
+     * preview URLs.
+     */
+    previewHostSuffix?: string;
     sandboxes?: Record<string, NimbusSandboxProfile>;
 }
 export interface NimbusFromEnvOptions {
@@ -64,10 +72,31 @@ export interface NimbusExecResult {
     duration: number;
     timestamp: number;
 }
-export interface NimbusStartResult extends NimbusExecResult {
-    pid: number | null;
-    process: NimbusProcess | null;
+export interface NimbusTerminalSize {
+    columns: number;
+    rows: number;
+}
+export interface NimbusDestroyOptions {
+    reason?: string;
+}
+export interface NimbusDestroyResult {
+    ok: true;
+    killed: number;
+    destroyedAt: number;
+    reason: string | null;
+}
+/**
+ * A started background process. It is still running when `startProcess`
+ * returns, so there is no exit code or captured output here — poll
+ * `processes.logs(pid)` (which carries the exit record once it lands),
+ * `processes.list()`, or `processes.attach(pid)`.
+ */
+export interface NimbusStartResult {
+    command: string;
+    pid: number;
+    process: NimbusProcess;
     ports: NimbusPort[];
+    startedAt: number;
 }
 export interface NimbusProcess {
     pid: number;
@@ -79,22 +108,63 @@ export interface NimbusProcess {
     startTime: number;
     endTime: number | null;
     longRunning: boolean;
+    attachedTty: boolean;
+}
+export interface NimbusProcessLogChunk {
+    seq: number;
+    ts: number;
+    stream: 'stdout' | 'stderr';
+    data: string;
+    binary?: boolean;
+}
+export interface NimbusProcessExitInfo {
+    code: number;
+    at: number;
+    reason?: string;
+}
+export interface NimbusProcessLogsOptions {
+    cursor?: number;
+    lines?: number;
+    bytes?: number;
+}
+export interface NimbusProcessLogsResult {
+    pid: number;
+    chunks: NimbusProcessLogChunk[];
+    text: string;
+    cursor: number;
+    truncated: boolean;
+    exit: NimbusProcessExitInfo | null;
+}
+export interface NimbusProcessAttachOptions {
+    pollIntervalMs?: number;
+    lines?: number;
+    bytes?: number;
+    signal?: AbortSignal;
 }
 export interface NimbusPort {
     port: number;
     pid: number;
     registeredAt: number;
 }
+export interface NimbusFileStat {
+    type: 'file' | 'directory' | string;
+    size: number;
+    ctime?: number;
+    mtime: number;
+    mode: number;
+}
 export interface NimbusRuntimeSummary {
     name: string;
     version: string;
     root: string;
+    abi: string;
     bins: string[];
     sizeBytes: number;
     license: string;
 }
 export interface NimbusAvailableRuntime {
     name: string;
+    abi: string;
     defaultVersion: string;
     versions: Array<{
         version: string;
@@ -102,7 +172,82 @@ export interface NimbusAvailableRuntime {
         license: string;
     }>;
 }
-type NimbusSessionNamespace = DurableObjectNamespace<any>;
+interface NimbusSessionStub {
+    _rpcReady(options?: {
+        preinstall?: string[];
+    }): Promise<{
+        ok: true;
+        preinstalled: string[];
+    }>;
+    _rpcExec(command: string, options?: Record<string, unknown>): Promise<NimbusExecResult>;
+    _rpcStartProcess(command: string, options?: Record<string, unknown>): Promise<NimbusStartResult>;
+    _rpcRunCode(code: string, options?: Record<string, unknown>): Promise<NimbusExecResult>;
+    _rpcReadFile(path: string): Promise<string | null>;
+    _rpcReadFileBytes(path: string): Promise<Uint8Array | null>;
+    _rpcWriteFile(path: string, content: string | Uint8Array): Promise<void>;
+    _rpcStat(path: string): Promise<NimbusFileStat | null>;
+    _rpcLstat(path: string): Promise<NimbusFileStat | null>;
+    _rpcReaddir(path: string): Promise<{
+        name: string;
+        type: string;
+    }[]>;
+    _rpcRename(from: string, to: string): Promise<void>;
+    _rpcChmod(path: string, mode: number): Promise<void>;
+    _rpcFsReadRange(path: string, offset: number, length: number): Promise<Uint8Array | null>;
+    _rpcExists(path: string): Promise<boolean>;
+    _rpcMkdir(path: string): Promise<void>;
+    _rpcDeleteFile(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    _rpcInstallRuntime(spec: string, options?: {
+        force?: boolean;
+    }): Promise<unknown>;
+    _rpcEnsureRuntimes(specs: string[], options?: {
+        force?: boolean;
+    }): Promise<unknown>;
+    _rpcListRuntimes(): Promise<{
+        installed: NimbusRuntimeSummary[];
+        available: NimbusAvailableRuntime[];
+    }>;
+    _rpcListProcesses(): Promise<NimbusProcess[]>;
+    _rpcKillProcess(pid: number): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    _rpcWriteProcessInput(pid: number, data: string): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    _rpcEndProcessInput(pid: number): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    _rpcResizeProcess(pid: number, size: NimbusTerminalSize): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    _rpcSignalProcess(pid: number, signal: string): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    _rpcProcessLogs(pid: number, options?: NimbusProcessLogsOptions): Promise<NimbusProcessLogsResult>;
+    _rpcListPorts(): Promise<NimbusPort[]>;
+    _rpcExposePort(port: number): Promise<{
+        port: number;
+        listening: boolean;
+        pid: number | null;
+        registeredAt: number | null;
+    }>;
+    _rpcUnexposePort(port: number): Promise<{
+        port: number;
+        ok: boolean;
+    }>;
+    _rpcDestroy(options?: NimbusDestroyOptions): Promise<NimbusDestroyResult>;
+}
+interface NimbusSessionNamespace {
+    idFromName(name: string): DurableObjectId;
+    get(id: DurableObjectId): NimbusSessionStub;
+}
 type NimbusTarget = {
     kind: 'binding';
     namespace: NimbusSessionNamespace;
@@ -149,15 +294,27 @@ export declare class NimbusSandbox {
     private remoteRpc;
     ready(): Promise<void>;
     exec(command: string, options?: NimbusExecOptions): Promise<NimbusExecResult>;
+    /**
+     * Start a command in the background. Returns as soon as the process has a
+     * pid — it does not wait for the command to finish.
+     */
     startProcess(command: string, options?: NimbusExecOptions): Promise<NimbusStartResult>;
     runCode(code: string, options?: NimbusExecOptions & {
         language?: 'javascript' | 'typescript' | 'python' | 'ruby' | 'shell';
         install?: 'never' | 'ifMissing';
     }): Promise<NimbusExecResult>;
+    destroy(options?: NimbusDestroyOptions): Promise<NimbusDestroyResult>;
     files: {
         read: (path: string) => Promise<string | null>;
         readBytes: (path: string) => Promise<Uint8Array | null>;
         write: (path: string, content: string | Uint8Array) => Promise<void>;
+        stat: (path: string) => Promise<NimbusFileStat | null>;
+        /** stat without following a symlink leaf. */
+        lstat: (path: string) => Promise<NimbusFileStat | null>;
+        rename: (from: string, to: string) => Promise<void>;
+        chmod: (path: string, mode: number) => Promise<void>;
+        /** Read `length` bytes at `offset` without materializing the whole file. */
+        readRange: (path: string, offset: number, length: number) => Promise<Uint8Array | null>;
         list: (path?: string) => Promise<{
             name: string;
             type: string;
@@ -188,10 +345,24 @@ export declare class NimbusSandbox {
             ok: boolean;
             pid: number;
         }>;
-        logs: (pid: number, options?: {
-            lines?: number;
-            bytes?: number;
-        }) => Promise<unknown>;
+        write: (pid: number, data: string) => Promise<{
+            ok: boolean;
+            pid: number;
+        }>;
+        endInput: (pid: number) => Promise<{
+            ok: boolean;
+            pid: number;
+        }>;
+        resize: (pid: number, size: NimbusTerminalSize) => Promise<{
+            ok: boolean;
+            pid: number;
+        }>;
+        signal: (pid: number, signal: string) => Promise<{
+            ok: boolean;
+            pid: number;
+        }>;
+        logs: (pid: number, options?: NimbusProcessLogsOptions) => Promise<NimbusProcessLogsResult>;
+        attach: (pid: number, options?: NimbusProcessAttachOptions) => NimbusProcessAttachment;
     };
     ports: {
         list: () => Promise<NimbusPort[]>;
@@ -230,7 +401,7 @@ export declare class NimbusSandbox {
                 execute: (input: unknown) => Promise<string | null>;
             };
             writeFile: {
-                execute: (input: any) => Promise<void>;
+                execute: (input: unknown) => Promise<void>;
             };
             listFiles: {
                 execute: (input?: unknown) => Promise<{
@@ -245,7 +416,7 @@ export declare class NimbusSandbox {
                 }[]>;
             };
             deleteFile: {
-                execute: (input: any) => Promise<void>;
+                execute: (input: unknown) => Promise<void>;
             };
             exists: {
                 execute: (input: unknown) => Promise<boolean>;
@@ -261,12 +432,48 @@ export declare class NimbusSandbox {
                     pid: number;
                 }>;
             };
+            writeProcessInput: {
+                execute: (input: {
+                    pid: number;
+                    data: string;
+                }) => Promise<{
+                    ok: boolean;
+                    pid: number;
+                }>;
+            };
+            endProcessInput: {
+                execute: (input: number | {
+                    pid: number;
+                }) => Promise<{
+                    ok: boolean;
+                    pid: number;
+                }>;
+            };
+            resizeProcess: {
+                execute: (input: {
+                    pid: number;
+                    columns: number;
+                    rows: number;
+                }) => Promise<{
+                    ok: boolean;
+                    pid: number;
+                }>;
+            };
+            signalProcess: {
+                execute: (input: {
+                    pid: number;
+                    signal: string;
+                }) => Promise<{
+                    ok: boolean;
+                    pid: number;
+                }>;
+            };
             logs: {
                 execute: (input: number | {
                     pid: number;
                     lines?: number;
                     bytes?: number;
-                }) => Promise<unknown>;
+                }) => Promise<NimbusProcessLogsResult>;
             };
             exposePort: {
                 execute: (input: number | {
@@ -304,7 +511,47 @@ export declare class NimbusSandbox {
     capabilities(): string[];
     private execOptions;
     private assertRuntimeAllowed;
+    /**
+     * Browser-facing URL for an exposed port, or undefined when the deployment
+     * is not addressable (no `endpoint`, no configured preview base).
+     *
+     * The URL carries NO credential. On a deployment with auth enforced it is
+     * the destination, not the ticket: the session mints a single-use attach
+     * token for it at `GET /s/<id>/api/preview-url?port=<n>`, which is what the
+     * session shell opens and what an embedder should hand to a browser.
+     */
     private portUrl;
+    private rpc;
+}
+export declare class NimbusProcessAttachment implements AsyncIterable<NimbusProcessLogChunk> {
+    private readonly sandbox;
+    readonly pid: number;
+    private readonly options;
+    private cursor;
+    constructor(sandbox: NimbusSandbox, pid: number, options?: NimbusProcessAttachOptions);
+    write(data: string): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    endInput(): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    resize(size: NimbusTerminalSize): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    signal(signal: string): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    kill(): Promise<{
+        ok: boolean;
+        pid: number;
+    }>;
+    logs(options?: NimbusProcessLogsOptions): Promise<NimbusProcessLogsResult>;
+    stream(options?: NimbusProcessAttachOptions): AsyncIterable<NimbusProcessLogChunk>;
+    [Symbol.asyncIterator](): AsyncIterator<NimbusProcessLogChunk>;
 }
 export {};
 //# sourceMappingURL=sandbox.d.ts.map