@declaw/sdk 1.1.9 → 1.1.11

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to the Declaw TypeScript / JavaScript SDK are documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.11]
+
+### Added
+
+- `sandbox.stdio.start(cmd)` — native interactive stdio for sandboxed
+  processes. Returns a `StdioProcess` handle with `sendStdin()`,
+  `closeStdin()`, `stream()`, `kill()`, and `wait()`. Supports
+  callbacks (`onStdout`, `onStderr`) and async iteration.
+- `sandbox.getHost(port)` — inbound HTTP port proxy URL for accessing
+  services running inside the sandbox.
+- `sandbox.getMcpUrl()` — convenience URL for MCP servers on port 50005.
+
 ## [1.1.8]
 
 ### Documentation

package/dist/index.cjs

@@ -59,6 +59,8 @@ __export(index_exports, {
   SandboxPaginator: () => SandboxPaginator,
   SandboxState: () => SandboxState,
   SnapshotPaginator: () => SnapshotPaginator,
+  Stdio: () => Stdio,
+  StdioProcess: () => StdioProcess,
   Template: () => Template,
   TemplateBase: () => TemplateBase,
   TemplateError: () => TemplateError,
@@ -1885,6 +1887,136 @@ var Pty = class {
   }
 };
 
+// src/sandbox/stdio/stdio.ts
+var import_stream2 = require("eventsource-parser/stream");
+var StdioProcess = class {
+  cmdId;
+  sandboxId;
+  client;
+  lastEntryId = 0;
+  _exitCode = null;
+  _bgStream = null;
+  constructor(cmdId, sandboxId, client, opts) {
+    this.cmdId = cmdId;
+    this.sandboxId = sandboxId;
+    this.client = client;
+    if (opts?.onStdout || opts?.onStderr) {
+      this._bgStream = this.stream({
+        onStdout: opts.onStdout,
+        onStderr: opts.onStderr
+      });
+    }
+  }
+  get exitCode() {
+    return this._exitCode;
+  }
+  async sendStdin(data, requestTimeout) {
+    const raw = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    let binary = "";
+    for (let i = 0; i < raw.length; i++) {
+      binary += String.fromCharCode(raw[i]);
+    }
+    const encoded = btoa(binary);
+    await this.client.post(
+      `/sandboxes/${this.sandboxId}/stdio/${this.cmdId}/stdin`,
+      {
+        json: { data: encoded },
+        timeout: requestTimeout
+      }
+    );
+  }
+  async closeStdin(requestTimeout) {
+    await this.client.post(
+      `/sandboxes/${this.sandboxId}/stdio/${this.cmdId}/stdin/close`,
+      { timeout: requestTimeout }
+    );
+  }
+  async kill(requestTimeout) {
+    const resp = await this.client.delete(
+      `/sandboxes/${this.sandboxId}/stdio/${this.cmdId}`,
+      { timeout: requestTimeout }
+    );
+    return Boolean(resp.killed);
+  }
+  async wait() {
+    if (this._bgStream) {
+      return this._bgStream;
+    }
+    return this.stream();
+  }
+  async stream(opts) {
+    if (this._bgStream && !opts) {
+      return this._bgStream;
+    }
+    let url = `/sandboxes/${this.sandboxId}/stdio/${this.cmdId}/stream`;
+    if (this.lastEntryId > 0) {
+      url += `?last_entry_id=${this.lastEntryId}`;
+    }
+    const response = await this.client.streamGet(url);
+    const stream = response.body;
+    if (!stream) {
+      throw new SandboxError("No response body for stdio stream");
+    }
+    const eventStream = stream.pipeThrough(new TextDecoderStream()).pipeThrough(new import_stream2.EventSourceParserStream());
+    for await (const event of eventStream) {
+      if (event.event === "exit") {
+        try {
+          const parsed = JSON.parse(event.data);
+          this._exitCode = parsed.exit_code ?? -1;
+        } catch {
+          this._exitCode = -1;
+        }
+        break;
+      }
+      if (event.event === "stdout" || event.event === "stderr") {
+        try {
+          const parsed = JSON.parse(event.data);
+          const entryId = parsed.entry_id ?? 0;
+          if (entryId > this.lastEntryId) {
+            this.lastEntryId = entryId;
+          }
+          const raw = atob(parsed.data ?? "");
+          const bytes = new Uint8Array(raw.length);
+          for (let i = 0; i < raw.length; i++) {
+            bytes[i] = raw.charCodeAt(i);
+          }
+          if (event.event === "stdout" && opts?.onStdout) {
+            opts.onStdout(bytes);
+          } else if (event.event === "stderr" && opts?.onStderr) {
+            opts.onStderr(bytes);
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+    return { exitCode: this._exitCode ?? -1 };
+  }
+};
+var Stdio = class {
+  sandboxId;
+  client;
+  constructor(sandboxId, client) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+  }
+  async start(cmd, opts) {
+    const user = opts?.user ?? "user";
+    const body = { cmd, user };
+    if (opts?.envs) body.envs = opts.envs;
+    if (opts?.cwd) body.cwd = opts.cwd;
+    const data = await this.client.post(
+      `/sandboxes/${this.sandboxId}/stdio`,
+      { json: body, timeout: opts?.requestTimeout }
+    );
+    const cmdId = data.cmd_id;
+    return new StdioProcess(cmdId, this.sandboxId, this.client, {
+      onStdout: opts?.onStdout,
+      onStderr: opts?.onStderr
+    });
+  }
+};
+
 // src/volumes/models.ts
 function parseVolumeInfo(data) {
   return {
@@ -1924,6 +2056,7 @@ var Sandbox = class _Sandbox {
   _commands;
   _files;
   _pty;
+  _stdio;
   constructor(sandboxId, config, client, envdAccessToken, sandboxDomain, trafficAccessToken) {
     this._sandboxId = sandboxId;
     this._config = config;
@@ -1934,6 +2067,7 @@ var Sandbox = class _Sandbox {
     this._commands = new Commands(sandboxId, client);
     this._files = new Filesystem(sandboxId, client);
     this._pty = new Pty(sandboxId, client);
+    this._stdio = new Stdio(sandboxId, client);
   }
   /** The unique sandbox identifier. */
   get sandboxId() {
@@ -1967,6 +2101,10 @@ var Sandbox = class _Sandbox {
   get pty() {
     return this._pty;
   }
+  /** Stdio sub-module for interactive subprocess sessions with stdin pipe. */
+  get stdio() {
+    return this._stdio;
+  }
   /**
    * Base URL for this sandbox's namespace on the Declaw API.
    *
@@ -1980,17 +2118,15 @@ var Sandbox = class _Sandbox {
   /**
    * Return the path-based URL that reverse-proxies to `port` inside the sandbox.
    *
-   * Note: the reverse-proxy backend is not yet deployed; calls to the returned
-   * URL will 404 until that feature ships. The URL shape is stable and safe to
-   * script against.
+   * Requires `allowPublicTraffic` to be enabled on the sandbox's network
+   * config (the default). The returned URL is authenticated via the same
+   * API key as all other sandbox operations.
    */
   getHost(port) {
     return `${this.envdApiUrl}/ports/${port}`;
   }
   /**
    * Return the URL for an MCP server listening on port 50005 inside the sandbox.
-   *
-   * Same deployment caveat as {@link getHost}.
    */
   getMcpUrl() {
     return `${this.getHost(MCP_PORT)}/mcp`;
@@ -2826,6 +2962,8 @@ var Volumes = class {
   SandboxPaginator,
   SandboxState,
   SnapshotPaginator,
+  Stdio,
+  StdioProcess,
   Template,
   TemplateBase,
   TemplateError,