@agent-commons/sdk 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -1,30 +1,95 @@
 // src/client.ts
 var CommonsClient = class {
   constructor(config) {
-    this.baseUrl = (config.baseUrl ?? "https://api.agentcommons.io").replace(/\/$/, "");
+    this.baseUrl = (config.baseUrl ?? "https://api.agentcommons.io").replace(
+      /\/$/,
+      ""
+    );
+    this.identityUrl = (config.identityUrl ?? "https://auth.agentcommons.io").replace(/\/api\/auth\/?$/, "").replace(/\/$/, "");
+    this.identityToken = config.identityToken;
     this.apiKey = config.apiKey;
     this.initiator = config.initiator;
     this._fetch = config.fetch ?? fetch;
   }
   // ── Helpers ───────────────────────────────────────────────────────────────
-  headers(extra) {
-    const h = { "Content-Type": "application/json" };
+  headers(extra, json = true) {
+    const h = {};
+    if (json) h["Content-Type"] = "application/json";
     if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;
     if (this.initiator) h["x-initiator"] = this.initiator;
     return { ...h, ...extra };
   }
-  async request(method, path, body) {
+  /**
+   * Call an API route that is not yet represented by a resource namespace.
+   * Most applications should use the typed helpers below.
+   */
+  async request(method, path, body, options = {}) {
+    const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
     const res = await this._fetch(`${this.baseUrl}${path}`, {
       method,
-      headers: this.headers(),
-      body: body !== void 0 ? JSON.stringify(body) : void 0
+      headers: this.headers(options.headers, !isFormData),
+      body: body === void 0 ? void 0 : isFormData ? body : JSON.stringify(body),
+      signal: options.signal
     });
     if (!res.ok) {
-      const err = await res.json().catch(() => ({ message: res.statusText }));
-      throw new CommonsError(err.message ?? res.statusText, res.status, err);
+      const err = await this.errorPayload(res);
+      throw new CommonsError(
+        this.errorMessage(err, res.statusText),
+        res.status,
+        err
+      );
+    }
+    if (res.status === 204) return void 0;
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.includes("json")) {
+      return await res.text();
     }
     return res.json();
   }
+  async errorPayload(res) {
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes("json")) {
+      return res.json().catch(() => ({ message: res.statusText }));
+    }
+    const message = await res.text().catch(() => "");
+    return { message: message || res.statusText };
+  }
+  errorMessage(error, fallback) {
+    if (!error || typeof error !== "object") return fallback;
+    if ("message" in error && typeof error.message === "string") {
+      return error.message;
+    }
+    if ("error" in error) {
+      if (typeof error.error === "string") return error.error;
+      if (error.error && typeof error.error === "object" && "message" in error.error && typeof error.error.message === "string") {
+        return error.error.message;
+      }
+    }
+    return fallback;
+  }
+  async identityRequest(method, path, body) {
+    const headers = {};
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    if (this.identityToken) {
+      headers.Authorization = `Bearer ${this.identityToken}`;
+    }
+    const response = await this._fetch(`${this.identityUrl}${path}`, {
+      method,
+      headers,
+      credentials: "include",
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const error = await this.errorPayload(response);
+      throw new CommonsError(
+        this.errorMessage(error, response.statusText),
+        response.status,
+        error
+      );
+    }
+    if (response.status === 204) return void 0;
+    return response.json();
+  }
   // ── Models ────────────────────────────────────────────────────────────────
   get models() {
     return {
@@ -39,12 +104,31 @@ var CommonsClient = class {
       list: (owner) => this.request("GET", `/v1/agents${owner ? `?owner=${owner}` : ""}`),
       get: (agentId) => this.request("GET", `/v1/agents/${agentId}`),
       update: (agentId, params) => this.request("PUT", `/v1/agents/${agentId}`, params),
+      getRuntime: (agentId) => this.request("GET", `/v1/agents/${agentId}/runtime`),
+      configureRuntime: (agentId, params) => this.request("PUT", `/v1/agents/${agentId}/runtime`, params),
+      deployRuntime: (agentId) => this.request("POST", `/v1/agents/${agentId}/runtime/deploy`),
+      sleepRuntime: (agentId) => this.request("POST", `/v1/agents/${agentId}/runtime/sleep`),
+      restartRuntime: (agentId) => this.request("POST", `/v1/agents/${agentId}/runtime/restart`),
+      manageRuntimeChannel: (agentId, channel, action, params = {}) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(agentId)}/runtime/channels/${encodeURIComponent(channel)}/${encodeURIComponent(action)}`,
+        params
+      ),
       /** List tools assigned to an agent. */
       listTools: (agentId) => this.request("GET", `/v1/agents/${agentId}/tools`),
       /** Assign a tool to an agent. */
       addTool: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/tools`, params),
+      /** Update an agent tool assignment. */
+      updateTool: (assignmentId, params) => this.request(
+        "PATCH",
+        `/v1/agents/tools/${encodeURIComponent(assignmentId)}`,
+        params
+      ),
       /** Remove a tool assignment from an agent. */
-      removeTool: (assignmentId) => this.request("DELETE", `/v1/agents/tools/${assignmentId}`),
+      removeTool: (assignmentId) => this.request(
+        "DELETE",
+        `/v1/agents/tools/${encodeURIComponent(assignmentId)}`
+      ),
       /** Create a liaison agent for an external agent. */
       createLiaison: (params) => this.request("POST", "/v1/liaison", params),
       /**
@@ -57,6 +141,11 @@ var CommonsClient = class {
        * }
        */
       stream: (params) => this._streamAgentRun(params),
+      /** Resume a streamed run after executing a caller-owned CLI tool. */
+      submitCliToolResult: (requestId, result) => this.request("POST", "/v1/agents/cli-tool-result", {
+        requestId,
+        result
+      }),
       // ── Heartbeat ─────────────────────────────────────────────────────────
       /** Get the current heartbeat status for an agent. */
       getAutonomy: (agentId) => this.request("GET", `/v1/agents/${agentId}/autonomy`),
@@ -73,32 +162,100 @@ var CommonsClient = class {
       /** Get the knowledgebase entries for an agent. */
       getKnowledgebase: (agentId) => this.request("GET", `/v1/agents/${agentId}/knowledgebase`),
       /** Replace the knowledgebase entries for an agent. */
-      updateKnowledgebase: (agentId, knowledgebase) => this.request("PUT", `/v1/agents/${agentId}/knowledgebase`, { knowledgebase }),
+      updateKnowledgebase: (agentId, knowledgebase) => this.request("PUT", `/v1/agents/${agentId}/knowledgebase`, {
+        knowledgebase
+      }),
       // ── Preferred Connections ────────────────────────────────────────────
       /** List agents that this agent prefers to collaborate with. */
       getPreferredConnections: (agentId) => this.request("GET", `/v1/agents/${agentId}/preferred-connections`),
       /** Add a preferred agent connection. */
-      addPreferredConnection: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/preferred-connections`, params),
+      addPreferredConnection: (agentId, params) => this.request(
+        "POST",
+        `/v1/agents/${agentId}/preferred-connections`,
+        params
+      ),
       /** Remove a preferred agent connection by its record ID. */
       removePreferredConnection: (id) => this.request("DELETE", `/v1/agents/preferred-connections/${id}`),
       // ── Computers ────────────────────────────────────────────────────────
       getComputerConfig: (agentId) => this.request("GET", `/v1/agents/${agentId}/computer/config`),
       updateComputerConfig: (agentId, params) => this.request("PUT", `/v1/agents/${agentId}/computer/config`, params),
-      listComputers: (agentId, filter) => {
-        const qs = new URLSearchParams();
-        if (filter?.sessionId) qs.set("sessionId", filter.sessionId);
-        if (filter?.includeTerminated) qs.set("includeTerminated", "true");
-        const query = qs.toString();
-        return this.request("GET", `/v1/agents/${agentId}/computers${query ? `?${query}` : ""}`);
-      },
-      startComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computers`, params),
-      getComputer: (agentId, computerId) => this.request("GET", `/v1/agents/${agentId}/computers/${computerId}`),
-      refreshComputer: (agentId, computerId) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/refresh`),
-      stopComputer: (agentId, computerId) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/stop`),
-      readComputerFile: (agentId, computerId, path) => this.request("GET", `/v1/agents/${agentId}/computers/${computerId}/files/read?path=${encodeURIComponent(path)}`),
-      runComputerCommand: (agentId, computerId, params) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/commands`, params),
-      openComputerBrowser: (agentId, computerId, params) => this.request("POST", `/v1/agents/${agentId}/computers/${computerId}/browser/open`, params),
-      listComputerEvents: (agentId, computerId, limit) => this.request("GET", `/v1/agents/${agentId}/computers/${computerId}/events${limit ? `?limit=${limit}` : ""}`),
+      /** Get the agent's one persistent cloud computer. */
+      getComputer: (agentId, _legacyComputerId) => this.request("GET", `/v1/agents/${agentId}/computer`),
+      /** Wake the agent's persistent cloud computer, provisioning it if needed. */
+      wakeComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computer/wake`, params),
+      /** Sleep the runtime while preserving the computer's durable workspace. */
+      sleepComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computer/sleep`, params),
+      /** Replace the runtime without replacing the persistent computer. */
+      restartComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computer/restart`, params),
+      resizeComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computer/resize`, params),
+      execComputer: (agentId, params) => this.request("POST", `/v1/agents/${agentId}/computer/exec`, params),
+      readComputerFile: (agentId, pathOrLegacyComputerId, legacyPath) => {
+        const path = legacyPath ?? pathOrLegacyComputerId;
+        return this.request(
+          "GET",
+          `/v1/agents/${agentId}/computer/files/read?path=${encodeURIComponent(path)}`
+        );
+      },
+      writeComputerFile: (agentId, params) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(agentId)}/computer/files/write`,
+        params
+      ),
+      openComputerBrowser: (agentId, paramsOrLegacyComputerId, legacyParams) => {
+        const params = typeof paramsOrLegacyComputerId === "string" ? legacyParams : paramsOrLegacyComputerId;
+        if (!params) {
+          return Promise.reject(new TypeError("Browser options are required."));
+        }
+        return this.request(
+          "POST",
+          `/v1/agents/${agentId}/computer/browser/open`,
+          params
+        );
+      },
+      testComputerBrowser: (agentId) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(agentId)}/computer/browser/test`,
+        {}
+      ),
+      listComputerEvents: (agentId, limitOrLegacyComputerId, legacyLimit) => {
+        const limit = typeof limitOrLegacyComputerId === "number" ? limitOrLegacyComputerId : legacyLimit;
+        return this.request(
+          "GET",
+          `/v1/agents/${agentId}/computer/events${limit ? `?limit=${limit}` : ""}`
+        );
+      },
+      // ── Deprecated per-instance compatibility ────────────────────────────
+      /** @deprecated Use getComputer. The singleton is returned as a one-item list. */
+      listComputers: (agentId, _filter) => {
+        return this.request(
+          "GET",
+          `/v1/agents/${agentId}/computer`
+        ).then(({ data }) => ({
+          data: data ? [data] : []
+        }));
+      },
+      /** @deprecated Use wakeComputer. Lifecycle, name, and session are ignored. */
+      startComputer: (agentId, params) => this.request(
+        "POST",
+        `/v1/agents/${agentId}/computer/wake`,
+        params?.reason ? { reason: params.reason } : void 0
+      ),
+      /** @deprecated Use getComputer. Computer IDs are ignored. */
+      refreshComputer: (agentId, _computerId) => this.request("GET", `/v1/agents/${agentId}/computer`),
+      /** @deprecated Use sleepComputer. Computer IDs are ignored. */
+      stopComputer: (agentId, _computerId) => this.request("POST", `/v1/agents/${agentId}/computer/sleep`),
+      /** @deprecated Use execComputer. Computer IDs are ignored. */
+      runComputerCommand: (agentId, paramsOrLegacyComputerId, legacyParams) => {
+        const params = typeof paramsOrLegacyComputerId === "string" ? legacyParams : paramsOrLegacyComputerId;
+        if (!params) {
+          return Promise.reject(new TypeError("Command options are required."));
+        }
+        return this.request(
+          "POST",
+          `/v1/agents/${agentId}/computer/exec`,
+          params
+        );
+      },
       // ── TTS Voices ───────────────────────────────────────────────────────
       /**
        * List available TTS voices for a provider.
@@ -110,10 +267,33 @@ var CommonsClient = class {
         if (provider) params.set("provider", provider);
         if (q) params.set("q", q);
         const qs = params.toString();
-        return this.request("GET", `/v1/agents/tts/voices${qs ? `?${qs}` : ""}`);
+        return this.request(
+          "GET",
+          `/v1/agents/tts/voices${qs ? `?${qs}` : ""}`
+        );
       }
     };
   }
+  get copilot() {
+    return {
+      get: () => this.request("GET", "/v1/copilot"),
+      updateSettings: (params) => this.request("PUT", "/v1/copilot/settings", params),
+      listChanges: (filter) => {
+        const query = new URLSearchParams();
+        if (filter?.status) query.set("status", filter.status);
+        if (filter?.resourceType)
+          query.set("resourceType", filter.resourceType);
+        if (filter?.resourceId) query.set("resourceId", filter.resourceId);
+        return this.request(
+          "GET",
+          `/v1/copilot/changes${query.size ? `?${query}` : ""}`
+        );
+      },
+      acceptChange: (changeId) => this.request("POST", `/v1/copilot/changes/${changeId}/accept`),
+      rejectChange: (changeId) => this.request("POST", `/v1/copilot/changes/${changeId}/reject`),
+      revertChange: (changeId) => this.request("POST", `/v1/copilot/changes/${changeId}/revert`)
+    };
+  }
   // ── Run (non-streaming) ───────────────────────────────────────────────────
   get run() {
     return {
@@ -124,20 +304,78 @@ var CommonsClient = class {
   get workflows() {
     return {
       create: (params) => this.request("POST", "/v1/workflows", params),
-      list: (ownerId, ownerType) => this.request("GET", `/v1/workflows?ownerId=${ownerId}&ownerType=${ownerType}`),
+      list: (ownerId, ownerType) => this.request(
+        "GET",
+        `/v1/workflows?ownerId=${ownerId}&ownerType=${ownerType}`
+      ),
+      discoverPublic: (filter) => {
+        const query = new URLSearchParams();
+        if (filter?.category) query.set("category", filter.category);
+        if (filter?.tags?.length) query.set("tags", filter.tags.join(","));
+        if (filter?.limit) query.set("limit", String(filter.limit));
+        return this.request(
+          "GET",
+          `/v1/workflows/public${query.size ? `?${query}` : ""}`
+        );
+      },
       get: (workflowId) => this.request("GET", `/v1/workflows/${workflowId}`),
       update: (workflowId, updates) => this.request("PUT", `/v1/workflows/${workflowId}`, updates),
       delete: (workflowId) => this.request("DELETE", `/v1/workflows/${workflowId}`),
+      fork: (workflowId, params) => this.request(
+        "POST",
+        `/v1/workflows/${encodeURIComponent(workflowId)}/fork`,
+        params
+      ),
+      getWebhook: (workflowId) => this.request(
+        "GET",
+        `/v1/workflows/${encodeURIComponent(workflowId)}/webhook`
+      ),
+      rotateWebhookToken: (workflowId) => this.request(
+        "POST",
+        `/v1/workflows/${encodeURIComponent(workflowId)}/webhook-token`,
+        {}
+      ),
+      disableWebhook: (workflowId) => this.request(
+        "DELETE",
+        `/v1/workflows/${encodeURIComponent(workflowId)}/webhook-token`
+      ),
+      executeWebhook: (token, payload, query) => {
+        const search = query ? new URLSearchParams(query).toString() : "";
+        return this.request(
+          "POST",
+          `/v1/workflows/webhooks/${encodeURIComponent(token)}${search ? `?${search}` : ""}`,
+          payload
+        );
+      },
       execute: (workflowId, params) => this.request("POST", `/v1/workflows/${workflowId}/execute`, params),
-      getExecution: (workflowId, executionId) => this.request("GET", `/v1/workflows/${workflowId}/executions/${executionId}`),
-      listExecutions: (workflowId, limit) => this.request("GET", `/v1/workflows/${workflowId}/executions${limit ? `?limit=${limit}` : ""}`),
-      cancelExecution: (workflowId, executionId) => this.request("POST", `/v1/workflows/${workflowId}/executions/${executionId}/cancel`),
+      getExecution: (workflowId, executionId) => this.request(
+        "GET",
+        `/v1/workflows/${workflowId}/executions/${executionId}`
+      ),
+      listExecutions: (workflowId, limit) => this.request(
+        "GET",
+        `/v1/workflows/${workflowId}/executions${limit ? `?limit=${limit}` : ""}`
+      ),
+      cancelExecution: (workflowId, executionId) => this.request(
+        "POST",
+        `/v1/workflows/${workflowId}/executions/${executionId}/cancel`
+      ),
       /** Approve a paused human_approval node and resume execution. */
-      approveExecution: (workflowId, executionId, params) => this.request("POST", `/v1/workflows/${workflowId}/executions/${executionId}/approve`, params),
+      approveExecution: (workflowId, executionId, params) => this.request(
+        "POST",
+        `/v1/workflows/${workflowId}/executions/${executionId}/approve`,
+        params
+      ),
       /** Reject a paused human_approval node and terminate execution. */
-      rejectExecution: (workflowId, executionId, params) => this.request("POST", `/v1/workflows/${workflowId}/executions/${executionId}/reject`, params),
+      rejectExecution: (workflowId, executionId, params) => this.request(
+        "POST",
+        `/v1/workflows/${workflowId}/executions/${executionId}/reject`,
+        params
+      ),
       /** Stream execution progress via SSE. Returns an async generator. */
-      stream: (workflowId, executionId) => this._streamSse(`/v1/workflows/${workflowId}/executions/${executionId}/stream`)
+      stream: (workflowId, executionId) => this._streamSse(
+        `/v1/workflows/${workflowId}/executions/${executionId}/stream`
+      )
     };
   }
   // ── Tasks ─────────────────────────────────────────────────────────────────
@@ -167,11 +405,30 @@ var CommonsClient = class {
       /** List all sessions for a given agent (all initiators). */
       listByAgent: (agentId) => this.request("GET", `/v1/sessions/agent/${agentId}`),
       /** List all sessions for a user across all agents. */
-      listByUser: (initiator) => this.request("GET", `/v1/sessions/user/${encodeURIComponent(initiator)}`),
+      listByUser: (initiator) => this.request(
+        "GET",
+        `/v1/sessions/user/${encodeURIComponent(initiator)}`
+      ),
       create: (params) => this.request("POST", "/v1/sessions", params),
       get: (sessionId) => this.request("GET", `/v1/sessions/${sessionId}`),
       /** Get full session with history, tasks, childSessions, and spaces. */
-      getFull: (sessionId) => this.request("GET", `/v1/sessions/${sessionId}/full`)
+      getFull: (sessionId) => this.request("GET", `/v1/sessions/${sessionId}/full`),
+      /** Rename a session. */
+      rename: (sessionId, title) => this.request(
+        "PATCH",
+        `/v1/sessions/${encodeURIComponent(sessionId)}`,
+        { title }
+      ),
+      /** Delete a session and its owned session data. */
+      delete: (sessionId) => this.request(
+        "DELETE",
+        `/v1/sessions/${encodeURIComponent(sessionId)}`
+      ),
+      /** Get the full chat transcript for a session. */
+      getChat: (sessionId) => this.request(
+        "GET",
+        `/v1/agents/sessions/${encodeURIComponent(sessionId)}/chat`
+      )
     };
   }
   // ── Tools ─────────────────────────────────────────────────────────────────
@@ -189,26 +446,141 @@ var CommonsClient = class {
       listStatic: () => this.request("GET", "/v1/tools/static")
     };
   }
+  // ── OAuth Connections ─────────────────────────────────────────────────────
+  get oauth() {
+    return {
+      /** List OAuth providers available on the platform (Google Workspace, GitHub, …). */
+      listProviders: () => this.request("GET", "/v1/oauth/providers"),
+      /** Get one provider's details, including its scope groups. */
+      getProvider: (providerKey) => this.request(
+        "GET",
+        `/v1/oauth/providers/${encodeURIComponent(providerKey)}`
+      ),
+      /**
+       * List the caller's OAuth connections (the accounts agents act with).
+       * `ownerId` is only needed when authenticating with a management key.
+       */
+      listConnections: (params) => {
+        const q = params ? new URLSearchParams(params).toString() : "";
+        return this.request("GET", `/v1/oauth/connections${q ? `?${q}` : ""}`);
+      },
+      /** Get one OAuth connection. */
+      getConnection: (connectionId) => this.request(
+        "GET",
+        `/v1/oauth/connections/${encodeURIComponent(connectionId)}`
+      ),
+      /** Update connection metadata or its active status. */
+      updateConnection: (connectionId, params) => this.request(
+        "PUT",
+        `/v1/oauth/connections/${encodeURIComponent(connectionId)}`,
+        params
+      ),
+      /**
+       * Start an OAuth connect flow. Returns the authorization URL the user
+       * must open in a browser to grant access.
+       */
+      connect: (params) => this.request("POST", "/v1/oauth/connect", params),
+      /** Refresh a connection's access token now. */
+      refresh: (connectionId) => this.request(
+        "POST",
+        `/v1/oauth/connections/${encodeURIComponent(connectionId)}/refresh`
+      ),
+      /** Check whether a connection's token is valid. */
+      test: (connectionId) => this.request(
+        "GET",
+        `/v1/oauth/connections/${encodeURIComponent(connectionId)}/test`
+      ),
+      /** Revoke a connection and delete its tokens. */
+      revoke: (connectionId) => this.request(
+        "DELETE",
+        `/v1/oauth/connections/${encodeURIComponent(connectionId)}`
+      )
+    };
+  }
   // ── Tool Keys ─────────────────────────────────────────────────────────────
   get toolKeys() {
     return {
-      list: (filter) => {
-        const q = new URLSearchParams(filter).toString();
-        return this.request("GET", `/v1/tool-keys${q ? `?${q}` : ""}`);
-      },
+      list: () => this.request("GET", "/v1/tool-keys"),
       create: (params) => this.request("POST", "/v1/tool-keys", params),
-      delete: (keyId) => this.request("DELETE", `/v1/tool-keys/${keyId}`)
+      get: (keyId) => this.request(
+        "GET",
+        `/v1/tool-keys/${encodeURIComponent(keyId)}`
+      ),
+      updateMetadata: (keyId, params) => this.request(
+        "PUT",
+        `/v1/tool-keys/${encodeURIComponent(keyId)}/metadata`,
+        params
+      ),
+      updateValue: (keyId, value) => this.request(
+        "PUT",
+        `/v1/tool-keys/${encodeURIComponent(keyId)}/value`,
+        { value }
+      ),
+      test: (keyId) => this.request(
+        "POST",
+        `/v1/tool-keys/${encodeURIComponent(keyId)}/test`,
+        {}
+      ),
+      mapToTool: (params) => this.request("POST", "/v1/tool-keys/map", params),
+      removeMapping: (mappingId) => this.request(
+        "DELETE",
+        `/v1/tool-keys/map/${encodeURIComponent(mappingId)}`
+      ),
+      delete: (keyId) => this.request(
+        "DELETE",
+        `/v1/tool-keys/${encodeURIComponent(keyId)}`
+      )
     };
   }
   // ── Tool Permissions ──────────────────────────────────────────────────────
   get toolPermissions() {
     return {
-      list: (toolId) => {
-        const q = toolId ? `?toolId=${toolId}` : "";
-        return this.request("GET", `/v1/tool-permissions${q}`);
+      /** @deprecated Use listForTool with a tool ID. */
+      list: (toolId) => this.request(
+        "GET",
+        `/v1/tool-permissions/tool/${encodeURIComponent(toolId)}`
+      ),
+      listForTool: (toolId) => this.request(
+        "GET",
+        `/v1/tool-permissions/tool/${encodeURIComponent(toolId)}`
+      ),
+      listForSubject: (subjectId, subjectType) => {
+        const query = new URLSearchParams({ subjectId, subjectType });
+        return this.request(
+          "GET",
+          `/v1/tool-permissions/subject?${query}`
+        );
+      },
+      accessibleTools: (subjectId, subjectType) => {
+        const query = new URLSearchParams({ subjectId, subjectType });
+        return this.request(
+          "GET",
+          `/v1/tool-permissions/accessible-tools?${query}`
+        );
       },
       grant: (params) => this.request("POST", "/v1/tool-permissions/grant", params),
-      revoke: (permissionId) => this.request("DELETE", `/v1/tool-permissions/revoke/${permissionId}`)
+      batchGrant: (params) => this.request("POST", "/v1/tool-permissions/batch-grant", params),
+      revoke: (permissionId) => this.request(
+        "DELETE",
+        `/v1/tool-permissions/${encodeURIComponent(permissionId)}`
+      ),
+      check: (params) => this.request(
+        "GET",
+        `/v1/tool-permissions/check?${new URLSearchParams(params)}`
+      ),
+      checkAgentAccess: (toolId, agentId, userId) => {
+        const query = new URLSearchParams({ toolId, agentId });
+        if (userId) query.set("userId", userId);
+        return this.request(
+          "GET",
+          `/v1/tool-permissions/check-agent-access?${query}`
+        );
+      },
+      transferOwnership: (params) => this.request(
+        "POST",
+        "/v1/tool-permissions/transfer-ownership",
+        params
+      )
     };
   }
   // ── Skills ────────────────────────────────────────────────────────────────
@@ -218,7 +590,8 @@ var CommonsClient = class {
         const params = new URLSearchParams();
         if (filter?.ownerId) params.set("ownerId", filter.ownerId);
         if (filter?.ownerType) params.set("ownerType", filter.ownerType);
-        if (filter?.isPublic !== void 0) params.set("isPublic", String(filter.isPublic));
+        if (filter?.isPublic !== void 0)
+          params.set("isPublic", String(filter.isPublic));
         const qs = params.toString();
         return this.request("GET", `/v1/skills${qs ? `?${qs}` : ""}`);
       },
@@ -270,7 +643,34 @@ var CommonsClient = class {
       me: () => this.request("GET", "/v1/auth/me")
     };
   }
-  // ── API Keys ──────────────────────────────────────────────────────────────
+  // ── Developer projects and project API keys ──────────────────────────────
+  get developer() {
+    return {
+      scopes: () => this.identityRequest("GET", "/api/platform/scopes"),
+      listProjects: () => this.identityRequest("GET", "/api/platform/projects"),
+      createProject: (params) => this.identityRequest("POST", "/api/platform/projects", params),
+      listApiKeys: (projectId) => this.identityRequest(
+        "GET",
+        `/api/platform/projects/${encodeURIComponent(projectId)}/api-keys`
+      ),
+      createApiKey: (projectId, params) => this.identityRequest(
+        "POST",
+        `/api/platform/projects/${encodeURIComponent(projectId)}/api-keys`,
+        params
+      ),
+      revokeApiKey: (keyId) => this.identityRequest(
+        "DELETE",
+        `/api/platform/api-keys/${encodeURIComponent(keyId)}`
+      )
+    };
+  }
+  // ── Legacy principal API keys ─────────────────────────────────────────────
+  /**
+   * Legacy per-principal keys (`sk-ac-*`).
+   *
+   * New developer integrations should use `client.developer`, which creates
+   * project-scoped `csk_*` keys with explicit environments and scopes.
+   */
   get apiKeys() {
     return {
       /**
@@ -280,7 +680,10 @@ var CommonsClient = class {
       create: (params) => this.request("POST", "/v1/auth/api-keys", params),
       /** List all active API keys for a principal (key values not included). */
       list: (principalId, principalType) => {
-        const q = new URLSearchParams({ principalId, principalType }).toString();
+        const q = new URLSearchParams({
+          principalId,
+          principalType
+        }).toString();
         return this.request("GET", `/v1/auth/api-keys?${q}`);
       },
       /** Revoke (soft-delete) an API key by its UUID. */
@@ -363,7 +766,10 @@ var CommonsClient = class {
         params: { id: taskId }
       }).then((r) => r.result),
       /** List recent A2A tasks for an agent. */
-      listTasks: (agentId, limit) => this.request("GET", `/v1/a2a/${agentId}/tasks${limit ? `?limit=${limit}` : ""}`),
+      listTasks: (agentId, limit) => this.request(
+        "GET",
+        `/v1/a2a/${agentId}/tasks${limit ? `?limit=${limit}` : ""}`
+      ),
       /** Stream A2A task updates (SSE). */
       stream: (agentId, taskId) => this._streamSse(`/v1/a2a/${agentId}/tasks/${taskId}/stream`)
     };
@@ -372,11 +778,18 @@ var CommonsClient = class {
   get mcp() {
     return {
       /** List MCP servers for an owner. */
-      listServers: (ownerId, ownerType) => this.request("GET", `/v1/mcp/servers?ownerId=${ownerId}&ownerType=${ownerType}`),
+      listServers: (ownerId, ownerType) => this.request(
+        "GET",
+        `/v1/mcp/servers?ownerId=${ownerId}&ownerType=${ownerType}`
+      ),
       /** Create a new MCP server. */
       createServer: (params) => {
         const { ownerId, ownerType, ...dto } = params;
-        return this.request("POST", `/v1/mcp/servers?ownerId=${ownerId}&ownerType=${ownerType}`, dto);
+        return this.request(
+          "POST",
+          `/v1/mcp/servers?ownerId=${ownerId}&ownerType=${ownerType}`,
+          dto
+        );
       },
       /** Get MCP server by ID. */
       getServer: (serverId) => this.request("GET", `/v1/mcp/servers/${serverId}`),
@@ -397,15 +810,25 @@ var CommonsClient = class {
       /** List tools discovered from an MCP server. */
       listTools: (serverId) => this.request("GET", `/v1/mcp/servers/${serverId}/tools`),
       /** List all MCP tools across all servers for a given owner. */
-      listToolsByOwner: (ownerId, ownerType) => this.request("GET", `/v1/mcp/tools?ownerId=${ownerId}&ownerType=${ownerType}`),
+      listToolsByOwner: (ownerId, ownerType) => this.request(
+        "GET",
+        `/v1/mcp/tools?ownerId=${ownerId}&ownerType=${ownerType}`
+      ),
       /** List resources from an MCP server. */
       listResources: (serverId) => this.request("GET", `/v1/mcp/servers/${serverId}/resources`),
       /** Read a resource by URI. */
-      readResource: (serverId, uri) => this.request("GET", `/v1/mcp/servers/${serverId}/resources/read?uri=${encodeURIComponent(uri)}`),
+      readResource: (serverId, uri) => this.request(
+        "GET",
+        `/v1/mcp/servers/${serverId}/resources/read?uri=${encodeURIComponent(uri)}`
+      ),
       /** List prompts from an MCP server. */
       listPrompts: (serverId) => this.request("GET", `/v1/mcp/servers/${serverId}/prompts`),
       /** Render a prompt with arguments. */
-      getPrompt: (serverId, promptName, args) => this.request("POST", `/v1/mcp/servers/${serverId}/prompts/${promptName}`, { arguments: args })
+      getPrompt: (serverId, promptName, args) => this.request(
+        "POST",
+        `/v1/mcp/servers/${serverId}/prompts/${promptName}`,
+        { arguments: args }
+      )
     };
   }
   // ── Memory ────────────────────────────────────────────────────────────────
@@ -417,7 +840,10 @@ var CommonsClient = class {
         if (opts?.type) params.set("type", opts.type);
         if (opts?.limit) params.set("limit", String(opts.limit));
         const qs = params.toString();
-        return this.request("GET", `/v1/memory/agents/${agentId}${qs ? `?${qs}` : ""}`);
+        return this.request(
+          "GET",
+          `/v1/memory/agents/${agentId}${qs ? `?${qs}` : ""}`
+        );
       },
       /** Get memory stats for an agent. */
       stats: (agentId) => this.request("GET", `/v1/memory/agents/${agentId}/stats`),
@@ -425,7 +851,10 @@ var CommonsClient = class {
       retrieve: (agentId, query, limit) => {
         const params = new URLSearchParams({ q: query });
         if (limit) params.set("limit", String(limit));
-        return this.request("GET", `/v1/memory/agents/${agentId}/retrieve?${params}`);
+        return this.request(
+          "GET",
+          `/v1/memory/agents/${agentId}/retrieve?${params}`
+        );
       },
       /** Get a single memory by ID. */
       get: (memoryId) => this.request("GET", `/v1/memory/${memoryId}`),
@@ -434,7 +863,11 @@ var CommonsClient = class {
       /** Update a memory. */
       update: (memoryId, params) => this.request("PATCH", `/v1/memory/${memoryId}`, params),
       /** Soft-delete (deactivate) a memory. */
-      delete: (memoryId) => this.request("DELETE", `/v1/memory/${memoryId}`)
+      delete: (memoryId) => this.request("DELETE", `/v1/memory/${memoryId}`),
+      /** Create an append-only memory scope shared by a set of owned agents. */
+      createSharedScope: (params) => this.request("POST", "/v1/memory/shared-scopes", params),
+      /** List shared-memory scopes available to an agent. */
+      listSharedScopes: (agentId) => this.request("GET", `/v1/memory/shared-scopes/agents/${agentId}`)
     };
   }
   // ── Usage / Observability ─────────────────────────────────────────────────
@@ -446,12 +879,340 @@ var CommonsClient = class {
         if (opts?.from) params.set("from", opts.from);
         if (opts?.to) params.set("to", opts.to);
         const qs = params.toString();
-        return this.request("GET", `/v1/usage/agents/${agentId}${qs ? `?${qs}` : ""}`);
+        return this.request(
+          "GET",
+          `/v1/usage/agents/${agentId}${qs ? `?${qs}` : ""}`
+        );
       },
       /** Get aggregated token + cost usage for a session. */
       getSessionUsage: (sessionId) => this.request("GET", `/v1/usage/sessions/${sessionId}`)
     };
   }
+  // ── Activity and logs ────────────────────────────────────────────────────
+  get activity() {
+    return {
+      list: (filter) => {
+        const query = new URLSearchParams();
+        if (filter?.actorId) query.set("actorId", filter.actorId);
+        if (filter?.eventType) query.set("eventType", filter.eventType);
+        if (filter?.since) query.set("since", filter.since);
+        if (filter?.limit) query.set("limit", String(filter.limit));
+        return this.request(
+          "GET",
+          `/v1/activity/events${query.size ? `?${query}` : ""}`
+        );
+      }
+    };
+  }
+  get logs() {
+    return {
+      list: (agentId, filter) => {
+        const query = new URLSearchParams();
+        if (filter?.sessionId) query.set("sessionId", filter.sessionId);
+        if (filter?.limit) query.set("limit", String(filter.limit));
+        return this.request(
+          "GET",
+          `/v1/logs/agents/${encodeURIComponent(agentId)}${query.size ? `?${query}` : ""}`
+        );
+      },
+      observability: (agentId, filter) => {
+        const query = new URLSearchParams();
+        if (filter?.from) query.set("from", filter.from);
+        if (filter?.to) query.set("to", filter.to);
+        if (filter?.limit) query.set("limit", String(filter.limit));
+        return this.request(
+          "GET",
+          `/v1/logs/agents/${encodeURIComponent(agentId)}/observability${query.size ? `?${query}` : ""}`
+        );
+      }
+    };
+  }
+  // ── Files and library ────────────────────────────────────────────────────
+  get files() {
+    return {
+      upload: (files, params) => {
+        const body = new FormData();
+        for (const file of files) {
+          body.append("files", file.data, file.name);
+        }
+        if (params?.agentId) body.set("agentId", params.agentId);
+        if (params?.sessionId) body.set("sessionId", params.sessionId);
+        if (params?.workspaceId) body.set("workspaceId", params.workspaceId);
+        if (params?.storageProvider)
+          body.set("storageProvider", params.storageProvider);
+        return this.request("POST", "/v1/files/upload", body);
+      },
+      get: (fileId, context) => {
+        const query = new URLSearchParams();
+        if (context?.agentId) query.set("agentId", context.agentId);
+        if (context?.sessionId) query.set("sessionId", context.sessionId);
+        return this.request(
+          "GET",
+          `/v1/files/${encodeURIComponent(fileId)}${query.size ? `?${query}` : ""}`
+        );
+      },
+      content: (fileId, options) => {
+        const query = new URLSearchParams();
+        if (options?.agentId) query.set("agentId", options.agentId);
+        if (options?.sessionId) query.set("sessionId", options.sessionId);
+        if (options?.offset !== void 0)
+          query.set("offset", String(options.offset));
+        if (options?.maxChars !== void 0)
+          query.set("maxChars", String(options.maxChars));
+        if (options?.includeImageUrls !== void 0)
+          query.set("includeImageUrls", String(options.includeImageUrls));
+        if (options?.includeDownloadUrl !== void 0)
+          query.set("includeDownloadUrl", String(options.includeDownloadUrl));
+        return this.request(
+          "GET",
+          `/v1/files/${encodeURIComponent(fileId)}/content${query.size ? `?${query}` : ""}`
+        );
+      }
+    };
+  }
+  get library() {
+    return {
+      list: (filter) => {
+        const query = new URLSearchParams();
+        if (filter?.query) query.set("query", filter.query);
+        if (filter?.view) query.set("view", filter.view);
+        if (filter?.source) query.set("source", filter.source);
+        if (filter?.favorite !== void 0)
+          query.set("favorite", String(filter.favorite));
+        if (filter?.sessionId) query.set("sessionId", filter.sessionId);
+        if (filter?.limit !== void 0)
+          query.set("limit", String(filter.limit));
+        if (filter?.offset !== void 0)
+          query.set("offset", String(filter.offset));
+        return this.request(
+          "GET",
+          `/v1/library${query.size ? `?${query}` : ""}`
+        );
+      },
+      get: (itemId) => this.request(
+        "GET",
+        `/v1/library/${encodeURIComponent(itemId)}`
+      ),
+      download: (itemId) => this.request(
+        "GET",
+        `/v1/library/${encodeURIComponent(itemId)}/download`
+      ),
+      preview: (itemId) => this.request(
+        "GET",
+        `/v1/library/${encodeURIComponent(itemId)}/preview`
+      ),
+      update: (itemId, params) => this.request(
+        "PATCH",
+        `/v1/library/${encodeURIComponent(itemId)}`,
+        params
+      ),
+      delete: (itemId) => this.request(
+        "DELETE",
+        `/v1/library/${encodeURIComponent(itemId)}`
+      ),
+      storagePreference: () => this.request("GET", "/v1/library/preferences/storage"),
+      setStoragePreference: (defaultStorageProvider) => this.request("PATCH", "/v1/library/preferences/storage", {
+        defaultStorageProvider
+      }),
+      grant: (itemId, params) => this.request(
+        "POST",
+        `/v1/library/${encodeURIComponent(itemId)}/grants`,
+        params
+      ),
+      revokeGrant: (itemId, grantId) => this.request(
+        "DELETE",
+        `/v1/library/${encodeURIComponent(itemId)}/grants/${encodeURIComponent(grantId)}`
+      ),
+      createShareLink: (itemId, expiresAt) => this.request(
+        "POST",
+        `/v1/library/${encodeURIComponent(itemId)}/share-links`,
+        { expiresAt }
+      ),
+      revokeShareLink: (itemId, shareId) => this.request(
+        "DELETE",
+        `/v1/library/${encodeURIComponent(itemId)}/share-links/${encodeURIComponent(shareId)}`
+      ),
+      resolveShare: (token) => this.request(
+        "GET",
+        `/v1/shared/artifacts/${encodeURIComponent(token)}`
+      )
+    };
+  }
+  // ── Spaces, projects, and goals ──────────────────────────────────────────
+  get spaces() {
+    return {
+      list: (filter) => {
+        const query = new URLSearchParams();
+        if (filter?.memberId) query.set("memberId", filter.memberId);
+        if (filter?.memberType) query.set("memberType", filter.memberType);
+        if (filter?.agentIds?.length)
+          query.set("agentIds", filter.agentIds.join(","));
+        if (filter?.publicOnly !== void 0)
+          query.set("publicOnly", String(filter.publicOnly));
+        if (filter?.search) query.set("search", filter.search);
+        if (filter?.includeMembers !== void 0)
+          query.set("includeMembers", String(filter.includeMembers));
+        if (filter?.limit !== void 0)
+          query.set("limit", String(filter.limit));
+        if (filter?.offset !== void 0)
+          query.set("offset", String(filter.offset));
+        return this.request(
+          "GET",
+          `/v1/spaces${query.size ? `?${query}` : ""}`
+        );
+      },
+      create: (params, creator) => this.request("POST", "/v1/spaces", params, {
+        headers: {
+          "x-creator-id": creator.id,
+          "x-creator-type": creator.type
+        }
+      }),
+      get: (spaceId) => this.request(
+        "GET",
+        `/v1/spaces/${encodeURIComponent(spaceId)}`
+      ),
+      getFull: (spaceId) => this.request(
+        "GET",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/full`
+      ),
+      update: (spaceId, params) => this.request(
+        "PUT",
+        `/v1/spaces/${encodeURIComponent(spaceId)}`,
+        params
+      ),
+      delete: (spaceId) => this.request(
+        "DELETE",
+        `/v1/spaces/${encodeURIComponent(spaceId)}`
+      ),
+      issueRtcTicket: (spaceId) => this.request(
+        "POST",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/rtc-ticket`,
+        {}
+      ),
+      listMembers: (spaceId) => this.request(
+        "GET",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/members`
+      ),
+      addMember: (spaceId, params) => this.request(
+        "POST",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/members`,
+        params
+      ),
+      updateMember: (spaceId, memberId, memberType, params) => this.request(
+        "PUT",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/members/${encodeURIComponent(memberId)}?memberType=${memberType}`,
+        params
+      ),
+      removeMember: (spaceId, memberId, memberType) => this.request(
+        "DELETE",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/members/${encodeURIComponent(memberId)}?memberType=${memberType}`
+      ),
+      listMessages: (spaceId, filter) => {
+        const query = new URLSearchParams();
+        if (filter?.limit !== void 0)
+          query.set("limit", String(filter.limit));
+        if (filter?.offset !== void 0)
+          query.set("offset", String(filter.offset));
+        if (filter?.memberId) query.set("memberId", filter.memberId);
+        return this.request(
+          "GET",
+          `/v1/spaces/${encodeURIComponent(spaceId)}/messages${query.size ? `?${query}` : ""}`
+        );
+      },
+      sendMessage: (spaceId, params, sender) => this.request(
+        "POST",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/messages`,
+        params,
+        {
+          headers: {
+            "x-sender-id": sender.id,
+            "x-sender-type": sender.type
+          }
+        }
+      ),
+      updateMessage: (spaceId, messageId, params) => this.request(
+        "PUT",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/messages/${encodeURIComponent(messageId)}`,
+        params
+      ),
+      deleteMessage: (spaceId, messageId) => this.request(
+        "DELETE",
+        `/v1/spaces/${encodeURIComponent(spaceId)}/messages/${encodeURIComponent(messageId)}`
+      )
+    };
+  }
+  get projects() {
+    const base = (agentId) => `/v1/agents/${encodeURIComponent(agentId)}/projects`;
+    return {
+      list: (agentId) => this.request("GET", base(agentId)),
+      create: (agentId, params) => this.request("POST", base(agentId), params),
+      get: (agentId, projectId) => this.request(
+        "GET",
+        `${base(agentId)}/${encodeURIComponent(projectId)}`
+      ),
+      writeFiles: (agentId, projectId, files, replace = false) => this.request(
+        "PUT",
+        `${base(agentId)}/${encodeURIComponent(projectId)}/files`,
+        { files, replace }
+      ),
+      publish: (agentId, projectId) => this.request(
+        "POST",
+        `${base(agentId)}/${encodeURIComponent(projectId)}/publish`,
+        {}
+      ),
+      verify: (agentId, projectId, actions) => this.request(
+        "POST",
+        `${base(agentId)}/${encodeURIComponent(projectId)}/verify`,
+        { actions }
+      ),
+      exportToComputer: (agentId, projectId, params) => this.request(
+        "POST",
+        `${base(agentId)}/${encodeURIComponent(projectId)}/export`,
+        params ?? {}
+      ),
+      exportToGitHub: (agentId, projectId, params) => this.request(
+        "POST",
+        `${base(agentId)}/${encodeURIComponent(projectId)}/github`,
+        params ?? {}
+      )
+    };
+  }
+  get goals() {
+    return {
+      create: (params) => this.request("POST", "/v1/goals", params),
+      get: (goalId) => this.request("GET", `/v1/goals/${encodeURIComponent(goalId)}`),
+      updateProgress: (goalId, progress, status) => this.request(
+        "PUT",
+        `/v1/goals/${encodeURIComponent(goalId)}`,
+        { progress, status }
+      )
+    };
+  }
+  // ── Audio and liaison agents ─────────────────────────────────────────────
+  get audio() {
+    return {
+      transcribe: (file, options) => {
+        const body = new FormData();
+        body.append("file", file.data, file.name);
+        if (options?.durationMs !== void 0)
+          body.set("durationMs", String(options.durationMs));
+        return this.request("POST", "/v1/audio/transcriptions", body, {
+          headers: options?.idempotencyKey ? { "x-idempotency-key": options.idempotencyKey } : void 0
+        });
+      }
+    };
+  }
+  get liaisons() {
+    return {
+      create: (params) => this.request("POST", "/v1/liaison", params),
+      interact: (liaisonAgentId, liaisonKey, message) => this.request(
+        "POST",
+        "/v1/liaison/interact",
+        { liaisonAgentId, message },
+        { headers: { "x-api-key": liaisonKey } }
+      )
+    };
+  }
   // ── Credits ──────────────────────────────────────────────────────────────
   get credits() {
     return {
@@ -470,10 +1231,45 @@ var CommonsClient = class {
         const qs = params.toString();
         return this.request("GET", `/v1/credits/ledger${qs ? `?${qs}` : ""}`);
       },
+      summary: () => this.request("GET", "/v1/credits/summary"),
+      campaigns: () => this.request("GET", "/v1/credits/campaigns"),
+      claimCampaign: (params) => this.request("POST", "/v1/credits/campaigns/claim", params),
+      transfers: () => this.request("GET", "/v1/credits/transfers"),
+      gift: (params) => this.request("POST", "/v1/credits/gifts", params),
       grant: (params) => this.request("POST", "/v1/credits/grants", params),
       debit: (params) => this.request("POST", "/v1/credits/debits", params)
     };
   }
+  // ── Billing ────────────────────────────────────────────────────────────────
+  get billing() {
+    return {
+      /** Public product catalog served from the backend source of truth. */
+      catalog: () => this.request("GET", "/v1/billing/catalog"),
+      /** Current plan, status, and entitlements for the caller. */
+      subscription: () => this.request("GET", "/v1/billing/subscription"),
+      /** Entitlements only (what paid features the caller may use). */
+      entitlements: () => this.request("GET", "/v1/billing/entitlements"),
+      /** Stripe invoice history for the caller. */
+      invoices: () => this.request("GET", "/v1/billing/invoices"),
+      /** Saved Stripe payment methods for the caller. */
+      paymentMethods: () => this.request("GET", "/v1/billing/payment-methods"),
+      /** Create a Stripe Checkout session for a subscription plan. */
+      subscribe: (planKey) => this.request("POST", "/v1/billing/checkout/subscription", { planKey }),
+      /** Create a Stripe Checkout session for a one-time credit top-up. */
+      topup: (packKey) => this.request("POST", "/v1/billing/checkout/topup", { packKey }),
+      /** Open the Stripe billing portal. */
+      portal: () => this.request("POST", "/v1/billing/portal", {})
+    };
+  }
+  // ── Feature flags ────────────────────────────────────────────────────────
+  get flags() {
+    return {
+      /** Evaluate all active flags for the caller (call once at boot). */
+      all: () => this.request("GET", "/v1/flags"),
+      /** Evaluate a single flag for the caller. */
+      evaluate: (key) => this.request("GET", `/v1/flags/${encodeURIComponent(key)}`)
+    };
+  }
 };
 var CommonsError = class extends Error {
   constructor(message, status, data) {