@opengeni/sdk 0.3.1 → 0.4.0

package/dist/index.js

@@ -426,6 +426,127 @@ var OpenGeniClient = class {
   async compactSessionContext(workspaceId, sessionId) {
     return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/context/compact`, {});
   }
+  // --- Channel-A structured services (P4.4) ------------------------------------
+  // FileSystem (Pierre tree), Git (Pierre diff), Terminal (exec + PTY). Each is a
+  // synchronous API-direct point query; the fs.changed/git.changed/terminal.pty.*
+  // notifications + the PTY output stream arrive on the existing event SSE.
+  /** FileSystem: list a directory tree (feeds the Pierre file tree). */
+  async fsList(workspaceId, sessionId, request = {}) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/list`, request);
+  }
+  /** FileSystem: read a file (text or base64; binary-safe, size-capped). */
+  async fsRead(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/read`, request);
+  }
+  /** FileSystem: write a file (last-writer-wins; emits fs.changed). */
+  async fsWrite(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/write`, request);
+  }
+  /** FileSystem: delete a path (emits fs.changed). */
+  async fsDelete(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/delete`, request);
+  }
+  /** FileSystem: move/rename a path (emits fs.changed; 409 if destination exists and overwrite is false). */
+  async fsMove(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/move`, request);
+  }
+  /** FileSystem: create a directory (emits fs.changed; recursive defaults to true). */
+  async fsMkdir(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/fs/mkdir`, request);
+  }
+  /** Git: working-tree/index status (the Pierre file-status feed). */
+  async gitStatus(workspaceId, sessionId, request = {}) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/status`, request);
+  }
+  /** Git: structured diff hunks (the Pierre diff feed). */
+  async gitDiff(workspaceId, sessionId, request = {}) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/diff`, request);
+  }
+  /** Git: commit log. */
+  async gitLog(workspaceId, sessionId, request = {}) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/log`, request);
+  }
+  /** Git: show a commit (diff vs first parent) or fetch a raw blob at a ref. */
+  async gitShow(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/git/show`, request);
+  }
+  /** Terminal: run a bounded command, returning buffered stdout/stderr inline. */
+  async terminalExec(workspaceId, sessionId, request) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/exec`, request);
+  }
+  /** Terminal: open an interactive PTY. Output streams on the event SSE as
+   *  terminal.pty.output.delta; drive it with terminalPtyWrite. */
+  async terminalPtyOpen(workspaceId, sessionId, request = {}) {
+    return await this.requestJson("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty`, request);
+  }
+  /** Terminal: send stdin to an open PTY (output rides A1). */
+  async terminalPtyWrite(workspaceId, sessionId, request) {
+    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/write`, request);
+  }
+  /** Terminal: resize an open PTY. */
+  async terminalPtyResize(workspaceId, sessionId, request) {
+    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/resize`, request);
+  }
+  /** Terminal: close an open PTY (idempotent). */
+  async terminalPtyClose(workspaceId, sessionId, request) {
+    await this.requestVoid("POST", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/terminal/pty/close`, request);
+  }
+  // --- Stream surfacing: capability negotiation + viewer lifecycle (Phase 5) ---
+  // The capability doc is the single source of UI truth (degradation is always a
+  // value, never a crash). The desktop pixel plane (Channel B) is gated behind an
+  // un-redacted-acknowledgment + a viewer holder; the structured terminal/files/
+  // git surfaces (Channel A) ride the methods above and the event SSE.
+  /** Read the negotiated capability doc for a session WITHOUT acquiring a viewer
+   *  holder (no warm, no spawn). Drives capability-gated rendering: which
+   *  surfaces mount, the per-surface unavailability reasons, and the lease
+   *  liveness the client polls on while `cold`/`warming`. The desktop URL/token
+   *  are minted in-process only when the box is warm AND the principal has
+   *  acknowledged the un-redacted plane. */
+  async getStreamCapabilities(workspaceId, sessionId) {
+    return await this.requestJson(
+      "GET",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities`
+    );
+  }
+  /** Record the calling principal's acknowledgment of the un-redacted desktop
+   *  pixel plane (and, when the box is shared, the shared-exposure disclosure).
+   *  The desktop viewer-attach path returns 409 until this is recorded. */
+  async acknowledgeStream(workspaceId, sessionId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/stream-capabilities/acknowledge`,
+      request
+    );
+  }
+  /** Attach a viewer holder (refcounted liveness — keeps the box warm while
+   *  watched/used), spinning the box up in-process when cold, and mint the scoped
+   *  direct-to-provider URLs for the requested plane(s). `request.desktop:true`
+   *  opts into the un-redacted pixel plane and mints the noVNC URL — that plane
+   *  alone throws `OpenGeniApiError(409)` when the un-redacted/shared
+   *  acknowledgment is missing (the consent gate). A terminal-only attach
+   *  (`desktop` omitted/false) warms the box + mints the pty-ws terminal cell with
+   *  NO consent gate. An omitted `viewerId` mints a fresh one. */
+  async attachViewer(workspaceId, sessionId, request = {}) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers`,
+      request
+    );
+  }
+  /** Heartbeat a viewer holder (Channel-A app-level liveness). A closed laptop
+   *  stops sending these → the reaper drops the holder within ~90s. Echoes
+   *  `leaseEpoch` so a superseded epoch is rejected (`alive:false` → re-attach). */
+  async heartbeatViewer(workspaceId, sessionId, viewerId, request) {
+    return await this.requestJson(
+      "POST",
+      `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}/heartbeat`,
+      request
+    );
+  }
+  /** Detach a viewer (delete this holder; idempotent delete-my-row). */
+  async detachViewer(workspaceId, sessionId, viewerId) {
+    await this.requestVoid("DELETE", `/v1/workspaces/${workspaceId}/sessions/${sessionId}/viewers/${viewerId}`);
+  }
   // --- Access + workspaces -----------------------------------------------------
   /**
    * The deployment's public client bootstrap config: the host-exposed models
@@ -632,6 +753,16 @@ var OpenGeniClient = class {
       `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}/reindex`
     );
   }
+  /**
+   * Delete a document from a base. Removes the document row and its indexed
+   * chunks while leaving the uploaded file asset available for other uses.
+   */
+  async deleteDocument(workspaceId, baseId, documentId) {
+    await this.requestVoid(
+      "DELETE",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}`
+    );
+  }
   async searchDocuments(workspaceId, baseId, request) {
     return await this.requestJson(
       "POST",
@@ -909,6 +1040,94 @@ function proxySessionEventStream(client, workspaceId, sessionId, options = {}) {
   });
 }
 
+// src/desktop.ts
+function desktopSocketUrl(cap) {
+  if (!cap.url) {
+    throw new Error("desktop capability has no url (transport is null)");
+  }
+  const u = new URL(cap.url);
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  if (/\/vnc(_lite)?\.html$/.test(u.pathname)) {
+    u.pathname = u.pathname.replace(/\/vnc(_lite)?\.html$/, "/websockify");
+    u.search = "";
+    u.hash = "";
+  }
+  return u.toString();
+}
+function nextDesktopState(current, ev) {
+  switch (ev.type) {
+    case "negotiated":
+      return "connecting";
+    case "connected":
+      return "connected";
+    case "rotate":
+      return current === "connected" ? "rotating" : current;
+    case "disconnected":
+      return current === "ended" ? "ended" : "reconnecting";
+    case "fail":
+      return "error";
+    case "abort":
+      return "ended";
+    default:
+      return current;
+  }
+}
+function applyUrlRotation(cap, payload, knownEpoch) {
+  if (payload.leaseEpoch < knownEpoch) {
+    return null;
+  }
+  return { ...cap, url: payload.url, token: payload.token, expiresAt: payload.expiresAt };
+}
+
+// src/terminal.ts
+function terminalSocketUrl(cap) {
+  if (!cap.url) {
+    throw new Error("terminal capability has no url (transport is not pty-ws)");
+  }
+  const u = new URL(cap.url);
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  return u.toString();
+}
+var TTYD_SUBPROTOCOL = "tty";
+var TtydClientCommand = {
+  /** stdin: "0" + raw input bytes. */
+  INPUT: "0",
+  /** window resize: "1" + JSON.stringify({ columns, rows }). */
+  RESIZE: "1",
+  /** flow-control pause (back-pressure): "2". */
+  PAUSE: "2",
+  /** flow-control resume: "3". */
+  RESUME: "3"
+};
+var TtydServerCommand = {
+  /** stdout/stderr: "0" + raw output bytes (write the rest into xterm). */
+  OUTPUT: "0",
+  /** set the window title: "1" + title string. */
+  SET_WINDOW_TITLE: "1",
+  /** ttyd client preferences JSON: "2" + json (ignored by us). */
+  SET_PREFERENCES: "2"
+};
+function ttydAuthFrame(opts) {
+  const frame = { AuthToken: "" };
+  if (opts?.columns && opts.columns > 0) frame.columns = opts.columns;
+  if (opts?.rows && opts.rows > 0) frame.rows = opts.rows;
+  return JSON.stringify(frame);
+}
+function ttydInputFrame(data) {
+  return TtydClientCommand.INPUT + data;
+}
+function ttydResizeFrame(columns, rows) {
+  return TtydClientCommand.RESIZE + JSON.stringify({ columns, rows });
+}
+
 // src/types.ts
 var SESSION_EVENT_TYPES = [
   "session.created",
@@ -942,7 +1161,24 @@ var SESSION_EVENT_TYPES = [
   "goal.completed",
   "goal.paused",
   "goal.resumed",
-  "goal.continuation"
+  "goal.continuation",
+  // Channel-B desktop pixel-plane signals (mirror of contracts SessionEventType;
+  // the contract-parity test asserts sorted equality).
+  "stream.url.rotated",
+  "stream.opened",
+  "stream.closed",
+  "stream.revoked",
+  // Channel-B recording signals (P4.3 — "agent films itself proving the fix").
+  "recording.started",
+  "recording.available",
+  "recording.failed",
+  // Channel-A structured-service notifications (P4.4; mirror of contracts
+  // SessionEventType — the contract-parity test asserts sorted equality).
+  "fs.changed",
+  "git.changed",
+  "terminal.pty.started",
+  "terminal.pty.output.delta",
+  "terminal.pty.exited"
 ];
 var KNOWN_PERMISSIONS = [
   "account:read",
@@ -956,8 +1192,17 @@ var KNOWN_PERMISSIONS = [
   "sessions:create",
   "sessions:read",
   "sessions:control",
+  // Sandbox-surfacing (mirror of @opengeni/contracts Permission). stream:view is
+  // strictly broader than sessions:read (un-redacted pixels); stream:control is
+  // the never-granted-v1 raw-input plane; stream:acknowledge is the secret-leak
+  // consent gate.
+  "stream:view",
+  "stream:control",
+  "stream:acknowledge",
   "files:upload",
   "files:read",
+  "files:write",
+  "terminal:attach",
   "documents:manage",
   "documents:search",
   "scheduled_tasks:manage",
@@ -978,7 +1223,10 @@ var KNOWN_USAGE_EVENT_TYPES = [
   "file.deleted",
   "document.indexed",
   "scheduled_task.fired",
-  "api_key.request"
+  "api_key.request",
+  // sandbox warm-time metering (P2.1) — mirrors contracts UsageEventType.
+  "sandbox.warm_seconds",
+  "sandbox.warm_cost"
 ];
 export {
   KNOWN_PERMISSIONS,
@@ -987,13 +1235,23 @@ export {
   OpenGeniClient,
   OpenGeniStreamError,
   SESSION_EVENT_TYPES,
+  TTYD_SUBPROTOCOL,
+  TtydClientCommand,
+  TtydServerCommand,
+  applyUrlRotation,
+  desktopSocketUrl,
   formatSseEvent,
   isRetryableStreamError,
+  nextDesktopState,
   parseSseStream,
   proxySessionEventStream,
   resumeSequenceFromRequest,
   sessionEventsToSseResponse,
   sessionEventsToSseStream,
-  streamSessionEvents
+  streamSessionEvents,
+  terminalSocketUrl,
+  ttydAuthFrame,
+  ttydInputFrame,
+  ttydResizeFrame
 };
 //# sourceMappingURL=index.js.map