@promigence/sdk 0.1.0-beta.14 → 0.1.0-beta.15

package/dist/pty.d.ts

@@ -1,11 +1,14 @@
 /**
  * Interactive terminals: `GET /v1/sandboxes/:id/pty` over a WebSocket (RFC 6455).
  *
- * The protocol:
+ * The protocol (`promigence.pty.v2`):
  *
- *   client → server  binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
+ *   client → server  first, one text frame `{"start":{"cmd"?,"secrets"?}}`: what to run and the secret
+ *                    names it gets, inside the connection, never in a header or the URL; then
+ *                    binary = keystrokes; text = `{"resize":{cols,rows}}` | `{"signal":N}` | `{"eof":true}`
  *   server → client  binary = terminal output; text = `{"event":"open",…}` first and
- *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame
+ *                    `{"event":"exit"|"error"|"closed",…}` last, then a Close frame. A terminal that
+ *                    cannot open says so in its first frame: `{"event":"error","status",…}`, then Close.
  *
  * Zero dependencies, so this is a small client over `node:http` rather than the global
  * `WebSocket`: that one cannot send an `Authorization` header, and a key in the query string is
@@ -32,26 +35,20 @@ export interface PtyExit {
         message: string;
     };
 }
-/** The header the terminal's command travels in, base64. Never a query parameter. */
-export declare const PTY_COMMAND_HEADER = "promigence-pty-command";
-/** The header the terminal's secret **names** travel in, base64 JSON. */
-export declare const PTY_SECRETS_HEADER = "promigence-pty-secrets";
+/** The WebSocket subprotocol a terminal speaks: its first message is `{"start": {"cmd"?, "secrets"?}}`. */
+export declare const PTY_PROTOCOL = "promigence.pty.v2";
 export interface PtyConnectOpts {
     /** `http(s)://host[:port]/v1/sandboxes/<id>/pty?cols=&rows=` — dimensions only. */
     url: string;
     apiKey: string;
     userAgent: string;
     /**
-     * The command to run, sent as a header rather than in the URL.
-     *
-     * It used to be `?cmd=`, with `envs` composed into it as `export K=v;` — so a terminal opened
-     * with an API key in its environment wrote that key into the query string of every request,
-     * and therefore into every access log along the path. Names and values both stay out of the
-     * URL now.
+     * The command to run. Sent in the terminal's first message, inside the connection: never in a
+     * header or the URL, where a log on the way could keep it.
      */
     command?: string;
     /** Stored secret names (or `{name, as}` bindings), resolved server-side into the terminal's
-     *  environment. JSON, base64, in a header. */
+     *  environment. Sent in the first message with the command. */
     secrets?: unknown[];
     /** The `promigence-caller` label, when one is set (`setCaller`). */
     caller?: string;

package/dist/pty.js

@@ -5,8 +5,10 @@ export const PTY_INPUT_CHUNK = 64 * 1024;
 export const PTY_INPUT_KEEP = 256 * 1024;
 export const PTY_RESUME_HEADER = "promigence-resume";
 const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
-export const PTY_COMMAND_HEADER = "promigence-pty-command";
-export const PTY_SECRETS_HEADER = "promigence-pty-secrets";
+export const PTY_PROTOCOL = "promigence.pty.v2";
+export function ptyStartMessage(command, secrets) {
+    return JSON.stringify({ start: { ...(command ? { cmd: command } : {}), ...(secrets?.length ? { secrets } : {}) } });
+}
 export function wsAccept(key) {
     return createHash("sha1").update(key + WS_GUID).digest("base64");
 }
@@ -250,15 +252,7 @@ function openLeg(opts, url, resume) {
             authorization: `Bearer ${opts.apiKey}`,
             "user-agent": opts.userAgent,
             ...(opts.caller ? { [CALLER_HEADER]: opts.caller } : {}),
-            ...(resume ? { [PTY_RESUME_HEADER]: resume } : {}),
-            ...(opts.command && !resume
-                ? { [PTY_COMMAND_HEADER]: Buffer.from(opts.command, "utf8").toString("base64") }
-                : {}),
-            ...(opts.secrets?.length && !resume
-                ? {
-                    [PTY_SECRETS_HEADER]: Buffer.from(JSON.stringify(opts.secrets), "utf8").toString("base64"),
-                }
-                : {}),
+            ...(resume ? { [PTY_RESUME_HEADER]: resume } : { "sec-websocket-protocol": PTY_PROTOCOL }),
         },
     });
     let resolveEnded;
@@ -291,6 +285,8 @@ function openLeg(opts, url, resume) {
                 return;
             }
             socket.setNoDelay(true);
+            if (!resume)
+                socket.write(encodeFrame(0x1, Buffer.from(ptyStartMessage(opts.command, opts.secrets), "utf8")));
             const reader = new FrameReader();
             let exit;
             let closeCode;
@@ -328,6 +324,12 @@ function openLeg(opts, url, resume) {
                                 ...(typeof v["wall_ms"] === "number" ? { wallMs: v["wall_ms"] } : {}),
                             };
                         }
+                        else if (v["event"] === "error" && !wasOpen && typeof v["status"] === "number") {
+                            const e = (v["error"] && typeof v["error"] === "object" ? v["error"] : { code: v["code"], message: v["message"] });
+                            fail(v["status"], JSON.stringify({ error: e }), typeof v["retry_after"] === "string" ? v["retry_after"] : undefined);
+                            socket.destroy();
+                            return;
+                        }
                         else if (v["event"] === "error" || v["event"] === "closed") {
                             exit = {
                                 exitCode: null, signal: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promigence/sdk",
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.15",
   "description": "The fastest sandboxes for AI agents and code. The Promigence TypeScript SDK: snapshot an environment once, fork it as often as you need, run commands in every copy. A simple Sandbox class and the full PromigenceClient, with zero runtime dependencies.",
   "license": "Apache-2.0",
   "homepage": "https://www.promigence.ai",