@opengeni/sdk 0.2.0 → 0.4.0

package/src/terminal.ts

@@ -0,0 +1,91 @@
+// Zero-dependency interactive-terminal (ttyd PTY-over-websocket) transport
+// contract. Symmetric with `desktop.ts`: the SDK ships only the pure transport
+// CONTRACT (a URL assembler + the ttyd wire-protocol frame codec), with no DOM
+// and no deps. The actual WebSocket open + xterm attach lives in `@opengeni/react`
+// (`use-terminal-stream.ts`).
+//
+// The interactive terminal is a REAL PTY streamed over the SAME Modal raw-TLS
+// tunnel as the desktop noVNC, with the SAME scoped stream-token mechanism. The
+// box bakes `ttyd` on `TERMINAL_STREAM_PORT` (7681); `session.resolveExposedPort`
+// mints the tunnel URL. The Terminal capability cell carries transport "pty-ws" +
+// that url + the scoped token when the box is warm and a viewer is attached.
+
+import type { TerminalCapability } from "./types";
+
+/**
+ * Translate the negotiated `pty-ws` Terminal capability into the WebSocket URL
+ * the ttyd client dials. The scoped provider token is ALREADY embedded in the
+ * minted `url` (the Modal tunnel host) by `session.resolveExposedPort(7681)` —
+ * we do NOT append `cap.token` (identical posture to the desktop: the gate is the
+ * unguessable short-TTL tunnel URL + the server-recorded scoped stream token; ttyd
+ * runs `--writable` with no `-c` credential in v1). We only normalize the scheme
+ * to `ws`/`wss`; a bare host is already the ttyd websocket endpoint.
+ */
+export function terminalSocketUrl(cap: Pick<TerminalCapability, "url">): string {
+  if (!cap.url) {
+    throw new Error("terminal capability has no url (transport is not pty-ws)");
+  }
+  const u = new URL(cap.url);
+  // https → wss, http → ws (ttyd is dialed as a WebSocket, not an HTTP page).
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  return u.toString();
+}
+
+// ── ttyd wire protocol ───────────────────────────────────────────────────────
+// ttyd frames are a single ASCII command char + payload. These mirror ttyd's
+// `protocol.h` Command enum. Client→server and server→client share the byte 0/1/2
+// values but mean different things per direction (see below).
+
+/** ttyd subprotocol — REQUIRED on the WebSocket handshake or ttyd refuses it. */
+export const TTYD_SUBPROTOCOL = "tty";
+
+/** Client→server command bytes (the first char of each outbound text frame). */
+export const 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",
+} as const;
+
+/** Server→client command bytes (the first char of each inbound frame). */
+export const 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",
+} as const;
+
+/**
+ * The ttyd handshake's first frame: an auth message. ttyd expects
+ * `JSON.stringify({ AuthToken })` as the FIRST text frame on the socket. We send
+ * an empty token — our gate is the tunnel URL + scoped stream token, NOT a ttyd
+ * `-c` basic-auth credential (which the box does not set in v1). Optional ttyd
+ * `columns`/`rows` can ride this frame to seed the PTY size before the first
+ * resize. Pure (string-building only) so it stays unit-testable in the SDK.
+ */
+export function ttydAuthFrame(opts?: { columns?: number; rows?: number }): string {
+  const frame: { AuthToken: string; columns?: number; rows?: number } = { 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);
+}
+
+/** Build a client→server INPUT (stdin) frame: "0" + data. */
+export function ttydInputFrame(data: string): string {
+  return TtydClientCommand.INPUT + data;
+}
+
+/** Build a client→server RESIZE frame: "1" + JSON.stringify({ columns, rows }). */
+export function ttydResizeFrame(columns: number, rows: number): string {
+  return TtydClientCommand.RESIZE + JSON.stringify({ columns, rows });
+}

package/src/types.ts

@@ -11,7 +11,193 @@ export type SessionStatus =
   | "failed"
   | "cancelled";
 
