@declaw/sdk 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.0.2]
+
+### Added
+
+- Real interactive PTY support. `sandbox.pty.create()` now returns a
+  `PtyHandle` with both an `onData` callback and an `async *stream()`
+  iterator that deliver raw terminal bytes as they arrive from the
+  sandbox (ANSI escapes included).
+- `PtyHandle.sendInput`, `PtyHandle.resize`, `PtyHandle.kill`,
+  `PtyHandle.disconnect`, `PtyHandle.wait()` for full lifecycle control.
+- `ApiClient.streamGet()` for SSE consumers.
+- `PtyHandle` exported from the package root.
+
+### Changed
+
+- `Pty.create()` accepts `onData` in `PtyCreateOpts` and returns the new
+  `PtyHandle` type. Existing fields are unchanged; callers that only
+  used the returned handle for `sendInput`/`resize`/`kill` continue to
+  work without edits.
+
 ## [1.0.0]
 
 First stable release. The public API described below is covered by

package/dist/index.cjs

@@ -42,6 +42,7 @@ __export(index_exports, {
   NotFoundError: () => NotFoundError,
   PIIType: () => PIIType,
   Pty: () => Pty,
+  PtyHandle: () => PtyHandle,
   RedactionAction: () => RedactionAction,
   Sandbox: () => Sandbox,
   SandboxError: () => SandboxError,
@@ -263,6 +264,13 @@ var ApiClient = class {
   async stream(path, opts) {
     return this.requestWithRetry("POST", path, opts, true);
   }
+  /**
+   * Send a GET request and return the raw Response for SSE streaming.
+   * Does NOT parse the response body. Used by PTY stream consumers.
+   */
+  async streamGet(path, opts) {
+    return this.requestWithRetry("GET", path, opts, true);
+  }
   /**
    * Abort all in-flight requests and release resources.
    */
@@ -542,18 +550,12 @@ function parseInjectionDefenseConfig(data) {
 // src/security/audit.ts
 function createAuditConfig(opts) {
   return {
-    enabled: opts?.enabled ?? false,
-    logRequestBody: opts?.logRequestBody ?? true,
-    logResponseBody: opts?.logResponseBody ?? false,
-    retentionHours: opts?.retentionHours ?? 24
+    enabled: opts?.enabled ?? true
   };
 }
 function parseAuditConfig(data) {
   return {
-    enabled: data.enabled ?? false,
-    logRequestBody: data.log_request_body ?? data.logRequestBody ?? true,
-    logResponseBody: data.log_response_body ?? data.logResponseBody ?? false,
-    retentionHours: data.retention_hours ?? data.retentionHours ?? 24
+    enabled: data.enabled ?? true
   };
 }
 function parseAuditEntry(data) {
@@ -850,7 +852,7 @@ function createSecurityPolicy(opts) {
     injectionDefense: opts?.injectionDefense ?? false,
     transformations: opts?.transformations ?? [],
     network: opts?.network,
-    audit: opts?.audit ?? false,
+    audit: opts?.audit ?? true,
     envSecurity: opts?.envSecurity ?? createEnvSecurityConfig(),
     toxicity: opts?.toxicity,
     codeSecurity: opts?.codeSecurity,
@@ -865,7 +867,7 @@ function parseSecurityPolicy(data) {
     injectionDefense: typeof injDef === "boolean" ? injDef : injDef ? parseInjectionDefenseConfig(injDef) : false,
     transformations: Array.isArray(data.transformations) ? data.transformations.map((t) => parseTransformationRule(t)) : [],
     network: data.network ? parseNetworkPolicy(data.network) : void 0,
-    audit: typeof auditData === "boolean" ? auditData : auditData ? parseAuditConfig(auditData) : false,
+    audit: typeof auditData === "boolean" ? auditData : auditData ? parseAuditConfig(auditData) : true,
     envSecurity: data.env_security ?? data.envSecurity ? parseEnvSecurityConfig(data.env_security ?? data.envSecurity) : createEnvSecurityConfig(),
     toxicity: data.toxicity ? parseToxicityConfig(data.toxicity) : void 0,
     codeSecurity: data.code_security ?? data.codeSecurity ? parseCodeSecurityConfig(data.code_security ?? data.codeSecurity) : void 0,
@@ -894,10 +896,7 @@ function securityPolicyToJSON(policy) {
   }
   const auditConfig = typeof policy.audit === "boolean" ? createAuditConfig({ enabled: policy.audit }) : policy.audit;
   const audit = {
-    enabled: auditConfig.enabled,
-    log_request_body: auditConfig.logRequestBody,
-    log_response_body: auditConfig.logResponseBody,
-    retention_hours: auditConfig.retentionHours
+    enabled: auditConfig.enabled
   };
   const envSec = {
     mask_patterns: policy.envSecurity.maskPatterns,
@@ -1364,6 +1363,11 @@ var Filesystem = class {
   /**
    * Write data to a file.
    *
+   * When `data` is a `Uint8Array`, the SDK streams the raw bytes to the
+   * binary-safe `PUT /files/raw` endpoint (500 MiB cap). When it's a string,
+   * the SDK uses the JSON `POST /files` endpoint. Callers do not need to
+   * pick the transport.
+   *
    * @param path - Absolute path to the file.
    * @param data - String or Uint8Array content to write.
    * @param opts - Optional user and request timeout.
@@ -1371,11 +1375,22 @@ var Filesystem = class {
    */
   async write(path, data, opts) {
     const user = opts?.user ?? DEFAULT_USER;
-    const strData = data instanceof Uint8Array ? new TextDecoder().decode(data) : data;
+    if (data instanceof Uint8Array) {
+      const result2 = await this.client.put(
+        `/sandboxes/${this.sandboxId}/files/raw`,
+        {
+          params: { path, username: user },
+          body: data,
+          headers: { "Content-Type": "application/octet-stream" },
+          timeout: opts?.requestTimeout
+        }
+      );
+      return parseWriteInfo(result2);
+    }
     const result = await this.client.post(
       `/sandboxes/${this.sandboxId}/files`,
       {
-        json: { path, data: strData, username: user },
+        json: { path, data, username: user },
         timeout: opts?.requestTimeout
       }
     );
@@ -1384,24 +1399,58 @@ var Filesystem = class {
   /**
    * Write multiple files in a single batch request.
    *
+   * The batch endpoint is JSON-only and cannot carry binary. Entries are
+   * partitioned: string entries go through `POST /files/batch` in one call,
+   * `Uint8Array` entries are streamed individually to `PUT /files/raw`.
+   * Results are merged back in input order.
+   *
    * @param files - Array of files to write.
    * @param opts - Optional user and request timeout.
-   * @returns Array of write info for each file.
+   * @returns Array of write info for each file, in input order.
    */
   async writeFiles(files, opts) {
     const user = opts?.user ?? DEFAULT_USER;
-    const encodedFiles = files.map((f) => ({
-      path: f.path,
-      data: f.data instanceof Uint8Array ? new TextDecoder().decode(f.data) : f.data
-    }));
-    const result = await this.client.post(
-      `/sandboxes/${this.sandboxId}/files/batch`,
-      {
-        json: { files: encodedFiles, username: user },
-        timeout: opts?.requestTimeout
+    const results = new Array(files.length);
+    const strIndices = [];
+    const bytesIndices = [];
+    for (let i = 0; i < files.length; i++) {
+      if (files[i].data instanceof Uint8Array) {
+        bytesIndices.push(i);
+      } else {
+        strIndices.push(i);
       }
-    );
-    return (result ?? []).map(parseWriteInfo);
+    }
+    if (strIndices.length > 0) {
+      const batchFiles = strIndices.map((i) => ({
+        path: files[i].path,
+        data: files[i].data
+      }));
+      const result = await this.client.post(
+        `/sandboxes/${this.sandboxId}/files/batch`,
+        {
+          json: { files: batchFiles, username: user },
+          timeout: opts?.requestTimeout
+        }
+      );
+      const parsed = (result ?? []).map(parseWriteInfo);
+      for (let k = 0; k < strIndices.length; k++) {
+        results[strIndices[k]] = parsed[k];
+      }
+    }
+    for (const i of bytesIndices) {
+      const entry = files[i];
+      const result = await this.client.put(
+        `/sandboxes/${this.sandboxId}/files/raw`,
+        {
+          params: { path: entry.path, username: user },
+          body: entry.data,
+          headers: { "Content-Type": "application/octet-stream" },
+          timeout: opts?.requestTimeout
+        }
+      );
+      results[i] = parseWriteInfo(result);
+    }
+    return results.filter((r) => r !== void 0);
   }
   /**
    * List entries in a directory.
@@ -1540,19 +1589,159 @@ var Filesystem = class {
 };
 
 // src/sandbox/pty/pty.ts
-var Pty = class {
+var PtyHandle = class {
+  pid;
   sandboxId;
   client;
-  constructor(sandboxId, client) {
+  exitPromise;
+  resolveExit;
+  aborter = new AbortController();
+  constructor(pid, sandboxId, client, onData) {
+    this.pid = pid;
     this.sandboxId = sandboxId;
     this.client = client;
+    this.exitPromise = new Promise((resolve) => {
+      this.resolveExit = resolve;
+    });
+    if (onData) {
+      void this.consumeStream(onData);
+    }
+  }
+  /** Forward keystrokes to the PTY. */
+  async sendInput(data, requestTimeout) {
+    const strData = typeof data === "string" ? data : new TextDecoder().decode(data);
+    await this.client.post(
+      `/sandboxes/${this.sandboxId}/pty/${this.pid}/stdin`,
+      { json: { data: strData }, timeout: requestTimeout }
+    );
+  }
+  /** Update the terminal size (TIOCSWINSZ inside the VM). */
+  async resize(size, requestTimeout) {
+    await this.client.patch(
+      `/sandboxes/${this.sandboxId}/pty/${this.pid}`,
+      {
+        json: { size: { cols: size.cols, rows: size.rows } },
+        timeout: requestTimeout
+      }
+    );
+  }
+  /** SIGKILL the remote process and close any open streams. */
+  async kill(requestTimeout) {
+    this.aborter.abort();
+    const data = await this.client.delete(
+      `/sandboxes/${this.sandboxId}/pty/${this.pid}`,
+      { timeout: requestTimeout }
+    );
+    return data.killed === true;
+  }
+  /**
+   * Stop consuming output without killing the process. The PTY keeps
+   * running server-side and a fresh `stream()` call reattaches.
+   */
+  disconnect() {
+    this.aborter.abort();
+  }
+  /** Resolves with the remote exit code when the PTY process exits. */
+  wait() {
+    return this.exitPromise;
   }
   /**
-   * Create a new PTY session.
+   * Async iterator over raw output chunks. Use when you want to drive
+   * the stream yourself:
+   *
+   *   for await (const chunk of handle.stream()) { ... }
    *
-   * Sends POST /sandboxes/:id/pty.
-   * @returns A CommandHandle for the PTY process.
+   * Don't mix this with `onData` on the same handle — they both try to
+   * consume the same underlying SSE connection.
    */
+  async *stream() {
+    const response = await this.client.streamGet(
+      `/sandboxes/${this.sandboxId}/pty/${this.pid}/stream`,
+      { timeout: void 0 }
+    );
+    if (!response.body) {
+      return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        if (this.aborter.signal.aborted) return;
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buffer.indexOf("\n\n")) >= 0) {
+          const frame = buffer.slice(0, idx);
+          buffer = buffer.slice(idx + 2);
+          const parsed = parseSSEFrame(frame);
+          if (!parsed) continue;
+          if (parsed.event === "exit") {
+            this.resolveExit(parsed.exitCode ?? -1);
+            return;
+          }
+          if (parsed.bytes) {
+            yield parsed.bytes;
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  async consumeStream(onData) {
+    try {
+      for await (const chunk of this.stream()) {
+        onData(chunk);
+      }
+    } catch (err) {
+      if (!this.aborter.signal.aborted) {
+        throw err;
+      }
+    } finally {
+      this.resolveExit(-1);
+    }
+  }
+};
+function parseSSEFrame(frame) {
+  let event = "message";
+  let data = "";
+  for (const line of frame.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) data += line.slice(5).trim();
+  }
+  if (!event) return null;
+  if (event === "exit") {
+    try {
+      const parsed = JSON.parse(data);
+      return { event, exitCode: parsed.exit_code ?? -1 };
+    } catch {
+      return { event, exitCode: -1 };
+    }
+  }
+  if (event === "data") {
+    try {
+      const parsed = JSON.parse(data);
+      if (typeof parsed.data === "string") {
+        const bin = atob(parsed.data);
+        const bytes = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+        return { event, bytes };
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+var Pty = class {
+  sandboxId;
+  client;
+  constructor(sandboxId, client) {
+    this.sandboxId = sandboxId;
+    this.client = client;
+  }
   async create(opts) {
     const size = opts?.size ?? { cols: 80, rows: 24 };
     const user = opts?.user ?? "user";
@@ -1560,32 +1749,17 @@ var Pty = class {
       size: { cols: size.cols, rows: size.rows },
       user
     };
-    if (opts?.cwd !== void 0) {
-      body.cwd = opts.cwd;
-    }
-    if (opts?.envs !== void 0) {
-      body.envs = opts.envs;
-    }
-    if (opts?.timeout !== void 0) {
-      body.timeout = opts.timeout;
-    }
+    if (opts?.cwd !== void 0) body.cwd = opts.cwd;
+    if (opts?.envs !== void 0) body.envs = opts.envs;
+    if (opts?.timeout !== void 0) body.timeout = opts.timeout;
     const data = await this.client.post(
       `/sandboxes/${this.sandboxId}/pty`,
-      {
-        json: body,
-        timeout: opts?.requestTimeout
-      }
+      { json: body, timeout: opts?.requestTimeout }
     );
-    const response = data;
-    const pid = response.pid;
-    return new CommandHandle(pid, this.sandboxId, this.client);
+    const pid = data.pid;
+    return new PtyHandle(pid, this.sandboxId, this.client, opts?.onData);
   }
-  /**
-   * Kill a PTY session.
-   *
-   * Sends DELETE /sandboxes/:id/pty/:pid.
-   * @returns true if the process was killed, false if already dead.
-   */
+  // --- Legacy low-level API (kept for callers that already hold a pid). ---
   async kill(pid, requestTimeout) {
     const data = await this.client.delete(
       `/sandboxes/${this.sandboxId}/pty/${pid}`,
@@ -1593,27 +1767,13 @@ var Pty = class {
     );
     return data.killed === true;
   }
-  /**
-   * Send input to a PTY session.
-   *
-   * Sends POST /sandboxes/:id/pty/:pid/stdin.
-   * If data is a Uint8Array, it is decoded to a string using TextDecoder.
-   */
   async sendStdin(pid, data, requestTimeout) {
     const strData = typeof data === "string" ? data : new TextDecoder().decode(data);
     await this.client.post(
       `/sandboxes/${this.sandboxId}/pty/${pid}/stdin`,
-      {
-        json: { data: strData },
-        timeout: requestTimeout
-      }
+      { json: { data: strData }, timeout: requestTimeout }
     );
   }
-  /**
-   * Resize a PTY session.
-   *
-   * Sends PATCH /sandboxes/:id/pty/:pid.
-   */
   async resize(pid, size, requestTimeout) {
     await this.client.patch(
       `/sandboxes/${this.sandboxId}/pty/${pid}`,
@@ -2398,6 +2558,7 @@ var Template = class {
   NotFoundError,
   PIIType,
   Pty,
+  PtyHandle,
   RedactionAction,
   Sandbox,
   SandboxError,