@miosa/sdk 2.0.6 → 3.0.0

package/dist/index.js

@@ -168,7 +168,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "2.0.6";
+var SDK_VERSION = "3.0.0";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -198,6 +198,7 @@ async function ensureHttp2Agent() {
   }
 }
 ensureHttp2Agent();
+var SSE_ACCEPT = "text/event-stream, application/json;q=0.9";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var RETRY_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
@@ -370,7 +371,7 @@ var HttpClient = class {
   async *stream(path, options = {}) {
     const method = options.method ?? "GET";
     let headers = this.baseHeaders({
-      Accept: "text/event-stream",
+      Accept: SSE_ACCEPT,
       ...options.headers
     });
     let body5 = null;
@@ -408,12 +409,14 @@ var HttpClient = class {
         response.headers.get("x-request-id") ?? void 0
       );
     }
+    if (response.status === 204) return;
     if (!response.body) {
       throw new MiosaError("SSE stream has no body", 0, "NO_STREAM_BODY");
     }
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    let eventName;
     try {
       while (true) {
         const { done, value } = await reader.read();
@@ -422,11 +425,22 @@ var HttpClient = class {
         const lines = buffer.split("\n");
         buffer = lines.pop() ?? "";
         for (const line of lines) {
+          if (line.startsWith("event:")) {
+            eventName = line.slice(6).trim();
+            continue;
+          }
+          if (line === "") {
+            eventName = void 0;
+            continue;
+          }
           if (line.startsWith("data:")) {
             const raw = line.slice(5).trim();
+            const name = eventName;
+            eventName = void 0;
             if (raw === "[DONE]" || raw === "") continue;
             try {
-              yield JSON.parse(raw);
+              const parsed = JSON.parse(raw);
+              yield name !== void 0 && parsed !== null && typeof parsed === "object" && !("type" in parsed) ? { type: name, ...parsed } : parsed;
             } catch {
             }
           }
@@ -7774,41 +7788,130 @@ var Jobs = class {
     return `/opencomputers/hosts/${hostId}`;
   }
   /**
-   * Dispatch a command to run on the remote host.
+   * Run a command on the host and wait for the buffered result.
+   *
+   * Sends `stream: false` so the server buffers output and answers with JSON.
+   * `stream` defaults to *true* server-side, which answers with a chunked SSE
+   * body instead - use {@link runStream} for that.
+   *
+   * Note this holds the connection open for the life of the command
+   * (`timeout_ms`, 30 s default), because the server does not answer until
+   * the command finishes.
    */
   async run(hostId, params) {
-    return this.http.post(`${this.base(hostId)}/exec`, params);
+    return this.http.post(`${this.base(hostId)}/exec`, {
+      ...params,
+      stream: false
+    });
   }
   /**
-   * List all jobs for a host.
+   * Run a command on the host and stream its output as it happens.
+   *
+   * Same endpoint as {@link run} with `stream: true`, which is the server's
+   * default mode. Terminates with one `exec_result` or one `exec_error`.
    */
-  async list(hostId) {
-    return this.http.get(`${this.base(hostId)}/exec`);
+  runStream(hostId, params) {
+    return translateExecStream(
+      this.http.stream(`${this.base(hostId)}/exec`, {
+        method: "POST",
+        body: { ...params, stream: true }
+      })
+    );
+  }
+  /**
+   * List recent job activity for a host.
+   *
+   * Hits `/jobs`, not `/exec`: there is no `GET /opencomputers/hosts/{id}/exec`
+   * route on the server, so the old path 404'd. The rows are audit-log events
+   * about jobs (`job.dispatched` / `job.done` / `job.failed`), newest first,
+   * not job records - see {@link JobAuditEvent}.
+   *
+   * @param limit Server caps this at 100 and defaults to 20.
+   */
+  async list(hostId, limit) {
+    return this.http.get(
+      `${this.base(hostId)}/jobs`,
+      limit === void 0 ? void 0 : { limit }
+    );
   }
   /**
    * Fetch the current state of a job.
+   *
+   * The server wraps the record in a `job` envelope; this unwraps it.
    */
   async get(hostId, jobId) {
-    return this.http.get(`${this.base(hostId)}/exec/${jobId}`);
+    const response = await this.http.get(
+      `${this.base(hostId)}/exec/${jobId}`
+    );
+    if (response && typeof response === "object" && "job" in response) {
+      return response.job;
+    }
+    return response;
   }
   /**
-   * Stream live output from a running job.
+   * Re-attach to a job that is already running and stream what is left.
    *
-   * Yields `JobEvent` objects with `type` of `stdout`, `stderr`, `exit`, or
-   * `done`. Break the loop when you receive `done` or `exit`.
+   * This is the reconnect endpoint. If the job has already reached a terminal
+   * state the server answers `204 No Content` and this yields nothing, rather
+   * than replaying output - the server never stored it.
    */
   stream(hostId, jobId) {
-    return this.http.stream(
-      `${this.base(hostId)}/exec/${jobId}/stream`
+    return translateExecStream(
+      this.http.stream(`${this.base(hostId)}/exec/${jobId}/stream`)
     );
   }
   /**
    * Cancel a running or queued job.
+   *
+   * Answers `204` on success and `409` when the job is already terminal.
    */
   async cancel(hostId, jobId) {
     return this.http.delete(`${this.base(hostId)}/exec/${jobId}`);
   }
 };
+var EXEC_EVENT_NAMES = /* @__PURE__ */ new Set(["exec_chunk", "exec_result", "exec_error"]);
+function asString(value) {
+  return typeof value === "string" ? value : null;
+}
+function asNumber(value) {
+  return typeof value === "number" ? value : null;
+}
+function toJobEvent(raw) {
+  if (raw === null || typeof raw !== "object") return null;
+  const record = raw;
+  const name = asString(record["type"]);
+  if (name === null || !EXEC_EVENT_NAMES.has(name)) return null;
+  if (name === "exec_chunk") {
+    return {
+      type: "exec_chunk",
+      // The server defaults this to :stdout when the host omits it; anything
+      // other than "stderr" is stdout by the same rule.
+      stream: record["stream"] === "stderr" ? "stderr" : "stdout",
+      data: asString(record["data"])
+    };
+  }
+  if (name === "exec_result") {
+    return {
+      type: "exec_result",
+      exit_code: asNumber(record["exit_code"]),
+      elapsed_ms: asNumber(record["elapsed_ms"])
+    };
+  }
+  const jobId = asString(record["job_id"]);
+  return {
+    type: "exec_error",
+    reason: asString(record["reason"]),
+    // Only the timeout path carries job_id. exactOptionalPropertyTypes means
+    // the key has to be omitted rather than set to undefined.
+    ...jobId === null ? {} : { job_id: jobId }
+  };
+}
+async function* translateExecStream(source) {
+  for await (const raw of source) {
+    const event = toJobEvent(raw);
+    if (event !== null) yield event;
+  }
+}
 
 // src/resources/open-computers/secrets.ts
 var Secrets = class {
@@ -8419,6 +8522,32 @@ var RuntimeCapabilitiesResource = class {
   }
 };
 
+// src/resources/sandbox-host-routes.ts
+var SANDBOXES_HOST_BASE_URL = "https://sandboxes.miosa.ai/api/v1";
+var SANDBOXES_HOST = "sandboxes.miosa.ai";
+function isSandboxesHost(baseUrl) {
+  try {
+    return new URL(baseUrl).host === SANDBOXES_HOST;
+  } catch {
+    return false;
+  }
+}
+async function* streamSandboxesHostRoute(http, path, alternative) {
+  try {
+    yield* http.stream(path);
+  } catch (err) {
+    if (err instanceof MiosaError && err.status === 404 && !isSandboxesHost(http.baseUrl)) {
+      throw new NotFoundError(
+        `HTTP 404 for GET ${path}. This route is mounted only on the sandboxes host router (${SANDBOXES_HOST}); it is not part of the platform router that serves this client's baseUrl (${http.baseUrl}). Either construct the client with baseUrl: "${SANDBOXES_HOST_BASE_URL}", or ${alternative}. A wrong sandbox id also produces a 404.`,
+        err.code,
+        err.details,
+        err.requestId
+      );
+    }
+    throw err;
+  }
+}
+
 // src/resources/sandboxes.ts
 function encodeContent(content) {
   const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
@@ -8443,6 +8572,12 @@ var AGENT_WORKSPACE_KEEP_LAST_SNAPSHOTS = 1;
 function isLegacyForkParams(opts) {
   return "name" in opts || "metadata" in opts;
 }
+async function* dropWatchHandshake(source) {
+  for await (const event of source) {
+    if (event.type === "connected") continue;
+    yield event;
+  }
+}
 function unwrap48(payload) {
   if (payload !== null && typeof payload === "object" && "data" in payload && payload.data !== void 0) {
     return payload.data;
@@ -8642,11 +8777,30 @@ var SandboxFiles = class {
     }
     return response;
   }
-  /** GET /api/v1/sandboxes/{id}/files/watch (SSE) — live file change events. */
+  /**
+   * GET /api/v1/sandboxes/{id}/files/watch (SSE) — live file change events.
+   *
+   * SANDBOXES-HOST ONLY. This route is declared in `Web.Router.Sandboxes`
+   * and not in `Web.Router.Platform`, so it 404s against the SDK's default
+   * `https://api.miosa.ai/api/v1` base URL. Construct the client with
+   * `baseUrl: "https://sandboxes.miosa.ai/api/v1"` to reach it, or poll
+   * {@link list}/{@link stat} instead. See `./sandbox-host-routes.ts`.
+   *
+   * The server opens with a handshake record (`event: connected` /
+   * `data: {"sandbox_id":...}`) before any change events. That record is
+   * not a file change, so it is dropped here rather than yielded as a
+   * `SandboxFileChange` with `type: "connected"` and no `path`. Real change
+   * records carry their own `type` (`created` | `modified` | `deleted`) in
+   * the JSON body, so the SSE `event: file_change` name never overwrites it.
+   */
   watch() {
     const http = this.sandbox.http;
-    return http.stream(
-      `/sandboxes/${this.sandbox.id}/files/watch`
+    return dropWatchHandshake(
+      streamSandboxesHostRoute(
+        http,
+        `/sandboxes/${this.sandbox.id}/files/watch`,
+        "poll list()/stat() instead"
+      )
     );
   }
 };
@@ -9398,19 +9552,40 @@ var Sandbox = class _Sandbox {
     const stream = options.stream ?? true;
     if (stream) {
       const sseResult = await this.tryReadinessStream(timeout);
-      if (sseResult !== null) return sseResult;
+      if (sseResult !== null) {
+        if (sseResult) await this.adoptReadyState();
+        return sseResult;
+      }
     }
     const deadlineMs = Date.now() + timeout * 1e3;
     while (Date.now() < deadlineMs) {
       try {
         const data = await this.readiness();
-        if (data.ready === true || data.status === "ready") return true;
+        if (data.ready === true || data.status === "ready") {
+          await this.adoptReadyState();
+          return true;
+        }
       } catch {
       }
       await new Promise((resolve) => setTimeout(resolve, 10));
     }
     return false;
   }
+  /**
+   * Readiness answers from the server; `assertRunning` reads the local
+   * snapshot. Leaving that snapshot behind meant a caller could await
+   * `waitUntilReady()`, receive `true`, and have the very next call refused
+   * for being "provisioning" — the sandbox was running the whole time, only
+   * this object had not been told. Nothing here can fail the wait: readiness
+   * has already answered, so a refresh that does not land is not the caller's
+   * problem.
+   */
+  async adoptReadyState() {
+    try {
+      await this.refresh();
+    } catch {
+    }
+  }
   /**
    * Returns `true` / `false` for terminal SSE events, or `null` if the
    * stream endpoint is unavailable (404 or transport error) so callers