-export type SandboxBackend = "docker" | "modal" | "local" | "none";
+// Mirror of `@opengeni/contracts` SandboxBackend (10 values; existing four keep
+// position). 3-way enum parity is pinned by `test/contract-parity.test.ts`.
+export type SandboxBackend =
+  | "docker"
+  | "modal"
+  | "local"
+  | "none"
+  | "daytona"
+  | "runloop"
+  | "e2b"
+  | "blaxel"
+  | "cloudflare"
+  | "vercel";
+
+// Mirror of `@opengeni/contracts` SandboxOs. Only "linux" is reachable in v1.
+export type SandboxOs = "linux" | "macos" | "windows";
+
+// Mirror of `@opengeni/contracts` SandboxCapabilityName.
+export type SandboxCapabilityName =
+  | "FileSystem"
+  | "Terminal"
+  | "Git"
+  | "DesktopStream"
+  | "Recording";
+
+// Mirror of `@opengeni/contracts` CapabilityUnavailableReason.
+export type CapabilityUnavailableReason =
+  | "backend_unsupported"
+  | "os_unsupported"
+  | "not_provisioned"
+  | "disabled_by_policy"
+  | "lease_cold"
+  | "tier_headless";
+
+// Mirror of `@opengeni/contracts` SessionCapabilities (the negotiated handshake
+// document). The descriptor table itself is NOT mirrored — it lives in
+// contracts (P0.1) and is consumed by the SDK config in a later PR.
+export type SessionCapabilities = {
+  sessionId: string;
+  backend: SandboxBackend;
+  os: SandboxOs;
+  liveness: "cold" | "warming" | "warm" | "draining";
+  leaseEpoch: number;
+  viewerHeartbeatIntervalMs: number;
+  FileSystem: {
+    available: boolean;
+    readOnly: boolean;
+    root: string;
+    pathSep: "/" | "\\";
+    treeMode: "lazy" | "snapshot";
+    reason: CapabilityUnavailableReason | null;
+  };
+  Terminal: {
+    transport: "sse-events" | "pty-ws" | null;
+    ptyCapable: boolean;
+    shell: string;
+    url: string | null;
+    token: string | null;
+    reason: CapabilityUnavailableReason | null;
+  };
+  Git: {
+    available: boolean;
+    repos: string[];
+    reason: CapabilityUnavailableReason | null;
+  };
+  DesktopStream: {
+    transport: "vnc-ws" | "rdp-ws" | "webrtc" | null;
+    client: "novnc" | "web-rdp" | null;
+    mode: "read-only" | "interactive";
+    url: string | null;
+    token: string | null;
+    expiresAt: string | null;
+    resolution: [number, number];
+    unredacted: boolean;
+    requiresAcknowledgment: boolean;
+    acknowledged: boolean;
+    // Shared-exposure disclosure (addendum E.1): `shared` when the group has >1
+    // session; `sharedSessionIds` lists the OTHER sessions' ids ONLY (never their
+    // conversation/metadata).
+    shared: boolean;
+    sharedSessionIds: string[];
+    reason: CapabilityUnavailableReason | null;
+  };
+  Recording: {
+    available: boolean;
+    modes: ("manual" | "on-turn" | "on-verify")[];
+    codecs: ("h264-mp4" | "vp9-webm")[];
+    reason: CapabilityUnavailableReason | null;
+  };
+  ComputerUse: {
+    available: boolean;
+    readOnly: boolean;
+    reason: CapabilityUnavailableReason | null;
+  };
+  negotiatedAt: string;
+};
+
+// Convenience aliases for the per-surface cells of `SessionCapabilities`, so the
+// client hooks/components can take a single cell without restating the inline
+// shape. These are exact structural views of the cells above.
+export type FileSystemCapability = SessionCapabilities["FileSystem"];
+export type TerminalCapability = SessionCapabilities["Terminal"];
+export type GitCapability = SessionCapabilities["Git"];
+export type DesktopStreamCapability = SessionCapabilities["DesktopStream"];
+export type RecordingCapability = SessionCapabilities["Recording"];
+export type ComputerUseCapability = SessionCapabilities["ComputerUse"];
+
+// ── Stream-surfacing client surface (Phase 5) ───────────────────────────────
+// Mirrors of the contracts viewer-attach / acknowledge / heartbeat shapes that
+// the capability-gated client (`@opengeni/react`) drives. The desktop pixel
+// plane rides Channel B (direct-to-provider noVNC); the structured terminal/
+// files/git surfaces ride Channel A (the existing event spine + the synchronous
+// fs/git/terminal point queries above). These are TYPES only (the SDK keeps zero
+// runtime deps); the contract-parity test pins them.
+
+// Mirror of `@opengeni/contracts` StreamUrlRotatedPayload — the Channel-A event
+// the client folds in to hot-swap its noVNC socket on a box rollover, fenced on
+// leaseEpoch.
+export type StreamUrlRotatedPayload = {
+  url: string;
+  token: string | null;
+  expiresAt: string | null;
+  leaseEpoch: number;
+  transport: "vnc-ws";
+  viewerId: string | null;
+};
+export type StreamOpenedPayload = { viewerId: string; shared: boolean; viewerCount: number };
+export type StreamClosedPayload = {
+  viewerId: string;
+  reason: "client-disconnect" | "reaped" | "revoked" | "box-rollover";
+  viewerCount: number;
+};
+export type StreamRevokedPayload = {
+  viewerId: string | null;
+  reason: "grant-revoked" | "session-failed" | "admin";
+};
+
+// Mirror of `@opengeni/contracts` AttachViewerRequest. Omitting `viewerId` mints
+// a fresh holder id (returned on the response, carried through heartbeat/detach).
+// `desktop:true` opts into the un-redacted pixel plane (the consent-gated noVNC
+// stream); a terminal/files-only warm attach omits it (defaults false) so it
+// warms the box + mints the pty-ws terminal cell WITHOUT tripping the consent 409.
+export type AttachViewerRequest = { viewerId?: string | undefined; desktop?: boolean | undefined };
+
+// Mirror of `@opengeni/contracts` ViewerHolder + the P4.2 desktop-stream fields
+// the POST /viewers handler folds in when the pixel plane is minted in-process.
+export type ViewerHolder = {
+  viewerId: string;
+  sandboxGroupId: string;
+  liveness: "cold" | "warming" | "warm" | "draining";
+  leaseEpoch: number;
+  viewerHeartbeatIntervalMs: number;
+  dataPlaneUrl: string | null;
+};
+export type AttachViewerResponse = ViewerHolder & {
+  // The scoped desktop-stream address minted for THIS holder (P4.2). Null when
+  // the deployment is headless / desktop is disabled / the mint degraded —
+  // the client then falls back to the Channel-A surfaces only.
+  streamToken: string | null;
+  streamExpiresAt: string | null;
+  resolution: [number, number] | null;
+  transport: "vnc-ws" | null;
+  client: "novnc" | null;
+  // The scoped ttyd PTY-over-websocket address minted for THIS holder — the REAL
+  // interactive terminal, symmetric with the desktop pixel plane (same Modal
+  // tunnel, same scoped stream token). Populated on a warm box; null when the
+  // terminal mint degraded (headless / no secret / tunnel failure), in which case
+  // the client falls back to the Channel-A read-only command-output firehose.
+  // `terminalTransport` is "pty-ws" iff a live `terminalUrl` was minted.
+  terminalUrl: string | null;
+  terminalToken: string | null;
+  terminalTransport: "pty-ws" | null;
+};
+
+// Mirror of `@opengeni/contracts` AcknowledgeStreamRequest/Response — the
+// un-redacted-pixel + shared-exposure consent gate (P3.2).
+export type AcknowledgeStreamRequest = {
+  acknowledgeUnredacted?: boolean | undefined;
+  acknowledgeShared?: boolean | undefined;
+};
+export type AcknowledgeStreamResponse = { acknowledged: boolean; acknowledgedShared: boolean };
+
+// Mirror of `@opengeni/contracts` ViewerHeartbeatRequest/Response — the
+// Channel-A viewer-liveness ping, epoch-fenced (a stale-epoch beat → alive:false
+// → the client re-attaches).
+export type ViewerHeartbeatRequest = { leaseEpoch: number };
+export type ViewerHeartbeatResponse = { alive: boolean };
 
 export type ReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
@@ -130,6 +316,23 @@ export const SESSION_EVENT_TYPES = [
   "goal.paused",
   "goal.resumed",
   "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",
 ] as const;
 
 export type KnownSessionEventType = (typeof SESSION_EVENT_TYPES)[number];
@@ -166,6 +369,144 @@ export type AgentToolCallCreatedPayload = {
 export type AgentToolCallOutputPayload = { id: string | null; output: unknown };
 export type SessionStatusChangedPayload = { status: SessionStatus };
 
+// Recording payloads (P4.3 — plain TS mirror of the contracts Zod schemas; the
+// SDK is zero-runtime-dep so these are TYPES, not Zod, F15). The contract-parity
+// test asserts the event-type literals; these shapes document the wire payloads.
+export type RecordingMode = "manual" | "on-turn" | "on-verify";
+export type RecordingCodec = "h264-mp4" | "vp9-webm";
+export type RecordingContentType = "video/mp4" | "video/webm";
+export type RecordingFailedReason =
+  | "ffmpeg-error"
+  | "box-death"
+  | "box-rollover"
+  | "upload-failed"
+  | "max-bytes-exceeded"
+  | "display-unavailable";
+
+export type RecordingStartedPayload = {
+  recordingId: string;
+  turnId: string | null;
+  mode: RecordingMode;
+  codec: RecordingCodec;
+  dimensions: [number, number];
+  framerate: number;
+  startedAt: string;
+  reason?: string | null | undefined;
+};
+export type RecordingAvailablePayload = {
+  recordingId: string;
+  turnId: string | null;
+  codec: RecordingCodec;
+  contentType: RecordingContentType;
+  storageKey: string;
+  durationSeconds: number | null;
+  sizeBytes: number;
+  dimensions: [number, number];
+};
+export type RecordingFailedPayload = {
+  recordingId: string;
+  turnId: string | null;
+  reason: RecordingFailedReason;
+  detail?: string | null | undefined;
+};
+
+// ── Channel-A structured services (P4.4) — hand-written wire mirrors ─────────
+
+// A1 notification payloads.
+export type SandboxCommandOutputDeltaPayload = {
+  stream: "stdout" | "stderr";
+  chunk: string;
+  commandId?: string | undefined;
+  seq?: number | undefined;
+};
+export type FsChangeKind = "created" | "modified" | "deleted" | "renamed";
+export type FsChangedPayload = {
+  changes: { path: string; kind: FsChangeKind; isDir: boolean; sizeBytes: number | null; oldPath?: string | undefined }[];
+  source: "write" | "watch" | "agent";
+  revision: number;
+  leaseEpoch: number;
+};
+export type GitChangedPayload = {
+  head: string | null;
+  dirty: boolean;
+  ahead: number;
+  behind: number;
+  changedFileCount: number;
+  reason: "commit" | "checkout" | "stage" | "worktree" | "fetch" | "unknown";
+  revision: number;
+  leaseEpoch: number;
+};
+export type TerminalPtyStartedPayload = { ptyId: string; cols: number; rows: number; shell: string; cwd: string };
+export type TerminalPtyOutputDeltaPayload = { ptyId: string; stream: "stdout" | "stderr"; chunk: string; seq: number };
+export type TerminalPtyExitedPayload = { ptyId: string; exitCode: number | null; reason: "exit" | "killed" | "owner_gone" | "timeout" };
+
+// A2 FileSystem request/response.
+export type FsNodeType = "file" | "dir" | "symlink" | "other";
+export type FsTreeNode = {
+  name: string;
+  path: string;
+  type: FsNodeType;
+  sizeBytes: number | null;
+  mtimeMs: number | null;
+  mode: number | null;
+  children?: FsTreeNode[] | undefined;
+  truncated: boolean;
+};
+export type FsEncoding = "utf8" | "base64";
+export type FsListRequest = { path?: string; depth?: number; maxEntries?: number; includeHidden?: boolean };
+export type FsListResponse = { root: FsTreeNode; revision: number; truncated: boolean };
+export type FsReadRequest = { path: string; encoding?: FsEncoding; maxBytes?: number };
+export type FsReadResponse = { path: string; encoding: FsEncoding; content: string; sizeBytes: number; truncated: boolean; isBinary: boolean; revision: number };
+export type FsWriteRequest = { path: string; encoding?: FsEncoding; content: string; overwrite?: boolean; createParents?: boolean };
+export type FsWriteResponse = { path: string; sizeBytes: number; revision: number };
+export type FsDeleteRequest = { path: string; recursive?: boolean };
+export type FsDeleteResponse = { revision: number };
+export type FsMoveRequest = { path: string; newPath: string; overwrite?: boolean; createParents?: boolean };
+export type FsMoveResponse = { path: string; newPath: string; revision: number };
+export type FsMkdirRequest = { path: string; recursive?: boolean };
+export type FsMkdirResponse = { path: string; revision: number };
+
+// A2 Git request/response (the Pierre-diff feed).
+export type GitFileStatusCode = "added" | "modified" | "deleted" | "renamed" | "copied" | "untracked" | "ignored" | "conflicted" | "typechange";
+export type GitFileStatus = { path: string; oldPath: string | null; index: GitFileStatusCode | null; worktree: GitFileStatusCode | null; isConflicted: boolean };
+export type GitStatusRequest = { path?: string };
+export type GitStatusResponse = { isRepo: boolean; head: string | null; detached: boolean; upstream: string | null; ahead: number; behind: number; files: GitFileStatus[]; revision: number };
+export type GitDiffLineType = "context" | "add" | "del" | "meta";
+export type GitDiffLine = { type: GitDiffLineType; oldNo: number | null; newNo: number | null; text: string };
+export type GitDiffHunk = { oldStart: number; oldLines: number; newStart: number; newLines: number; header: string; lines: GitDiffLine[] };
+export type GitFileDiff = { path: string; oldPath: string | null; status: GitFileStatusCode; isBinary: boolean; isImage: boolean; additions: number; deletions: number; hunks: GitDiffHunk[]; truncated: boolean };
+export type GitDiffRequest = { path?: string; staged?: boolean; fromRef?: string; toRef?: string; pathspec?: string[]; contextLines?: number; maxBytesPerFile?: number };
+export type GitDiffResponse = { files: GitFileDiff[]; revision: number };
+export type GitLogRequest = { path?: string; ref?: string; maxCount?: number; skip?: number; pathspec?: string[] };
+export type GitCommit = {
+  sha: string;
+  shortSha: string;
+  parents: string[];
+  author: { name: string; email: string; timestamp: number };
+  committer: { name: string; email: string; timestamp: number };
+  subject: string;
+  body: string;
+  refs: string[];
+};
+export type GitLogResponse = { commits: GitCommit[]; hasMore: boolean };
+export type GitShowRequest = { path?: string; ref: string; filePath?: string; encoding?: FsEncoding; maxBytesPerFile?: number };
+export type GitShowResponse = { commit: GitCommit | null; files: GitFileDiff[]; blob: { content: string; encoding: FsEncoding; sizeBytes: number; truncated: boolean } | null; revision: number };
+
+// A2 Terminal exec + PTY.
+export type TerminalExecRequest = { command: string; cwd?: string; timeoutMs?: number; emitStream?: boolean };
+export type TerminalExecResponse = { stdout: string; stderr: string; exitCode: number | null; running: boolean; wallTimeSeconds: number };
+export type PtyOpenRequest = { cols?: number; rows?: number; cwd?: string; shell?: string };
+export type PtyOpenResponse = { ptyId: string; streamVia: "sse-events"; supportsInput: boolean };
+export type PtyWriteRequest = { ptyId: string; data: string };
+export type PtyResizeRequest = { ptyId: string; cols: number; rows: number };
+export type PtyCloseRequest = { ptyId: string };
+
+export type SessionStructuredCapabilities = {
+  FileSystem: { available: boolean; readOnly: boolean; root: string };
+  Terminal: { events: boolean; exec: boolean; pty: { available: boolean } };
+  Git: { available: boolean; repos: string[] };
+};
+
 export type ScheduledTaskStatus = "active" | "paused";
 
 export type ScheduledTaskRunMode = "new_session_per_run" | "reusable_session";
@@ -258,8 +599,17 @@ export const 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",
@@ -282,6 +632,58 @@ export type Permission = KnownPermission | (string & {});
 
 export type ProductAccessMode = "local" | "configured" | "managed";
 
+/**
+ * One model a client may select at send time, plus the provider that serves it.
+ * The wire API (`responses` | `chat`) lets a client reason about provider
+ * capabilities; the provider id/label drive a picker's grouping. Mirrors the
+ * `ClientModel` shape projected into `ClientConfig` by the server.
+ */
+export type ClientModel = {
+  id: string;
+  label: string;
+  /** Provider id (e.g. `openai`, `azure`, or a registry provider id). */
+  provider: string;
+  providerLabel: string;
+  api: "responses" | "chat";
+  contextWindowTokens?: number | undefined;
+};
+
+/**
+ * How a deployment expects clients to authenticate to it, surfaced so a UI can
+ * wire up the right header/cookie without prior knowledge of the host setup.
+ * Discriminated on `mode`; `none` is the back-compat default.
+ */
+export type ClientAuthConfig =
+  | { mode: "none" }
+  | { mode: "deploymentKey"; headerName: "x-opengeni-access-key" }
+  | { mode: "configuredToken"; headerName: "authorization"; scheme: "bearer" }
+  | { mode: "managedSession"; session: "cookie" };
+
+/**
+ * Public, unauthenticated-by-default client bootstrap config returned by
+ * `GET /v1/config/client`: which models + reasoning efforts are exposed, the
+ * MCP servers and file-upload limits a composer should offer, and how the
+ * deployment expects the client to authenticate. `allowedModels` is kept for
+ * back-compat; `models` carries the richer provider-grouped list for a picker.
+ */
+export type ClientConfig = {
+  deploymentRevision: string;
+  defaultModel: string;
+  allowedModels: string[];
+  models: ClientModel[];
+  defaultReasoningEffort: ReasoningEffort;
+  allowedReasoningEfforts: ReasoningEffort[];
+  mcpServers: { id: string; name: string }[];
+  fileUploads: { enabled: boolean; maxSizeBytes: number };
+  productAccessMode: ProductAccessMode;
+  auth: ClientAuthConfig;
+  // Server-wide hint: does this deployment support Channel-A structured services
+  // at all (P4.4). Per-session availability is negotiated on /stream-capabilities;
+  // this is the coarse on/off the client uses to decide whether to even attempt
+  // the fs/git/terminal panels.
+  structuredServices: { fileSystem: boolean; git: boolean; terminalEvents: boolean };
+};
+
 export type AccountRole = "owner" | "admin" | "member";
 
 export type AccountGrant = {
@@ -369,6 +771,32 @@ export type ListApiKeysResponse = {
   apiKeys: ApiKey[];
 };
 
+// A person (or API key) with access to a workspace. `subjectId` is
+// `user:<betterAuthUserId>` or `api_key:<id>`; the People surface lists the
+// `user:` subjects (api_key subjects belong to the API keys section).
+export type WorkspaceMember = {
+  subjectId: string;
+  subjectLabel: string | null;
+  role: string;
+  permissions: Permission[];
+  createdAt: string;
+};
+
+export type ListWorkspaceMembersResponse = {
+  members: WorkspaceMember[];
+};
+
+export type AddWorkspaceMemberRequest = {
+  email: string;
+  role?: string | undefined;
+  permissions: Permission[];
+};
+
+export type UpdateWorkspaceMemberRequest = {
+  role?: string | undefined;
+  permissions: Permission[];
+};
+
 // --- Goals -------------------------------------------------------------------
 
 export type SessionGoalStatus = "active" | "paused" | "completed";
@@ -945,6 +1373,9 @@ export const KNOWN_USAGE_EVENT_TYPES = [
   "document.indexed",
   "scheduled_task.fired",
   "api_key.request",
+  // sandbox warm-time metering (P2.1) — mirrors contracts UsageEventType.
+  "sandbox.warm_seconds",
+  "sandbox.warm_cost",
 ] as const;
 
 export type KnownUsageEventType = (typeof KNOWN_USAGE_EVENT_TYPES)[number];